@holmes-lab/holmes-kit 0.25.1 → 0.26.1

package/dist/holmes/cpg/cycle-report.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CYCLE_LINE_MEMBERS = exports.CYCLE_LINE_CAP = void 0;
+exports.ignoredCycleKeys = ignoredCycleKeys;
+exports.cycleStatusDetails = cycleStatusDetails;
+// @implements A-SPEC-694
+/**
+ * The two ends around a judgement that was already right.
+ *
+ * `cycleRatchetViolations(current, allowed)` has honoured a named exception since A-SPEC-574.4, and
+ * the Stop hook has supplied `allowed: []` since the same day — there was nowhere to name one. And
+ * what the judgement found had no bounded way to be said: `trackedLines` joins every detail of an
+ * article into ONE line, and measured 2026-09-20 this repository carries a 46-member cycle inside a
+ * vendored tree. Wiring the evidence without these two would have printed thousands of characters a
+ * turn about code nobody here can change — "a rule that blocks adoption is not a rule, it is a
+ * barrier" (REQ-574), in its observational form.
+ *
+ * Pure, and it judges nothing: one function fills the list the judgement reads, the other renders
+ * what the judgement returned. The caps bound RENDERING only — no verdict reads them (REQ-569 S5).
+ */
+const cycle_detect_1 = require("./cycle-detect");
+/** How many cycles one ART-2 line names before it counts the rest. */
+exports.CYCLE_LINE_CAP = 5;
+/** How many members of one cycle are named before the rest are counted. The ledger keeps them all. */
+exports.CYCLE_LINE_MEMBERS = 5;
+/**
+ * A prefix as the scanner spells paths: forward slashes, no leading `./`, no trailing `/`.
+ *
+ * A prefix that normalises to nothing (`''`, `.`, `/`, `./`) means "everything" and is DROPPED. One
+ * line that switches the whole ratchet off is not an exception, it is a switch, and a switch is a
+ * different decision from the one this field records.
+ */
+function normalisePrefix(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const p = raw.replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '').replace(/^\/+/, '');
+    return p === '' || p === '.' ? null : p;
+}
+/** At a path boundary only — `reference` must not pardon `reference-impl/` (shape is not location). */
+const under = (file, prefix) => file === prefix || file.startsWith(`${prefix}/`);
+/**
+ * The keys of the cycles that lie ENTIRELY inside ignored areas — what the hook supplies as `allowed`.
+ *
+ * Entirely, because a cycle that straddles project code and a vendored tree is the project's to
+ * fix: if one ignored member were enough, the declaration would become a way to hide the project's
+ * own cycles behind a neighbour.
+ */
+function ignoredCycleKeys(cycles, prefixes) {
+    const areas = (Array.isArray(prefixes) ? prefixes : []).map(normalisePrefix).filter((p) => p !== null);
+    if (areas.length === 0)
+        return [];
+    return cycles
+        .filter((c) => c.files.length > 0 && c.files.every((f) => areas.some((a) => under(f, a))))
+        .map((c) => (0, cycle_detect_1.cycleKey)(c.files));
+}
+/**
+ * The ratchet's violations as `tracked` details of bounded length.
+ *
+ * The wording is A-SPEC-574.4's (`code import cycle: a -> b -> a`), kept so nothing that reads it
+ * has to change. What is folded is COUNTED, per cycle and across cycles: a truncation that does not
+ * announce itself reads as the whole list. The full membership is in the observation ledger.
+ */
+function cycleStatusDetails(violations, scopeSuffix) {
+    const details = violations.slice(0, exports.CYCLE_LINE_CAP).map((v) => {
+        const shown = v.files.slice(0, exports.CYCLE_LINE_MEMBERS);
+        const folded = v.files.length - shown.length;
+        const more = folded > 0 ? ` -> (+${folded} more)` : '';
+        return `code import cycle: ${shown.join(' -> ')}${more} -> ${v.files[0]}${scopeSuffix}`;
+    });
+    const foldedCycles = violations.length - exports.CYCLE_LINE_CAP;
+    if (foldedCycles > 0)
+        details.push(`… and ${foldedCycles} more import cycle(s)${scopeSuffix}`);
+    return details;
+}

package/dist/holmes/cpg/forbidden-edge-report.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The forbidden-edge judgement, as lines a person closing a turn can act on.
+ *
+ * `judgeForbiddenEdges` (A-SPEC-691) computed an honest answer — what is violated, which allowance
+ * has run out and how many times it was renewed, which languages could not be judged — and nothing
+ * in the product read it. Measured 2026-09-20: zero consumers outside the tests. An expired baseline
+ * does not block (owner decision, 2026-09-19), so while it was also invisible a time-boxed baseline
+ * was indistinguishable from a permanent pardon — the decay A-SPEC-691 was written to prevent.
+ *
+ * Pure: a judgement in, strings out. A line is spent only on something the reader can do something
+ * about, so a baseline inside its window and a kind that was judged everywhere say nothing.
+ */
+import type { judgeForbiddenEdges } from './forbidden-edges';
+/**
+ * How many violation LINES are printed. It bounds the rendering and nothing else — no verdict reads
+ * it (REQ-569 S5, REQ-691: counts never enter a judgement). What is folded is counted, never dropped:
+ * a truncation that does not announce itself reads as the whole list.
+ */
+export declare const FORBIDDEN_EDGE_LINE_CAP = 10;
+export declare function forbiddenEdgeStatusLines(j: ReturnType<typeof judgeForbiddenEdges>): string[];

package/dist/holmes/cpg/forbidden-edge-report.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORBIDDEN_EDGE_LINE_CAP = void 0;
+exports.forbiddenEdgeStatusLines = forbiddenEdgeStatusLines;
+/**
+ * How many violation LINES are printed. It bounds the rendering and nothing else — no verdict reads
+ * it (REQ-569 S5, REQ-691: counts never enter a judgement). What is folded is counted, never dropped:
+ * a truncation that does not announce itself reads as the whole list.
+ */
+exports.FORBIDDEN_EDGE_LINE_CAP = 10;
+function forbiddenEdgeStatusLines(j) {
+    const lines = [];
+    for (const v of j.violations.slice(0, exports.FORBIDDEN_EDGE_LINE_CAP)) {
+        lines.push(`forbidden edge: ${v.sourcePath}: ${v.rule}  (${v.kind} → ${v.to})`);
+    }
+    const folded = j.violations.length - exports.FORBIDDEN_EDGE_LINE_CAP;
+    if (folded > 0)
+        lines.push(`… and ${folded} more forbidden edge violation(s)`);
+    for (const b of j.baselines) {
+        if (!b.expired)
+            continue;
+        const since = b.since ? ` since ${b.since}` : '';
+        lines.push(`baseline expired ${b.until}: ${b.kind} ${b.sourcePath} -> ${b.target} (reconfirmed ${b.reconfirmed}${since})`);
+    }
+    for (const kind of Object.keys(j.scopeByKind).sort()) {
+        const missed = j.scopeByKind[kind]?.unavailable ?? [];
+        if (missed.length > 0)
+            lines.push(`${kind} rules NOT judged in: ${missed.join(', ')}`);
+    }
+    return lines;
+}

package/dist/holmes/cpg/forbidden-edges.d.ts

@@ -25,7 +25,15 @@ export declare function splitCorpus(prefix: string): {
  * to remove.
  */
 export interface ForbiddenEdgeRule {
-    kind: 'import' | 'call';
+    /**
+     * @implements A-SPEC-691
+     * `inherits` joined the two originals because the sentence above stopped being true. It named
+     * the kinds "the two things the D-CPG can actually see", measured 2026-08-22 — when `inherits`
+     * reached the graph from NO language at all. It now resolves in eight families (A-SPEC-286,
+     * A-SPEC-288, A-SPEC-511.1). Counting again and widening is what that rule asks for; offering a
+     * shape for something still invisible is what it forbids.
+     */
+    kind: 'import' | 'call' | 'inherits';
     /** Which corpus this rule judges. @implements A-SPEC-229 */
     corpus: RuleCorpus;
     /** Repo-relative prefix of the files the rule judges. */
@@ -41,7 +49,33 @@ export interface ForbiddenEdgeViolation {
     /** The enclosing definition the edge leaves from — `<module>` for a top-level import. */
     from: string;
     to: string;
-    kind: 'import' | 'call';
+    kind: 'import' | 'call' | 'inherits';
+}
+/**
+ * @implements A-SPEC-691
+ * One grandfathered violation — how a project adopts a rule it already breaks.
+ *
+ * Its whole worth is that it EXPIRES. An expiry that blocked would make the rule a barrier to
+ * adoption, which REQ-574 named the failure mode ("a rule that blocks adoption is not a rule, it is
+ * a barrier"), so expiry SHOWS instead. That only works if the showing is real: `reconfirmed` and
+ * `since` travel with the entry so a twelfth renewal cannot hide. Not blocking and not being seen
+ * are different things.
+ */
+export interface BaselineEntry {
+    kind: 'import' | 'call' | 'inherits';
+    /** The exact file this allowance covers — never a prefix. */
+    sourcePath: string;
+    /** The exact edge target this allowance covers. */
+    target: string;
+    /** ISO date the allowance runs to. */
+    until: string;
+    /** How many times the author has renewed it. */
+    reconfirmed: number;
+    /** When the allowance was first taken, if the author recorded it. */
+    since?: string;
+    /** Past `until` at judgement time. Reported, never enforced. */
+    expired: boolean;
+    text: string;
 }
 /**
  * Read the rules out of a `## Forbidden Edges` section.
@@ -56,6 +90,8 @@ export interface ForbiddenEdgeViolation {
  */
 export declare function parseForbiddenEdges(section: string): {
     rules: ForbiddenEdgeRule[];
+    /** @implements A-SPEC-691 — grandfathered violations, living in the same section on purpose. */
+    baselines: BaselineEntry[];
     malformed: string[];
 };
 /**
@@ -71,3 +107,50 @@ export declare function parseForbiddenEdges(section: string): {
  * would make `list` catch `listFiles`.
  */
 export declare function findForbiddenEdgeViolations(files: ScannedFile[], rules: ForbiddenEdgeRule[]): ForbiddenEdgeViolation[];
+/**
+ * @implements A-SPEC-691
+ * Is this violation one the project already declared it carries?
+ *
+ * EXACT on all three fields. A prefix here would turn "these violations" into "this whole area",
+ * which is a way to switch the rule off rather than a way to carry legacy forward.
+ *
+ * Exported because BOTH judgement paths need it — the scan-wide one and the pre-edit gate — and a
+ * second copy of this predicate is how a baseline comes to mean one thing in the report and another
+ * at the gate.
+ */
+export declare function isBaselined(v: {
+    kind: string;
+    sourcePath: string;
+    to: string;
+}, baselines: readonly BaselineEntry[]): boolean;
+/**
+ * @implements A-SPEC-691
+ * The judgement with its own honesty attached: what was found, what was grandfathered, and which
+ * languages could be judged at all.
+ *
+ * `findForbiddenEdgeViolations` keeps its array return, so every existing caller and pin is
+ * untouched — this WRAPS it rather than replacing it, because a second copy of the matching rule is
+ * how two paths quietly disagree.
+ *
+ * `scope` follows the distinction REQ-688 established for cycles. An extension that produced edges
+ * but NONE of the kind a rule reads is `unavailable`: it was looked at and could not be judged. An
+ * extension that produced nothing at all is in neither list, because "there was nothing to see" and
+ * "we could not see" are different facts, and reporting them as one lets an empty scan read as a
+ * clean one.
+ */
+export declare function judgeForbiddenEdges(files: ScannedFile[], rules: ForbiddenEdgeRule[], opts?: {
+    baselines?: BaselineEntry[];
+    now?: Date;
+}): {
+    violations: ForbiddenEdgeViolation[];
+    baselines: BaselineEntry[];
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+    /** @implements A-SPEC-693 — the same question asked once per rule kind in play. */
+    scopeByKind: Partial<Record<ForbiddenEdgeRule['kind'], {
+        judged: string[];
+        unavailable: string[];
+    }>>;
+};

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

@@ -36,6 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.splitCorpus = splitCorpus;
 exports.parseForbiddenEdges = parseForbiddenEdges;
 exports.findForbiddenEdgeViolations = findForbiddenEdgeViolations;
+exports.isBaselined = isBaselined;
+exports.judgeForbiddenEdges = judgeForbiddenEdges;
 // @implements A-SPEC-224
 const path = __importStar(require("node:path"));
 const test_files_1 = require("./test-files");
@@ -45,7 +47,15 @@ function splitCorpus(prefix) {
         ? { corpus: 'tests', sourcePrefix: prefix.slice('tests:'.length) }
         : { corpus: 'production', sourcePrefix: prefix };
 }
-const RULE = /^(import|call)\s+(\S+)\s+-x->\s+(\S+)$/;
+const RULE = /^(import|call|inherits)\s+(\S+)\s+-x->\s+(\S+)$/;
+/**
+ * @implements A-SPEC-691
+ * `allow until <date> [(reconfirmed <n> since <date>)] : <kind> <path> -> <target>`
+ *
+ * The arrow differs from a rule's `-x->` on purpose: the two shapes cannot be confused for each
+ * other, and a baseline written wrong falls through to `malformed` rather than disappearing.
+ */
+const BASELINE = /^allow until (\d{4}-\d{2}-\d{2})(?:\s*\(reconfirmed (\d+)(?: since (\d{4}-\d{2}-\d{2}))?\))?\s*:\s*(import|call|inherits)\s+(\S+)\s+->\s+(\S+)$/;
 /**
  * Read the rules out of a `## Forbidden Edges` section.
  *
@@ -59,6 +69,7 @@ const RULE = /^(import|call)\s+(\S+)\s+-x->\s+(\S+)$/;
  */
 function parseForbiddenEdges(section) {
     const rules = [];
+    const baselines = [];
     const malformed = [];
     for (const raw of String(section ?? '').split('\n')) {
         const line = raw.trim();
@@ -67,6 +78,26 @@ function parseForbiddenEdges(section) {
         // 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, ' ');
+        // @implements A-SPEC-691 — a baseline is tried first; its `allow until` opening cannot be a
+        // rule, so trying the rule shape first would only ever produce a confusing `malformed`.
+        if (body.startsWith('allow until')) {
+            const b = BASELINE.exec(body);
+            if (!b) {
+                malformed.push(raw.trim());
+                continue;
+            }
+            baselines.push({
+                kind: b[4],
+                sourcePath: b[5],
+                target: b[6],
+                until: b[1],
+                reconfirmed: b[2] ? Number(b[2]) : 0,
+                ...(b[3] ? { since: b[3] } : {}),
+                expired: false, // decided at judgement time, against that call's clock
+                text: body,
+            });
+            continue;
+        }
         const m = RULE.exec(body);
         if (!m) {
             malformed.push(raw.trim());
@@ -75,7 +106,7 @@ function parseForbiddenEdges(section) {
         const { corpus, sourcePrefix } = splitCorpus(m[2]);
         rules.push({ kind: m[1], corpus, sourcePrefix, target: m[3], text: body });
     }
-    return { rules, malformed };
+    return { rules, baselines, malformed };
 }
 /**
  * Where an import specifier lands, as a repo-relative path.
@@ -126,6 +157,14 @@ function findForbiddenEdgeViolations(files, rules) {
                     if (!importTargetOf(sourcePath, e.to).startsWith(r.target))
                         continue;
                 }
+                else if (r.kind === 'inherits') {
+                    // @implements A-SPEC-691 — EXACT, for the reason `call` is exact: a prefix would let one
+                    // `Base` rule swallow every `Base*` and the rule would stop meaning anything.
+                    if (e.rel !== 'inherits')
+                        continue;
+                    if (e.to !== r.target)
+                        continue;
+                }
                 else {
                     if (e.rel !== 'calls')
                         continue;
@@ -138,3 +177,97 @@ function findForbiddenEdgeViolations(files, rules) {
     }
     return out;
 }
+/**
+ * @implements A-SPEC-691
+ * Is this violation one the project already declared it carries?
+ *
+ * EXACT on all three fields. A prefix here would turn "these violations" into "this whole area",
+ * which is a way to switch the rule off rather than a way to carry legacy forward.
+ *
+ * Exported because BOTH judgement paths need it — the scan-wide one and the pre-edit gate — and a
+ * second copy of this predicate is how a baseline comes to mean one thing in the report and another
+ * at the gate.
+ */
+function isBaselined(v, baselines) {
+    return baselines.some((b) => b.kind === v.kind && b.sourcePath === v.sourcePath && b.target === v.to);
+}
+/** @implements A-SPEC-691 — which edge relation each rule kind reads. */
+const REL_OF = {
+    import: 'imports', call: 'calls', inherits: 'inherits',
+};
+/**
+ * @implements A-SPEC-691
+ * The judgement with its own honesty attached: what was found, what was grandfathered, and which
+ * languages could be judged at all.
+ *
+ * `findForbiddenEdgeViolations` keeps its array return, so every existing caller and pin is
+ * untouched — this WRAPS it rather than replacing it, because a second copy of the matching rule is
+ * how two paths quietly disagree.
+ *
+ * `scope` follows the distinction REQ-688 established for cycles. An extension that produced edges
+ * but NONE of the kind a rule reads is `unavailable`: it was looked at and could not be judged. An
+ * extension that produced nothing at all is in neither list, because "there was nothing to see" and
+ * "we could not see" are different facts, and reporting them as one lets an empty scan read as a
+ * clean one.
+ */
+function judgeForbiddenEdges(files, rules, opts) {
+    const today = (opts?.now ?? new Date()).toISOString().slice(0, 10);
+    const baselines = (opts?.baselines ?? []).map((b) => ({ ...b, expired: b.until < today }));
+    const all = findForbiddenEdgeViolations(files, rules);
+    // @implements A-SPEC-693 — asked ONCE PER KIND. The first version pooled the kinds in play, so an
+    // extension that showed imports read as `judged` beside an `inherits` rule it could not be judged
+    // for (measured 2026-09-20 on exactly the mix C-SPEC-224 declares). Which relations an extension
+    // produced is recorded per extension; each kind then reads its own relation out of that.
+    //
+    // A kind's scope counts only the files a rule OF THAT KIND actually judges — the same corpus and
+    // prefix test the matcher applies. Measured on this repository: counted over the whole scan, an
+    // import rule scoped to `src/holmes/cpg/` reported fixture extensions from elsewhere as "not
+    // judged", every turn, about files no rule speaks of. True, and nothing anyone can act on.
+    const kindsInPlay = [...new Set(rules.map((r) => r.kind))].sort();
+    const relsByKindExt = new Map();
+    const seenExt = new Set();
+    for (const f of files) {
+        const sourcePath = f?.sourcePath;
+        if (typeof sourcePath !== 'string' || (f.edges ?? []).length === 0)
+            continue;
+        const corpus = (0, test_files_1.isTestFile)(sourcePath) ? 'tests' : 'production';
+        const ext = sourcePath.slice(sourcePath.lastIndexOf('.'));
+        for (const kind of kindsInPlay) {
+            if (!rules.some((r) => r.kind === kind && r.corpus === corpus && sourcePath.startsWith(r.sourcePrefix)))
+                continue;
+            seenExt.add(ext);
+            const byExt = relsByKindExt.get(kind) ?? new Map();
+            relsByKindExt.set(kind, byExt);
+            const rels = byExt.get(ext) ?? new Set();
+            byExt.set(ext, rels);
+            for (const e of f.edges ?? [])
+                rels.add(e.rel);
+        }
+    }
+    const scopeByKind = {};
+    const unavailable = new Set();
+    for (const kind of kindsInPlay) {
+        const judgedHere = [];
+        const unavailableHere = [];
+        for (const [ext, rels] of relsByKindExt.get(kind) ?? []) {
+            if (rels.has(REL_OF[kind]))
+                judgedHere.push(ext);
+            else {
+                unavailableHere.push(ext);
+                unavailable.add(ext);
+            }
+        }
+        scopeByKind[kind] = { judged: judgedHere.sort(), unavailable: unavailableHere.sort() };
+    }
+    return {
+        violations: all.filter((v) => !isBaselined(v, baselines)),
+        baselines,
+        // The flat lists fold toward the honest side: unjudged for ANY kind in play is unavailable, and
+        // only an extension judged for EVERY kind is judged. With one kind this is what it always was.
+        scope: {
+            judged: [...seenExt].filter((e) => !unavailable.has(e)).sort(),
+            unavailable: [...unavailable].sort(),
+        },
+        scopeByKind,
+    };
+}

package/dist/holmes/cpg/import-resolver.d.ts

@@ -0,0 +1,12 @@
+import { ScannedFile } from './cpg-scanner';
+export interface ImportResolver {
+    /** One specifier → a scanned file path, or null when it names nothing the scan holds. */
+    resolve(fromFile: string, spec: string): string | null;
+    /** Go only: a package specifier → every scanned file of that package. Empty elsewhere. */
+    fanOut(fromFile: string, spec: string): string[];
+}
+export interface ImportResolverOptions {
+    /** Injected go.mod module path; when absent it is walked up from the first Go file. */
+    goModule?: string;
+}
+export declare function createImportResolver(scanned: readonly ScannedFile[], opts?: ImportResolverOptions): ImportResolver;

package/dist/holmes/cpg/import-resolver.js

@@ -0,0 +1,215 @@
+"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.createImportResolver = createImportResolver;
+// @implements A-SPEC-688
+/**
+ * The ONE place an import specifier becomes a scanned file path.
+ *
+ * It used to be two. `rtm/addImportEdges` grew the per-language rules (see A-SPEC-289, A-SPEC-406,
+ * A-SPEC-525.1, A-SPEC-527.1) while the Stop hook's cycle ratchet re-implemented a crippled
+ * version beside it — relative specifiers only, four extensions. Measured 2026-09-18 on fixtures
+ * shaped the way each language's rules require: this resolver reached 18 of 20 specifiers and
+ * found all 9 planted cycles; the ratchet's copy reached 2 and found 1. The defect cost nothing in
+ * this repository (all TypeScript, where the two agree exactly: 919 edges each), which is why it
+ * survived to v0.23.2 — and everything in a consumer written in Java, Go, Python or Rust.
+ *
+ * Extracted here rather than left in `rtm/` because resolution is a fact about CODE, not about the
+ * requirement graph, and because `rtm/` and `hooks/` both already import `cpg/` — so this placement
+ * adds no layer edge. Choosing the direction at design time is the cheap moment; that is the whole
+ * subject of the slice this module belongs to.
+ *
+ * The founding rule is unchanged and is what makes every branch safe: resolve ONLY to a file the
+ * scan actually contains. An unresolvable specifier emits nothing rather than a guess.
+ *
+ * The rules below are MOVED, not rewritten. Their originating specs are cited by number rather
+ * than anchored, because the authority for this file is A-SPEC-688 alone.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+function fsReadGoMod(p) {
+    try {
+        return fs.readFileSync(p, 'utf8').match(/^module\s+(\S+)/m)?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function createImportResolver(scanned, opts) {
+    const known = new Set(scanned.map((f) => f.sourcePath));
+    const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx', '.py',
+        '/index.ts', '/index.js', '/__init__.py'];
+    const firstKnown = (base) => EXTENSIONS.map((ext) => `${base}${ext}`).find((candidate) => known.has(candidate)) ?? null;
+    // A-SPEC-525.1 — the five languages' resolution rules, selected by the IMPORTING file's
+    // extension because resolution IS per-language semantics. The founding rule is unchanged
+    // everywhere: resolve only to files the scan actually contains; the ambiguous resolve to none.
+    const knownList = [...known];
+    const uniqueSuffix = (suffix) => {
+        const hits = knownList.filter((k) => k === suffix || k.endsWith(`/${suffix}`));
+        return hits.length === 1 ? hits[0] : null; // two files may not become a guess
+    };
+    // go.mod discovery: injected via opts when the caller knows it; otherwise walked up from the
+    // first Go file's ABSOLUTE path (bounded), so production builds resolve without extra wiring.
+    let goModCache;
+    const goModuleOf = () => {
+        if (opts?.goModule)
+            return opts.goModule;
+        if (goModCache !== undefined)
+            return goModCache ?? undefined;
+        goModCache = null;
+        const anyGo = scanned.find((f) => /\.go$/.test(f.sourcePath) && f.path);
+        if (anyGo) {
+            let dir = path.dirname(anyGo.path);
+            for (let hops = 0; hops < 12; hops++) {
+                try {
+                    const txt = fsReadGoMod(path.join(dir, 'go.mod'));
+                    if (txt !== null) {
+                        goModCache = txt;
+                        break;
+                    }
+                }
+                catch { /* keep walking */ }
+                const up = path.dirname(dir);
+                if (up === dir)
+                    break;
+                dir = up;
+            }
+        }
+        return goModCache ?? undefined;
+    };
+    const goPackage = (spec) => {
+        const mod = goModuleOf();
+        if (!mod || !(spec === mod || spec.startsWith(`${mod}/`)))
+            return []; // external, honestly
+        const dir = spec === mod ? '' : spec.slice(mod.length + 1);
+        const prefix = dir === '' ? '' : `${dir}/`;
+        return knownList.filter((k) => k.startsWith(prefix) && k.endsWith('.go')
+            && !k.endsWith('_test.go') && !k.slice(prefix.length).includes('/'));
+    };
+    const rustResolve = (fromFile, spec) => {
+        const segs = spec.split('::');
+        const head = segs.shift();
+        let baseDir;
+        if (head === 'crate') {
+            // the crate root is the src/ directory nearest above the importing file
+            const m = fromFile.match(/^(.*?src)\//);
+            baseDir = m ? m[1] : 'src';
+        }
+        else if (head === 'super') {
+            baseDir = path.posix.dirname(path.posix.dirname(fromFile));
+            while (segs[0] === 'super') {
+                // A-SPEC-527.1 — super:: above the crate root is an rustc error; resolving it pinned '.'
+                // and produced edges to repo-root files (adversarial sweep). Refuse.
+                if (baseDir === '.' || baseDir === '/')
+                    return null;
+                segs.shift();
+                baseDir = path.posix.dirname(baseDir);
+            }
+        }
+        else if (head === 'self') {
+            baseDir = path.posix.dirname(fromFile);
+        }
+        else {
+            return null; // external crate
+        }
+        const tryPath = (parts) => {
+            if (parts.length === 0)
+                return null;
+            const base = path.posix.normalize(path.posix.join(baseDir, ...parts));
+            if (known.has(`${base}.rs`))
+                return `${base}.rs`;
+            if (known.has(`${base}/mod.rs`))
+                return `${base}/mod.rs`;
+            return null;
+        };
+        // the last segment may be an ITEM, not a module — drop it once and retry
+        return tryPath(segs) ?? tryPath(segs.slice(0, -1));
+    };
+    const resolve = (fromFile, spec) => {
+        // A-SPEC-525.1 — language branches BEFORE the JS/Python-shaped fallthrough.
+        if (/\.go$/.test(fromFile))
+            return null; // Go fans out separately (a package is its files)
+        if (/\.rs$/.test(fromFile))
+            return rustResolve(fromFile, spec);
+        if (/\.java$/.test(fromFile))
+            return uniqueSuffix(`${spec.split('.').join('/')}.java`);
+        if (/\.cs$/.test(fromFile))
+            return uniqueSuffix(`${spec.split('.').join('/')}.cs`);
+        if (/\.(cpp|cc|cxx|hpp|h)$/.test(fromFile)) {
+            // A-SPEC-527.1 — an ABSOLUTE include is not a repository coordinate: joining it into the
+            // repo frame let `#include "/etc/passwd"` match a coincidentally-shaped scanned file
+            // (adversarial sweep). Absolute means absolute; it resolves to nothing here.
+            if (spec.startsWith('/'))
+                return null;
+            // extension preserved: the dotted split below would butcher `util/env.h`
+            const relative = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec));
+            if (known.has(relative))
+                return relative;
+            return known.has(spec) ? spec : null; // repo-root-relative include
+        }
+        // A-SPEC-406
+        // A specifier without a leading dot used to be refused outright, on the ground that it names an
+        // external package. That holds for `node:fs` and `js-yaml`; it does NOT hold for Python, which
+        // writes intra-repository modules absolutely — `from src.core.memory_audit import X`. Measured
+        // on the jarvis corpus: 1060 specifiers, 0 relative, 542 naming a file the scan already had, and
+        // 0 import edges in the graph. The whole import layer was missing for that language because the
+        // resolver's shape was JS's.
+        //
+        // The rule the original was written under is unchanged and is what makes this safe: resolve
+        // ONLY to a file the scan actually contains. `os.path` becomes `os/path.py`, which is in no
+        // scan, so it still emits nothing. Nothing is invented; the dotted form is simply also read.
+        if (!spec.startsWith('.')) {
+            if (spec.includes(':'))
+                return null; // `node:fs` and friends are never a repository path
+            return firstKnown(path.posix.normalize(spec.split('.').filter(Boolean).join('/')));
+        }
+        // A-SPEC-289
+        // Python writes a relative import as `.b` / `..pkg.mod`, where the leading dots are LEVELS and
+        // the remaining dots are path separators — not the `./b` form JS uses. Treating `.b` as a path
+        // yields the literal name `.b`, which matches nothing. Detected by the absence of a slash: a
+        // specifier that already contains one is a JS-style path and is left alone.
+        let relative = spec;
+        if (!spec.includes('/')) {
+            const dots = spec.match(/^\.+/)[0].length;
+            const rest = spec.slice(dots).split('.').filter(Boolean).join('/');
+            relative = `${'../'.repeat(Math.max(0, dots - 1)) || './'}${rest}`;
+        }
+        return firstKnown(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), relative)));
+    };
+    return {
+        resolve,
+        fanOut: (fromFile, spec) => (/\.go$/.test(fromFile) ? goPackage(spec) : []),
+    };
+}

package/dist/holmes/cpg/language-capability.d.ts

@@ -54,6 +54,20 @@ export interface LanguageGap {
  * meet would bury the ones this answer actually rests on. A language with nothing missing drops out
  * entirely, so the report shrinks to nothing as extraction catches up rather than becoming noise.
  */
+/**
+ * @implements A-SPEC-689
+ * The gap shape for ONE capability, as a pure function of it.
+ *
+ * Split out so the concept can be pinned on a constructed capability instead of on whichever real
+ * language happens to lag. That was already the stated intent of the sibling test, but not its
+ * practice: the pin was moved from `.java` to `.cjs` when Java graduated, and `.cjs` has now
+ * graduated too, which would have moved it a third time — to nothing, because no advertised
+ * extension lags any more. A test that must be rewritten every time the product improves is not
+ * pinning the product; it is following it.
+ *
+ * Returns null when the capability has no gap at all.
+ */
+export declare function gapOf(ext: string, cap: LanguageCapability): LanguageGap | null;
 export declare function capabilityGapsFor(sourcePaths: readonly string[]): LanguageGap[];
 /** Every advertised extension must have an entry; a blank would be a silent overclaim. */
 export declare const ADVERTISED_EXTENSIONS: readonly string[];