@pareto4/pp-core 1.11.1 → 1.12.0

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

@@ -0,0 +1,390 @@
+"use strict";
+/**
+ * `pp-tools discovery element-sweep [--check]` — the prototype element sweep.
+ *
+ * Lists every functional element on every prototype page, so none can be skipped when deciding
+ * whether it must become a requirement. `--check` asserts `_sweep.md` decides each one exactly once.
+ * Output is content-free: pages, tags, element ids and requirement IDs, never element text.
+ */
+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;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const rollup = require("./discovery-rollup.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const table = require("./discovery-table.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISCOVERY_DIR = node_path_1.default.join('.planning', 'discovery');
+const PROTOTYPE_DIR = 'prototype';
+const SWEEP_FILE = '_sweep.md';
+const REQUIREMENTS_FILE = '_requirements.md';
+const ELEMENT_SWEEP_FAILED = ERROR_REASON.DISCOVERY_ELEMENT_SWEEP_FAILED;
+const SWEEP_USAGE = 'Usage: pp-tools discovery element-sweep [--check]';
+const OUTCOMES = Object.freeze(['covered', 'requirement', 'ui', 'drop']);
+const FUNCTIONAL_TAGS = new Set([
+    'a', 'button', 'input', 'select', 'textarea', 'form', 'table', 'th', 'dialog', 'details',
+    'summary', 'img', 'svg', 'canvas', 'video', 'progress', 'meter', 'output',
+]);
+const FUNCTIONAL_ROLES = new Set([
+    'button', 'link', 'tab', 'tablist', 'switch', 'checkbox', 'radio', 'alert', 'status', 'dialog',
+    'menu', 'menuitem', 'progressbar', 'slider', 'grid', 'listbox', 'option', 'combobox', 'img',
+]);
+const VOID_TAGS = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr',
+]);
+const RAW_TEXT_TAGS = new Set(['script', 'style', 'noscript']);
+const ID_RE = /^[A-Za-z][A-Za-z0-9_:.-]{0,79}$/;
+const REQ_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const DECISION_RE = /^D-\d{2}-\d+$/;
+const ELEMENT_RE = /^(\*|[A-Za-z0-9_.-]+\.html?)#([A-Za-z][A-Za-z0-9_:.-]{0,79})$/;
+const ROUND_RE = /^## Sweep (\d{1,2}) — \d{4}-\d{2}-\d{2} — .+$/;
+const TABLE_HEADER = ['Element', 'Outcome', 'Reference'];
+// ─── HTML scanning ────────────────────────────────────────────────────────────
+function lineAt(text, index) {
+    let n = 1;
+    for (let i = 0; i < index; i += 1)
+        if (text.charCodeAt(i) === 10)
+            n += 1;
+    return n;
+}
+function parseAttrs(src) {
+    const attrs = new Map();
+    const re = /([^\s=/>"']+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s>]+))?/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const raw = m[2] ?? '';
+        const value = raw.startsWith('"') || raw.startsWith("'") ? raw.slice(1, -1) : raw;
+        attrs.set(m[1].toLowerCase(), value);
+    }
+    return attrs;
+}
+function isFunctional(tag, attrs) {
+    if (attrs.has('data-req'))
+        return true;
+    if (tag === 'input' && (attrs.get('type') || '').toLowerCase() === 'hidden')
+        return false;
+    if (FUNCTIONAL_TAGS.has(tag) || tag.includes('-'))
+        return true;
+    const role = (attrs.get('role') || '').toLowerCase();
+    return FUNCTIONAL_ROLES.has(role);
+}
+function screenFrom(tag, attrs) {
+    const declared = attrs.get('data-screen');
+    if (declared && /^SCR-\d{2}$/.test(declared))
+        return declared;
+    const tpl = tag === 'template' ? /^scr-(\d{2})$/i.exec(attrs.get('id') || '') : null;
+    return tpl ? `SCR-${tpl[1]}` : null;
+}
+function reqIdsOf(value) {
+    const cut = value.indexOf(' · ');
+    if (cut <= 0)
+        return null;
+    const ids = value.slice(0, cut).split(',').map((s) => s.trim());
+    return ids.every((id) => REQ_ID_RE.test(id)) ? ids : null;
+}
+/** Walk one page's tags, tracking the enclosing screen; script and style bodies are skipped. */
+function scanPage(page, html, violations) {
+    const text = html.replace(/<!--[\s\S]*?-->/g, (c) => c.replace(/[^\n]/g, ' '));
+    const stack = [];
+    const found = [];
+    const tagRe = /<(\/?)([A-Za-z][A-Za-z0-9-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/g;
+    let m;
+    while ((m = tagRe.exec(text)) !== null) {
+        const closing = m[1] === '/';
+        const tag = m[2].toLowerCase();
+        if (closing) {
+            const at = stack.map((s) => s.tag).lastIndexOf(tag);
+            if (at !== -1)
+                stack.length = at;
+            continue;
+        }
+        const attrs = parseAttrs(m[3]);
+        const parentScreen = stack.length ? stack[stack.length - 1].screen : null;
+        const screen = screenFrom(tag, attrs) ?? parentScreen;
+        const line = lineAt(text, m.index);
+        if (isFunctional(tag, attrs)) {
+            const id = attrs.get('id') ?? null;
+            let reqs = [];
+            if (attrs.has('data-req')) {
+                const parsed = reqIdsOf(attrs.get('data-req') || '');
+                if (parsed === null)
+                    violations.push({ artifact: `${PROTOTYPE_DIR}/${page}`, reason: 'bad_tag', line, tag });
+                else
+                    reqs = parsed;
+            }
+            if (id === null)
+                violations.push({ artifact: `${PROTOTYPE_DIR}/${page}`, reason: 'element_without_id', line, tag });
+            else if (!ID_RE.test(id))
+                violations.push({ artifact: `${PROTOTYPE_DIR}/${page}`, reason: 'bad_element_id', line, tag });
+            else
+                found.push({ id, tag, screen, reqs, line });
+        }
+        // A script holding a template (`text/x-template` and kin) is markup the kit renders; sweep it.
+        const scriptType = tag === 'script' ? (attrs.get('type') || '').toLowerCase() : '';
+        const isTemplate = tag === 'script' && scriptType !== '' && !/javascript|ecmascript|^module$|json/.test(scriptType);
+        if (RAW_TEXT_TAGS.has(tag) && !isTemplate) {
+            const end = text.toLowerCase().indexOf(`</${tag}`, tagRe.lastIndex);
+            tagRe.lastIndex = end === -1 ? text.length : end;
+            continue;
+        }
+        if (!VOID_TAGS.has(tag) && !m[3].trim().endsWith('/'))
+            stack.push({ tag, screen });
+    }
+    return found;
+}
+/** The current prototype's pages: the top level only, since earlier versions are archived in subfolders. */
+function listPages(dir) {
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((e) => e.isFile() && /\.html?$/i.test(e.name)).map((e) => e.name).sort();
+}
+/** Every functional element across the prototype; an id on several pages is one shared element. */
+function collectElements(protoDir, violations) {
+    const pages = listPages(protoDir);
+    const byId = new Map();
+    for (const page of pages) {
+        let html = '';
+        try {
+            html = node_fs_1.default.readFileSync(node_path_1.default.join(protoDir, page), 'utf-8');
+        }
+        catch {
+            violations.push({ artifact: `${PROTOTYPE_DIR}/${page}`, reason: 'artifact_unreadable' });
+            continue;
+        }
+        const seen = new Set();
+        for (const el of scanPage(page, html, violations)) {
+            if (seen.has(el.id)) {
+                violations.push({ artifact: `${PROTOTYPE_DIR}/${page}`, reason: 'duplicate_element_id', line: el.line, id: el.id });
+                continue;
+            }
+            seen.add(el.id);
+            const entry = byId.get(el.id);
+            if (entry) {
+                entry.pages.push(page);
+                el.reqs.forEach((r) => entry.reqs.add(r));
+                if (entry.screen !== el.screen)
+                    entry.screen = null;
+            }
+            else {
+                byId.set(el.id, { pages: [page], tag: el.tag, screen: el.screen, reqs: new Set(el.reqs) });
+            }
+        }
+    }
+    const elements = [...byId.entries()].map(([id, e]) => ({
+        element: `${e.pages.length > 1 ? '*' : e.pages[0]}#${id}`,
+        pages: e.pages,
+        tag: e.tag,
+        screen: e.screen,
+        reqs: [...e.reqs].sort(),
+    }));
+    elements.sort((a, b) => (a.element < b.element ? -1 : a.element > b.element ? 1 : 0));
+    return { pages: pages.length, elements };
+}
+// ─── _sweep.md ────────────────────────────────────────────────────────────────
+/** The rows of the highest-numbered round; every round's heading and sequence is checked. */
+function parseSweep(content, violations) {
+    const lines = content.split(/\r?\n/);
+    const rounds = [];
+    let current = null;
+    lines.forEach((raw, i) => {
+        const line = raw.trim();
+        if (line.startsWith('## ')) {
+            const m = ROUND_RE.exec(line);
+            if (!m) {
+                violations.push({ artifact: SWEEP_FILE, reason: 'bad_round_heading', line: i + 1 });
+                current = null;
+                return;
+            }
+            current = { n: Number(m[1]), rows: [] };
+            rounds.push(current);
+            return;
+        }
+        if (!current || !line.startsWith('|') || table.SEPARATOR_ROW_RE.test(line))
+            return;
+        const cells = table.splitTableCells(line);
+        if (cells.join('|') === TABLE_HEADER.join('|'))
+            return;
+        if (cells.length !== 3) {
+            violations.push({ artifact: SWEEP_FILE, reason: 'bad_row', line: i + 1 });
+            return;
+        }
+        current.rows.push({
+            element: cells[0],
+            outcome: cells[1],
+            refs: cells[2].split(',').map((s) => s.trim()).filter(Boolean),
+            line: i + 1,
+        });
+    });
+    const numbers = rounds.map((r) => r.n);
+    const max = table.boundedSequenceMax(numbers);
+    if (max === null) {
+        violations.push({ artifact: SWEEP_FILE, reason: 'sequence_gap' });
+    }
+    else {
+        for (let n = 1; n <= max; n += 1) {
+            const count = numbers.filter((x) => x === n).length;
+            if (count === 0)
+                violations.push({ artifact: SWEEP_FILE, reason: 'sequence_gap', round: n });
+            if (count > 1)
+                violations.push({ artifact: SWEEP_FILE, reason: 'duplicate_round', round: n });
+        }
+    }
+    if (rounds.length === 0)
+        return { round: null, rows: [] };
+    const latest = rounds.reduce((a, b) => (b.n > a.n ? b : a));
+    return { round: latest.n, rows: latest.rows };
+}
+function loadRequirements(dir, violations) {
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(node_path_1.default.join(dir, REQUIREMENTS_FILE), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const parsed = rollup.parseRequirementsArtifact(content);
+    if (!parsed.ok) {
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+        return null;
+    }
+    return new Map(parsed.rows.map((r) => [r.id, r.disposition]));
+}
+function checkRows(rows, elements, reqs, violations) {
+    const byElement = new Map(elements.map((e) => [e.element, e]));
+    const decided = new Set();
+    for (const row of rows) {
+        const at = { artifact: SWEEP_FILE, line: row.line };
+        if (!ELEMENT_RE.test(row.element)) {
+            violations.push({ ...at, reason: 'bad_element' });
+            continue;
+        }
+        const el = byElement.get(row.element);
+        if (!el) {
+            violations.push({ ...at, reason: 'stale_element', element: row.element });
+            continue;
+        }
+        if (decided.has(row.element)) {
+            violations.push({ ...at, reason: 'duplicate_element', element: row.element });
+            continue;
+        }
+        decided.add(row.element);
+        if (!OUTCOMES.includes(row.outcome)) {
+            violations.push({ ...at, reason: 'bad_outcome', element: row.element });
+            continue;
+        }
+        if (row.refs.length === 0) {
+            violations.push({ ...at, reason: 'missing_reference', element: row.element });
+            continue;
+        }
+        if (row.outcome === 'ui' || row.outcome === 'drop') {
+            if (row.refs.length !== 1 || !DECISION_RE.test(row.refs[0]))
+                violations.push({ ...at, reason: 'bad_reference', element: row.element });
+            continue;
+        }
+        for (const id of row.refs) {
+            if (!REQ_ID_RE.test(id)) {
+                violations.push({ ...at, reason: 'bad_reference', element: row.element });
+                continue;
+            }
+            const disposition = reqs?.get(id);
+            if (reqs && disposition === undefined)
+                violations.push({ ...at, reason: 'unknown_requirement', element: row.element, id });
+            else if (disposition && disposition.startsWith('Dropped'))
+                violations.push({ ...at, reason: 'dropped_requirement', element: row.element, id });
+            if (!el.reqs.includes(id))
+                violations.push({ ...at, reason: 'reference_not_tagged', element: row.element, id });
+        }
+    }
+    return elements.map((e) => e.element).filter((e) => !decided.has(e));
+}
+// ─── Entry points ─────────────────────────────────────────────────────────────
+function runElementSweep(cwd, check) {
+    const dir = node_path_1.default.join(cwd, DISCOVERY_DIR);
+    const protoDir = node_path_1.default.join(dir, PROTOTYPE_DIR);
+    const violations = [];
+    if (!node_fs_1.default.existsSync(protoDir)) {
+        return { ok: true, pages: 0, elements: [], undecided: [], round: null, violations };
+    }
+    const { pages, elements } = collectElements(protoDir, violations);
+    const reqs = loadRequirements(dir, violations);
+    if (reqs) {
+        for (const el of elements) {
+            for (const id of el.reqs) {
+                if (!reqs.has(id))
+                    violations.push({ artifact: PROTOTYPE_DIR, reason: 'unknown_requirement', element: el.element, id });
+            }
+        }
+    }
+    let undecided = [];
+    let round = null;
+    if (check && pages > 0) {
+        let content = null;
+        try {
+            content = node_fs_1.default.readFileSync(node_path_1.default.join(dir, SWEEP_FILE), 'utf-8');
+        }
+        catch {
+            violations.push({ artifact: SWEEP_FILE, reason: 'sweep_missing' });
+        }
+        if (content !== null) {
+            const parsed = parseSweep(content, violations);
+            round = parsed.round;
+            if (round === null)
+                violations.push({ artifact: SWEEP_FILE, reason: 'no_round' });
+            undecided = checkRows(parsed.rows, elements, reqs, violations);
+        }
+        else {
+            undecided = elements.map((e) => e.element);
+        }
+    }
+    return { ok: violations.length === 0 && undecided.length === 0, pages, elements, undecided, round, violations };
+}
+function formatViolation(v) {
+    const where = v.line === undefined ? v.artifact : `${v.artifact}:${v.line}`;
+    const detail = [v.element, v.tag && `<${v.tag}>`, v.id, v.round !== undefined && `round ${v.round}`].filter(Boolean).join(', ');
+    return detail ? `  ${where}: ${v.reason} (${detail})` : `  ${where}: ${v.reason}`;
+}
+function cmdDiscoveryElementSweep(cwd, args, raw) {
+    const rest = args.slice(2);
+    if (rest.some((a) => a !== '--check')) {
+        error(SWEEP_USAGE, ERROR_REASON.USAGE);
+        return; // unreachable — error() exits
+    }
+    const check = rest.includes('--check');
+    const result = runElementSweep(cwd, check);
+    const payload = {
+        ok: result.ok,
+        pages: result.pages,
+        elements: result.elements,
+        round: result.round,
+        undecided: result.undecided,
+        violations: result.violations.length,
+    };
+    if (!result.ok) {
+        output(payload, raw);
+        const lines = result.violations.map(formatViolation);
+        result.undecided.forEach((e) => lines.push(`  ${SWEEP_FILE}: undecided_element (${e})`));
+        error(`discovery element-sweep: ${lines.length} fault(s):\n${lines.join('\n')}`, ELEMENT_SWEEP_FAILED);
+        return; // unreachable — error() exits
+    }
+    output(payload, raw);
+}
+module.exports = {
+    OUTCOMES,
+    SWEEP_FILE,
+    ELEMENT_SWEEP_FAILED,
+    scanPage,
+    collectElements,
+    parseSweep,
+    runElementSweep,
+    cmdDiscoveryElementSweep,
+};

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

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Shared markdown-table primitives for the discovery engines (discovery-v2
+ * Phase 4, D-60).
+ *
+ * This is a LEAF: it imports nothing but what TypeScript gives it, has no
+ * `node:` dependencies of its own, and names no artifact, ID family or reason
+ * code. It holds the structural primitives BOTH register engines need: turning
+ * one markdown pipe-table line into cells, recognising a separator row, and
+ * taking the bounded maximum of a parsed sequence.
+ *
+ * The charter was widened from "table primitives" to "register-structure
+ * primitives" deliberately, to close AR-04-02. `boundedSequenceMax` had lived
+ * privately in `discovery-screens.cts`, so the sibling engine kept its own
+ * unbounded `Math.max(...seqs)` and the two drifted the moment the screens
+ * engine was hardened. A bound that exists in two places is two things to
+ * maintain and one of them is always the stale one; there is now exactly one.
+ *
+ * Consumers: `discovery-research-track.cts` (which owned `splitRegisterCells`
+ * before this module existed) and `discovery-screens.cts`. Both read artifacts
+ * with declared FREE-TEXT cells — `Item` and `Data to obtain` for the research
+ * track; `Purpose`, the deferral reason and the feedback text for the screen
+ * inventory — and free text contains pipes.
+ *
+ * `discovery-rollup.cts` deliberately keeps its own naive `splitCells` and its
+ * own separator constant. Re-pointing a fail-loud parser at a different
+ * splitter is a behaviour change to the `_requirements.md` grammar — an author
+ * whose row today fails to parse would start parsing, or vice versa — and no
+ * Phase 4 decision authorises that. The duplication is the conservative half of
+ * the trade the phase deliberately made: share the splitter, leave both
+ * existing row collectors and rollup's separator constant exactly where they
+ * are. See discovery-v2 Phase 4 (D-60) and `04-PATTERNS.md`.
+ */
+/**
+ * Split a pipe-table line into trimmed cells (outer pipes stripped), honouring
+ * the markdown `\|` escape.
+ *
+ * Moved verbatim in behaviour from `discovery-research-track.cts`'s
+ * `splitRegisterCells`. A naive `.split('|')` shifts every subsequent column
+ * once a free-text cell contains a pipe, landing prose in an enum slot where it
+ * is both echoed and reported as a cascade of false faults (`03-REVIEW.md`
+ * § CR-02). The correctly-escaped `\|` is the author's documented workaround.
+ *
+ * Regex rationale (T-03-02 discipline, accepted at AR-03-02 on exactly this
+ * shape): the lookbehind is FIXED-WIDTH (one character), quantifier-free and
+ * alternation-free, and it is applied to a SINGLE already-split line — never
+ * unanchored across whole-file untrusted content. It cannot backtrack
+ * catastrophically, so it adds no denial-of-service surface.
+ */
+function splitTableCells(line) {
+    const trimmed = line.trim().replace(/^\|/, '').replace(/(?<!\\)\|$/, '');
+    return trimmed.split(/(?<!\\)\|/).map(c => c.replace(/\\\|/g, '|').trim());
+}
+/**
+ * A markdown table separator row (`|----|----|`, alignment colons allowed).
+ *
+ * The pattern is copied from `discovery-rollup.cts`; rollup's own constant is
+ * NOT re-pointed at this one, for the reason given in the module comment above.
+ */
+const SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
+/**
+ * The widest span a sequence check will ever walk. Every discovery ID family is
+ * two digits, so a span beyond this is not a real inventory — it is a malformed
+ * number that reached the sequence loop.
+ */
+const MAX_SEQUENCE_SPAN = 99;
+/**
+ * The highest number in `seqs`, or `null` when it exceeds `MAX_SEQUENCE_SPAN`.
+ *
+ * Two separate hazards are closed here, deliberately in ONE place that every
+ * sequence check in both engines calls, so neither hazard can be repaired for
+ * one register family and left open for another:
+ *
+ *   - `Math.max(...seqs)` spreads the array into an argument list and throws
+ *     `RangeError: Maximum call stack size exceeded` on a few hundred thousand
+ *     entries. The `reduce` has no such limit.
+ *   - Every caller's gap loop allocates one violation per MISSING number, so an
+ *     unbounded max turns one mistyped heading into an out-of-memory abort. The
+ *     ceiling is enforced HERE rather than only in the callers' grammars, so a
+ *     later widening of any of those regexes cannot silently re-open the hole.
+ *
+ * EXPORTED SO IT CAN BE FALSIFIED. Both hazards are secondary floors: the
+ * primary guards are the two-digit ID grammars, which make the `null` arm
+ * unreachable end to end. While this fold was private, neutering its ceiling
+ * and restoring the spread each left the whole suite green (04-SECURITY M4/M5)
+ * — real in the code, invisible to the suite. Exporting it is what gives the
+ * pins something to reach.
+ */
+function boundedSequenceMax(seqs) {
+    const max = seqs.reduce((a, b) => (b > a ? b : a), 0);
+    return max > MAX_SEQUENCE_SPAN ? null : max;
+}
+module.exports = {
+    splitTableCells,
+    SEPARATOR_ROW_RE,
+    MAX_SEQUENCE_SPAN,
+    boundedSequenceMax,
+};