From f6e61e92cd4f592b35ddbb8acae6f8b5c45118c2 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 1 May 2026 13:30:43 +0200 Subject: [PATCH] feat(ultraplan-local): add lib/validators/review-validator.mjs --- .../lib/validators/review-validator.mjs | 109 +++++++++++++++++ .../validators/review-validator.test.mjs | 114 ++++++++++++++++++ 2 files changed, 223 insertions(+) create mode 100644 plugins/ultraplan-local/lib/validators/review-validator.mjs create mode 100644 plugins/ultraplan-local/tests/validators/review-validator.test.mjs diff --git a/plugins/ultraplan-local/lib/validators/review-validator.mjs b/plugins/ultraplan-local/lib/validators/review-validator.mjs new file mode 100644 index 0000000..18b3443 --- /dev/null +++ b/plugins/ultraplan-local/lib/validators/review-validator.mjs @@ -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 - \\n - `', + )); + } 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] \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); +} diff --git a/plugins/ultraplan-local/tests/validators/review-validator.test.mjs b/plugins/ultraplan-local/tests/validators/review-validator.test.mjs new file mode 100644 index 0000000..417dfd2 --- /dev/null +++ b/plugins/ultraplan-local/tests/validators/review-validator.test.mjs @@ -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)); +});