@event4u/agent-config 16.4.0 → 16.5.0

package/dist/scripts/_lib/scan_scope.js

@@ -0,0 +1,105 @@
+/**
+ * Scan-scope assertions — "a gate that read nothing did not pass".
+ *
+ * WHY THIS EXISTS (audit 2026-07-29, `agents/settings/contexts/gates-that-cannot-fail.md`):
+ * ADR-051 moved the source container and a later commit deleted `packages/`.
+ * Fourteen `lint_*`/`check_*` gates kept a hardcoded literal path, and every
+ * one of them treats a missing directory as "nothing to check" — so they exit 0
+ * and print a green checkmark while scanning zero files. Their own output said
+ * so (`0 file(s) scanned`, `0 name(s) checked`, `0 declarer(s)`); nothing ever
+ * asserted on the number.
+ *
+ * Two shapes cover the whole class:
+ *
+ * - **Corpus gates** walk a root and check N units → {@link assertScanned}.
+ *   Zero units is a failure unless the gate declares a justified `allowEmpty`.
+ * - **Watch-list gates** (diff-based, no corpus to count) name specific files
+ *   they guard → {@link assertWatchlistResolves}. A watch list that resolves to
+ *   nothing on disk means the guard is watching phantoms.
+ *
+ * Both throw {@link DeadScopeError}; callers map it to a non-zero exit. The
+ * point is that the failure is LOUD and names the root, so the next path
+ * migration cannot silently disarm a gate again.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+/** Raised when a gate's scope is empty — it cannot have checked anything. */
+export class DeadScopeError extends Error {
+    gate;
+    constructor(gate, message) {
+        super(message);
+        this.name = 'DeadScopeError';
+        this.gate = gate;
+    }
+}
+/**
+ * Assert a corpus gate examined at least one unit.
+ *
+ * @throws {DeadScopeError} when `scanned === 0` and no `allowEmpty` reason is given.
+ */
+export function assertScanned(opts) {
+    if (opts.scanned > 0) {
+        return;
+    }
+    if (opts.allowEmpty !== undefined && opts.allowEmpty.trim() !== '') {
+        return;
+    }
+    const roots = opts.roots.length > 0 ? opts.roots.join(', ') : '(no root declared)';
+    throw new DeadScopeError(opts.gate, `${opts.gate}: scanned 0 ${opts.units} under ${roots} — the scan scope is ` +
+        'dead or the root moved. A gate that read nothing has not passed. ' +
+        'Repoint the root (prefer the shared resolver in _lib/agent_src.ts), ' +
+        'or declare a justified `allowEmpty` reason if an empty corpus is genuinely expected.');
+}
+/**
+ * Assert a corpus gate's scope AND publish the count it just validated.
+ *
+ * The two halves of scope hardening drifted apart in practice: 14 gates emit
+ * the machine-readable `scanned:` line the coverage guard reads, 12 assert
+ * their scope, and only 8 do both. A gate that publishes a number it never
+ * asserted can print `scanned: 0` and exit green; a gate that asserts without
+ * publishing is invisible to `check_gate_coverage`. Splitting the two also
+ * lets the published number drift from the number that was validated — the
+ * invented-count failure that is mechanically undetectable downstream.
+ *
+ * One call closes both: the emitted number is, by construction, the number the
+ * assertion just accepted. Use this for any gate that should also carry a floor
+ * in `src/config/gate-coverage.yml`; plain {@link assertScanned} stays correct
+ * for a gate that only needs its scope guarded.
+ *
+ * The line goes to stdout unconditionally — a count only visible without
+ * `--quiet` is not a count, since CI passes `--quiet` (the `lint_handoffs`
+ * lesson, preserved here so no caller has to rediscover it).
+ */
+export function reportScanned(opts, write = process.stdout.write.bind(process.stdout)) {
+    assertScanned(opts);
+    write(`scanned: ${String(opts.scanned)}\n`);
+}
+/**
+ * Assert a watch-list gate's targets exist on disk, and return the ones that do.
+ *
+ * A diff-based guard has no corpus to count: it compares changed paths against
+ * a fixed list. If that list resolves to nothing, the guard reports "clean"
+ * forever — the exact shape of the `check_safety_floor_untouched` defect, which
+ * announced `4 rules guarded` while guarding none.
+ *
+ * @returns the subset of `candidates` that exist.
+ * @throws {DeadScopeError} when none of them exist.
+ */
+export function assertWatchlistResolves(opts) {
+    const resolved = opts.candidates.filter((rel) => {
+        try {
+            return fs.statSync(path.join(opts.repoRoot, rel)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+    if (resolved.length === 0) {
+        throw new DeadScopeError(opts.gate, `${opts.gate}: none of its ${opts.candidates.length} guarded path(s) exist ` +
+            `under ${opts.repoRoot} — the guard is watching phantoms and can never fire. ` +
+            `Checked: ${opts.candidates.join(', ')}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=scan_scope.js.map

package/dist/scripts/_lib/svg_dom.js

@@ -0,0 +1,284 @@
+/**
+ * svg_dom — a dependency-free XML well-formedness parser, and the tree it
+ * builds.
+ *
+ * Step 3.1 of `road-to-svg-review-followups`, amending step 1.1 of
+ * `road-to-svg-with-a-witness`. Review claim C11: a regex cannot prove nesting
+ * or resolve a reference, and the alternatives were all refused for reasons
+ * that still hold — `package.json`'s runtime dependencies carry no XML parser,
+ * `happy-dom` is dev-only, the three vendored tree-sitter grammars are php,
+ * typescript and javascript, and Playwright is absent in a consumer, so the
+ * browser cannot carry a static layer. The remaining option is to write one,
+ * which is what `lint_design_quality` already does for its own surface.
+ *
+ * WHAT IT IS. One scanner over the bytes, producing every node kind an SVG
+ * carries — elements with their attributes, comments, CDATA sections,
+ * processing instructions, DOCTYPEs and text — each with a line and a column,
+ * assembled into a tree with parent links, plus a list of well-formedness
+ * errors.
+ *
+ * TWO SCANNERS, NOT ONE, and this header used to claim otherwise.
+ * `parseElements` in `svg_rules.ts` is an independent scanner over the same
+ * bytes, so the two CAN disagree about what a file contains — finding 3 of the
+ * third completion review of this change found a case where they did, and the
+ * disagreement produced an error-severity false positive. That one is fixed
+ * where it was (the prolog), but the general claim was false and is not
+ * restored: a reader deciding whether a fix here also lands there must check,
+ * not assume. Merging them is a larger change than the finding asked for and
+ * is not attempted under a remediation.
+ *
+ * WHAT IT IS NOT. Not a validating parser, not namespace-aware beyond keeping
+ * the prefix in the name, and it does not expand entities. It reports that a
+ * file is not well-formed; it does not report which schema it violates.
+ *
+ * WHY A FILE THAT IS NOT WELL-FORMED IS A FINDING RATHER THAN A SKIPPED FILE.
+ * A skipped file reads as a clean one in every count that matters, and the
+ * shape this exists to catch — `<g><path></g></path>` — is exactly the shape a
+ * flat element list cannot see: both tags are present, both are spelled
+ * correctly, and the document is nonetheless not a tree.
+ */
+/** 1-based line and column of an offset. Built once per parse. */
+function positions(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i += 1) {
+        if (content[i] === '\n')
+            starts.push(i + 1);
+    }
+    return (offset) => {
+        // Binary search for the last line start at or before `offset`.
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (starts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return { line: lo + 1, column: offset - starts[lo] + 1 };
+    };
+}
+/**
+ * End of the tag, honouring quoted attribute values that may contain `>`.
+ *
+ * Exported because `svg_rules.parseElements` scans the same bytes and had its
+ * own byte-identical copy — finding 9 of the third completion review, which
+ * also noted that BOTH copies ship in the per-`.svg`-write hook chunk. Two
+ * scanners is a fact this file's header now states plainly; two copies of
+ * their shared primitives is not a consequence of it.
+ */
+export function tagEnd(content, from) {
+    let quote = null;
+    for (let i = from + 1; i < content.length; i += 1) {
+        const ch = content[i];
+        if (quote !== null) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '>')
+            return i;
+    }
+    return -1;
+}
+/** Attributes of one tag, lowercased keys. Shared with `svg_rules` — see `tagEnd`. */
+export function attrsOf(raw) {
+    const attrs = {};
+    const re = /([A-Za-z_:][\w.:-]*)\s*=\s*("([^"]*)"|'([^']*)')/g;
+    let m;
+    while ((m = re.exec(raw)) !== null) {
+        const key = (m[1] ?? '').toLowerCase();
+        const value = m[3] ?? m[4] ?? '';
+        attrs[key] = value.replace(/&amp;/g, '&');
+    }
+    return attrs;
+}
+/**
+ * Parse one document.
+ *
+ * Never throws: a malformed file produces whatever tree could be built plus
+ * the errors that explain it. A parser that threw would make an unparseable
+ * file indistinguishable from a crash, and the caller's job is to REPORT the
+ * file, not to fall over on it.
+ */
+export function parseDocument(content) {
+    const at = positions(content);
+    const roots = [];
+    const elements = [];
+    const errors = [];
+    const stack = [];
+    const make = (kind, start, name = '', value = '', attrs = {}) => {
+        const { line, column } = at(start);
+        return { kind, name, attrs, line, column, start, value, children: [], parent: null };
+    };
+    const append = (node) => {
+        const parent = stack[stack.length - 1];
+        if (parent === undefined) {
+            roots.push(node);
+        }
+        else {
+            node.parent = parent;
+            parent.children.push(node);
+        }
+    };
+    let i = 0;
+    while (i < content.length) {
+        const lt = content.indexOf('<', i);
+        if (lt === -1) {
+            const rest = content.slice(i);
+            if (rest.trim() !== '')
+                append(make('text', i, '', rest));
+            break;
+        }
+        if (lt > i) {
+            const text = content.slice(i, lt);
+            if (text.trim() !== '')
+                append(make('text', i, '', text));
+        }
+        if (content.startsWith('<!--', lt)) {
+            const end = content.indexOf('-->', lt + 4);
+            if (end === -1) {
+                const p = at(lt);
+                errors.push({ message: 'unterminated comment', line: p.line, column: p.column });
+                append(make('comment', lt, '', content.slice(lt + 4)));
+                break;
+            }
+            append(make('comment', lt, '', content.slice(lt + 4, end)));
+            i = end + 3;
+            continue;
+        }
+        if (content.startsWith('<![CDATA[', lt)) {
+            const end = content.indexOf(']]>', lt + 9);
+            if (end === -1) {
+                const p = at(lt);
+                errors.push({ message: 'unterminated CDATA section', line: p.line, column: p.column });
+                append(make('cdata', lt, '', content.slice(lt + 9)));
+                break;
+            }
+            append(make('cdata', lt, '', content.slice(lt + 9, end)));
+            i = end + 3;
+            continue;
+        }
+        if (content.startsWith('<?', lt)) {
+            const end = content.indexOf('?>', lt + 2);
+            if (end === -1) {
+                // Finding 11 of this change's completion review: this and the
+                // declaration below swallowed the rest of the document into one
+                // node and returned cleanly, so a file ending in
+                // `<?xml version="1.0"` read as WELL-FORMED — a skip, under a
+                // contract whose whole point is that a file which does not
+                // parse is a finding rather than a skipped file.
+                const p = at(lt);
+                errors.push({ message: 'unterminated processing instruction', line: p.line, column: p.column });
+            }
+            const stop = end === -1 ? content.length : end + 2;
+            append(make('pi', lt, '', content.slice(lt + 2, end === -1 ? content.length : end)));
+            i = stop;
+            continue;
+        }
+        if (content.startsWith('<!', lt)) {
+            // A DOCTYPE may carry a bracketed internal subset; it ends after it.
+            const bracket = content.indexOf('[', lt);
+            const close = content.indexOf('>', lt);
+            let stop;
+            if (bracket !== -1 && close !== -1 && bracket < close) {
+                const endBracket = content.indexOf(']', bracket);
+                const after = endBracket === -1 ? close : content.indexOf('>', endBracket);
+                stop = after === -1 ? content.length : after + 1;
+            }
+            else {
+                stop = close === -1 ? content.length : close + 1;
+            }
+            if (close === -1) {
+                const p = at(lt);
+                errors.push({ message: 'unterminated declaration', line: p.line, column: p.column });
+            }
+            append(make('doctype', lt, '', content.slice(lt + 2, Math.max(lt + 2, stop - 1))));
+            i = stop;
+            continue;
+        }
+        const gt = tagEnd(content, lt);
+        if (gt === -1) {
+            const p = at(lt);
+            errors.push({ message: 'unterminated tag', line: p.line, column: p.column });
+            break;
+        }
+        const raw = content.slice(lt, gt + 1);
+        const nameMatch = /^<\/?\s*([A-Za-z_][\w.:-]*)/.exec(raw);
+        if (!nameMatch) {
+            // Finding 11, third case: a `<` that opens something with no legal
+            // element name is malformed markup, not whitespace. Skipping it
+            // silently is the same skip the other two were.
+            const p = at(lt);
+            errors.push({ message: `"${raw.slice(0, 24)}" is not a tag`, line: p.line, column: p.column });
+            i = gt + 1;
+            continue;
+        }
+        const name = (nameMatch[1] ?? '').toLowerCase();
+        const closing = raw.startsWith('</');
+        const selfClosing = raw.endsWith('/>');
+        if (closing) {
+            const open = stack[stack.length - 1];
+            const p = at(lt);
+            if (open === undefined) {
+                errors.push({ message: `closing tag </${name}> with no open element`, line: p.line, column: p.column });
+            }
+            else if (open.name !== name) {
+                // The shape a flat element list cannot see. Reported against
+                // the CLOSING tag, which is where a reader looking at the file
+                // sees the problem.
+                errors.push({
+                    message: `closing tag </${name}> does not match the open <${open.name}> (line ${String(open.line)})`,
+                    line: p.line,
+                    column: p.column,
+                });
+                // Recover by popping to the matching open element WHEN THERE
+                // IS ONE, so a single mistake does not cascade into an error
+                // per remaining tag.
+                //
+                // When there is none, pop NOTHING. Finding 2 of the fourth
+                // completion review: the `else stack.pop()` detached a
+                // perfectly good ancestor to pay for a stray tag that never
+                // opened anything — a file whose `</g>` has no `<g>` lost its
+                // `<svg>` from the stack, so the real `</svg>` at the end then
+                // had no open element and the file collected a SECOND error it
+                // had not earned. Cascading is exactly what this branch exists
+                // to prevent, and the unmatched case was the one where it did
+                // the cascading itself. A closing tag with no match is a stray
+                // tag: report it and carry on.
+                const idx = stack.map((n) => n.name).lastIndexOf(name);
+                if (idx !== -1)
+                    stack.length = idx;
+            }
+            else {
+                stack.pop();
+            }
+            i = gt + 1;
+            continue;
+        }
+        const node = make('element', lt, name, '', attrsOf(raw));
+        append(node);
+        elements.push(node);
+        if (!selfClosing)
+            stack.push(node);
+        i = gt + 1;
+    }
+    for (const unclosed of stack) {
+        errors.push({
+            message: `<${unclosed.name}> is never closed`,
+            line: unclosed.line,
+            column: unclosed.column,
+        });
+    }
+    return { roots, elements, errors };
+}
+// `ancestors` and `documentElement` used to live here. Finding 11 of the third
+// completion review: both were exported, called by nothing, and bundled into
+// the per-`.svg`-write dispatch chunk — own-orphans of this same diff, which
+// `minimal-safe-diff` says the diff that made them removes. `XmlNode.parent`
+// is the primitive either would have been built on and it is still here.
+//# sourceMappingURL=svg_dom.js.map