@pareto4/pp-core 1.13.0 → 1.18.0

package/pp-core/bin/lib/vault-standards-review.cjs

@@ -0,0 +1,293 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.deriveStandardsReview = deriveStandardsReview;
+exports.formatReviewCounts = formatReviewCounts;
+exports.validateReviewArtifact = validateReviewArtifact;
+/**
+ * src/vault-standards-review.cts — the derived half of `/pp-vault-review`
+ * (FORK-ONLY, the standards-only vault).
+ *
+ * `/pp-vault-review` reviews a completed phase against the client vault's
+ * standards documents: one verdict per document that governed the phase
+ * (PASS / FAIL / N-A / INCONCLUSIVE), judged by the `pp-vault-reviewer` agent.
+ * This module gives that agent its facts and checks the artifact it writes;
+ * it judges nothing itself. It REPORTS and never gates: no envelope here has a
+ * `block` key, and no capability declares `check vault-review` as a gate.
+ *
+ * `deriveStandardsReview` reads, for one phase:
+ *   - every PLAN's `<vault_standards>` block: which INDEX documents governed
+ *     which plan, and why;
+ *   - every SUMMARY's `## Standards Consulted` section: whether each document
+ *     was read, and the plan's commit anchors;
+ *   - per plan, the commit range those anchors bound (falling back to the
+ *     directory's recorded start, as the seal does) and the source files
+ *     changed in it (planning files excluded);
+ *   - per document, where the cached copy is, so the agent can read it.
+ * It never fetches and never writes. Its only spawns are bounded, read-only
+ * git queries through `execGitLocal`.
+ *
+ * `validateReviewArtifact` checks the `{padded}-VAULT-REVIEW.md` the agent
+ * wrote against the derivation: every governing document appears exactly once
+ * in the verdict table, each verdict is one of the four, a non-PASS verdict
+ * states its reason, and the counts line agrees with the table.
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/vault-standards-review.cjs`.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultStandardsLeaf = require("./vault-standards.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultSeal = require("./vault-seal.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultIndexLeaf = require("./vault-index.cjs");
+// ─── Types ───────────────────────────────────────────────────────────────────
+/** The four verdicts, in the order the counts line states them. */
+exports.REVIEW_VERDICTS = Object.freeze(['PASS', 'FAIL', 'N-A', 'INCONCLUSIVE']);
+/** The artifact's file-name suffix and frontmatter marker. */
+exports.REVIEW_ARTIFACT_SUFFIX = '-VAULT-REVIEW.md';
+exports.REVIEW_ARTIFACT_MARKER = 'artifact: vault-review';
+/** The verdict table's heading; the validator finds the table under it. */
+exports.REVIEW_VERDICTS_HEADING = '## Standard Verdicts';
+/** How many changed files one plan lists before it only counts. */
+exports.REVIEW_FILES_CAP = 200;
+/** Bound on a git query a review makes. */
+const REVIEW_GIT_TIMEOUT_MS = 30_000;
+// ─── Derivation ──────────────────────────────────────────────────────────────
+const PLAN_RE = /(^|-)PLAN\.md$/;
+const SUMMARY_RE = /(^|-)SUMMARY\.md$/;
+function readBounded(abs) {
+    try {
+        const st = node_fs_1.default.statSync(abs);
+        if (!st.isFile() || st.size > vaultSeal.TRACE_ARTIFACT_BYTE_CAP)
+            return null;
+        return node_fs_1.default.readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function consultedText(entry, hasSummary) {
+    if (!hasSummary)
+        return 'no summary';
+    if (entry === undefined)
+        return 'unfilled';
+    if (entry.status === 'read')
+        return vaultStandardsLeaf.STANDARDS_CONSULTED_READ;
+    if (entry.status === 'not-read')
+        return `${vaultStandardsLeaf.STANDARDS_CONSULTED_NOT_READ}${entry.reason ?? ''}`.trim();
+    return 'unfilled';
+}
+/**
+ * Derive the review's facts for one phase. Never throws: every fault is a
+ * status or a gap. Inert (with a statement) when the project has no
+ * `.platform-bindings.json` or the vault is off.
+ */
+function deriveStandardsReview(root, cwd, positional, opts = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const vault = require('./vault.cjs');
+    if (!vault.hasPlatformBindings(root) || !vault.isVaultGateActive(cwd)) {
+        return {
+            status: 'inert',
+            statement: 'The client vault is off for this project, so there are no standards to review against.',
+        };
+    }
+    if (positional === undefined || positional === '') {
+        return {
+            status: 'no-argument',
+            statement: 'No phase was given. Re-run with the phase directory or the phase number.',
+        };
+    }
+    if (positional.startsWith('--')) {
+        return { status: 'usage', statement: 'The phase must come first: check vault-review <phase-dir|phase-number> [--raw].' };
+    }
+    const phase = vault.resolveTracePhaseDir(root, cwd, positional);
+    if (!phase) {
+        return {
+            status: 'unresolved',
+            statement: 'That argument is not a phase directory inside the project or a phase number the locator resolves.',
+        };
+    }
+    const exec = opts._exec ?? shell_command_projection_cjs_1.execGitLocal;
+    const gaps = [];
+    let names = [];
+    try {
+        names = node_fs_1.default.readdirSync(phase.abs).sort();
+    }
+    catch {
+        gaps.push(`the phase directory ${phase.rel} could not be listed`);
+    }
+    const summaries = new Map();
+    for (const name of names.filter((n) => SUMMARY_RE.test(n))) {
+        const text = readBounded(node_path_1.default.join(phase.abs, name));
+        if (text === null) {
+            gaps.push(`${name} could not be read (missing, unreadable or over the size cap)`);
+            continue;
+        }
+        const section = vaultStandardsLeaf.parseConsultedSection(text, { artifact: name });
+        if (section.present && section.planId !== null && !summaries.has(section.planId)) {
+            summaries.set(section.planId, { name, section, text });
+        }
+    }
+    const cacheDir = vault.resolveVaultCacheDir(cwd).dir;
+    const isAncestor = vaultSeal.sealIsAncestorVia(shell_command_projection_cjs_1.execGitLocal, root);
+    const plans = [];
+    const documents = new Map();
+    for (const name of names.filter((n) => PLAN_RE.test(n))) {
+        const text = readBounded(node_path_1.default.join(phase.abs, name));
+        if (text === null) {
+            gaps.push(`${name} could not be read (missing, unreadable or over the size cap)`);
+            continue;
+        }
+        const parsed = vaultStandardsLeaf.parseStandardsBlock(text, { artifact: name });
+        const record = parsed.record;
+        if (!parsed.present || record === null) {
+            gaps.push(`${name} carries no readable <vault_standards> block, so the documents that governed it are unknown`);
+            continue;
+        }
+        const summary = summaries.get(record.planId);
+        let range = null;
+        let files = [];
+        let filesTruncated = false;
+        if (summary !== undefined) {
+            const anchors = vaultSeal.resolveRecordAnchors(summary.text, vaultSeal.RECORDED_ARTIFACT_KIND.STANDARDS_CONSULTED, phase.abs, { isAncestor });
+            if (anchors.end !== undefined) {
+                range = { start: anchors.start ?? null, end: anchors.end };
+                if (anchors.start !== undefined) {
+                    const diff = exec(['diff', '--name-only', '-z', '--no-renames', anchors.start, anchors.end], { cwd: root, timeout: REVIEW_GIT_TIMEOUT_MS });
+                    if (diff.exitCode === 0) {
+                        const all = diff.stdout.split('\0').filter((p) => p !== '' && !vaultSeal.isNonSourcePath(p));
+                        filesTruncated = all.length > exports.REVIEW_FILES_CAP;
+                        files = all.slice(0, exports.REVIEW_FILES_CAP);
+                    }
+                    else {
+                        gaps.push(`the files changed by plan ${record.planId} could not be listed from its anchors`);
+                    }
+                }
+                else {
+                    gaps.push(`plan ${record.planId} records an end anchor but no start, so its changed files are unknown`);
+                }
+            }
+            else {
+                gaps.push(`plan ${record.planId}'s Standards Consulted section carries no anchor, so its commit range is unknown`);
+            }
+        }
+        else {
+            gaps.push(`plan ${record.planId} has no SUMMARY with a Standards Consulted section`);
+        }
+        plans.push({
+            planId: record.planId,
+            plan: `${phase.rel}/${name}`,
+            summary: summary === undefined ? null : `${phase.rel}/${summary.name}`,
+            range,
+            files,
+            filesTruncated,
+            degraded: record.degraded === null ? null : `${record.degraded.kind}: ${record.degraded.reason}`,
+        });
+        for (const doc of record.documents) {
+            let entry = documents.get(doc.path);
+            if (entry === undefined) {
+                const abs = node_path_1.default.join(cacheDir, ...doc.path.split('/'));
+                entry = { path: doc.path, cachePath: node_fs_1.default.existsSync(abs) ? abs : null, governed: [] };
+                if (entry.cachePath === null)
+                    gaps.push(`${vaultIndexLeaf.displayVaultPath(doc.path)} is not in the vault cache; fetch the vault to judge it`);
+                documents.set(doc.path, entry);
+            }
+            entry.governed.push({
+                planId: record.planId,
+                reason: doc.reason,
+                consulted: consultedText(summary?.section.entries.find((e) => e.path === doc.path), summary !== undefined),
+            });
+        }
+    }
+    if (plans.length === 0 || documents.size === 0) {
+        return {
+            status: 'no-records',
+            statement: plans.length === 0
+                ? `No plan in ${phase.rel} carries a standards record, so there is nothing to review.`
+                : `No plan in ${phase.rel} was governed by a standards document, so there is nothing to review.`,
+            phaseDir: phase.rel,
+            plans,
+            documents: [],
+            gaps,
+        };
+    }
+    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps };
+}
+/** The counts line, in verdict order: `p PASS · f FAIL · n N-A · i INCONCLUSIVE (of N documents)`. */
+function formatReviewCounts(counts) {
+    const total = exports.REVIEW_VERDICTS.reduce((n, v) => n + counts[v], 0);
+    return `${exports.REVIEW_VERDICTS.map((v) => `${counts[v]} ${v}`).join(' · ')} (of ${total} document${total === 1 ? '' : 's'})`;
+}
+/**
+ * Check a review artifact against the derivation. The verdict table is the
+ * first markdown table under `## Standard Verdicts`; its first column holds the
+ * document path in backticks, the second the verdict, the third the reason
+ * or evidence. Never throws; an empty list means the artifact is well formed.
+ */
+function validateReviewArtifact(text, documents) {
+    const problems = [];
+    if (!text.includes(exports.REVIEW_ARTIFACT_MARKER)) {
+        problems.push({ kind: 'marker_missing', detail: `the frontmatter does not carry "${exports.REVIEW_ARTIFACT_MARKER}"` });
+    }
+    const lines = text.split(/\r?\n/);
+    const at = lines.findIndex((l) => l.trim() === exports.REVIEW_VERDICTS_HEADING);
+    const rows = [];
+    if (at === -1) {
+        problems.push({ kind: 'table_missing', detail: `there is no "${exports.REVIEW_VERDICTS_HEADING}" section` });
+    }
+    else {
+        for (let i = at + 1; i < lines.length && !lines[i].startsWith('## '); i += 1) {
+            const line = lines[i].trim();
+            if (!line.startsWith('|'))
+                continue;
+            const cells = line.slice(1, line.endsWith('|') ? -1 : undefined).split('|').map((c) => c.trim());
+            const m = /^`([^`]+)`$/.exec(cells[0] ?? '');
+            if (!m)
+                continue;
+            rows.push({ path: m[1], verdict: cells[1] ?? '', reason: cells[2] ?? '' });
+        }
+        if (rows.length === 0)
+            problems.push({ kind: 'table_missing', detail: 'the verdict table has no document rows' });
+    }
+    const known = new Set(documents.map((d) => d.path));
+    const seen = new Map();
+    for (const row of rows) {
+        seen.set(row.path, (seen.get(row.path) ?? 0) + 1);
+        if (!known.has(row.path))
+            problems.push({ kind: 'document_unknown', detail: `${row.path} did not govern this phase` });
+        if (!exports.REVIEW_VERDICTS.includes(row.verdict)) {
+            problems.push({ kind: 'verdict_invalid', detail: `${row.path} has verdict "${row.verdict}", not one of ${exports.REVIEW_VERDICTS.join(', ')}` });
+        }
+        else if (row.verdict !== 'PASS' && (row.reason === '' || row.reason === '-')) {
+            problems.push({ kind: 'reason_missing', detail: `${row.path} is ${row.verdict} without a stated reason` });
+        }
+    }
+    for (const doc of documents) {
+        const n = seen.get(doc.path) ?? 0;
+        if (n === 0)
+            problems.push({ kind: 'document_missing', detail: `${doc.path} has no verdict` });
+        if (n > 1)
+            problems.push({ kind: 'document_duplicated', detail: `${doc.path} has ${n} verdict rows` });
+    }
+    const counts = { PASS: 0, FAIL: 0, 'N-A': 0, INCONCLUSIVE: 0 };
+    for (const row of rows) {
+        if (exports.REVIEW_VERDICTS.includes(row.verdict))
+            counts[row.verdict] += 1;
+    }
+    const expected = formatReviewCounts(counts);
+    const countsLine = lines.find((l) => /\bPASS · /.test(l));
+    if (countsLine === undefined) {
+        problems.push({ kind: 'counts_missing', detail: `there is no counts line; it should read "${expected}"` });
+    }
+    else if (!countsLine.includes(expected)) {
+        problems.push({ kind: 'counts_mismatch', detail: `the counts line does not match the table; it should read "${expected}"` });
+    }
+    return problems;
+}