@holmes-lab/holmes-kit 0.1.7 → 0.1.8

package/dist/holmes/review/coverage.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Partitions changed files into two sets: those the CpgScanner ingested
+ * (scanned) and those it skipped (unscanned).
+ *
+ * A changed file is considered "scanned" iff its repo-relative POSIX path
+ * is present in the scannedSourcePaths set. This provides an honest signal
+ * about what the review actually analyzed vs what it did not (REQ-124 gate 2a).
+ *
+ * @param changedFiles - List of repo-relative POSIX paths that changed
+ * @param scannedSourcePaths - Set of repo-relative POSIX paths the scanner ingested
+ * @returns Object with sorted, deduplicated scanned and unscanned arrays
+ */
+export declare function partitionChangedFiles(changedFiles: string[], scannedSourcePaths: string[]): {
+    scanned: string[];
+    unscanned: string[];
+};
+/**
+ * Human-readable description of what the CpgScanner ingests.
+ * Used to make the "unscanned" signal self-documenting in review output.
+ */
+export declare const SCANNABLE_NOTE = "CpgScanner analyzes the TS/JS family (.ts/.mts/.cts/.tsx/.jsx/.js/.mjs/.cjs, incl. JSX), Python (.py), C# (.cs), Java (.java), Go (.go), Rust (.rs), and C++ (.cpp/.cc/.cxx/.hpp/.hh/.h) \u2014 the Aider-Polyglot + C# language set \u2014 extracting function/class/method symbols and @implements anchors. Excludes *.test.*/*.spec.*, Python (test_*.py/*_test.py) and Go (*_test.go) test files; skips node_modules/dist/.git. Call/import EDGES are extracted for TS/JS only (other languages: symbols + anchors, edges deferred). Other languages (e.g. Kotlin/Swift/Ruby/PHP) appear as unscanned.";

package/dist/holmes/review/findings.d.ts

@@ -0,0 +1,49 @@
+export type Severity = 'critical' | 'important' | 'minor';
+export interface Finding {
+    id: string;
+    severity: Severity;
+    category: string;
+    file?: string;
+    specRef?: string;
+    summary: string;
+    status: 'open' | 'resolved';
+    /**
+     * @implements A-SPEC-157
+     * The world this judgement was made in, as a basis digest.
+     *
+     * WRITTEN BY THE LEDGER, never by the caller. A judge that stamps its own basis turns the field
+     * from evidence into self-report — the same reason `HOLMES_ROLE` is out-of-band. Measured
+     * 2026-08-08: the live server answered "no impacted specs" for a commit touching 39 of them, so an
+     * agent recording "no problems" against a fresh-looking basis would have sealed that falsehood
+     * into the audit trail permanently.
+     *
+     * Absent on records written before this field existed. That absence is honest and is left alone.
+     */
+    basis?: string;
+}
+/**
+ * Append-only, spec/code-linked audit trail of review findings. Each call to
+ * `record` appends one JSON line per finding to a `.jsonl` file — never
+ * truncated, never rewritten — so the file itself is the durable evidence
+ * trail (Decision-Event style) that a diff-only review lacks.
+ *
+ * Ids and timestamps are caller-supplied: this ledger has no clock and no id
+ * generator, so recording is fully deterministic given its inputs.
+ */
+export declare class FindingsLedger {
+    private readonly path;
+    constructor(path: string);
+    /**
+     * @implements A-SPEC-157
+     * `basis` is a SEPARATE argument, not a field on the findings, so the caller cannot choose it.
+     * Optional because making it required would break every existing call site without declaring it
+     * (ADR-013 tier ③); when it is absent, no basis is written and that absence is observable.
+     */
+    record(findings: Finding[], basis?: string): void;
+    list(filter?: {
+        status?: 'open' | 'resolved';
+        severity?: Severity;
+    }): Finding[];
+    /** Ordered-object serialization so identical findings always produce identical bytes. */
+    private static serialize;
+}

package/dist/holmes/review/package.d.ts

@@ -0,0 +1,26 @@
+import { RtmGraph } from '../rtm/rtm-graph';
+import { Spec } from '../spec/spec-parser';
+import { ReviewScope } from './scope';
+import { ContextBundle, ContentSource } from '../context/bundler';
+export interface ReviewPackage {
+    scope: ReviewScope;
+    bundles: Array<{
+        seedId: string;
+        bundle: ContextBundle;
+    }>;
+    droppedSeeds: string[];
+}
+/**
+ * Assembles a review package: the review scope (impacted specs, acceptance
+ * criteria, coverage gaps, etc.) plus a graph-scoped context bundle seeded at
+ * each impacted spec AND at each changed code symbol, so a reviewer sees the
+ * impacted specs, the changed code itself, and their neighborhoods — the
+ * surpass point over a diff-only review.
+ *
+ * Pure/deterministic given the injected content source: no Date, randomness,
+ * or LLM calls. Same inputs always yield a deep-equal ReviewPackage.
+ */
+export declare function assembleReviewPackage(graph: RtmGraph, specs: Spec[], changedSymbols: string[], content: ContentSource, budget: number, opts?: {
+    maxSeeds?: number;
+    perSeedBudget?: number;
+}): ReviewPackage;

package/dist/holmes/review/review-targets.d.ts

@@ -0,0 +1,28 @@
+import { Spec } from '../spec/spec-parser';
+import { ScannedFile } from '../cpg/cpg-scanner';
+/** An outstanding P4 routing signal: a spec whose approved content moved, and the files to re-review. */
+export interface ReviewNeeded {
+    spec: string;
+    from: string;
+    to: string;
+    files: string[];
+}
+/**
+ * Read the outstanding `review-needed` signals off the provenance chain. P4 does not auto-clear, so
+ * every recorded signal is currently "outstanding" — the surface lists them so a reviewer knows what
+ * moved and which files to examine. A missing/unreadable chain → [] (nothing to route), never a throw.
+ */
+export declare function readReviewNeeded(ledgerFile: string): ReviewNeeded[];
+/**
+ * The deterministic set of source files a targeted adversarial review must re-examine when a spec's
+ * approved content MOVES (P4). This is a ROUTING computation, not a verdict: it names WHERE to look,
+ * never whether the code is right — that judgment stays with the review layer / a human, which is the
+ * whole point of P4 (the decision layer checks form/existence/execution, never meaning).
+ *
+ * - An A-SPEC's targets are the source files whose scanned `@implements` names it (its direct anchors).
+ * - A REQ's or H-SPEC's targets are the union of its APPROVED direct A-SPEC children's anchors (one
+ *   hop): a moved parent implicates the code under the approved slices beneath it.
+ *
+ * Pure, deduped, path-sorted — same (spec, anchor graph) → same set.
+ */
+export declare function anchoredForReview(specId: string, scanned: ScannedFile[], specs: Spec[]): string[];

package/dist/holmes/review/scope.d.ts

@@ -0,0 +1,13 @@
+import { RtmGraph } from '../rtm/rtm-graph';
+import { Spec } from '../spec/spec-parser';
+export interface ReviewScope {
+    changedSymbols: string[];
+    impactedSpecs: string[];
+    acceptanceCriteria: Array<{
+        specId: string;
+        criteria: string;
+    }>;
+    unrequestedSymbols: string[];
+    coverageGaps: string[];
+}
+export declare function computeReviewScope(graph: RtmGraph, specs: Spec[], changedSymbols: string[]): ReviewScope;

package/dist/holmes/review/test-evidence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * EXECUTION evidence for ART-4 coverage honesty (closes the standing "syntactic count is not
+ * execution proof" limit).
+ *
+ * countTestCases is a syntactic LOWER BOUND — it can be fabricated (`if(false){it(…)}`, aliasing).
+ * A real test RUN cannot: jest's per-file assertionResults list only cases that actually executed.
+ * This module turns a run into durable per-A-SPEC evidence, stored beside the other L4 ledgers (a
+ * write-gated surface), stamped with the git HEAD it was produced at so a STALE record can never
+ * vouch for changed code.
+ *
+ * Precedence used by the constitution: executed evidence for an A-SPEC (fresh) is AUTHORITATIVE —
+ * >0 satisfies ART-4, and an explicit 0 is a violation even if the syntactic count is high. An
+ * A-SPEC absent from the evidence falls back to the syntactic lower bound (a scoped run legitimately
+ * covers only part of the graph).
+ *
+ * Pure half: computeExecutedByAspec / isFresh (no clock, no I/O). I/O half: read/write, fail-open.
+ */
+export interface TestEvidence {
+    ts: string;
+    head: string;
+    tier: string;
+    passed: boolean;
+    executedByAspec: Record<string, number>;
+}
+/** Map per-test-file executed counts onto the A-SPECs those files @implement (pure). */
+export declare function computeExecutedByAspec(executedByFile: Record<string, number>, testAnchors: Record<string, string[]>): Record<string, number>;
+/** Evidence is usable only for the exact commit it was produced at (pure). */
+export declare function isFresh(ev: TestEvidence | undefined, currentHead: string): boolean;
+export declare const EVIDENCE_FILE: string;
+export declare function writeTestEvidence(root: string, ev: TestEvidence): boolean;
+export declare function readTestEvidence(root: string): TestEvidence | undefined;

package/dist/holmes/review/test-runner.d.ts

@@ -0,0 +1,141 @@
+import { RegressionTier, TestScope } from '../rtm/test-scope';
+/**
+ * Operational wiring for the intelligent test-scope (target-arch §5): turn a TestScope decision into
+ * an actual test run. The PLAN is pure/deterministic (testable); the EXECUTE half shells out to jest.
+ *
+ *   full            -> run the entire suite (a foundational/wide change earns full regression)
+ *   unit | partial  -> run only the impacted test files (partial may widen later; today both are scoped)
+ *
+ * If a scoped run has no impacted test files, the plan is a no-op (nothing to run) — the caller decides
+ * whether that means "safe" or "add coverage" (a coverage gap is surfaced separately by review_scope).
+ */
+export interface TestRunPlan {
+    mode: 'full' | 'scoped' | 'noop';
+    testFiles: string[];
+    reason: string;
+}
+export declare function planTestRun(scope: Pick<TestScope, 'tier' | 'impactedTestFiles'>): TestRunPlan;
+export interface TestRunResult {
+    tier: RegressionTier;
+    mode: TestRunPlan['mode'];
+    ranFiles: string[];
+    passed: boolean;
+    skipped: boolean;
+    tail: string;
+    /** repo-relative test file -> number of test cases that ACTUALLY EXECUTED. */
+    executedByFile?: Record<string, number>;
+    /**
+     * Test files whose ecosystem has no runner adapter yet, so nothing was executed for them. Reported
+     * rather than dropped: a scoped gate that silently ran only part of its scope has verified less
+     * than it claims, and the caller must be able to see that.
+     */
+    unsupported?: string[];
+    /** Which adapters actually ran, for evidence provenance. */
+    ranWith?: string[];
+}
+export type Ecosystem = 'jest' | 'pytest' | 'go' | 'rust' | 'java' | 'dotnet';
+/** Ecosystem of a test file, by extension/convention. `null` when no runner adapter exists for it. */
+export declare function ecosystemOf(file: string): Ecosystem | null;
+/**
+ * @implements A-SPEC-137.1
+ * Executed-test counts per Go package from `go test -json` output. A test is EXECUTED when a NAMED
+ * test (`Test` present) reaches `Action: 'pass'` or `'fail'` — a skip does not count (matching the
+ * jest/pytest rule), and a package-level result (no `Test`) is not a test case. Non-JSON lines (go
+ * interleaves build output) are ignored. Pure; empty/garbage input yields `{}` rather than throwing.
+ */
+export declare function parseGoTestJson(out: string): Record<string, number>;
+/**
+ * Parse jest --json output into per-file EXECUTED case counts. This is the execution-proof upgrade
+ * over the syntactic countTestCases lower bound: a case only appears here if jest actually ran it
+ * (pending/skipped assertions are excluded), so `if(false){it(…)}`, aliasing, and other syntactic
+ * fabrications cannot produce evidence. Returns {} for unparseable output (caller falls back).
+ */
+export declare function parseExecutedCounts(stdout: string, cwd: string): Record<string, number>;
+/**
+ * Parse pytest's built-in JUnit XML into per-file EXECUTED case counts — the pytest analogue of
+ * parseExecutedCounts. `--junit-xml` ships with pytest core, so this needs no plugin, and it is the
+ * only pytest output that is both machine-readable and per-file.
+ *
+ * A `<testcase>` counts as executed unless it carries `<skipped>`, matching the jest rule where
+ * pending/skipped assertions are excluded. Errors and failures DO count: they executed.
+ */
+export declare function parseJUnitXmlCounts(xml: string, ext?: string): Record<string, number>;
+/**
+ * @implements A-SPEC-137.2
+ * Executed-test count from `cargo test` text output. cargo prints one `test <name> ... ok|FAILED|
+ * ignored` line per test across all test binaries (unit/integration/doctest); `ok` and `FAILED` are
+ * EXECUTED, `ignored` is the skip rule. The `test result:` summary line is not itself counted (the
+ * per-test lines are the evidence). Crate-granular — cargo does not name a passing test's source
+ * file. Pure; empty input → 0.
+ */
+export declare function parseCargoTest(out: string): number;
+/**
+ * @implements A-SPEC-137.2
+ * Run the rust half of a plan. cargo runs the WHOLE crate (a crate is its smallest test unit), so
+ * scoped and full both invoke `cargo test` in the crate root; the crate total is credited to each
+ * input test file (crate-granular). A red suite still yields the count (cargo writes the test lines
+ * to stdout on failure). Absent toolchain → `unsupported`, never a pass. `opts.cargoPresent`
+ * overrides the probe for testing.
+ */
+export declare function runCargo(files: string[], _mode: TestRunPlan['mode'], cwd: string, opts?: {
+    cargoPresent?: boolean;
+}): {
+    passed: boolean;
+    tail: string;
+    executed: Record<string, number>;
+    unsupported?: string[];
+};
+/**
+ * @implements A-SPEC-137.3
+ * Run the Java half of a plan via gradle or maven, taking evidence from the JUnit XML they write.
+ * The presence probe RUNS `java -version` (a `/usr/bin/java` shim with no JDK fails — PATH is not
+ * enough). Absent → `unsupported`, never a pass. On this machine (no JDK) only the degradation is
+ * exercised; the run+read path is reviewed but unverified here (see A-SPEC-137.3).
+ */
+export declare function runGradle(files: string[], _mode: TestRunPlan['mode'], cwd: string, opts?: {
+    javaPresent?: boolean;
+}): {
+    passed: boolean;
+    tail: string;
+    executed: Record<string, number>;
+    unsupported?: string[];
+};
+/**
+ * @implements A-SPEC-137.3
+ * Run the C# half of a plan via `dotnet test` with the JUnit logger. The probe RUNS `dotnet
+ * --version`; absent → `unsupported`, never a pass. dotnet is absent on this machine, so only the
+ * degradation is exercised; the run+read path is reviewed but unverified here.
+ */
+export declare function runDotnet(files: string[], _mode: TestRunPlan['mode'], cwd: string, opts?: {
+    dotnetPresent?: boolean;
+}): {
+    passed: boolean;
+    tail: string;
+    executed: Record<string, number>;
+    unsupported?: string[];
+};
+/**
+ * @implements A-SPEC-137.1
+ * Run the go half of a plan. Evidence is PACKAGE-granular (go test names a passing test's package,
+ * not its file), so each package's non-skip count is credited to its input `_test.go` files. A red
+ * suite still yields counts (go writes JSON events to stdout on failure too). Absent toolchain →
+ * `unsupported`, never a pass. `opts.goPresent` overrides the probe for testing.
+ */
+export declare function runGo(files: string[], mode: TestRunPlan['mode'], cwd: string, opts?: {
+    goPresent?: boolean;
+}): {
+    passed: boolean;
+    tail: string;
+    executed: Record<string, number>;
+    unsupported?: string[];
+};
+/**
+ * Execute a plan (I/O). Deterministic inputs → deterministic command; the pass/fail is the suite's.
+ * A no-op plan is `skipped: true, passed: true` (nothing to run is not a failure).
+ *
+ * Test files are grouped by ecosystem and each group runs under its own adapter, so a mixed repo is
+ * covered rather than silently reduced to whichever language happens to sort first. Files whose
+ * ecosystem has no adapter are returned in `unsupported` — never dropped quietly, because a scoped
+ * gate that ran part of its scope has verified less than it reports.
+ */
+export declare function runTestScope(scope: TestScope, cwd: string): TestRunResult;

package/dist/holmes/rtm/dataflow-taint.d.ts

@@ -0,0 +1,81 @@
+import { DataFlowFacts } from '../cpg/language-parser';
+/**
+ * Taint propagation over data-flow FACTS (REQ-140).
+ *
+ * This is the precise pass, as distinct from REQ-138's `taintReachability`, which reports call paths
+ * and cannot tell tainted data from sanitized data. On the requirement's own fixture:
+ *
+ *     const raw  = req.body.cmd;
+ *     const safe = sanitize(raw);
+ *     run(raw);   // reported here
+ *     run(safe);  // NOT reported here — reachability reports both
+ *
+ * Both passes remain available; each states which it is via `kind`. Neither claims exploitability.
+ */
+/** One file's facts, keyed by the path the finding should name. */
+export interface DataFlowFactSet extends Array<{
+    file: string;
+    facts: DataFlowFacts;
+}> {
+}
+export interface DataFlowTaintConfig {
+    /** Case-insensitive substrings matched against a def's expression TEXT (`req.body`). */
+    sources: string[];
+    /**
+     * Callee names matched EXACTLY (case-insensitively). `callee` is already a bare last segment, so
+     * an exact match is the right shape and a substring match is not.
+     *
+     * Measured on this repository with substring matching: every one of the four findings was a false
+     * positive, and two of them came from the matcher alone — `eval` matched `evaluateStop` and `exec`
+     * matched `computeExecutedByAspec`. Neither has anything to do with evaluation or execution.
+     * List the variants you mean (`exec`, `execSync`, `execFile`); a name is not a prefix.
+     */
+    sinks: string[];
+    /** Callee names whose result is CLEAN whatever it reads — matched EXACTLY, same rule as `sinks`. */
+    sanitizers: string[];
+    /** Fixpoint bound; a run that stops here reports `converged: false`. Default 10. */
+    maxIterations?: number;
+    /** Reported-finding cap; the remainder is reported in `truncated`. Default 100. */
+    maxFindings?: number;
+}
+/** One step in the derivation of a finding — the rule that fired and what it tainted. */
+export interface FlowStep {
+    rule: 'source' | 'assign' | 'arg-param' | 'return' | 'sink';
+    /** `fn::name`, or the sink call's identity for the final step. */
+    variable: string;
+    file: string;
+    line: number;
+    detail: string;
+}
+export interface DataFlowFinding {
+    file: string;
+    /** The qualified name of the function containing the sink call. */
+    fn: string;
+    callee: string;
+    line: number;
+    argIndex: number;
+    argText: string;
+    /** How the data got here: every step, in derivation order, naming the rule that fired. */
+    flow: FlowStep[];
+}
+export interface DataFlowTaintResult {
+    kind: 'data-flow';
+    findings: DataFlowFinding[];
+    /** Every tainted `fn::name`, sorted — the fixpoint's state, exposed so a hop can be tested directly. */
+    tainted: string[];
+    limits: string[];
+    truncated: number;
+    converged: boolean;
+}
+/**
+ * What this pass does NOT model. Carried in every result, for the same reason REQ-138 carries
+ * `TAINT_LIMITS`: a screening signal that does not state its blind spots is read as a proof.
+ */
+export declare const DATAFLOW_LIMITS: readonly ["no field sensitivity (obj.a and obj.b are one value)", "no aliasing", "no path sensitivity", "no container/element tracking", "no reflection or dynamic dispatch", "sink matching is by callee NAME with no receiver type — RE.exec(s) is indistinguishable from child_process.exec(s)", "no anonymous-function parameters (arrow/function-expression params are not bound)", "not statement-order sensitive — a variable tainted anywhere in a function is tainted throughout it", "reports reachability of tainted data to a sink, never exploitability"];
+/**
+ * Taint propagation to a fixpoint.
+ *
+ * Pure: no I/O, no clock, no randomness. Facts are visited in a stable order and findings are
+ * deduped and sorted, so the same input always produces byte-identical output.
+ */
+export declare function taintDataFlow(factSet: DataFlowFactSet, cfg: DataFlowTaintConfig): DataFlowTaintResult;

package/dist/holmes/rtm/gap-analyzer.d.ts

@@ -0,0 +1,28 @@
+import { Spec } from '../spec/spec-parser';
+import { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * L6 — implementation↔spec CONVERGENCE gap analyzer (target-architecture §7 L6).
+ *
+ * The convergence loop repeatedly detects where the implementation and the governed spec set have
+ * drifted apart, so each iteration can close a gap instead of guessing. Deterministic, graph-derived —
+ * spec-kit's converge / bkit's gap-analyzer made semantic via the CPG↔RTM link:
+ *
+ *   unimplementedSpecs — approved A-SPECs no source file @implements (approved intent, no code)
+ *   unanchoredFiles    — scanned source files carrying NO @implements anchor (code outside governance;
+ *                        scope drift in the "unrequested work" direction)
+ *   untestedSpecs      — approved A-SPECs with implementing code but no anchored TEST file (the H1/
+ *                        ART-4 evidence view, precomputed here for the loop)
+ *
+ * Dangling anchors (code → nonexistent spec) are already rtmCheck's `dangling-implements`; this module
+ * covers the remaining drift directions. Pure: caller supplies the scan + specs (+ test anchors).
+ * ADVISORY by design — an unimplemented approved spec is NORMAL mid-development, so gaps feed the
+ * convergence loop (pick next work) and reviews, not a blocking gate.
+ */
+export interface ConvergenceGaps {
+    unimplementedSpecs: string[];
+    unanchoredFiles: string[];
+    untestedSpecs: string[];
+    /** convergence metric: 0 gaps -> 1.0; more gaps -> toward 0. Deterministic, monotone. */
+    score: number;
+}
+export declare function computeConvergenceGaps(scanned: ScannedFile[], specs: Spec[], testAnchors?: Record<string, string[]>): ConvergenceGaps;

package/dist/holmes/rtm/git-changes.d.ts

@@ -0,0 +1,33 @@
+import { ChangeSet } from './incremental';
+/**
+ * Pure parser for `git diff --name-status` output. Paths are already
+ * repo-relative POSIX paths as emitted by git — no path normalization here.
+ *
+ * Recognized status codes (one per tab-separated line):
+ *  - `A\tpath`            -> added
+ *  - `M\tpath`             -> modified
+ *  - `D\tpath`             -> deleted
+ *  - `R<score>\tfrom\tto`  -> renamed { from, to }
+ *  - `C<score>\tfrom\tto`  -> treated as an add of `to` (a copy introduces a
+ *    new file at `to`; the original at `from` is untouched, so there is no
+ *    corresponding delete/replace to emit for it).
+ *
+ * Blank lines are ignored. Unrecognized status codes are ignored rather than
+ * throwing, so a git version with an unfamiliar status letter degrades
+ * gracefully instead of crashing the whole reindex.
+ */
+export declare function parseNameStatus(raw: string): ChangeSet;
+/**
+ * Rejects any git rev/ref that begins with `-`. Without this, a value like
+ * `--output=/victim/file` passed as `base`/`head` to `git diff` is parsed by
+ * git as an OPTION (not a positional ref), letting an attacker make git write
+ * or truncate an arbitrary file (audit B1, argument-injection). Defense in
+ * depth alongside the `--end-of-options` guard below.
+ */
+export declare function assertSafeRev(v: string): void;
+/**
+ * Thin, side-effecting wrapper: invokes real git and hands the raw output to
+ * the pure parser above. Kept isolated here so `parseNameStatus` stays
+ * testable on a raw string with no process/filesystem dependency.
+ */
+export declare function gitChangedFiles(repoRoot: string, base: string, head: string): ChangeSet;

package/dist/holmes/rtm/heatmap.d.ts

@@ -0,0 +1,21 @@
+export interface SpecSummary {
+    id: string;
+    title: string;
+    covered: boolean;
+}
+export interface HeatmapOptions {
+    title?: string;
+    theme?: 'dark' | 'light';
+}
+export interface HeatmapReport {
+    html: string;
+    coveragePct: number;
+    totalSpecs: number;
+    coveredSpecs: number;
+}
+/**
+ * Generate a standalone interactive HTML/SVG Heatmap Report for RTM Traceability & Taint Coverage.
+ *
+ * @implements A-SPEC-212
+ */
+export declare function generateRtmHeatmap(specs: SpecSummary[] | null | undefined, options?: HeatmapOptions): HeatmapReport;

package/dist/holmes/rtm/incremental.d.ts

@@ -0,0 +1,38 @@
+import { RtmGraph } from './rtm-graph';
+import { Spec } from '../spec/spec-parser';
+import { ScannedFile } from '../cpg/cpg-scanner';
+/** Paths are repo-relative POSIX paths. */
+export interface ChangeSet {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    renamed: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+/**
+ * Reduces every add/modify/delete/rename case to one primitive: replace file
+ * F's subgraph. Processing order is deterministic: deleted, renamed, added,
+ * modified.
+ *
+ * - deleted F: graph.removeBySource(F) — no re-add.
+ * - renamed {from,to}: graph.removeBySource(from); then `to` is treated as added.
+ * - added/modified F: graph.removeBySource(F); scanOne(F); if non-null,
+ *   buildFileSubgraph(sf, specs, graph).
+ *
+ * removeBySource runs before any re-add — including for a pure add — so the
+ * operation is idempotent: re-applying the same ChangeSet has no net effect
+ * beyond the first application.
+ *
+ * SPEC-file changes (paths under .ax/specs/) are out of scope here: scanOne
+ * returns null for non-code files, so only their removeBySource side (a
+ * no-op, since SPEC nodes are keyed on the spec's own sourcePath — see
+ * buildRtm/rtm-builder) would run. Incremental SPEC-node updates are
+ * deferred to a full spec reload for now.
+ */
+export declare function applyIncremental(graph: RtmGraph, changes: ChangeSet, ctx: {
+    repoRoot: string;
+    specs: Spec[];
+    scanOne: (relPath: string) => ScannedFile | null;
+}): void;

package/dist/holmes/rtm/localize.d.ts

@@ -0,0 +1,36 @@
+import { Spec } from '../spec/spec-parser';
+import { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * N1 — issue LOCALIZATION engine v0 (target-architecture §7-N N1, first-class subsystem).
+ *
+ * Turns free-text issue/bug/task text into a STRUCTURED localization report — ranked candidate
+ * locations (files + symbols) with the evidence for each — as a reusable artifact, so downstream
+ * coding starts from a diagnosis instead of re-searching the repo every attempt (localization eats
+ * ~half of repair interaction cost — SweRank/SHERLOC motivation).
+ *
+ * v0 is the DETERMINISTIC core: lexical token matching over the CPG (symbol names, file paths) fused
+ * with the RTM spec link — issue terms that match a SPEC's title/sections pull in the files that
+ * @implements that spec (graph hop the lexical layer alone cannot make). No LLM, no clock, no I/O:
+ * same inputs → same report. The agentic multi-turn refinement layer (query reformulation, memory)
+ * is a documented later stage that builds ON this report format.
+ */
+export interface LocalizationHit {
+    file: string;
+    score: number;
+    matchedSymbols: string[];
+    viaSpecs: string[];
+    why: string[];
+}
+export interface LocalizationReport {
+    terms: string[];
+    hits: LocalizationHit[];
+    matchedSpecs: string[];
+}
+/**
+ * Significant tokens of the text, UNICODE-aware (review D2: the old [^a-z0-9] split dropped every
+ * non-ASCII codepoint, so Korean issue text — and this repo's Korean spec titles — tokenized to
+ * NOTHING and localization was a silent no-op). Letters/digits of any script are token chars;
+ * camelCase/snake are split; Latin tokens need length>=3, non-ASCII (e.g. Korean) length>=2.
+ */
+export declare function significantTerms(text: string): string[];
+export declare function localizeIssue(issueText: string, scanned: ScannedFile[], specs: Spec[], topN?: number): LocalizationReport;

package/dist/holmes/rtm/rtm-builder.d.ts

@@ -0,0 +1,101 @@
+import { Spec } from '../spec/spec-parser';
+import { RtmGraph } from './rtm-graph';
+import { ScannedFile } from '../cpg/cpg-scanner';
+export interface BuildRtmOptions {
+    /** Resolve a spec id to its source file path (e.g. its .md file) for provenance tagging. */
+    specSourcePath?: (id: string) => string | undefined;
+}
+/**
+ * Adds one scanned file's CODE nodes and `implements` edges to the graph,
+ * tagged with that file's sourcePath so RtmGraph.removeBySource(f.sourcePath)
+ * can later drop exactly this file's contribution (used by the incremental
+ * orchestrator — see Task 4).
+ */
+export declare function buildFileSubgraph(f: ScannedFile, specs: Spec[], graph: RtmGraph): void;
+export declare function buildRtm(specs: Spec[], scanned: ScannedFile[], graph: RtmGraph, opts?: BuildRtmOptions): void;
+/**
+ * Resolve each file's recovered call relations to graph edges.
+ *
+ * A scanner emits `to` as a bare callee name, because a file cannot know where the callee lives.
+ * Resolution therefore happens here, where the whole scan is visible, under a deliberately strict
+ * rule — PRECISION OVER RECALL, per the D-CPG principle:
+ *
+ *   1. same file first — a call resolves to a definition in the calling file if one matches;
+ *   2. otherwise, only if the name is defined in EXACTLY ONE file across the scan;
+ *   3. otherwise nothing is emitted.
+ *
+ * Rule 3 is the important one. A `save()` defined in nine modules is genuinely ambiguous without type
+ * resolution, and guessing produces nine wrong edges that then poison every impact answer traversing
+ * them. A missing edge merely leaves a gap that L6 already surfaces; a wrong edge is silent.
+ *
+ * OWNERSHIP: the edge is tagged with the CALLER's file, which is the file whose text contains the
+ * call. Since both endpoints are `CODE:<qn>@<path>` ids, only the caller's file can ever emit this
+ * exact (src,dst,rel) triple — so the first-writer-wins hazard documented on RtmGraph cannot arise
+ * for call edges, and `removeBySource(caller)` drops exactly them.
+ */
+export declare function addCallEdges(scanned: ScannedFile[], graph: RtmGraph): void;
+/**
+ * Bounds on call-edge propagation (REQ-127). Defaults are constants, not laws — a project can tune
+ * them, and `explain` reports what each bound actually did.
+ */
+export interface ImpactOptions {
+    /**
+     * How many `calls` hops to walk backwards from the changed symbol. Unbounded reachability is not
+     * merely slow, it is useless: measured on a 240k-function layered graph, changing one hub reached
+     * 30% of the codebase, and a bundle that size destroys the token economy the harness exists to
+     * protect. 0 disables call propagation entirely (anchor-only, the pre-W4 behaviour).
+     */
+    maxCallDepth?: number;
+    /**
+     * A symbol called from more than this many places is a HUB — a logger, a config accessor, an error
+     * constructor. Changing one genuinely does touch everything, which is exactly why propagating
+     * through it answers "the whole codebase" and helps nobody. Callers of a hub are still reported;
+     * the walk simply does not continue PAST it.
+     */
+    hubInDegree?: number;
+}
+export declare const DEFAULT_IMPACT: Required<ImpactOptions>;
+export interface ImpactExplanation {
+    specs: string[];
+    /** CODE nodes reached, by hop distance — 0 is the changed symbol itself. */
+    reachedByDepth: number[];
+    /** Symbols the walk refused to continue past, and why. Bounds must be visible, never silent. */
+    stoppedAt: Array<{
+        id: string;
+        reason: 'hub' | 'depth';
+        inDegree?: number;
+    }>;
+    /**
+     * Set when a CHANGED symbol is itself a hub — something called from more places than
+     * `hubInDegree`. Measured on a real target: one such symbol had 245 direct callers and its impact
+     * set covered 59% of all specs.
+     *
+     * That answer is CORRECT, and truncating it would be a lie. But it is also unusable as a context
+     * bundle, and no bound fixes that — tightening the hub threshold changed the maximum not at all,
+     * because the breadth is already there at depth 1. The two obvious designs are both wrong:
+     * damping the seed reports "nothing is affected" when a logger changes, while not damping it
+     * reports most of the codebase.
+     *
+     * So the size is reported instead of being forced down. A consumer that would otherwise bundle
+     * every impacted spec can see that this is a CONTRACT change — review the symbol's contract and
+     * its tests, not two hundred call sites — which is both the useful reading and the one that keeps
+     * the token economy intact.
+     */
+    seedIsHub?: {
+        callers: number;
+        threshold: number;
+    };
+}
+/**
+ * Impact of changing a set of symbols, as the set of specs that could be affected.
+ *
+ * DIRECTION MATTERS. `implements` runs code -> spec and is followed FORWARD; `calls` runs caller ->
+ * callee and must be followed BACKWARD, because the things at risk when you change `f` are the
+ * things that CALL `f`, not the things `f` calls. Walking calls forward would answer a different
+ * question and quietly return the wrong set.
+ *
+ * Anchor-only impact (no call hops) is a strict subset of this, so the bounded walk can only ever
+ * ADD to what the previous implementation returned.
+ */
+export declare function impactedBy(graph: RtmGraph, changedSymbolQNames: string[], opts?: ImpactOptions): string[];
+export declare function explainImpact(graph: RtmGraph, changedSymbolQNames: string[], opts?: ImpactOptions): ImpactExplanation;