@holmes-lab/holmes-kit 0.1.9 → 0.1.11

package/dist/holmes/cpg/forbidden-edges.js

@@ -0,0 +1,140 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitCorpus = splitCorpus;
+exports.parseForbiddenEdges = parseForbiddenEdges;
+exports.findForbiddenEdgeViolations = findForbiddenEdgeViolations;
+// @implements A-SPEC-224
+const path = __importStar(require("node:path"));
+const test_files_1 = require("./test-files");
+/** Split a leading `tests:` marker off a source prefix. */
+function splitCorpus(prefix) {
+    return prefix.startsWith('tests:')
+        ? { corpus: 'tests', sourcePrefix: prefix.slice('tests:'.length) }
+        : { corpus: 'production', sourcePrefix: prefix };
+}
+const RULE = /^(import|call)\s+(\S+)\s+-x->\s+(\S+)$/;
+/**
+ * Read the rules out of a `## Forbidden Edges` section.
+ *
+ * @implements A-SPEC-224
+ * A malformed list item is RETURNED, never dropped. A typo that silently parses to nothing reads as
+ * "the rule passed" — the same shape as a gate that concludes there is nothing to govern, which
+ * this repository has now paid for in A-SPEC-191 §17, §29 and again in A-SPEC-222.2.
+ *
+ * Prose and blank lines are neither: a section is allowed to explain itself, and treating every
+ * sentence as a broken rule would make the report useless.
+ */
+function parseForbiddenEdges(section) {
+    const rules = [];
+    const malformed = [];
+    for (const raw of String(section ?? '').split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('- '))
+            continue; // prose, blank, or a non-list line
+        // Strip a trailing comment and the backticks a Markdown author naturally reaches for, so the
+        // rule reads the same whether or not it was written for a human eye.
+        const body = line.slice(2).replace(/\s+#.*$/, '').replace(/`/g, '').trim().replace(/\s+/g, ' ');
+        const m = RULE.exec(body);
+        if (!m) {
+            malformed.push(raw.trim());
+            continue;
+        }
+        const { corpus, sourcePrefix } = splitCorpus(m[2]);
+        rules.push({ kind: m[1], corpus, sourcePrefix, target: m[3], text: body });
+    }
+    return { rules, malformed };
+}
+/**
+ * Where an import specifier lands, as a repo-relative path.
+ *
+ * A relative specifier is resolved against the importing file; anything else (`node:path`, a package
+ * name) has nothing to resolve against and is compared as the literal string it is. Mixing the two
+ * inside one comparison would make a rule mean different things depending on how the author spelled
+ * the target.
+ */
+function importTargetOf(sourcePath, to) {
+    if (!to.startsWith('.'))
+        return to;
+    return path.posix.normalize(path.posix.join(path.posix.dirname(sourcePath), to));
+}
+/**
+ * Judge a scan against a set of prohibitions.
+ *
+ * @implements A-SPEC-224
+ * Pure: no filesystem, no `process`. That is what lets the same function be exercised by synthetic
+ * fixtures AND by the real corpus — and the real corpus is the one that matters, because a rule
+ * checked only against fixtures stays green while the repository drifts.
+ *
+ * `import` matches by PREFIX so one rule covers a directory and survives an extension-less
+ * specifier. `call` matches EXACTLY, because its target is a bare callee name and a prefix there
+ * would make `list` catch `listFiles`.
+ */
+function findForbiddenEdgeViolations(files, rules) {
+    const out = [];
+    if (!Array.isArray(files) || !Array.isArray(rules) || rules.length === 0)
+        return out;
+    for (const f of files) {
+        const sourcePath = f?.sourcePath;
+        if (typeof sourcePath !== 'string')
+            continue;
+        // @implements A-SPEC-229 — the file's corpus is decided by `isTestFile`, the same table the
+        // scanner and the phase gate already share. A third definition would drift from those two, and
+        // the cost of that drift is on record: one Python file was excluded from the graph as a test
+        // AND gated as production code at the same time.
+        const corpus = (0, test_files_1.isTestFile)(sourcePath) ? 'tests' : 'production';
+        const applicable = rules.filter((r) => r.corpus === corpus && sourcePath.startsWith(r.sourcePrefix));
+        if (applicable.length === 0)
+            continue;
+        for (const e of f.edges ?? []) {
+            for (const r of applicable) {
+                if (r.kind === 'import') {
+                    if (e.rel !== 'imports')
+                        continue;
+                    if (!importTargetOf(sourcePath, e.to).startsWith(r.target))
+                        continue;
+                }
+                else {
+                    if (e.rel !== 'calls')
+                        continue;
+                    if (e.to !== r.target)
+                        continue;
+                }
+                out.push({ rule: r.text, sourcePath, from: e.from, to: e.to, kind: r.kind });
+            }
+        }
+    }
+    return out;
+}

package/dist/holmes/cpg/hash-cache.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HashCache = void 0;
 const fs = __importStar(require("node:fs"));
+const json_state_1 = require("../project/json-state");
 const path = __importStar(require("node:path"));
 const node_crypto_1 = require("node:crypto");
 // @implements A-SPEC-113.1
@@ -58,16 +59,23 @@ class HashCache {
         this.hashes = this.load();
     }
     load() {
+        let parsed;
         try {
-            const raw = fs.readFileSync(this.file, 'utf8');
-            return JSON.parse(raw);
+            parsed = JSON.parse(fs.readFileSync(this.file, 'utf8'));
         }
         catch {
-            // Missing dir/file, or unreadable/corrupt JSON: treat as no prior hash
-            // rather than throwing — a cold or damaged cache must never block a
-            // reindex, only make it fall back to a full re-scan.
+            // Missing dir/file, or JSON that does not parse.
             return {};
         }
+        // @implements A-SPEC-237
+        // A SECOND check, because the one above cannot see the corruption that matters most. `null`,
+        // `42`, `"x"`, `true` and `[1,2]` are all valid JSON: the parse SUCCEEDS and the failure
+        // lands later, at the first property access, as a TypeError. Measured 2026-08-23 — four of those
+        // forms made `unchanged()` and `put()` throw, while this method's own comment promised that a
+        // damaged cache "must never block a reindex". The promise lived only in prose, so nobody checked.
+        if (!(0, json_state_1.isJsonStateObject)(parsed))
+            return {};
+        return parsed;
     }
     static hashOf(content) {
         return (0, node_crypto_1.createHash)('sha256').update(content, 'utf8').digest('hex');

package/dist/holmes/cpg/language-parser-walk.js

@@ -593,24 +593,90 @@ function extractEdgesFromTree(tree, lang = 'typescript') {
         }
         return parts.length ? parts.join('.') : '<module>';
     };
-    const visit = (node) => {
+    // @implements A-SPEC-231
+    // A dependency wears more than one spelling, and until 2026-08-22 the graph saw exactly one of
+    // them. Measured: `await import('../x')`, `require('../x')`, `export {y} from '../x'` and
+    // `export * from '../x'` all produced NO imports edge, so a Forbidden Edges ban could be walked
+    // past four ways. A rule that sees one spelling bans the spelling, not the dependency.
+    //
+    // RELATIVE specifiers only, string literals only. `require('js-yaml')` is an external dependency
+    // and a different subject; `require(base + '/x')` cannot be read statically and stays a stated
+    // blind spot rather than a guess.
+    const relativeLiteral = (n) => {
+        if (!n)
+            return null;
+        // A template literal WITHOUT substitutions is a string literal wearing different quotes —
+        // \`require(\`../x\`)\` walked past the first cut of this check (adversarial pass 2, 2026-08-22).
+        // One with substitutions is computed and stays unreadable, which is the stated blind spot.
+        const isTemplate = n.type === 'template_string';
+        if (n.type !== 'string' && !isTemplate)
+            return null;
+        if (isTemplate && n.namedChildren && n.namedChildren.some((c) => c.type === 'template_substitution'))
+            return null;
+        const text = n.text.replace(/^['"`]|['"`]$/g, '');
+        return text.startsWith('.') ? text : null;
+    };
+    const firstArgSpecifier = (node) => {
+        const args = node.childForFieldName('arguments');
+        if (!args || !args.namedChildren || args.namedChildren.length === 0)
+            return null;
+        return relativeLiteral(args.namedChildren[0]);
+    };
+    // @implements A-SPEC-231
+    // The enclosing name is carried DOWN the descent instead of re-walked UP from every call site.
+    // Same answer, different cost: the upward walk is O(nodes x depth), invisible in a batch scan
+    // and intolerable in a hook. Measured 2026-08-22 before this change — a 2KB file nested 800 deep
+    // took 10,558ms and 500 deep took 2,663ms, while a FLAT 1MB file took 1,031ms. The cost followed
+    // depth, not size, so no size cap could have bounded it. The quadratic predates this work;
+    // A-SPEC-230 is what moved it onto the write path.
+    const namedScopeOf = (node) => {
+        if (node.type !== 'function_declaration' && node.type !== 'method_definition' && node.type !== 'class_declaration')
+            return null;
+        const nm = node.childForFieldName('name');
+        return nm ? nm.text : null;
+    };
+    const visit = (node, scope) => {
         if (node.type === 'import_statement') {
             const src = node.childForFieldName('source') ?? (node.namedChildren && node.namedChildren.find((c) => c.type === 'string'));
             if (src)
                 out.push({ from: '<module>', to: src.text.replace(/['"]/g, ''), rel: 'imports' });
         }
+        else if (node.type === 'export_statement') {
+            // `export { x } from '…'` and `export * from '…'` — a re-export names no local binding but is
+            // every bit a module dependency.
+            const src = node.childForFieldName('source');
+            const spec = relativeLiteral(src);
+            if (spec)
+                out.push({ from: '<module>', to: spec, rel: 'imports' });
+        }
         else if (node.type === 'call_expression') {
             const fn = node.childForFieldName('function');
+            // Dynamic `import('…')`: the callee is neither an identifier nor a member expression, so the
+            // branch below never saw it at all.
+            if (fn && fn.type === 'import') {
+                const spec = firstArgSpecifier(node);
+                if (spec)
+                    out.push({ from: '<module>', to: spec, rel: 'imports' });
+            }
             if (fn && (fn.type === 'identifier' || fn.type === 'member_expression')) {
                 const property = fn.childForFieldName && fn.childForFieldName('property');
                 const callee = fn.type === 'identifier' ? fn.text : (property ? property.text : fn.text);
-                out.push({ from: enclosingFn(node), to: callee, rel: 'calls' });
+                out.push({ from: scope.length ? scope.join('.') : '<module>', to: callee, rel: 'calls' });
+                // The calls edge above is KEPT. Adding the imports edge alongside makes this an extension;
+                // replacing it would leave no single run able to say which it had been.
+                if (callee === 'require') {
+                    const spec = firstArgSpecifier(node);
+                    if (spec)
+                        out.push({ from: '<module>', to: spec, rel: 'imports' });
+                }
             }
         }
+        const named = namedScopeOf(node);
+        const childScope = named ? scope.concat(named) : scope;
         for (let i = 0; i < node.childCount; i++)
-            visit(node.child(i));
+            visit(node.child(i), childScope);
     };
-    visit(tree.rootNode);
+    visit(tree.rootNode, []);
     return out;
 }
 /**

package/dist/holmes/cpg/proposed-content.d.ts

@@ -0,0 +1,51 @@
+import { CodeEdge } from './language-parser';
+import { ForbiddenEdgeRule } from './forbidden-edges';
+import { RequiredCallRule } from './required-calls';
+/** What the gate could actually see. `none` means no verdict was formed, not that nothing was wrong. */
+export type JudgedAs = 'full' | 'fragment' | 'none';
+export interface ProposedContentCheck {
+    forbidden: ForbiddenEdgeRule[];
+    required: RequiredCallRule[];
+    sourcePath: string;
+    content: string;
+    /** `full` for a whole-file write; `fragment` for an edit's replacement text. */
+    mode: 'full' | 'fragment';
+    parser: {
+        extractEdges(code: string, lang: 'typescript'): CodeEdge[];
+    };
+}
+/**
+ * Judge ONE proposed file against structural constraints, without scanning the repository.
+ *
+ * @implements A-SPEC-230
+ * Both engines already judge file by file — a rule's `sourcePrefix` selects the path and only that
+ * file's edges are read — so the gate needs one parse, not a scan. Measured 2026-08-22: 2ms for a
+ * typical file, 18ms for the 109KB outlier, against 3.3s + 1.5s for the two full scans.
+ *
+ * FRAGMENTS ARE JUDGED DIFFERENTLY, and the asymmetry is the point:
+ *
+ *  - A BAN is sound on a fragment. If the added text contains a forbidden edge, that edge is really
+ *    being added. Not seeing the rest of the file can make this MISS something; it cannot make it
+ *    WRONG.
+ *  - An OBLIGATION is not. The companion call may already sit elsewhere in the file, so concluding
+ *    "absent" from a fragment manufactures a false positive — and false positives are precisely what
+ *    make a rule distrusted and then removed.
+ *
+ * A parse failure yields no verdict rather than a denial. This repository usually fails closed and
+ * that judgement has been right, but the asymmetry matters: the seal gate blocks forgery of evidence
+ * that cannot be recovered, while this one blocks a design-discipline violation that the suite
+ * catches again before the commit. Blocking every unparseable work-in-progress buys nothing the
+ * suite does not already provide.
+ */
+export declare function checkProposedContent(opts: ProposedContentCheck): {
+    violations: string[];
+    judged: JudgedAs;
+};
+/**
+ * What this check does NOT promise, carried in the refusal itself.
+ *
+ * @implements A-SPEC-230
+ * A gate's silence reads as "safe". Stating the approximations where the reader already is — rather
+ * than in a document they will not open — is what keeps a pass from becoming false confidence.
+ */
+export declare const CSPEC_GATE_LIMITS: string;

package/dist/holmes/cpg/proposed-content.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CSPEC_GATE_LIMITS = void 0;
+exports.checkProposedContent = checkProposedContent;
+const forbidden_edges_1 = require("./forbidden-edges");
+const required_calls_1 = require("./required-calls");
+/** Extensions the TypeScript grammar can actually read. @implements A-SPEC-231 */
+const TS_FAMILY_RE = /\.(ts|tsx|mts|cts|js|mjs|cjs|jsx)$/i;
+/**
+ * Judge ONE proposed file against structural constraints, without scanning the repository.
+ *
+ * @implements A-SPEC-230
+ * Both engines already judge file by file — a rule's `sourcePrefix` selects the path and only that
+ * file's edges are read — so the gate needs one parse, not a scan. Measured 2026-08-22: 2ms for a
+ * typical file, 18ms for the 109KB outlier, against 3.3s + 1.5s for the two full scans.
+ *
+ * FRAGMENTS ARE JUDGED DIFFERENTLY, and the asymmetry is the point:
+ *
+ *  - A BAN is sound on a fragment. If the added text contains a forbidden edge, that edge is really
+ *    being added. Not seeing the rest of the file can make this MISS something; it cannot make it
+ *    WRONG.
+ *  - An OBLIGATION is not. The companion call may already sit elsewhere in the file, so concluding
+ *    "absent" from a fragment manufactures a false positive — and false positives are precisely what
+ *    make a rule distrusted and then removed.
+ *
+ * A parse failure yields no verdict rather than a denial. This repository usually fails closed and
+ * that judgement has been right, but the asymmetry matters: the seal gate blocks forgery of evidence
+ * that cannot be recovered, while this one blocks a design-discipline violation that the suite
+ * catches again before the commit. Blocking every unparseable work-in-progress buys nothing the
+ * suite does not already provide.
+ */
+function checkProposedContent(opts) {
+    const { forbidden, required, sourcePath, content, mode, parser } = opts;
+    const rulesPresent = (forbidden?.length ?? 0) > 0 || (required?.length ?? 0) > 0;
+    if (!rulesPresent || typeof content !== 'string' || content.trim().length === 0) {
+        return { violations: [], judged: 'none' };
+    }
+    // @implements A-SPEC-231 — the parser is asked for TypeScript, so only TypeScript-family files may
+    // be handed to it. Measured 2026-08-22: a Python file's `list()` parsed as TypeScript became a
+    // calls edge and a false positive against an obligation rule, and false positives are what get a
+    // rule switched off. Not judging is reported as `none`, never as a pass.
+    if (!TS_FAMILY_RE.test(sourcePath))
+        return { violations: [], judged: 'none' };
+    let edges;
+    try {
+        edges = parser.extractEdges(content, 'typescript');
+    }
+    catch {
+        return { violations: [], judged: 'none' };
+    }
+    const asScanned = [{ path: sourcePath, sourcePath, symbols: [], edges, implementsSpecs: [] }];
+    const violations = [];
+    for (const v of (0, forbidden_edges_1.findForbiddenEdgeViolations)(asScanned, forbidden ?? [])) {
+        violations.push(`${v.sourcePath}: ${v.rule}  (${v.kind} → ${v.to})`);
+    }
+    // Obligations only where the whole file is visible — see the asymmetry above.
+    if (mode === 'full') {
+        for (const v of (0, required_calls_1.findRequiredCallViolations)(asScanned, required ?? [])) {
+            violations.push(`${v.sourcePath} :: ${v.fn}: ${v.rule}  (calls ${v.trigger}, none of the required)`);
+        }
+    }
+    return { violations, judged: mode };
+}
+/**
+ * What this check does NOT promise, carried in the refusal itself.
+ *
+ * @implements A-SPEC-230
+ * A gate's silence reads as "safe". Stating the approximations where the reader already is — rather
+ * than in a document they will not open — is what keeps a pass from becoming false confidence.
+ */
+exports.CSPEC_GATE_LIMITS = '이 검사가 보장하지 않는 것: 제어 흐름을 보지 않으므로 분기에 따라 규칙을 비껴가는 코드는 통과합니다;'
+    + ' 모듈 최상위 호출은 파일 단위로 귀속됩니다; 판정 대상은 이 파일 하나이며 저장소 전체가 아닙니다.';

package/dist/holmes/cpg/required-calls.d.ts

@@ -0,0 +1,62 @@
+import { ScannedFile } from './cpg-scanner';
+import { RuleCorpus } from './forbidden-edges';
+/**
+ * An obligation: within a scope, calling one thing requires calling another.
+ *
+ * @implements A-SPEC-228
+ * `Forbidden Edges` says "do not call B". It cannot say "if you call B, also call C", and that is
+ * the rule this session paid for three times — "anything reading the active graph must go through
+ * `filterGoverned`" lived only in prose, so its bypasses were found one at a time.
+ *
+ * `Allowed Dependencies` read as a whitelist does not express it either: a whitelist is the
+ * complement of a ban, not an implication.
+ */
+export interface RequiredCallRule {
+    /** Which corpus this rule judges. @implements A-SPEC-229 */
+    corpus: RuleCorpus;
+    /** Repo-relative prefix of the files this obligation applies to. */
+    sourcePrefix: string;
+    /** The call that triggers the obligation. */
+    trigger: string;
+    /** Any ONE of these satisfies it. */
+    required: string[];
+    /** The rule's own text, so a violation can quote what it broke. */
+    text: string;
+}
+export interface RequiredCallViolation {
+    rule: string;
+    sourcePath: string;
+    /** The enclosing definition that called the trigger without a companion. */
+    fn: string;
+    trigger: string;
+}
+/**
+ * Read the obligations out of a `## Layer Rules` section.
+ *
+ * @implements A-SPEC-228
+ * `-needs->` pairs with `Forbidden Edges`' `-x->` so a reader can tell a ban from an obligation at a
+ * glance. A malformed list item is RETURNED rather than dropped: a typo that parses to nothing reads
+ * as "the rule passed", which is the failure shape this whole line of work exists to remove.
+ */
+export declare function parseRequiredCalls(section: string): {
+    rules: RequiredCallRule[];
+    malformed: string[];
+};
+/**
+ * Judge a scan against a set of obligations.
+ *
+ * @implements A-SPEC-228
+ * The unit is the FUNCTION, taken from `CodeEdge.from`. File granularity would pass a file that
+ * calls the trigger in one function and the companion in another, and that relaxation defeats the
+ * rule's purpose.
+ *
+ * Deliberately incomplete, and the direction is stated rather than discovered: static co-occurrence
+ * does not read control flow, so a function that skips the companion on one branch still passes.
+ * Measured evidence that it is worth having anyway — run against the pre-71cd807 dashboard, it flags
+ * `startDashboardServer`, the real defect that shipped three bypassed endpoints.
+ *
+ * Test files are outside the scan entirely (`CpgScanner` excludes them so test symbols cannot
+ * corrupt the production graph), so the `tspec-mirror.test.ts` bypass of the same rule remains
+ * invisible here. Catching one incident of three is not "solved".
+ */
+export declare function findRequiredCallViolations(files: ScannedFile[], rules: RequiredCallRule[]): RequiredCallViolation[];

package/dist/holmes/cpg/required-calls.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRequiredCalls = parseRequiredCalls;
+exports.findRequiredCallViolations = findRequiredCallViolations;
+const test_files_1 = require("./test-files");
+const forbidden_edges_1 = require("./forbidden-edges");
+const RULE = /^call\s+(\S+)\s+(\S+)\s+-needs->\s+(.+)$/;
+/**
+ * Read the obligations out of a `## Layer Rules` section.
+ *
+ * @implements A-SPEC-228
+ * `-needs->` pairs with `Forbidden Edges`' `-x->` so a reader can tell a ban from an obligation at a
+ * glance. A malformed list item is RETURNED rather than dropped: a typo that parses to nothing reads
+ * as "the rule passed", which is the failure shape this whole line of work exists to remove.
+ */
+function parseRequiredCalls(section) {
+    const rules = [];
+    const malformed = [];
+    for (const raw of String(section ?? '').split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('- '))
+            continue; // prose, blank, or not a list item
+        const body = line.slice(2).replace(/\s+#.*$/, '').replace(/`/g, '').trim().replace(/\s+/g, ' ');
+        if (!/-needs->/.test(body) && !/^call\b/.test(body))
+            continue; // not an obligation at all
+        const m = RULE.exec(body);
+        if (!m) {
+            malformed.push(raw.trim());
+            continue;
+        }
+        const required = m[3].split('|').map((s) => s.trim()).filter(Boolean);
+        if (required.length === 0) {
+            malformed.push(raw.trim());
+            continue;
+        }
+        const { corpus, sourcePrefix } = (0, forbidden_edges_1.splitCorpus)(m[1]);
+        rules.push({ corpus, sourcePrefix, trigger: m[2], required, text: body });
+    }
+    return { rules, malformed };
+}
+/**
+ * Judge a scan against a set of obligations.
+ *
+ * @implements A-SPEC-228
+ * The unit is the FUNCTION, taken from `CodeEdge.from`. File granularity would pass a file that
+ * calls the trigger in one function and the companion in another, and that relaxation defeats the
+ * rule's purpose.
+ *
+ * Deliberately incomplete, and the direction is stated rather than discovered: static co-occurrence
+ * does not read control flow, so a function that skips the companion on one branch still passes.
+ * Measured evidence that it is worth having anyway — run against the pre-71cd807 dashboard, it flags
+ * `startDashboardServer`, the real defect that shipped three bypassed endpoints.
+ *
+ * Test files are outside the scan entirely (`CpgScanner` excludes them so test symbols cannot
+ * corrupt the production graph), so the `tspec-mirror.test.ts` bypass of the same rule remains
+ * invisible here. Catching one incident of three is not "solved".
+ */
+function findRequiredCallViolations(files, rules) {
+    const out = [];
+    if (!Array.isArray(files) || !Array.isArray(rules) || rules.length === 0)
+        return out;
+    for (const f of files) {
+        const sourcePath = f?.sourcePath;
+        if (typeof sourcePath !== 'string')
+            continue;
+        // @implements A-SPEC-229 — see forbidden-edges.ts for why `isTestFile` decides this.
+        const corpus = (0, test_files_1.isTestFile)(sourcePath) ? 'tests' : 'production';
+        const applicable = rules.filter((r) => r.corpus === corpus && sourcePath.startsWith(r.sourcePrefix));
+        if (applicable.length === 0)
+            continue;
+        const callsByFunction = new Map();
+        for (const e of f.edges ?? []) {
+            if (e.rel !== 'calls' || !e.from)
+                continue;
+            let set = callsByFunction.get(e.from);
+            if (!set) {
+                set = new Set();
+                callsByFunction.set(e.from, set);
+            }
+            set.add(e.to);
+        }
+        for (const [fn, calls] of callsByFunction) {
+            for (const r of applicable) {
+                if (!calls.has(r.trigger))
+                    continue;
+                if (r.required.some((req) => calls.has(req)))
+                    continue;
+                out.push({ rule: r.text, sourcePath, fn, trigger: r.trigger });
+            }
+        }
+    }
+    return out;
+}

package/dist/holmes/guardrail/cspec-change.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The C-SPEC a risk action is about, or `null` when it is about something else.
+ *
+ * @implements A-SPEC-225
+ * Both spellings resolve to the same id, because the same edit reaches the same document whether the
+ * caller named `C-SPEC-224` or `.ax/specs/04_cpg/C-SPEC-224.md`. A verdict that depends on how the
+ * caller spelled the target is a verdict the caller chooses — the identity-not-spelling rule
+ * A-SPEC-163 set for paths, applied to this field.
+ */
+export declare function cspecTargetId(target: string): string | null;
+/**
+ * Did the proposal change what this C-SPEC forbids?
+ *
+ * @implements A-SPEC-225
+ * Pure — text in, boolean out — so the verdict can be exercised without a store, and the I/O stays
+ * in the handler exactly as `risk-classifier`'s existing split requires.
+ *
+ * An unreadable side answers `true`. Concluding "unchanged" from content one cannot see is the
+ * failure this repository has now paid for three times: A-SPEC-191 §17 and §29 both began as "the
+ * gate did not refuse to govern — it concluded there was nothing to govern", and A-SPEC-222.2 was
+ * the same shape again. Not seeing is not sameness.
+ */
+export declare function cspecConstraintChanged(current: string | null, proposed: string | null): boolean;

package/dist/holmes/guardrail/cspec-change.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cspecTargetId = cspecTargetId;
+exports.cspecConstraintChanged = cspecConstraintChanged;
+// @implements A-SPEC-225
+const spec_parser_1 = require("../spec/spec-parser");
+const forbidden_edges_1 = require("../cpg/forbidden-edges");
+/**
+ * The C-SPEC a risk action is about, or `null` when it is about something else.
+ *
+ * @implements A-SPEC-225
+ * Both spellings resolve to the same id, because the same edit reaches the same document whether the
+ * caller named `C-SPEC-224` or `.ax/specs/04_cpg/C-SPEC-224.md`. A verdict that depends on how the
+ * caller spelled the target is a verdict the caller chooses — the identity-not-spelling rule
+ * A-SPEC-163 set for paths, applied to this field.
+ */
+function cspecTargetId(target) {
+    if (typeof target !== 'string')
+        return null;
+    const m = /\bC-SPEC-\d{3,}(?:\.\d+)?\b/.exec(target);
+    return m ? m[0] : null;
+}
+/** The constraint content of one document, in a form two documents can be compared by. */
+function constraintFingerprint(text) {
+    let spec;
+    try {
+        spec = (0, spec_parser_1.parseSpec)(text);
+    }
+    catch {
+        return null;
+    }
+    const sections = spec.sections ?? {};
+    const forbidden = sections['Forbidden Edges'];
+    const layerRules = sections['Layer Rules'];
+    if (forbidden === undefined && layerRules === undefined)
+        return null;
+    const { rules, malformed } = (0, forbidden_edges_1.parseForbiddenEdges)(forbidden ?? '');
+    // Sorted sets, not raw text: whitespace, backticks and trailing comments are not constraints, and
+    // calling a human for those would make the rule itself distrusted.
+    const ruleKeys = rules.map((r) => `${r.kind}|${r.sourcePrefix}|${r.target}`).sort();
+    // Malformed lines count. A rule broken by a typo is a rule that no longer binds anything, which is
+    // indistinguishable in effect from deleting it.
+    const brokenKeys = malformed.map((l) => l.replace(/\s+/g, ' ').trim()).sort();
+    // Layer Rules is compared as normalised prose. Nothing judges that section yet (A-SPEC-224 leaves
+    // it out), but DETECTION IS NOT JUDGEMENT — and the field this feeds names both sections. Missing
+    // it would honour "a constraint change needs a human" for only half of what it promises.
+    const layerKey = (layerRules ?? '').replace(/\s+/g, ' ').trim();
+    return JSON.stringify({ ruleKeys, brokenKeys, layerKey });
+}
+/**
+ * Did the proposal change what this C-SPEC forbids?
+ *
+ * @implements A-SPEC-225
+ * Pure — text in, boolean out — so the verdict can be exercised without a store, and the I/O stays
+ * in the handler exactly as `risk-classifier`'s existing split requires.
+ *
+ * An unreadable side answers `true`. Concluding "unchanged" from content one cannot see is the
+ * failure this repository has now paid for three times: A-SPEC-191 §17 and §29 both began as "the
+ * gate did not refuse to govern — it concluded there was nothing to govern", and A-SPEC-222.2 was
+ * the same shape again. Not seeing is not sameness.
+ */
+function cspecConstraintChanged(current, proposed) {
+    if (!current || !proposed)
+        return true;
+    const a = constraintFingerprint(current);
+    const b = constraintFingerprint(proposed);
+    if (a === null || b === null)
+        return true;
+    return a !== b;
+}