@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/review/semantic-arm.d.ts

@@ -0,0 +1,271 @@
+import type { ScannedFile } from '../cpg/cpg-scanner';
+import type { Spec } from '../spec/spec-parser';
+/** Tokens of a file as the ranker sees it: its symbol names and its path. */
+export declare function fileTokens(f: ScannedFile): Set<string>;
+/**
+ * Inverse document frequency over the scanned corpus.
+ *
+ * Smoothed (`(N+1)/(df+1)`) and floored at zero: a term present in every file must be WEAK evidence,
+ * never negative evidence. Unsmoothed IDF would make it exactly 0 and let a file that matches only
+ * ubiquitous terms tie with a file that matches nothing, which reads as "no opinion" when the truth
+ * is "a little opinion".
+ */
+export declare function corpusIdf(scanned: readonly ScannedFile[]): Map<string, number>;
+export interface ArmHit {
+    file: string;
+    score: number;
+}
+/**
+ * Rank files by IDF-weighted term overlap.
+ *
+ * Symbol matches stay worth 3× a path match, as in the product's scorer — changing two things at
+ * once would leave the measurement unable to say which one moved. The only difference from the
+ * current arm is that each match is multiplied by how rare its term is in this corpus.
+ */
+export declare function rankIdf(issueText: string, scanned: readonly ScannedFile[], topN: number): ArmHit[];
+/** How much a term counts. The product's scorer is this arm with `() => 1`. */
+export type TermWeight = (term: string) => number;
+/**
+ * IDF, rescaled so the MEAN weight over the corpus vocabulary is 1.
+ *
+ * Without this the arm would not be a one-variable change. Raw IDF values sit well below 1 on a
+ * corpus of a few hundred files, so every lexical contribution shrinks at once while the spec-anchor
+ * bonus (+4/sqrt(anchors)) and the citation bonus (+20/sqrt(anchors)) keep their size — the arm would
+ * then be measuring how much the graph bonuses dominate, not how much term rarity helps. Rescaling
+ * keeps the lexical term's total magnitude comparable and changes only its DISTRIBUTION across
+ * terms, which is the hypothesis under test.
+ *
+ * An unseen term weighs exactly 1: a word absent from the corpus is not evidence against a file, and
+ * mapping it to 0 would silently delete the request's most distinctive vocabulary.
+ */
+export declare function normalisedIdf(scanned: readonly ScannedFile[]): Map<string, number>;
+/**
+ * The product's scorer with the term weight lifted out as a parameter.
+ *
+ * This mirrors `localizeIssue` deliberately and the mirror is load-bearing, so a test pins it: with
+ * `() => 1` this function must return the product's ranking and its scores EXACTLY. If someone
+ * changes the product's scoring and not this one, that test goes red rather than the replay quietly
+ * reporting a difference between rankers that is really a difference between vintages.
+ */
+export declare function rankWeighted(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, 
+/**
+ * @implements A-SPEC-352
+ * Weighted spec gate. Absent = the product's `overlap >= 2` count.
+ *
+ * Passed in here rather than reimplemented by the caller for a reason paid for three times: the
+ * first IDF arm hand-rolled a scorer and silently dropped the spec and citation bonuses; a probe
+ * of this very gate hand-rolled one again and dropped the citation path, whose +20 bonus is the
+ * largest single gain this repository has measured. Both produced confident, worthless numbers.
+ * Every arm goes through this function so the features it does NOT vary cannot go missing.
+ */
+gateThreshold?: number): ArmHit[];
+export interface ExpansionOptions {
+    /** How far to walk from a matched spec. 0 reproduces the unexpanded arm exactly. */
+    hops: number;
+    /** Weight multiplier per hop. 0 disables expansion; 1 would treat a neighbour like a hit. */
+    decay: number;
+}
+/**
+ * Rank with GraphRAG-style expansion over the spec graph.
+ *
+ * The gap this addresses is the one graph retrieval exists for: the answer does not contain the
+ * request's words, but it is the neighbour of something that does. The lexical layer scores a file
+ * only if the request's terms reach the file or a spec it anchors — one hop. A sibling requirement,
+ * written in different words for the same feature, is invisible however closely it is related.
+ *
+ * Deliberately weaker than a hit at every hop: the bonus is the matched-spec bonus times `decay^k`.
+ * A neighbour is evidence, not an answer, and if decay ever let it outrank a direct match the
+ * retrieval would be trading the answer for its neighbourhood. A test pins that ordering.
+ *
+ * Everything else is `rankWeighted` unchanged — the one-variable rule from A-SPEC-349 applies here
+ * too, or a win could not be attributed to expansion rather than to weighting.
+ */
+export declare function rankExpanded(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, opts: ExpansionOptions): ArmHit[];
+/**
+ * Which A-SPECs the request is taken to have matched — the entry point into the knowledge graph.
+ *
+ * The product's rule counts overlapping terms: two shared words admit a spec, one does not (unless
+ * the request is very short). That treats a shared `handler` exactly like a shared `quarantine`, and
+ * it costs more here than it does in file scoring: an admitted spec sprays its bonus over EVERY file
+ * anchoring it, so one wrongly-opened gate promotes a whole group of unrelated files at once.
+ *
+ * Weighing the overlap instead of counting it means a request has to bring either several ordinary
+ * words or one genuinely distinctive one. With `weight = () => 1` and `threshold = 2` this is the
+ * product's original rule exactly, which is what makes any measured difference attributable.
+ *
+ * A-SPEC only: files anchor A-SPECs, so admitting any other kind can never pull a file through the
+ * hop and would only overstate what influenced the ranking.
+ */
+export declare function matchedSpecsWeighted(issueText: string, specs: readonly Spec[], weight: TermWeight, threshold: number): string[];
+/**
+ * The spec bonus, damped by how much code the spec covers.
+ *
+ * The existing normalisation divides by how many anchors a FILE carries (A-SPEC-270) — it answers
+ * "how much of this file's identity is this spec?". It never asks the other question: "how much of
+ * this spec's territory is this file?". A spec spanning twenty files says little about any one of
+ * them; a spec covering one says a great deal, and today they pay the same +4.
+ *
+ * That asymmetry is invisible in a repository with hundreds of narrow specs and decisive in one with
+ * a few broad ones — which is exactly where the measured precision loss appeared (A-SPEC-362: on a
+ * 54-spec corpus the product loses Top-5 recall and Top-10 precision to plain word matching, and the
+ * weighting-only arm is indistinguishable from that baseline).
+ *
+ * sqrt, matching the existing normalisation's shape: a one-file spec is untaxed, a twenty-file spec
+ * is damped by ~4.5x rather than erased. Damping to zero would delete the very hop that carries all
+ * of this harness's measured advantage.
+ */
+export declare function rankBreadthDamped(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold?: number): ArmHit[];
+/**
+ * How much of the corpus carries an `@implements` anchor at all.
+ *
+ * The spec layer's evidence is only representative when a decent share of the tree is governed. If
+ * five files in a thousand carry anchors, matching one of their specs says something about those
+ * five and nothing about the other nine hundred and ninety-five — yet the bonus is paid at full
+ * strength and displaces lexically correct candidates.
+ */
+export declare function anchorCoverage(scanned: readonly ScannedFile[], specs?: readonly Spec[]): number;
+/**
+ * The spec bonus scaled by how much of the tree the spec layer actually covers.
+ *
+ * Measured on one repository with only the spec count varied (A-SPEC-364): 585 specs gave Top-10
+ * recall 0.770, but 146 gave 0.253 and 59 gave 0.264 — BELOW the 0.305 of no spec layer at all. A
+ * partly populated spec store is worse than an empty one, and every project that adopts Holmes
+ * passes through that valley on its way to the peak. jarvis, at 54 specs, is sitting in it.
+ *
+ * Scaling by coverage makes the layer fade in rather than switch on: at zero coverage the ranking is
+ * exactly the lexical arm (the floor a project starts from), and at full coverage the bonus is
+ * unchanged (the peak this repository measures). No threshold, because a threshold would create a
+ * cliff where authoring one more spec changes every ranking at once.
+ */
+export declare function rankCoverageAware(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold?: number): ArmHit[];
+/**
+ * The gate, chosen by whether the request names a spec at all.
+ *
+ * No single threshold serves both conditions. Measured over 60 point-in-time cases (A-SPEC-369):
+ *
+ *   threshold 1 — cited Top-10 recall 0.770, uncited 0.275 (a no-graph baseline gets 0.357)
+ *   threshold 4 — cited 0.743 and Top-1 0.333 → 0.283, uncited 0.349
+ *
+ * Under a citation, the named spec locates the request in the corpus, and the specs that merely
+ * share vocabulary with it are corroborated rather than speculative — the permissive gate pays. With
+ * no citation, those same matches are twenty-six unanchored guesses per case whose bonuses bury the
+ * lexical signal, and the strict gate keeps them out.
+ *
+ * The condition is read from the request itself, and only a citation the store can RESOLVE counts:
+ * a stray `A-SPEC-999` in a bug report must not unlock the permissive path.
+ */
+export declare function rankCitationConditioned(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, citedThreshold: number, uncitedThreshold: number): ArmHit[];
+/**
+ * Drop the lexically-matched specs when too many of them match.
+ *
+ * Conditioning on whether the request cited a spec repaired this repository and cost the second
+ * corpus its lead, because that corpus cites nothing and would always take the strict path. Both
+ * measurements point at the same underlying quantity: HOW MANY specs the request matched. jarvis
+ * matches 0.87 per case, this repository 26.6 (A-SPEC-367).
+ *
+ * One matching spec is a claim about where the request belongs. Twenty-six matching specs is a fact
+ * about the request's vocabulary — it was written in words the corpus uses everywhere — and their
+ * bonuses, spread over a hundred anchored files, bury the lexical ranking that would otherwise work.
+ *
+ * A citation is never capped: it names something rather than resembling it, and it is the one signal
+ * in this scorer measured to carry the localization result.
+ */
+export declare function rankCapped(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold: number, maxMatchedSpecs: number): ArmHit[];
+/**
+ * The cap, applied only to requests that named nothing.
+ *
+ * The two halves the measurements each found: a citation corroborates the specs that merely share
+ * vocabulary with the request, so with one present they help (dropping them cost Top-10 recall
+ * 0.770 → 0.743). Without one, a large number of matches is a fact about the request's wording
+ * rather than evidence, and their bonuses bury the lexical ranking (0.275 against a 0.357 baseline).
+ * A SMALL number of matches with no citation is still meaningful — that is the second corpus, at
+ * 0.87 matches per case, and capping it there threw away the modest lead it had.
+ *
+ * So: exempt cited requests, and cap only the uncited ones that matched more specs than a request
+ * can plausibly be about.
+ */
+export declare function rankUncitedCapped(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold: number, maxMatchedSpecs: number): ArmHit[];
+/**
+ * One `calls` hop out from the lexical hits, added at a discount.
+ *
+ * With no citation the spec layer is off and the ranking is exactly what grepping the request's
+ * words would produce. The call graph is the only structure left that could beat it, and A-SPEC-318
+ * measured the opportunity: 13 missed files one `calls` hop away, all 58 hop edges being calls, none
+ * imports or inherits. That was measured under cited requests, where the spec layer had already
+ * found most of the answer — uncited, the lexical hits are the only seed, so the hop has more to add.
+ *
+ * Half the seed's score, and never more: a callee is evidence about the seed's neighbourhood, not
+ * about itself. If a hop could outrank a direct hit, the ranking would be trading the answer for its
+ * surroundings, which is the failure the spec-graph expansion arm was rejected for.
+ */
+export declare function rankWithCallHop(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold: number, maxMatchedSpecs: number, 
+/** @implements A-SPEC-394 — use import edges to bind names the global map calls ambiguous. */
+importAware?: boolean): ArmHit[];
+/**
+ * @implements A-SPEC-395
+ * The product's scorer with each layer switchable, so a cost can be attributed instead of guessed.
+ *
+ * On history sampled away from the benchmarker's own commits, this ranking scores BELOW the no-graph
+ * baseline (Top-10 recall 0.618 against 0.668). The contaminated slice showed the opposite, so the
+ * regression is newly visible and it is shipped. Four layers sit between the two — corpus IDF
+ * weighting, the spec gate and anchor bonus, the citation bonus, and the vendored demotion — and
+ * turning them off one at a time is the only way to learn which one costs.
+ */
+export interface AblationOptions {
+    idf: boolean;
+    specBonus: boolean;
+    vendorDemotion: boolean;
+}
+export declare function ablate(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, opts: AblationOptions): ArmHit[];
+/**
+ * @implements A-SPEC-396
+ * Limit how many files each matched spec may lift.
+ *
+ * The ablation isolated the cost: turning the spec bonus off restores the baseline exactly, so that
+ * layer buys Top-1 (0.244 → 0.267 here, 0.400 → 0.433 on jarvis) and sells precision (0.156 → 0.104).
+ *
+ * Three earlier attempts all changed WHICH specs are admitted — breadth damping, coverage scaling,
+ * a cap on matched specs — and all three were rejected. This changes something else: once a spec is
+ * admitted, every file anchoring it rises together, and that simultaneity is the shape of the
+ * precision loss. Ranking a spec's anchored files by their own lexical evidence and lifting only the
+ * strongest few keeps the top of the list while leaving the tail alone.
+ *
+ * The cost is explicit: a file with no lexical evidence can no longer be lifted by its spec alone,
+ * so the layer loses the files it uniquely contributed. Whether that trade is positive is the
+ * measurement, not the assumption.
+ */
+export declare function rankSpecLiftLimited(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold: number, liftPerSpec: number): ArmHit[];
+/**
+ * @implements A-SPEC-397
+ * The spec bonus with its magnitude as a parameter.
+ *
+ * Four arms failed to recover the 0.052 of precision the layer costs, and each changed a different
+ * thing: which specs are admitted (breadth damping, coverage scaling, a cap on matches) and how far
+ * an admitted one reaches (the lift limit). Magnitude was never touched.
+ *
+ * The default is 4 per anchor against a lexical symbol hit worth 3 and a path hit worth 1, so a
+ * single matched spec outweighs a symbol match — a file whose only evidence is one anchor can
+ * outrank a file whose name actually contains the request's words. That is a plausible source of the
+ * tail pollution and it is the last untried one.
+ *
+ * Reducing it should cost Top-1 as it recovers precision, so both are reported: a setting that fixes
+ * one by destroying the other is not a fix.
+ */
+export declare function rankWithBonusScale(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold: number, bonusScale: number): ArmHit[];
+/**
+ * @implements A-SPEC-398
+ * The spec bonus may REORDER, but may not ADMIT.
+ *
+ * Five arms failed to recover the 0.052 of precision the spec layer costs, and counting the lists
+ * showed why none of them could: the baseline returns 7.09 files per case and the product returns
+ * 9.27, filling all ten slots in 36 of 45 cases against the baseline's 16. The layer is not ranking
+ * the same set differently — it is **adding about two files per case**, and those additions are
+ * mostly wrong. Every arm so far reordered or rescaled; none declined to add.
+ *
+ * So: a file with lexical evidence keeps its bonus and can move up. A file whose only evidence is an
+ * anchor does not enter the list at all.
+ *
+ * The cost is the one thing the spec layer uniquely did — reaching a file the request's words never
+ * touch. That is a real loss and the measurement has to weigh it, not assume it away.
+ */
+export declare function rankSpecReorderOnly(issueText: string, scanned: readonly ScannedFile[], specs: readonly Spec[], topN: number, weight: TermWeight, gateThreshold: number): ArmHit[];