@holmes-lab/holmes-kit 0.1.7 → 0.1.9

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

@@ -0,0 +1,13 @@
+import { Spec } from '../spec/spec-parser';
+import { ScannedFile } from '../cpg/cpg-scanner';
+export interface RtmIssue {
+    kind: 'orphan' | 'cycle' | 'dangling' | 'duplicate-id' | 'dangling-implements' | 'wrong-kind-implements';
+    id: string;
+    detail: string;
+}
+export declare function computeBlastRadius(specs: Spec[], targetId: string): {
+    impactedSpecCount: number;
+    hitsFoundational: boolean;
+};
+export declare function rtmCheck(specs: Spec[]): RtmIssue[];
+export declare function checkImplements(scanned: ScannedFile[], specs: Spec[]): RtmIssue[];

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

@@ -0,0 +1,88 @@
+/**
+ * The RTM graph. **NOT PERSISTED — read this before assuming otherwise.**
+ *
+ * Every one of the seven handlers that touches a graph (`rtm_impact`, `rtm_reindex`,
+ * `context_bundle`, `review_scope`, `review_prepare`, `risk_check`, `test_run`) constructs
+ * `new RtmGraph()` with no path, so the store is `:memory:`, built from scratch on each call and
+ * discarded when the call returns. Nothing writes `.ax/rtm.sqlite`.
+ *
+ * The surrounding machinery reads as though a persistent graph exists — `applyIncremental`,
+ * `rtm_reindex`, a `.gitignore` entry for `.ax/rtm.sqlite` — and it does not. I misread exactly this
+ * and reasoned from a persistent graph that was never there, so it is stated here rather than left
+ * to be inferred from seven constructor calls.
+ *
+ * This is a DELIBERATE position, not an omission (ADR-011): the graph is a derived index whose four
+ * inputs all come from git-tracked files, so rebuilding is always correct, a past commit's `.md` +
+ * source reconstructs that commit's graph for free, and staleness cannot occur. Persisting is
+ * deferred until graph build exceeds ~1 s per call, at which point ADR-011 lists the safety
+ * machinery that has to land with it.
+ *
+ * CONSEQUENCE FOR `rtm_reindex`: it calls `buildRtm` (a full build at HEAD) and only then
+ * `applyIncremental`, which removes and re-adds the changed files' subgraphs from that same scan.
+ * The result is identical to the full build, so the incremental pass is currently redundant work
+ * rather than a saving. It becomes meaningful the moment a persisted graph exists.
+ */
+export declare class RtmGraph {
+    private readonly db;
+    constructor(dbPath?: string);
+    private nodeStmt?;
+    private edgeStmt?;
+    addNode(id: string, kind: string, sourcePath?: string): void;
+    addEdge(src: string, dst: string, rel: string, sourcePath?: string): void;
+    /**
+     * @implements A-SPEC-139
+     * Run `fn` inside ONE SQLite transaction, so a build commits once instead of once per insert.
+     * Returns fn's value; on a throw it rolls back and re-throws — a failed build leaves no half-graph
+     * a caller could mistake for a complete one (stricter than the previous partial-insert behavior).
+     * better-sqlite3 nests via savepoints, so calling this inside an outer transaction is safe.
+     */
+    transaction<T>(fn: () => T): T;
+    reachable(fromId: string): string[];
+    incoming(toId: string): string[];
+    /**
+     * Callers of a symbol — `calls` edges only, walked backwards. Impact propagation needs exactly
+     * this and not `incoming`, which would also drag in `implements` and `depends_on` and turn a
+     * "who calls me" question into "what is attached to me in any way at all".
+     */
+    callersOf(id: string): string[];
+    /** How many distinct symbols call this one. The hub signal for bounded propagation (REQ-127). */
+    callerCount(id: string): number;
+    /**
+     * Specs this code node anchors, plus their transitive `depends_on` ancestors.
+     *
+     * Deliberately NOT `reachable`, which follows every relation. Once call edges exist, a generic
+     * forward walk from a CODE node crosses `calls` too and collects the specs of everything the
+     * symbol CALLS — silently answering "what does this depend on" while claiming to answer "what
+     * breaks if I change this". Adversarial review caught exactly that: changing a caller reported the
+     * callee's spec. Impact walks callers BACKWARD; only anchors are followed forward.
+     */
+    specsOf(codeId: string): string[];
+    /**
+     * Neighbours with the relation that connects them, so a traversal can price a `calls` hop
+     * differently from a spec-chain hop. Same ordering guarantee as `neighbors`.
+     *
+     * A node reachable by several relations appears once per relation; callers take the cheapest.
+     */
+    neighborsWithRel(id: string): Array<{
+        id: string;
+        rel: string;
+    }>;
+    /**
+     * This node's `depends_on` PARENTS — outgoing only, so it climbs the spec chain without descending
+     * into siblings. A shared parent (one REQ under which many slices hang) is a bidirectional hub;
+     * following it in both directions walks from any slice into every other one.
+     */
+    parentsOf(id: string): string[];
+    /** Nodes exactly one edge away in EITHER direction, sorted ascending and deduped. */
+    neighbors(id: string): string[];
+    removeBySource(sourcePath: string): void;
+    codeNodeIds(qn: string): string[];
+    callReachable(fromId: string): string[];
+    /** @implements A-SPEC-138 — every CODE node id, for the taint pass to match source/sink names against. */
+    allCodeNodeIds(): string[];
+    /** @implements A-SPEC-138 — direct calls-only callees of a node (one hop), for BFS path assembly. */
+    callees(fromId: string): string[];
+    nodeCount(): number;
+    edgeCount(): number;
+    close(): void;
+}

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

@@ -0,0 +1,35 @@
+import { RtmGraph } from './rtm-graph';
+/**
+ * Call-graph taint REACHABILITY (REQ-138). This is a SCREENING signal, not a data-flow proof: it
+ * reports call paths from a source-named function to a sink-named function, so a security review has
+ * candidate paths to start from. It does NOT track tainted data (no def-use, no parameter/return
+ * propagation) and does NOT model sanitizers — so it over-reports (a call path that never carries
+ * tainted data) and can under-report (flow through a non-call channel). Every consumer must carry the
+ * honesty envelope (see `TAINT_LIMITS`) and phrase findings as "reaches", never "vulnerable".
+ */
+export interface TaintConfig {
+    sources: string[];
+    sinks: string[];
+    maxPaths?: number;
+}
+export interface TaintPair {
+    source: string;
+    sink: string;
+    path: string[];
+}
+/** The limits every taint report must disclose — this is reachability, not data-flow. */
+export declare const TAINT_LIMITS: readonly ["name-based matching", "no def-use", "no sanitizers", "call-edge-only"];
+/**
+ * A small, conservative default source/sink set. Patterns are case-insensitive substrings on a node's
+ * qualified name. Deliberately narrow (precision over recall) and overridable by config.
+ */
+export declare const DEFAULT_TAINT_CONFIG: TaintConfig;
+/**
+ * Source→sink call-reachability pairs over the graph. Deterministic: sources and sinks are iterated
+ * in the graph's sorted node order, pairs are deduped by (source, sink) and sorted, and capped at
+ * `maxPaths` with `truncated` reporting the remainder. Pure except the graph read.
+ */
+export declare function taintReachability(graph: RtmGraph, cfg: TaintConfig): {
+    pairs: TaintPair[];
+    truncated: number;
+};

package/dist/holmes/rtm/test-scope.d.ts

@@ -0,0 +1,85 @@
+import { Spec } from '../spec/spec-parser';
+/**
+ * Intelligent regression test-scope (target-architecture §5, differentiator ③) — SAFE by default.
+ *
+ * Decides HOW MUCH to re-test for a change. Adversarial review (C1/C2/C3/H1) proved the first cut was
+ * unsound in production, so this version is rebuilt around one rule: NEVER report a narrower scope than
+ * can be justified. When the impact analysis is uncertain or the test↔spec mapping is incomplete, it
+ * escalates to `full` — a false "safe" (skipping a test that would have caught a regression) is the
+ * only unacceptable outcome; over-running tests is merely slower.
+ *
+ *   unit    — impacted specs map to anchored tests, low downstream blast, no coverage gaps
+ *   partial — moderate downstream blast
+ *   full    — foundational REQ reached, wide blast, a coverage gap, OR impacted specs with NO
+ *             resolvable anchored tests (can't narrow safely) OR no analysis at all
+ *
+ * Key fixes vs. the first cut:
+ *  - C1: impacted spec ids are stripped of the graph's `SPEC:` node-id prefix before use.
+ *  - C2: impacted TEST files come from a SEPARATE test-file @implements scan (scanTestAnchors), because
+ *        the CPG scanner deliberately excludes test files from the production symbol graph.
+ *  - C3/H1: the tier is driven by downstream BLAST RADIUS + coverage gaps + test resolvability, not by
+ *        the ancestor-chain length (which is ~constant depth, not breadth) — and defaults to `full`.
+ */
+export type RegressionTier = 'unit' | 'partial' | 'full';
+export interface TestScopeThresholds {
+    partialBlast?: number;
+    fullBlast?: number;
+}
+export interface TestScope {
+    tier: RegressionTier;
+    impactedSpecs: string[];
+    impactedTestFiles: string[];
+    blastRadius: number;
+    hitsFoundational: boolean;
+    coverageGaps: string[];
+    reason: string;
+    /** Changed source files that resolved into NO lane (A-SPEC-130) — nonempty forces `full`. */
+    unresolvedFiles: string[];
+}
+/**
+ * @implements A-SPEC-130
+ * Lane-3 self-selection and the unresolved remainder, threaded into the tier decision. Optional and
+ * additive: every existing five-argument caller is untouched, and an empty extras changes nothing.
+ */
+export interface TestScopeExtras {
+    /** Changed files that ARE test files: they join the selected set of any non-full tier. */
+    changedTestFiles?: string[];
+    /** Changed scannable sources no lane resolved: tier becomes `full`, reason names them. */
+    unresolvedFiles?: string[];
+}
+/**
+ * @implements A-SPEC-130
+ * Three-lane resolution for changed files. Impact propagation is symbol-keyed, so three classes of
+ * changed file used to vanish before the tier decision (measured 2026-08-06: five changed sources,
+ * zero changed symbols, tier "nothing to re-test", noop passed:true):
+ *
+ *   lane 1  symbols changed        -> the existing symbol path owns it; not accounted here
+ *   lane 2  scanned, 0 symbols,    -> its `implementsSpecs` join the impacted set directly — the
+ *           readable @implements      anchor was always on disk; only the symbol keying dropped it
+ *   lane 3  a test file            -> selects ITSELF (the symbol scan excludes tests by design)
+ *   else    scannable source       -> UNRESOLVED: the graph cannot see it, the tier must widen
+ *
+ * Docs, specs, playbooks and anything under `.ax/` never qualify as unresolved — a documentation
+ * change must not trigger a full regression. Pure set arithmetic over signals already in memory.
+ */
+export interface ChangedFileAccount {
+    anchorImpactedSpecs: string[];
+    changedTestFiles: string[];
+    unresolvedFiles: string[];
+}
+export declare function accountChangedFiles(changedFiles: string[], scanEntry: (rel: string) => {
+    implementsSpecs: string[];
+    symbolCount: number;
+} | undefined): ChangedFileAccount;
+/** Frameworks this counter understands, for diagnostics and tests. */
+export declare const SUPPORTED_TEST_FRAMEWORKS: string[];
+export declare function countTestCases(source: string, filePath?: string): number;
+/** A-SPEC ids anchored by a file, counting only standalone comment-line markers outside literals. */
+export declare function extractAnchors(source: string): string[];
+/**
+ * Scan the repo for TEST files and the A-SPEC ids they @implement. Separate from the CPG scan (which
+ * excludes tests), so the test↔spec edges actually exist for scoping. Returns repo-relative POSIX
+ * paths → the impacted-spec ids they anchor. Pure-ish (fs read only); resilient to unreadable files.
+ */
+export declare function scanTestAnchors(root: string): Record<string, string[]>;
+export declare function computeTestScope(impactedSpecsRaw: string[], testAnchors: Record<string, string[]>, specs: Spec[], coverageGaps?: string[], cfg?: TestScopeThresholds, extras?: TestScopeExtras): TestScope;

package/dist/holmes/server/dashboard.d.ts

@@ -0,0 +1,85 @@
+import * as http from 'node:http';
+export interface DashboardOptions {
+    root: string;
+    port?: number;
+}
+export interface DashboardServerHandle {
+    server: http.Server;
+    url: string;
+    port: number;
+    stop: () => Promise<void>;
+}
+export interface GraphNode {
+    id: string;
+    type: 'spec' | 'code';
+    kind: string;
+    label: string;
+    covered?: boolean;
+}
+export interface GraphEdge {
+    from: string;
+    to: string;
+    rel: 'implements' | 'depends_on' | 'calls' | 'contains' | 'verifies';
+}
+/**
+ * Start a lightweight standalone Node.js HTTP server for interactive dashboard & RTM visualization.
+ *
+ * @implements A-SPEC-215
+ * @implements A-SPEC-219
+ */
+export declare function startDashboardServer(options: DashboardOptions): Promise<DashboardServerHandle>;
+/**
+ * One end-to-end 6-stage trace row: REQ -> H-SPEC -> A-SPEC -> T-SPEC -> File -> AST Symbol.
+ *
+ * Every stage is nullable ON PURPOSE. A stage that does not exist in the repository is reported as
+ * `null` and named in `missingStages`; it is never back-filled with a synthesized spec id or with a
+ * placeholder file/symbol, because a traceability matrix that invents its own evidence cannot be
+ * audited against the repository it claims to describe.
+ *
+ * @implements A-SPEC-219
+ */
+export interface PipelineRow {
+    reqId: string;
+    reqTitle: string;
+    hspecId: string | null;
+    aspecId: string | null;
+    tspecId: string | null;
+    fileId: string | null;
+    symbolId: string | null;
+    symbolLine: number | null;
+    /** How many of the 6 stages are backed by a real artifact (1..6; REQ itself always counts). */
+    stagesComplete: number;
+    /** Human-readable names of the stages with no artifact, in pipeline order. */
+    missingStages: string[];
+    /** COVERED only when all 6 stages resolve to a real artifact. */
+    status: 'COVERED' | 'UNCOVERED';
+    findingsCount: number;
+    criticalCount: number;
+    /**
+     * false when no findings ledger exists. `findingsCount: 0` then means "not scanned", never
+     * "scanned and clean", and the audit lens must render the two differently.
+     */
+    findingsScanned: boolean;
+    mutantCount: number;
+    /**
+     * `null` — never a number. A mutation SCORE requires executing the test suite once per mutant;
+     * this endpoint only generates mutants statically, so it has no basis for a score and says so
+     * rather than reporting a constant that reads as a measurement.
+     */
+    mutationScore: null;
+    mutationScoreMeasured: false;
+}
+export declare function isCanonicalStatus(status: unknown): boolean;
+/** `A-SPEC-219.1` -> `A-SPEC`, `REQ-021` -> `REQ`. */
+export declare function specKindOf(id: string): string;
+/**
+ * Build the 6-stage pipeline matrix from the repository's real specs, scanned files and findings.
+ *
+ * Pure and exported so the truthfulness invariants can be asserted directly, without an HTTP round
+ * trip: no row may name an artifact that the inputs do not contain, and no symbol may be dropped.
+ *
+ * @implements A-SPEC-219
+ */
+export declare function buildPipelineRows(specs: any[], files: any[], allFindings: any[], options?: {
+    findingsScanned?: boolean;
+}): PipelineRow[];