feat(ultraplan-local): add lib/validators/review-validator.mjs
This commit is contained in:
Kjell Tore Guttormsen
parent
e0bf75e17a
commit
f6e61e92cd
2 changed files with 223 additions and 0 deletions
109
plugins/ultraplan-local/lib/validators/review-validator.mjs
Normal file
109
plugins/ultraplan-local/lib/validators/review-validator.mjs
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
// lib/validators/review-validator.mjs
|
||||
// Validate ultrareview frontmatter + body invariants.
|
||||
// 3-layer pattern (Content → File → CLI shim) mirroring brief-validator.
|
||||
|
||||
import { readFileSync, existsSync } from 'node:fs';
|
||||
import { parseDocument } from '../util/frontmatter.mjs';
|
||||
import { issue, ok, fail } from '../util/result.mjs';
|
||||
|
||||
export const REVIEW_REQUIRED_FRONTMATTER = [
|
||||
'type',
|
||||
'review_version',
|
||||
'task',
|
||||
'slug',
|
||||
'project_dir',
|
||||
'brief_path',
|
||||
'scope_sha_end',
|
||||
'reviewed_files_count',
|
||||
'findings',
|
||||
];
|
||||
export const REVIEW_BODY_SECTIONS = ['Executive Summary', 'Coverage', 'Remediation Summary'];
|
||||
|
||||
const HEX_ID_RE = /^[0-9a-f]{40}$/;
|
||||
|
||||
export function validateReviewContent(text, opts = {}) {
|
||||
const strict = opts.strict !== false;
|
||||
const doc = parseDocument(text);
|
||||
if (!doc.valid) return doc;
|
||||
|
||||
const fm = doc.parsed.frontmatter || {};
|
||||
const body = doc.parsed.body || '';
|
||||
const errors = [];
|
||||
const warnings = [];
|
||||
|
||||
for (const k of REVIEW_REQUIRED_FRONTMATTER) {
|
||||
if (!(k in fm)) {
|
||||
errors.push(issue('REVIEW_MISSING_FIELD', `Required frontmatter field missing: ${k}`));
|
||||
}
|
||||
}
|
||||
|
||||
if (fm.type !== undefined && fm.type !== 'ultrareview') {
|
||||
errors.push(issue('REVIEW_WRONG_TYPE', `frontmatter.type must be "ultrareview", got "${fm.type}"`));
|
||||
}
|
||||
|
||||
if (fm.findings !== undefined) {
|
||||
if (!Array.isArray(fm.findings)) {
|
||||
errors.push(issue(
|
||||
'REVIEW_BAD_FINDINGS_TYPE',
|
||||
`Field "findings" must be an array of finding-IDs, got ${typeof fm.findings}`,
|
||||
'Use block-style YAML: `findings:\\n - <id1>\\n - <id2>`',
|
||||
));
|
||||
} else {
|
||||
for (let i = 0; i < fm.findings.length; i++) {
|
||||
const id = fm.findings[i];
|
||||
if (typeof id !== 'string' || !HEX_ID_RE.test(id)) {
|
||||
errors.push(issue(
|
||||
'REVIEW_BAD_FINDING_ID',
|
||||
`findings[${i}] is not a 40-char hex ID: ${JSON.stringify(id)}`,
|
||||
));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const section of REVIEW_BODY_SECTIONS) {
|
||||
const re = new RegExp(`^##\\s+${section}\\b`, 'm');
|
||||
if (!re.test(body)) {
|
||||
const issueObj = issue('REVIEW_MISSING_SECTION', `Required body section missing: ## ${section}`);
|
||||
if (strict) errors.push(issueObj);
|
||||
else warnings.push(issueObj);
|
||||
}
|
||||
}
|
||||
|
||||
if (typeof fm.review_version === 'string') {
|
||||
const m = fm.review_version.match(/^(\d+)\.(\d+)$/);
|
||||
if (!m) {
|
||||
warnings.push(issue('REVIEW_VERSION_FORMAT', `review_version "${fm.review_version}" not in N.M form`));
|
||||
}
|
||||
}
|
||||
|
||||
return { valid: errors.length === 0, errors, warnings, parsed: { frontmatter: fm, body } };
|
||||
}
|
||||
|
||||
export function validateReview(filePath, opts = {}) {
|
||||
if (!existsSync(filePath)) return fail(issue('REVIEW_NOT_FOUND', `File not found: ${filePath}`));
|
||||
let text;
|
||||
try { text = readFileSync(filePath, 'utf-8'); }
|
||||
catch (e) { return fail(issue('REVIEW_READ_ERROR', `Cannot read ${filePath}: ${e.message}`)); }
|
||||
const r = validateReviewContent(text, opts);
|
||||
return { ...r, parsed: { ...r.parsed, filePath } };
|
||||
}
|
||||
|
||||
if (import.meta.url === `file://${process.argv[1]}`) {
|
||||
const args = process.argv.slice(2);
|
||||
const strict = !args.includes('--soft');
|
||||
const filePath = args.find(a => !a.startsWith('--'));
|
||||
if (!filePath) {
|
||||
process.stderr.write('Usage: review-validator.mjs [--soft] [--json] <review.md>\n');
|
||||
process.exit(2);
|
||||
}
|
||||
const r = validateReview(filePath, { strict });
|
||||
if (args.includes('--json')) {
|
||||
process.stdout.write(JSON.stringify({ valid: r.valid, errors: r.errors, warnings: r.warnings }, null, 2) + '\n');
|
||||
} else {
|
||||
process.stdout.write(`review-validator: ${r.valid ? 'PASS' : 'FAIL'} ${filePath}\n`);
|
||||
for (const e of r.errors) process.stderr.write(` ERROR [${e.code}] ${e.message}\n`);
|
||||
for (const w of r.warnings) process.stderr.write(` WARN [${w.code}] ${w.message}\n`);
|
||||
}
|
||||
process.exit(r.valid ? 0 : 1);
|
||||
}
|
||||
|
|
@ -0,0 +1,114 @@
|
|||
import { test } from 'node:test';
|
||||
import { strict as assert } from 'node:assert';
|
||||
import { validateReviewContent } from '../../lib/validators/review-validator.mjs';
|
||||
|
||||
const GOOD_REVIEW = `---
|
||||
type: ultrareview
|
||||
review_version: "1.0"
|
||||
created: 2026-05-01
|
||||
task: "Add JWT auth"
|
||||
slug: jwt-auth
|
||||
project_dir: .claude/projects/2026-04-30-jwt-auth/
|
||||
brief_path: .claude/projects/2026-04-30-jwt-auth/brief.md
|
||||
scope_sha_start: abc123
|
||||
scope_sha_end: def456
|
||||
reviewed_files_count: 7
|
||||
findings:
|
||||
- 0123456789abcdef0123456789abcdef01234567
|
||||
- fedcba9876543210fedcba9876543210fedcba98
|
||||
---
|
||||
|
||||
# Review
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Verdict: ALLOW.
|
||||
|
||||
## Coverage
|
||||
|
||||
| File | Treatment | Reason |
|
||||
|------|-----------|--------|
|
||||
| lib/foo.mjs | deep-review | risk |
|
||||
|
||||
## Remediation Summary
|
||||
|
||||
None.
|
||||
`;
|
||||
|
||||
test('validateReview — happy path', () => {
|
||||
const r = validateReviewContent(GOOD_REVIEW, { strict: true });
|
||||
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
||||
});
|
||||
|
||||
test('validateReview — wrong type rejected (REVIEW_WRONG_TYPE)', () => {
|
||||
const t = GOOD_REVIEW.replace('type: ultrareview', 'type: ultrabrief');
|
||||
const r = validateReviewContent(t);
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'REVIEW_WRONG_TYPE'));
|
||||
});
|
||||
|
||||
test('validateReview — missing required field (REVIEW_MISSING_FIELD)', () => {
|
||||
const t = GOOD_REVIEW.replace(/^brief_path: .*\n/m, '');
|
||||
const r = validateReviewContent(t);
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'REVIEW_MISSING_FIELD' && /brief_path/.test(e.message)));
|
||||
});
|
||||
|
||||
test('validateReview — missing required body section in strict (REVIEW_MISSING_SECTION)', () => {
|
||||
const t = GOOD_REVIEW.replace(/## Coverage[\s\S]*?(?=## Remediation)/m, '');
|
||||
const r = validateReviewContent(t, { strict: true });
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'REVIEW_MISSING_SECTION' && /Coverage/.test(e.message)));
|
||||
});
|
||||
|
||||
test('validateReview — Coverage section is REQUIRED (no soft demotion to make Coverage optional)', () => {
|
||||
const t = GOOD_REVIEW.replace(/## Coverage[\s\S]*?(?=## Remediation)/m, '');
|
||||
const r = validateReviewContent(t, { strict: true });
|
||||
assert.equal(r.valid, false);
|
||||
});
|
||||
|
||||
test('validateReview — soft mode demotes section errors to warnings', () => {
|
||||
const t = GOOD_REVIEW.replace(/## Remediation Summary[\s\S]*$/m, '');
|
||||
const r = validateReviewContent(t, { strict: false });
|
||||
assert.equal(r.valid, true);
|
||||
assert.ok(r.warnings.find(w => w.code === 'REVIEW_MISSING_SECTION'));
|
||||
});
|
||||
|
||||
test('validateReview — missing frontmatter is hard error (FM_MISSING)', () => {
|
||||
const r = validateReviewContent('# review\n\nno frontmatter\n');
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'FM_MISSING'));
|
||||
});
|
||||
|
||||
test('validateReview — findings not an array → REVIEW_BAD_FINDINGS_TYPE', () => {
|
||||
// Replace block-style list with scalar → parser yields string
|
||||
const t = GOOD_REVIEW.replace(
|
||||
/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+/,
|
||||
'findings: not-an-array',
|
||||
);
|
||||
const r = validateReviewContent(t);
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(
|
||||
r.errors.find(e => e.code === 'REVIEW_BAD_FINDINGS_TYPE'),
|
||||
`expected REVIEW_BAD_FINDINGS_TYPE, got: ${JSON.stringify(r.errors)}`,
|
||||
);
|
||||
});
|
||||
|
||||
test('validateReview — finding-ID not 40-char hex → REVIEW_BAD_FINDING_ID', () => {
|
||||
const t = GOOD_REVIEW.replace(
|
||||
'0123456789abcdef0123456789abcdef01234567',
|
||||
'NOT-A-VALID-HEX-ID',
|
||||
);
|
||||
const r = validateReviewContent(t);
|
||||
assert.equal(r.valid, false);
|
||||
assert.ok(r.errors.find(e => e.code === 'REVIEW_BAD_FINDING_ID'));
|
||||
});
|
||||
|
||||
test('validateReview — empty findings array is acceptable (no findings = ALLOW verdict)', () => {
|
||||
const t = GOOD_REVIEW.replace(
|
||||
/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+/,
|
||||
'findings: []',
|
||||
);
|
||||
const r = validateReviewContent(t);
|
||||
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue