@holmes-lab/holmes-kit 0.2.0 → 0.3.0

package/dist/holmes/mcp/maintenance-analyze.d.ts

@@ -0,0 +1,435 @@
+import type { ScannedFile } from '../cpg/cpg-scanner';
+import type { Spec } from '../spec/spec-parser';
+import type { RtmGraph } from '../rtm/rtm-graph';
+import type { ContextBundle } from '../context/bundler';
+import { type TestScope } from '../rtm/test-scope';
+import type { ResolutionReport } from '../rtm/rtm-builder';
+import { type TestEvidence } from '../review/test-evidence';
+import { type LanguageGap } from '../cpg/language-capability';
+export declare const MAINTENANCE_ANALYSIS_SCHEMA = "maintenance-analysis/1.13";
+export declare const MAINTENANCE_ANALYSIS_EXTRACTOR = "holmes-graph-fusion/1.13";
+/**
+ * The evidence kinds an ablation arm can actually produce. Completeness is measured by asking each
+ * arm which of these it FILLED — the first cut hardcoded 1 / 2 / 2+n, so "enhanced beats current"
+ * was an identity of the code rather than a result of a measurement.
+ */
+export declare const EVIDENCE_DIMENSIONS: readonly ["candidates", "specs", "directImpact", "transitiveImpact", "tests", "history", "versionedBasis"];
+export type EvidenceDimension = typeof EVIDENCE_DIMENSIONS[number];
+/**
+ * Externally supplied truth for a replayed change — normally the files, symbols, and test files a
+ * historical commit actually touched. The arms cannot see it; it only scores them.
+ */
+export interface MaintenanceGroundTruth {
+    files?: readonly string[];
+    symbols?: readonly string[];
+    tests?: readonly string[];
+}
+/**
+ * @implements A-SPEC-271
+ * How many ranked candidates form the `primary` tier. A fixed rank cut, not a score threshold:
+ * measured over the 12-commit replay corpus at matched set sizes, a `score >= ratio * top` cut was
+ * never better than the plain rank cut on both axes at once (top-3 beat ratio>=0.5 on recall AND
+ * precision), and tuning a threshold on 12 samples would be fitting noise.
+ */
+export declare const PRIMARY_TIER_WIDTH = 3;
+export interface AblationArm {
+    localizationCandidates: number;
+    localizationRecall: number | null;
+    localizationPrecision: number | null;
+    impactRecall: number | null;
+    impactPrecision: number | null;
+    testRecall: number | null;
+    testPrecision: number | null;
+    evidenceDimensions: EvidenceDimension[];
+    evidenceCompleteness: number;
+    /**
+     * @implements A-SPEC-271
+     * Recall/precision of the `primary` tier alone. Reported only by the arm that HAS tiers; null
+     * everywhere ground truth is absent, exactly like the flat metrics.
+     */
+    primaryRecall: number | null;
+    primaryPrecision: number | null;
+    /**
+     * @implements A-SPEC-274
+     * The closure-only tier, scored separately so the decision to drop it from the prediction stays
+     * open to review: if another corpus shows it carrying true positives, the number says so.
+     */
+    impactedFilesRecall: number | null;
+    impactedFilesPrecision: number | null;
+    /** @implements A-SPEC-289 — the import tier, scored on its own so its worth stays visible. */
+    importedByRecall: number | null;
+    importedByPrecision: number | null;
+}
+export interface MaintenanceHistoryRecord {
+    commit: string;
+    date: string;
+    subject: string;
+    files: readonly string[];
+}
+export interface MaintenanceAnalysisInput {
+    /**
+     * @implements A-SPEC-478 — the INJECTED semantic runtime for the uncited head rerank. The
+     * handler resolves the tier, awaits the query embedding, and injects; the replay harness
+     * injects nothing, which is what keeps every pinned benchmark constant untouched. queryVector
+     * null (embedding failed) disables the rerank — the hot path never breaks on this layer.
+     */
+    semantic?: {
+        label: string;
+        queryVector: number[] | null;
+        cachedDocVector: (text: string) => number[] | null;
+    };
+    request: string;
+    scanned: readonly ScannedFile[];
+    specs: readonly Spec[];
+    graph: RtmGraph;
+    testAnchors: Readonly<Record<string, readonly string[]>>;
+    history: readonly MaintenanceHistoryRecord[];
+    /**
+     * @implements A-SPEC-378
+     * Per-file multipliers from the temporal graph: how recently each file changed, as of the analysis
+     * basis. Absent files score 1 — unknown history is not evidence against a file.
+     *
+     * The first signal measured to beat plain word matching on requests that cite no spec, which is
+     * the condition every incoming bug report is in and where five spec-graph mechanisms had all come
+     * back negative. Measured at a 10-commit half-life over 60 point-in-time cases: uncited Top-10
+     * recall 0.349 -> 0.434 against a 0.357 baseline, cited 0.770 -> 0.843, second corpus 0.684 ->
+     * 0.724. Change FREQUENCY was measured alongside recency and made the uncited case worse, so it is
+     * deliberately not here.
+     *
+     * Supplied by the caller rather than read here, because this function performs no I/O — the same
+     * property that lets the replay benchmark run it against a materialised tree.
+     */
+    changePrior?: Record<string, number>;
+    /**
+     * @implements A-SPEC-388
+     * Per-file multipliers from how much each file's COMMIT PROSE talks like the request, normalised
+     * to 0..1. Absent files are unaffected.
+     *
+     * The path is query -> Commit -> `MODIFIED_IN` -> File: the request's words are matched against
+     * what the graph records about a file rather than against the file's own identifiers, which is
+     * what lets it reach code named nothing like the report that describes it.
+     *
+     * Measured on history sampled away from the benchmarker's own recent commits (A-SPEC-387), on both
+     * corpora: Top-1 0.244 -> 0.333 and 0.400 -> 0.500, Top-5 recall 0.539 -> 0.624 and 0.376 -> 0.464,
+     * Top-10 recall 0.668 -> 0.674 and 0.393 -> 0.601. Precision falls, 0.156 -> 0.117 and 0.244 ->
+     * 0.145 — the answer is found more often and the list of ten is less pure, and neither half of
+     * that is the whole result.
+     */
+    commitTextBoost?: Record<string, number>;
+    contextBundle?: ContextBundle | null;
+    /**
+     * @implements A-SPEC-290
+     * The stored test-run record, if any. Used ONLY when it was produced at this analysis's HEAD:
+     * a stale execution record read as current evidence is exactly the failure this codebase keeps
+     * closing.
+     */
+    runtimeEvidence?: TestEvidence;
+    /**
+     * @implements A-SPEC-292
+     * What graph resolution discarded, produced by the resolution loop itself. Absent means nobody
+     * measured it — reported as null, never as zeros, because zeros would claim nothing was discarded.
+     */
+    resolution?: ResolutionReport;
+    /** Optional replay ground truth. Absent means recall/precision are UNKNOWN, reported as null. */
+    groundTruth?: MaintenanceGroundTruth;
+    /**
+     * @implements A-SPEC-269
+     * Optional changed-file basis (e.g. a base..head diff). The architecture axis reads
+     * `.ax/decisions/*.md` and the C-SPEC folder — documents the CPG scanner never scans — so it
+     * cannot be derived from the localized code files. Without this the axis is reported as NOT
+     * assessed rather than as empty.
+     */
+    changedFiles?: readonly string[];
+    basis: {
+        head: string;
+        loadedBuild: string;
+        diskBuild: string;
+        specFingerprint: string;
+    };
+    coverage: {
+        scannedFiles: number;
+        skippedFiles: readonly string[];
+        unsupportedLanguages: readonly string[];
+        historyStatus?: 'available' | 'unavailable' | 'not-requested';
+    };
+}
+export interface MaintenanceAnalysis {
+    schemaVersion: string;
+    extractorVersion: string;
+    classification: 'existing-requirement-change' | 'new-requirement' | 'ambiguous';
+    /**
+     * @implements A-SPEC-436
+     * MEASURED ANTI-PREDICTIVE. On both corpora's 30-case clean slices this field correlates
+     * NEGATIVELY with how much of the change the analysis actually found — holmes r = −0.309, the
+     * second corpus r = −0.212 — and on both the highest band is the worst one. On the second corpus
+     * the two cases scored 0.85 returned nothing correct at all. Do not read it as a quality signal;
+     * a caller who weights answers by it weights the wrong ones up. The numbers and their sample
+     * sizes are pinned in review/confidence-calibration.ts, and the formula is unchanged because
+     * nobody has a hypothesis for why it inverts.
+     */
+    confidence: number;
+    /**
+     * @implements A-SPEC-375
+     * A-SPECs worth citing, when the request cited nothing. Empty when it already did.
+     *
+     * Measured over 60 point-in-time cases: a request naming its spec reaches Top-10 recall 0.770
+     * against 0.305 for matching its words alone; a request naming nothing reaches 0.349 against
+     * 0.357 — level, with five graph mechanisms tried in that condition and every one negative. So
+     * this is not a nag, it is the single input that changes what the analysis can do.
+     *
+     * Few, deliberately: 26.6 A-SPECs match lexically per case on this repository, and offering all of
+     * them would be a haystack rather than a suggestion.
+     */
+    citationCandidates: string[];
+    /**
+     * @implements A-SPEC-390
+     * What kind of call edges this graph actually holds.
+     *
+     * Measured on this repository: 7,917 `calls` edges, 1,078 binding to exactly one other file and
+     * 6,050 naming a target the scan does not contain — and those 6,050 are `join`, `push`, `map`,
+     * `filter`, `existsSync`. Builtins, correctly unresolvable, stored under the same relation as
+     * internal calls. Reporting "7,917 call edges" without this split describes a graph seven times
+     * denser than the one that exists.
+     *
+     * Reporting only: the impact walk already skips targets it cannot resolve, so no ranking, impact
+     * set or candidate order depends on these counts.
+     */
+    callEdges: {
+        total: number;
+        /** Binds to exactly one OTHER file in the scan — the edges a walk can actually use. */
+        internalResolved: number;
+        /** The name is declared in several files, so binding it would be a guess. */
+        ambiguous: number;
+        /** Declared nowhere in the scan: a library, a builtin, or a method on an unknown type. */
+        outOfScan: number;
+        /** Lands in the file it came from. */
+        withinFile: number;
+        /** null when there are no call edges — unmeasured, never a perfect score. */
+        internalResolvedShare: number | null;
+    };
+    candidates: Array<{
+        file: string;
+        score: number;
+        symbols: string[];
+        evidence: string[];
+    }>;
+    /**
+     * @implements A-SPEC-494 — the semantic ALTERNATES: top-3 cached-vector cosines among files
+     * the emission did NOT reach. Additive evidence (cloud tier only) — S-511 measured the ceiling
+     * gain at ×1.25–×2.25 in weak windows with precision rising too; selection stays with the
+     * consumer. Absent when the gate is shut or nothing off-emission is covered.
+     */
+    semanticAlternates?: Array<{
+        file: string;
+        cos: number;
+    }>;
+    /**
+     * @implements A-SPEC-409
+     * Ranks 11-20 of the same fused ordering, in the same shape as `candidates`.
+     *
+     * Two blind sets agree the harness picks the single best file better than reading-and-grepping
+     * does (Top-1 0.375 vs 0.125, then 0.750 vs 0.625) and recovers the whole change worse (Top-10
+     * recall 0.404 vs 0.554, then 0.833 vs 0.938). The gap was traced to judgement, not retrieval:
+     * reranking the fused top-20 by hand moved Top-1 to 0.500 and Top-5 recall to 0.575 on eight
+     * cases whose truth was unread at the time. The reachable recall of the wider list is measured —
+     * holmes 0.634 at ten to 0.691 at twenty, jarvis 0.612 to 0.739, and jarvis is flat by thirty.
+     *
+     * This field buys none of that on its own. It hands the calling agent the material; whether recall
+     * actually improves depends on how well that agent reranks, and that is not measured here.
+     */
+    rerankPool: Array<{
+        file: string;
+        score: number;
+        symbols: string[];
+        evidence: string[];
+    }>;
+    candidateSpecs: string[];
+    impacts: {
+        /**
+         * Every file this analysis names as a modification candidate: the ranked localization hits PLUS
+         * the files that own transitively impacted symbols. This is the ONE prediction that gets
+         * persisted and scored — the enhanced ablation arm takes credit for caller-reachable files, so
+         * the result has to name them rather than leave them visible only as a count.
+         */
+        files: string[];
+        /**
+         * @implements A-SPEC-271
+         * The same files, GRADED. `primary` is the head of the ranking, `secondary` the rest of the
+         * ranked candidates, `reachable` the files reached only by a call edge. This does not narrow
+         * the prediction — the union is exactly `files` — it says where the density is. Measured
+         * 2026-08-28 over 12 real commits: top-3 precision 0.167 against 0.061 for the flat set.
+         */
+        tiers: {
+            primary: string[];
+            secondary: string[];
+        };
+        /**
+         * @implements A-SPEC-274
+         * Files reached ONLY through a call edge. These are not modification candidates — measured
+         * 2026-08-28 over 12 real commits, this list contributed 59 files and **zero** true positives,
+         * about a third of the whole prediction. They are what the change may AFFECT, so they are still
+         * reported (and still drive spec ancestry and test selection) but they are no longer folded
+         * into `files`. Nothing is lost; the name now matches what the list actually is.
+         */
+        impactedFiles: string[];
+        /**
+         * @implements A-SPEC-469
+         * The GRADED impact prediction: PPR mass over the same graph, top-K, the changed set excluded.
+         * The closure above stays the gate-facing reach set (mass never enters a gate decision); this
+         * list is the consumer-facing answer to "what will change WITH this". Adopted on S-484's
+         * three-corpus measurement — the closure's own numbers were recall 0.0347 / precision 0.0413
+         * (HOLMES), the graded top-10's 0.5713 / 0.1611, and both metrics won on all three corpora,
+         * which is the bar that A-SPEC-309/313 set and their expansions failed.
+         */
+        rankedImpact: Array<{
+            file: string;
+            score: number;
+            semCos?: number;
+        }>;
+        /**
+         * @implements A-SPEC-289
+         * Files that IMPORT a predicted file. A coarser dependency than a call, and the only axis that
+         * reaches a file depending on another without calling a symbol the resolver could pin down.
+         *
+         * Reported, never folded into `files`. Measured over 12 real commits: folding it in lifts recall
+         * 0.826 -> 0.913 but adds 129 files carrying 2 truth files (precision 0.0155) and roughly halves
+         * the prediction's density. Those 2 are reachable by nothing else, so the information is worth
+         * reporting — and, by A-SPEC-274's rule, being affected is still not being a candidate.
+         */
+        importedByFiles: string[];
+        /**
+         * @implements A-SPEC-290
+         * Which impacted contracts were actually OBSERVED executing, and whether that observation can
+         * be trusted at all. `fresh` means the record was produced at this very commit; `stale` means a
+         * record exists for a different one and is therefore not evidence about this tree; `absent`
+         * means none exists. Only `fresh` ever populates `specs`.
+         *
+         * This NEVER removes a test from the selection. Absence of observation is not absence of
+         * relevance — the test may simply not have run — so runtime evidence adds a quality label and
+         * takes nothing away.
+         */
+        runtimeObserved: {
+            status: 'fresh' | 'stale' | 'absent';
+            specs: string[];
+        };
+        /**
+         * @implements A-SPEC-292
+         * Relations the graph declined to link, by reason. `null` when unmeasured.
+         */
+        unresolvedRelations: ResolutionReport | null;
+        direct: string[];
+        transitive: string[];
+        contract: string[];
+        test: string[];
+    };
+    impactBounds: {
+        maxCallDepth: number;
+        hubInDegree: number;
+        stoppedAt: Array<{
+            id: string;
+            reason: 'hub' | 'depth';
+            inDegree?: number;
+        }>;
+        seedIsHub?: {
+            callers: number;
+            threshold: number;
+        };
+    };
+    /**
+     * @implements A-SPEC-279
+     * The two constraint axes Phase 2 asks for beyond architecture. Both are ALWAYS assessed when
+     * their input exists — taint reachability costs ~5ms on an already-built graph, measured — and
+     * `assessed: false` means the input was missing, never that the axis came back clean.
+     */
+    constraints: {
+        security: {
+            assessed: boolean;
+            limits: string[];
+            paths: Array<{
+                source: string;
+                sink: string;
+                files: string[];
+            }>;
+        };
+        compatibility: {
+            assessed: boolean;
+            breakingChanges: Array<{
+                spec: string;
+                kind: string;
+            }>;
+        };
+        /**
+         * @implements A-SPEC-293
+         * Architecture decisions that constrain the predicted files or candidate specs — what the
+         * change must not break, as opposed to what it touches.
+         */
+        decisions: string[];
+    };
+    /**
+     * @implements A-SPEC-285
+     * For the languages ACTUALLY in this scan, the relation kinds their extractor does not recover.
+     * An empty list means every language present gave up everything it could — not that no language
+     * was involved.
+     */
+    languageCoverage: LanguageGap[];
+    /**
+     * @implements A-SPEC-294
+     * Why the candidate requirements exist, read from each REQ's `source` frontmatter. The analysis
+     * used to report WHICH specs and never WHY — and the why is the one thing the code cannot be read
+     * back from. An `adr` source links to the decision it came from.
+     */
+    /**
+     * @implements A-SPEC-295
+     * Candidate requirements whose Success Criteria cannot answer "did we satisfy this?" — the
+     * section is missing, or it says only that the implementation was completed and tested.
+     */
+    unactionableCriteria: Array<{
+        req: string;
+        quality: 'absent' | 'boilerplate';
+    }>;
+    intent: Array<{
+        req: string;
+        kind: string;
+        ref: string | null;
+        retrieved: string | null;
+        note: string | null;
+        decision: string | null;
+    }>;
+    testScope: TestScope;
+    relevantTests: string[];
+    relevantTestSpecs: string[];
+    historicalRationale: MaintenanceHistoryRecord[];
+    contextBundle: ContextBundle | null;
+    assumptions: string[];
+    contradictions: string[];
+    unknowns: string[];
+    coverage: {
+        scannedFiles: number;
+        skippedFiles: string[];
+        unsupportedLanguages: string[];
+        historyStatus?: 'available' | 'unavailable' | 'not-requested';
+    };
+    graphBasis: MaintenanceAnalysisInput['basis'] & {
+        stale: boolean;
+    };
+    ablation: {
+        graphOff: AblationArm;
+        current: AblationArm;
+        enhanced: AblationArm;
+    };
+    evidenceDigest: string;
+}
+/**
+ * Decode a pathname as git prints it in `--name-only`/`--name-status` output. With the default
+ * `core.quotepath=true`, any non-ASCII or control byte makes git wrap the name in double quotes and
+ * emit C-style escapes (`"src/\354\227\260.ts"`). Comparing that raw form against the scanner's
+ * real relative path never matches, which silently emptied the historical rationale while the
+ * provenance still claimed the history was `available`.
+ */
+export declare function unquoteGitPath(line: string): string;
+/**
+ * Fuse lexical localization, RTM ancestry, call-graph blast radius, test anchors, and history into a
+ * single immutable evidence contract. This core intentionally performs no I/O, so handlers can
+ * reproduce and compare an analysis from the exact same captured inputs.
+ */
+export declare function analyzeMaintenance(input: MaintenanceAnalysisInput): MaintenanceAnalysis;