383 lines
17 KiB
JavaScript
383 lines
17 KiB
JavaScript
// lib/validators/review-validator.mjs
|
|
// Validate trekreview frontmatter + body invariants.
|
|
// 3-layer pattern (Content → File → CLI shim) mirroring brief-validator.
|
|
//
|
|
// Schema is forward-compatible: unknown top-level frontmatter keys are
|
|
// tolerated silently. Strict-key checks are intentionally avoided so new
|
|
// optional fields (jf. the source_findings precedent) can be added without
|
|
// a review_version bump.
|
|
//
|
|
// K7 (ordre 5, review_version 1.1): `verdict: ALLOW | WARN | BLOCK` is REQUIRED.
|
|
// Strict (write-time) mode rejects a review without it; soft (read-time) mode
|
|
// warns, so a 1.0 review can still seed a plan (N-1 window, Handover 6). The
|
|
// gate that decides on the verdict is lib/review/verdict-gate.mjs, which never
|
|
// reads a missing verdict as ALLOW.
|
|
//
|
|
// review_version 1.2: optional round, policy, pre-existing, ran and `## Answers`
|
|
// fields; each one present is checked for shape (`review12Issues`). A 1.1
|
|
// review is read as before (N-1 window).
|
|
|
|
import { readFileSync, existsSync } from 'node:fs';
|
|
import { parseDocument } from '../util/frontmatter.mjs';
|
|
import { issue, ok, fail } from '../util/result.mjs';
|
|
import { isMain } from '../util/is-main.mjs';
|
|
import { extractFindingsBlock } from '../review/findings-schema.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'];
|
|
export const VERDICT_VALUES = Object.freeze(['ALLOW', 'WARN', 'BLOCK']);
|
|
|
|
const HEX_ID_RE = /^[0-9a-f]{40}$/;
|
|
/**
|
|
* IDs of BLOCKER findings in the trailing JSON block ([] when absent/unparseable).
|
|
* Read with the one block reader, so three backticks inside a JSON string do
|
|
* not end the block early and hide a BLOCKER (release review of 6.3.0, round 8).
|
|
*/
|
|
function blockerIdsFromBody(body) {
|
|
const last = extractFindingsBlock(body);
|
|
if (last === null) return [];
|
|
try {
|
|
const payload = JSON.parse(last);
|
|
return (Array.isArray(payload?.findings) ? payload.findings : [])
|
|
.filter((f) => f?.severity === 'BLOCKER' && typeof f.id === 'string')
|
|
.map((f) => f.id);
|
|
} catch {
|
|
return [];
|
|
}
|
|
}
|
|
|
|
/** Finding IDs named by `Source finding:` lines under `## Remediation Steps` step headings. */
|
|
export function remediationStepSources(body) {
|
|
const start = body.search(/^##\s+Remediation Steps\b/m);
|
|
if (start === -1) return new Set();
|
|
const rest = body.slice(start).replace(/^##\s+Remediation Steps[^\n]*\n/, '');
|
|
const next = rest.search(/^##\s+/m);
|
|
const section = next === -1 ? rest : rest.slice(0, next);
|
|
const ids = new Set();
|
|
for (const step of section.split(/^###\s+Step\s+R\d+\b/m).slice(1)) {
|
|
const m = step.match(/Source finding:\**\s*`?([0-9a-f]{40})`?/);
|
|
if (m) ids.add(m[1]);
|
|
}
|
|
return ids;
|
|
}
|
|
|
|
// ---- review_version 1.2 shapes ------------------------------------------------
|
|
// Codes: REVIEW_ANSWERS_MALFORMED (the `## Answers` table, and a MAJOR answered
|
|
// `fixed` without its R-step), REVIEW_POLICY_MALFORMED (`review_policy`,
|
|
// `review_policy_sha256`, a finding's `instruction_ref`), REVIEW_ROUND_MALFORMED
|
|
// (`round`, `round_base`, `finalized`, `resolved`, `ran`, a finding's
|
|
// `carried_from`) and REVIEW_PRE_EXISTING_MALFORMED (a finding's `pre_existing`,
|
|
// `pre_existing_counts`).
|
|
|
|
const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
|
|
const SHA256_RE = /^[0-9a-f]{64}$/;
|
|
const SEVERITIES = ['BLOCKER', 'MAJOR', 'MINOR', 'SUGGESTION'];
|
|
const REVIEW_POLICY_VALUES = ['absent', 'applied', 'not-applied'];
|
|
const RAN_ENGINES = ['code-review', 'security-review'];
|
|
const ANSWERS_HEADER = '| Finding | Answer | Reason | Record | Carried from |';
|
|
const ANSWER_FINDING_RE = /^([0-9a-f]{40})(?:#\d+)?$/;
|
|
const CARRIED_FROM_RE = /^review-round-[0-9a-f]{12}-\d+\.md#[0-9a-f]{40}$/;
|
|
|
|
const isPlainObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
|
|
|
|
/** The lines of the `## Answers` section (heading excluded), up to the next `## ` heading or a fence; null when absent. */
|
|
function answersSectionLines(body) {
|
|
const lines = body.split('\n');
|
|
const at = lines.findIndex((l) => /^##\s+Answers\s*$/.test(l));
|
|
if (at === -1) return null;
|
|
const out = [];
|
|
for (const l of lines.slice(at + 1)) {
|
|
if (/^##\s/.test(l) || /^\s{0,3}(`{3,}|~{3,})/.test(l)) break;
|
|
out.push(l);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* Parse the `## Answers` table. Returns `{rows, problems}`; rows hold
|
|
* `{id, answer, reason, record, carriedFrom}`. An absent section, or one with
|
|
* no table, has no rows.
|
|
*/
|
|
function parseAnswersTable(body) {
|
|
const section = answersSectionLines(body);
|
|
const rows = [];
|
|
const problems = [];
|
|
if (section === null) return { rows, problems };
|
|
const table = section.map((l) => l.trim()).filter((l) => l.startsWith('|'));
|
|
if (table.length === 0) return { rows, problems };
|
|
if (table[0] !== ANSWERS_HEADER) {
|
|
problems.push(`## Answers header must be exactly "${ANSWERS_HEADER}", got ${JSON.stringify(table[0])}`);
|
|
return { rows, problems };
|
|
}
|
|
if (table.length < 2 || !/^\|(?:\s*:?-{3,}:?\s*\|){5}$/.test(table[1])) {
|
|
problems.push('## Answers table has no separator line of five columns under its header');
|
|
return { rows, problems };
|
|
}
|
|
const seen = new Set();
|
|
table.slice(2).forEach((line, i) => {
|
|
const where = `## Answers row ${i + 1}`;
|
|
if (!line.endsWith('|')) { problems.push(`${where} does not end with "|"`); return; }
|
|
const cells = line.slice(1, -1).split('|').map((c) => c.trim());
|
|
if (cells.length !== 5) { problems.push(`${where} has ${cells.length} cells, not 5`); return; }
|
|
const [finding, answer, reason, record, carriedFrom] = cells;
|
|
const m = finding.match(ANSWER_FINDING_RE);
|
|
if (!m) problems.push(`${where}: Finding ${JSON.stringify(finding)} is not a 40-char hex id (optionally #n)`);
|
|
if (answer !== 'accepted' && answer !== 'fixed') {
|
|
problems.push(`${where}: Answer must be accepted|fixed, got ${JSON.stringify(answer)}`);
|
|
}
|
|
if (answer === 'accepted' && reason === '') problems.push(`${where}: an accepted answer needs a non-empty Reason`);
|
|
if (!SHA256_RE.test(record)) problems.push(`${where}: Record ${JSON.stringify(record)} is not a 64-char hex record hash`);
|
|
if (carriedFrom !== '-' && !CARRIED_FROM_RE.test(carriedFrom)) {
|
|
problems.push(`${where}: Carried from must be "-" or review-round-<run12>-<n>.md#<id>, got ${JSON.stringify(carriedFrom)}`);
|
|
}
|
|
if (m) {
|
|
if (seen.has(m[1])) problems.push(`${where}: a second row for finding ${m[1]} (at most one row per finding)`);
|
|
seen.add(m[1]);
|
|
rows.push({ id: m[1], answer, reason, record, carriedFrom });
|
|
}
|
|
});
|
|
return { rows, problems };
|
|
}
|
|
|
|
/** The parsed trailing JSON block, or null when absent or unparseable (other checks report those). */
|
|
function findingsPayload(body) {
|
|
const last = extractFindingsBlock(body);
|
|
if (last === null) return null;
|
|
try { return JSON.parse(last); } catch { return null; }
|
|
}
|
|
|
|
/** Issues for the review_version 1.2 fields that are present. Absent fields are never an issue. */
|
|
function review12Issues(fm, body) {
|
|
const out = [];
|
|
const round = (msg) => out.push(issue('REVIEW_ROUND_MALFORMED', msg));
|
|
const policy = (msg) => out.push(issue('REVIEW_POLICY_MALFORMED', msg));
|
|
const pre = (msg) => out.push(issue('REVIEW_PRE_EXISTING_MALFORMED', msg));
|
|
const answers = (msg) => out.push(issue('REVIEW_ANSWERS_MALFORMED', msg));
|
|
|
|
// Frontmatter.
|
|
if ('round' in fm && !(Number.isInteger(fm.round) && fm.round >= 1 && fm.round <= 3)) {
|
|
round(`frontmatter.round must be an integer 1-3, got ${JSON.stringify(fm.round)}`);
|
|
}
|
|
if ('round_base' in fm && fm.round_base !== null
|
|
&& !(typeof fm.round_base === 'string' && FULL_SHA_RE.test(fm.round_base))) {
|
|
round(`frontmatter.round_base must be a full 40- or 64-hex commit id or null, got ${JSON.stringify(fm.round_base)}`);
|
|
}
|
|
if ('finalized' in fm && typeof fm.finalized !== 'boolean') {
|
|
round(`frontmatter.finalized must be a boolean, got ${JSON.stringify(fm.finalized)}`);
|
|
}
|
|
if ('review_policy' in fm && !REVIEW_POLICY_VALUES.includes(fm.review_policy)) {
|
|
policy(`frontmatter.review_policy must be one of ${REVIEW_POLICY_VALUES.join('|')}, got ${JSON.stringify(fm.review_policy)}`);
|
|
}
|
|
if ('review_policy_sha256' in fm
|
|
&& !(fm.review_policy_sha256 === 'none' || (typeof fm.review_policy_sha256 === 'string' && SHA256_RE.test(fm.review_policy_sha256)))) {
|
|
policy(`frontmatter.review_policy_sha256 must be 64-char hex or none, got ${JSON.stringify(fm.review_policy_sha256)}`);
|
|
}
|
|
|
|
// Trailing JSON block.
|
|
const payload = findingsPayload(body);
|
|
const findings = Array.isArray(payload?.findings) ? payload.findings : [];
|
|
findings.forEach((f, i) => {
|
|
if (!isPlainObject(f)) return;
|
|
if ('pre_existing' in f && typeof f.pre_existing !== 'boolean') {
|
|
pre(`findings[${i}].pre_existing must be a boolean, got ${JSON.stringify(f.pre_existing)}`);
|
|
}
|
|
if ('carried_from' in f && !(typeof f.carried_from === 'string' && HEX_ID_RE.test(f.carried_from))) {
|
|
round(`findings[${i}].carried_from must be a 40-char hex finding id, got ${JSON.stringify(f.carried_from)}`);
|
|
}
|
|
if ('instruction_ref' in f && typeof f.instruction_ref !== 'string') {
|
|
policy(`findings[${i}].instruction_ref must be a string, got ${JSON.stringify(f.instruction_ref)}`);
|
|
}
|
|
});
|
|
if (isPlainObject(payload)) {
|
|
if ('pre_existing_counts' in payload) {
|
|
const c = payload.pre_existing_counts;
|
|
const okCounts = isPlainObject(c) && Object.entries(c)
|
|
.every(([k, n]) => SEVERITIES.includes(k) && Number.isInteger(n) && n >= 0);
|
|
if (!okCounts) pre(`pre_existing_counts must map ${SEVERITIES.join('|')} to counts ≥ 0, got ${JSON.stringify(c)}`);
|
|
}
|
|
if ('resolved' in payload) {
|
|
const r = payload.resolved;
|
|
if (!(Array.isArray(r) && r.every((id) => typeof id === 'string' && HEX_ID_RE.test(id)))) {
|
|
round(`resolved must be an array of 40-char hex finding ids, got ${JSON.stringify(r)}`);
|
|
}
|
|
}
|
|
if ('ran' in payload) {
|
|
const r = payload.ran;
|
|
const okRan = isPlainObject(r)
|
|
&& Array.isArray(r.engines) && r.engines.every((e) => RAN_ENGINES.includes(e))
|
|
&& Array.isArray(r.reviewers) && r.reviewers.every((s) => typeof s === 'string');
|
|
if (!okRan) {
|
|
round(`ran must be {engines: subset of ${RAN_ENGINES.join('|')}, reviewers: [string]}, got ${JSON.stringify(r)}`);
|
|
}
|
|
}
|
|
}
|
|
|
|
// ## Answers.
|
|
const { rows, problems } = parseAnswersTable(body);
|
|
for (const p of problems) answers(p);
|
|
const majors = new Set(findings
|
|
.filter((f) => isPlainObject(f) && typeof f.id === 'string' && String(f.severity).toUpperCase() === 'MAJOR')
|
|
.map((f) => f.id));
|
|
const fixedMajors = rows.filter((r) => r.answer === 'fixed' && majors.has(r.id));
|
|
if (fixedMajors.length > 0) {
|
|
const steps = remediationStepSources(body);
|
|
for (const r of fixedMajors) {
|
|
if (!steps.has(r.id)) {
|
|
answers(`MAJOR ${r.id} is answered fixed but no "### Step R<n>" under ## Remediation Steps has "Source finding: ${r.id}"`);
|
|
}
|
|
}
|
|
}
|
|
return out;
|
|
}
|
|
|
|
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 !== 'trekreview') {
|
|
errors.push(issue('REVIEW_WRONG_TYPE', `frontmatter.type must be "trekreview", 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)}`,
|
|
));
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
if (!('verdict' in fm) || fm.verdict === null || fm.verdict === '') {
|
|
const issueObj = issue(
|
|
'REVIEW_MISSING_VERDICT',
|
|
'Required frontmatter field missing: verdict (ALLOW | WARN | BLOCK)',
|
|
'Copy the coordinator verdict from the trailing JSON block into the frontmatter.',
|
|
);
|
|
if (strict) errors.push(issueObj);
|
|
else warnings.push(issueObj);
|
|
} else if (!VERDICT_VALUES.includes(fm.verdict)) {
|
|
errors.push(issue(
|
|
'REVIEW_BAD_VERDICT',
|
|
`frontmatter.verdict must be one of ${VERDICT_VALUES.join('|')}, got ${JSON.stringify(fm.verdict)}`,
|
|
));
|
|
}
|
|
|
|
// Every BLOCKER is written as a numbered remediation step that Handover 6 can
|
|
// append to a plan unchanged: `### Step R<n>: …` with `Source finding: <id>`.
|
|
// Borrowed: review gaps become appended, numbered tasks with a source-ref,
|
|
// never rewriting earlier ones (Spec Kit `templates/commands/converge.md:156-163`, MIT).
|
|
// 1.1+ only (N-1 window): a 1.0 review never carried the section.
|
|
const v = typeof fm.review_version === 'string' ? fm.review_version.match(/^(\d+)\.(\d+)$/) : null;
|
|
const atLeast11 = v && (Number(v[1]) > 1 || (Number(v[1]) === 1 && Number(v[2]) >= 1));
|
|
const blockerIds = atLeast11 ? blockerIdsFromBody(body) : [];
|
|
if (blockerIds.length > 0) {
|
|
const steps = remediationStepSources(body);
|
|
for (const id of blockerIds) {
|
|
if (!steps.has(id)) {
|
|
const issueObj = issue(
|
|
'REVIEW_MISSING_REMEDIATION_STEP',
|
|
`BLOCKER ${id} has no "### Step R<n>" with "Source finding: ${id}" under ## Remediation Steps`,
|
|
'Write one numbered remediation step per BLOCKER (Handover 6).',
|
|
);
|
|
if (strict) errors.push(issueObj);
|
|
else warnings.push(issueObj);
|
|
}
|
|
}
|
|
}
|
|
|
|
// 1.1+: what the coordinator set aside is listed, never left out (ordre 5).
|
|
if (atLeast11 && !/^##\s+Declined to Judge\b/m.test(body)) {
|
|
const issueObj = issue('REVIEW_MISSING_SECTION', 'Required body section missing: ## Declined to Judge (review_version ≥ 1.1)');
|
|
if (strict) errors.push(issueObj);
|
|
else warnings.push(issueObj);
|
|
}
|
|
|
|
// 1.2+: every new field is optional; a malformed one present is an error
|
|
// (strict) or a warning (soft). A 1.1 file is read as before (N-1 window).
|
|
const atLeast12 = v && (Number(v[1]) > 1 || (Number(v[1]) === 1 && Number(v[2]) >= 2));
|
|
if (atLeast12) {
|
|
for (const issueObj of review12Issues(fm, body)) {
|
|
if (strict) errors.push(issueObj);
|
|
else warnings.push(issueObj);
|
|
}
|
|
}
|
|
|
|
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 (isMain(import.meta.url)) {
|
|
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);
|
|
}
|