@pareto4/pp-core 1.11.1 → 1.12.0

package/pp-core/bin/lib/discovery-rollup.cjs

@@ -0,0 +1,476 @@
+"use strict";
+/**
+ * Discovery requirements rollup engine (discovery-v2 Phase 1, REQM-04, D-05..D-08).
+ *
+ * Parses the per-engagement `.planning/discovery/_requirements.md` artifact
+ * (grammar single-source: pp-core/references/discovery-id-conventions.md) and
+ * computes per-prefix × per-disposition totals with explicit ID enumeration
+ * per bucket, plus the per-prefix next mintable ID (D-12: derived, never stored).
+ *
+ * Phase 2 (REQM-05, D-26/D-27): validates the Provenance cell — origin
+ * (accession cite / session ref / decision ID) plus an optional closed-verb
+ * relation suffix (`refines` / `absorbed into`) whose target requirement ID
+ * must exist in the same table. Grammar single-source: same reference file.
+ *
+ * Phase 3 (D-44), extended by Phase 4 (D-50): a Prefix Registry row may not
+ * claim one of the six reserved prefixes (`D-` `A-` `SP-` `DG-` `RS-` `SCR-`)
+ * — they all match the requirement-ID regex, so registering one collides with
+ * the decision / action / sparring / data-gathering / research / screen ID
+ * families. Reserved set single-source: same reference file.
+ *
+ * Fail-loud contract (D-08): any unparseable row, malformed/duplicate ID,
+ * unknown prefix, out-of-enum MoSCoW/Disposition, or strike/disposition
+ * inconsistency is a structured error naming the offending row. There is no
+ * warn-and-skip — a row the parser cannot count is drift by definition.
+ *
+ * The command is read-only (D-06): it emits JSON plus a rendered markdown
+ * totals table; the workflow replaces the `<!-- rollup:auto -->` block with
+ * that output verbatim. `--check` (D-07) recomputes and exits non-zero when
+ * the written block disagrees with the rows.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISPOSITIONS = Object.freeze({ MVP: 'MVP', LATER: 'Later', DROPPED: 'Dropped' });
+const MOSCOW = Object.freeze({ MUST: 'Must', SHOULD: 'Should', COULD: 'Could', WONT: 'Wont' });
+// D-44 (discovery-v2 Phase 3): these six all match the requirement-ID regex, so
+// registering one as a domain prefix collides with the decision/action/research
+// ID families. See references/discovery-id-conventions.md.
+// D-50 (discovery-v2 Phase 4) added `SCR-`: screen IDs are a flat global
+// `SCR-<nn>` sequence, so an engagement registering `SCR-` as a domain prefix
+// would make `SCR-01` ambiguous between the screen inventory and the
+// requirements table.
+const RESERVED_PREFIXES = new Set(['D-', 'A-', 'SP-', 'DG-', 'RS-', 'SCR-']);
+const ROW_ID_RE = /^([A-Z][A-Z0-9]*-)(\d+)$/;
+const DROPPED_RE = /^Dropped \((D-\d{2}-\d+)\)$/;
+const SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
+const ROLLUP_OPEN = '<!-- rollup:auto -->';
+const ROLLUP_CLOSE = '<!-- /rollup:auto -->';
+const REGISTRY_PREFIX_RE = /^[A-Z][A-Z0-9]*-$/;
+const STRIKE_RE = /^~~.+~~$/;
+// Provenance cell grammar (REQM-05, D-26/D-27) — anchored, non-backtracking,
+// applied to already-split single cells (T-01-02 idiom carried forward; the
+// accession locator is bounded to 80 chars, T-02-02). Separator is
+// space + middle dot U+00B7 + space.
+const PROVENANCE_SEP = ' · ';
+const ACCESSION_CITE_RE = /^\[(\d{2})( §[^\]]{1,80})?\]$/;
+const SESSION_REF_RE = /^S\d+$/;
+const PROVENANCE_DECISION_RE = /^D-\d{2}-\d+$/;
+const RELATION_RE = /^(refines|absorbed into) ([A-Z][A-Z0-9]*-\d+)$/;
+const MOSCOW_SET = new Set(Object.values(MOSCOW));
+const REGISTRY_HEADING = '## Prefix Registry';
+const REQUIREMENTS_HEADING = '## Requirements';
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+/** Split a pipe-table line into trimmed cell strings (outer pipes stripped). */
+function splitCells(line) {
+    const trimmed = line.trim();
+    const inner = trimmed.replace(/^\|/, '').replace(/\|$/, '');
+    return inner.split('|').map(c => c.trim());
+}
+/**
+ * Collect the table-row lines belonging to the section under `heading`,
+ * stopping at the next `## ` heading (or, for Requirements, the rollup
+ * marker — defensive; the canonical template puts markers under their own
+ * heading). Returns null when the heading itself is absent.
+ */
+function sectionRows(lines, heading) {
+    const start = lines.findIndex(l => l.trim() === heading);
+    if (start === -1)
+        return null;
+    const rows = [];
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed.startsWith('## ') || trimmed === ROLLUP_OPEN)
+            break;
+        if (!trimmed.includes('|'))
+            continue;
+        // Skip markdown table separator rows and header rows immediately preceding them.
+        if (SEPARATOR_ROW_RE.test(line))
+            continue;
+        if (i + 1 < lines.length && SEPARATOR_ROW_RE.test(lines[i + 1]))
+            continue;
+        rows.push({ line, num: i + 1 });
+    }
+    return rows;
+}
+/**
+ * Parse a `_requirements.md` artifact into registry entries and requirement
+ * rows. Fail-loud (D-08): ALL grammar violations are collected before the
+ * ok:false return — never warn-and-skip.
+ */
+function parseRequirementsArtifact(content) {
+    const errors = [];
+    if (!content || typeof content !== 'string') {
+        return { ok: false, errors: [{ row: 0, cell: '', reason: 'missing_section' }] };
+    }
+    const lines = content.split(/\r?\n/);
+    const registryRows = sectionRows(lines, REGISTRY_HEADING);
+    const requirementRows = sectionRows(lines, REQUIREMENTS_HEADING);
+    if (registryRows === null)
+        errors.push({ row: 0, cell: REGISTRY_HEADING, reason: 'missing_section' });
+    if (requirementRows === null)
+        errors.push({ row: 0, cell: REQUIREMENTS_HEADING, reason: 'missing_section' });
+    if (registryRows === null || requirementRows === null)
+        return { ok: false, errors };
+    const registry = [];
+    // Registered prefixes match ^[A-Z][A-Z0-9]*-$ (validated below), which
+    // excludes __proto__/constructor-shaped keys; lookups still go through a
+    // Set/Map, never a plain {} keyed by parsed content (engine convention).
+    const registeredPrefixes = new Set();
+    for (const { line, num } of registryRows) {
+        const cells = splitCells(line);
+        const prefix = cells[0] ?? '';
+        if (!REGISTRY_PREFIX_RE.test(prefix)) {
+            errors.push({ row: num, cell: prefix, reason: 'bad_registry_row' });
+            continue;
+        }
+        // D-44: ordering is load-bearing — a reserved prefix must never reach
+        // registeredPrefixes, or its requirement rows parse cleanly and only the
+        // registry row errors, which reads confusingly.
+        if (RESERVED_PREFIXES.has(prefix)) {
+            errors.push({ row: num, cell: prefix, reason: 'reserved_prefix' });
+            continue;
+        }
+        registry.push({ prefix, domain: cells[1] ?? '' });
+        registeredPrefixes.add(prefix);
+    }
+    const rows = [];
+    const seenIds = new Set();
+    for (const { line, num } of requirementRows) {
+        const cells = splitCells(line);
+        const idCell = cells[0] ?? '';
+        const reqCell = cells[1] ?? '';
+        const moscowCell = cells[2] ?? '';
+        const dispositionCell = cells[3] ?? '';
+        let rowErrors = 0;
+        // ID chain: grammar → registry membership → uniqueness. First failure
+        // wins for this axis; the row is still checked on the other axes.
+        let prefix = '';
+        let seq = 0;
+        const idMatch = ROW_ID_RE.exec(idCell);
+        if (!idMatch) {
+            errors.push({ row: num, cell: idCell, reason: 'bad_id' });
+            rowErrors += 1;
+        }
+        else if (!registeredPrefixes.has(idMatch[1])) {
+            errors.push({ row: num, cell: idCell, reason: 'unknown_prefix' });
+            rowErrors += 1;
+        }
+        else if (seenIds.has(idCell)) {
+            errors.push({ row: num, cell: idCell, reason: 'duplicate_id' });
+            rowErrors += 1;
+        }
+        else {
+            seenIds.add(idCell);
+            prefix = idMatch[1];
+            seq = parseInt(idMatch[2], 10);
+        }
+        // MoSCoW: closed enum, case-normalized on parse (D-03).
+        const moscow = moscowCell
+            ? moscowCell.charAt(0).toUpperCase() + moscowCell.slice(1).toLowerCase()
+            : '';
+        if (!MOSCOW_SET.has(moscow)) {
+            errors.push({ row: num, cell: moscowCell, reason: 'bad_moscow' });
+            rowErrors += 1;
+        }
+        // Disposition: exactly MVP, Later, or Dropped (D-<ss>-<n>). Bare
+        // `Dropped` without a killing decision ID is an error (D-03, D-04).
+        let disposition = '';
+        let droppedDecisionId = null;
+        if (dispositionCell === DISPOSITIONS.MVP || dispositionCell === DISPOSITIONS.LATER) {
+            disposition = dispositionCell;
+        }
+        else {
+            const dm = DROPPED_RE.exec(dispositionCell);
+            if (dm) {
+                disposition = DISPOSITIONS.DROPPED;
+                droppedDecisionId = dm[1];
+            }
+            else {
+                errors.push({ row: num, cell: dispositionCell, reason: 'bad_disposition' });
+                rowErrors += 1;
+            }
+        }
+        // Strike consistency: ~~...~~ if-and-only-if Dropped (checked only when
+        // the disposition itself parsed — a bad disposition already errored).
+        if (disposition) {
+            const struck = STRIKE_RE.test(reqCell);
+            const dropped = disposition === DISPOSITIONS.DROPPED;
+            if (struck !== dropped) {
+                errors.push({ row: num, cell: reqCell, reason: 'strike_mismatch' });
+                rowErrors += 1;
+            }
+        }
+        // Provenance (REQM-05, D-26): origin plus an optional single relation
+        // suffix, split on the exact ` · ` separator. An empty or unparseable
+        // cell is a structured error — every requirement answers "where did you
+        // come from"; no warn-and-skip (D-08). Header text is not parsed
+        // (positional contract), so pre-rename artifacts whose fifth cells hold
+        // valid decision/session refs keep parsing.
+        const provenanceCell = (cells[4] ?? '').trim();
+        let provenance = null;
+        const parts = provenanceCell.split(PROVENANCE_SEP);
+        if (parts.length > 2 || parts[0] === '') {
+            errors.push({ row: num, cell: provenanceCell, reason: 'bad_provenance' });
+            rowErrors += 1;
+        }
+        else {
+            const origin = parts[0];
+            let kind = null;
+            if (ACCESSION_CITE_RE.test(origin))
+                kind = 'accession';
+            else if (SESSION_REF_RE.test(origin))
+                kind = 'session';
+            else if (PROVENANCE_DECISION_RE.test(origin))
+                kind = 'decision';
+            let relation = null;
+            let relationOk = true;
+            if (parts.length === 2) {
+                const rm = RELATION_RE.exec(parts[1]);
+                if (rm) {
+                    relation = { verb: rm[1] === 'refines' ? 'refines' : 'absorbed into', target: rm[2] };
+                }
+                else {
+                    relationOk = false;
+                }
+            }
+            if (kind === null || !relationOk) {
+                errors.push({ row: num, cell: provenanceCell, reason: 'bad_provenance' });
+                rowErrors += 1;
+            }
+            else {
+                provenance = { origin, kind, relation };
+            }
+        }
+        if (rowErrors === 0 && provenance !== null) {
+            rows.push({
+                id: idCell,
+                prefix,
+                seq,
+                requirement: reqCell,
+                moscow,
+                disposition,
+                droppedDecisionId,
+                provenance,
+                line: num,
+            });
+        }
+    }
+    // Relation-target existence post-pass (D-27): a refines/absorbed-into
+    // target must be an ID present in the same table. Any disposition counts —
+    // existence is the only check.
+    for (const row of rows) {
+        const relation = row.provenance.relation;
+        if (relation && !seenIds.has(relation.target)) {
+            errors.push({
+                row: row.line,
+                cell: `${row.provenance.origin}${PROVENANCE_SEP}${relation.verb} ${relation.target}`,
+                reason: 'unknown_relation_target',
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, registry, rows };
+}
+// ─── Rollup computation ───────────────────────────────────────────────────────
+/**
+ * Bucket parsed rows per registry prefix × disposition. Buckets are keyed in
+ * registry order; IDs sort ascending by numeric sequence. next_id per prefix
+ * is max sequence + 1 (1 for a prefix with zero rows) — D-12: the table IS
+ * the counter.
+ */
+function computeRollup(rows, registry) {
+    const bucketMap = new Map();
+    for (const entry of registry) {
+        bucketMap.set(entry.prefix, { MVP: [], Later: [], Dropped: [] });
+    }
+    for (const row of rows) {
+        let bucket = bucketMap.get(row.prefix);
+        if (!bucket) {
+            // Defensive: parse guarantees registry membership, but keep unknown
+            // prefixes countable rather than silently dropping rows.
+            bucket = { MVP: [], Later: [], Dropped: [] };
+            bucketMap.set(row.prefix, bucket);
+        }
+        if (row.disposition === DISPOSITIONS.MVP)
+            bucket.MVP.push(row);
+        else if (row.disposition === DISPOSITIONS.LATER)
+            bucket.Later.push(row);
+        else
+            bucket.Dropped.push(row);
+    }
+    const counts = {};
+    const nextId = {};
+    const totals = { MVP: 0, Later: 0, Dropped: 0, total: 0 };
+    const bySeq = (a, b) => a.seq - b.seq;
+    for (const [prefix, bucket] of bucketMap) {
+        counts[prefix] = {
+            MVP: bucket.MVP.slice().sort(bySeq).map(r => r.id),
+            Later: bucket.Later.slice().sort(bySeq).map(r => r.id),
+            Dropped: bucket.Dropped.slice().sort(bySeq).map(r => r.id),
+        };
+        totals.MVP += bucket.MVP.length;
+        totals.Later += bucket.Later.length;
+        totals.Dropped += bucket.Dropped.length;
+        const maxSeq = [...bucket.MVP, ...bucket.Later, ...bucket.Dropped]
+            .reduce((max, r) => (r.seq > max ? r.seq : max), 0);
+        nextId[prefix] = maxSeq + 1;
+    }
+    totals.total = totals.MVP + totals.Later + totals.Dropped;
+    return { counts, totals, next_id: nextId };
+}
+// ─── Rendering ────────────────────────────────────────────────────────────────
+function renderCell(ids) {
+    return ids.length > 0 ? `${ids.length} (${ids.join(', ')})` : '0';
+}
+/**
+ * Render the machine-owned totals table (D-06). Deterministic: registry
+ * order, then a bold Total row — the workflow pastes this verbatim between
+ * the rollup:auto markers.
+ */
+function renderRollupTable(rollup) {
+    const lines = [
+        '| Prefix | MVP | Later | Dropped | Total |',
+        '|--------|-----|-------|---------|-------|',
+    ];
+    for (const prefix of Object.keys(rollup.counts)) {
+        const bucket = rollup.counts[prefix];
+        const rowTotal = bucket.MVP.length + bucket.Later.length + bucket.Dropped.length;
+        lines.push(`| ${prefix} | ${renderCell(bucket.MVP)} | ${renderCell(bucket.Later)} | ${renderCell(bucket.Dropped)} | ${rowTotal} |`);
+    }
+    const t = rollup.totals;
+    lines.push(`| **Total** | ${t.MVP} | ${t.Later} | ${t.Dropped} | ${t.total} |`);
+    return lines.join('\n');
+}
+// ─── Check (D-07) ─────────────────────────────────────────────────────────────
+/** Whitespace-normalize for block comparison: trim lines, collapse runs, drop blanks. */
+function normalizeBlock(text) {
+    return text
+        .split(/\r?\n/)
+        .map(l => l.trim().replace(/\s+/g, ' '))
+        .filter(l => l.length > 0)
+        .join('\n');
+}
+function countOccurrences(haystack, needle) {
+    return haystack.split(needle).length - 1;
+}
+/**
+ * Verify the written rollup:auto block against totals recomputed from the
+ * rows (D-07). Missing/duplicated/out-of-order markers and parse failures
+ * are structured failures too — a block that cannot be located or a table
+ * that cannot be counted is drift by definition.
+ */
+function checkRollup(content) {
+    const parsed = parseRequirementsArtifact(content);
+    if (!parsed.ok)
+        return { ok: false, reason: 'parse_error', errors: parsed.errors };
+    const openCount = countOccurrences(content, ROLLUP_OPEN);
+    const closeCount = countOccurrences(content, ROLLUP_CLOSE);
+    if (openCount !== 1 || closeCount !== 1) {
+        return {
+            ok: false,
+            reason: 'rollup_markers',
+            detail: `expected exactly one ${ROLLUP_OPEN} and one ${ROLLUP_CLOSE} (found ${openCount}/${closeCount})`,
+        };
+    }
+    const openIdx = content.indexOf(ROLLUP_OPEN);
+    const closeIdx = content.indexOf(ROLLUP_CLOSE);
+    if (closeIdx < openIdx) {
+        return { ok: false, reason: 'rollup_markers', detail: 'close marker precedes open marker' };
+    }
+    const rollup = computeRollup(parsed.rows, parsed.registry);
+    const expected = normalizeBlock(renderRollupTable(rollup));
+    const actual = normalizeBlock(content.slice(openIdx + ROLLUP_OPEN.length, closeIdx));
+    if (expected !== actual) {
+        return { ok: false, reason: 'rollup_mismatch', expected, actual };
+    }
+    return { ok: true, totals: rollup.totals };
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+function formatRollupErrors(errors) {
+    return errors.map(e => `  row ${e.row}: ${e.reason}${e.cell ? ` (${e.cell})` : ''}`).join('\n');
+}
+/**
+ * CLI adapter for `pp-tools discovery rollup <path> [--check]`.
+ *
+ * Exit semantics (D-06/D-07/D-08): plain mode is the recompute source — it
+ * exits 0 with JSON + rendered table even when the written block is stale,
+ * but fails loud (non-zero) on any parse error. `--check` exits non-zero on
+ * drift, marker problems, or parse errors, via error() which honors
+ * --json-errors.
+ */
+function cmdDiscoveryRollup(cwd, args, raw) {
+    const check = args.includes('--check');
+    for (const a of args.slice(2)) {
+        if (a.startsWith('--') && a !== '--check') {
+            error(`discovery rollup: unknown flag ${a}`, ERROR_REASON.USAGE);
+        }
+    }
+    const target = args.slice(2).find(a => !a.startsWith('--'));
+    if (!target) {
+        error('Usage: pp-tools discovery rollup <path> [--check]', ERROR_REASON.USAGE);
+        return; // unreachable — error() exits
+    }
+    // Path-traversal guard: the resolved target must stay under the project
+    // root (threat T-01-01; mirrors the workstream-inventory guard convention).
+    const root = node_path_1.default.resolve(cwd);
+    const resolved = node_path_1.default.resolve(cwd, target);
+    if (!resolved.startsWith(root + node_path_1.default.sep)) {
+        error('discovery rollup: path escapes project root', ERROR_REASON.USAGE);
+    }
+    let content = '';
+    try {
+        content = node_fs_1.default.readFileSync(resolved, 'utf-8');
+    }
+    catch {
+        error(`discovery rollup: cannot read ${target}`, ERROR_REASON.USAGE);
+    }
+    if (check) {
+        const result = checkRollup(content);
+        if (!result.ok) {
+            if (result.reason === 'parse_error') {
+                error(`discovery rollup --check: parse failed:\n${formatRollupErrors(result.errors)}`, ERROR_REASON.DISCOVERY_ROLLUP_PARSE_FAILED);
+                return; // unreachable — error() exits; return keeps tsc narrowing sound
+            }
+            const detail = result.reason === 'rollup_markers'
+                ? result.detail
+                : `expected:\n${result.expected}\nactual:\n${result.actual}`;
+            error(`discovery rollup --check: ${result.reason}\n${detail}`, ERROR_REASON.DISCOVERY_ROLLUP_MISMATCH);
+            return; // unreachable — error() exits
+        }
+        output({ ok: true, checked: true, totals: result.totals }, raw);
+        return;
+    }
+    const parsed = parseRequirementsArtifact(content);
+    if (!parsed.ok) {
+        error(`discovery rollup: parse failed:\n${formatRollupErrors(parsed.errors)}`, ERROR_REASON.DISCOVERY_ROLLUP_PARSE_FAILED);
+        return; // unreachable — error() exits
+    }
+    const rollup = computeRollup(parsed.rows, parsed.registry);
+    const table = renderRollupTable(rollup);
+    output({
+        ok: true,
+        registry: parsed.registry,
+        counts: rollup.counts,
+        totals: rollup.totals,
+        next_id: rollup.next_id,
+        table,
+    }, raw, table);
+}
+module.exports = {
+    DISPOSITIONS,
+    MOSCOW,
+    parseRequirementsArtifact,
+    computeRollup,
+    renderRollupTable,
+    checkRollup,
+    cmdDiscoveryRollup,
+};