@davesheffer/hunch 1.41.6 → 1.42.0

package/dist/core/siblingfix.d.ts

@@ -0,0 +1,124 @@
+export interface SiblingCommit {
+    sha: string;
+    subject: string;
+    fix: boolean;
+    /** The commit's changed lines inside the sibling, in hunk order, `+`/`-` prefixed. */
+    change: string[];
+    /** Test files the same commit changed: the proof that came with the fix. */
+    tests?: string[];
+}
+export interface SiblingLesson {
+    symbol: string;
+    file: string;
+    line: number;
+    sibling: string;
+    siblingFile: string;
+    siblingStart: number;
+    siblingEnd: number;
+    similarity: number;
+    commits: SiblingCommit[];
+}
+export interface SiblingOptions {
+    /** Candidate pairs whose history is inspected (best similarity first). */
+    maxPairs?: number;
+    /** Lessons returned. */
+    maxLessons?: number;
+    /** Per git call; each call is also capped by what is left of `budgetMs`. */
+    timeoutMs?: number;
+    /** Wall-clock budget for the whole computation; past it the result is incomplete. */
+    budgetMs?: number;
+    /** Cap on the no-index inventory scan (tests force truncation with it). */
+    inventoryBudgetMs?: number;
+    /** Set false to bypass the .hunch-cache read/write (tests). */
+    cache?: boolean;
+    /** Clock for the incomplete-run retry window (tests). */
+    now?: number;
+}
+interface IndexedSymbol {
+    file: string;
+    name: string;
+    kind: string;
+}
+/** `isHunchProviderHook` → {is, hunch, provider, hook}. */
+export declare function nameTokens(name: string): Set<string>;
+/** Identifier-ish tokens of a body's CODE, including those inside regex/string
+ *  literals. Comment lines are dropped: a fix usually adds an explanation, and
+ *  its prose would otherwise swamp the shared shape. */
+export declare function codeTokens(text: string): Set<string>;
+/** Overlap coefficient: shared / smaller set. A hardened copy grows, so
+ *  containment — not Jaccard — is what "same shape" means for bodies. */
+export declare function overlap(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+export declare function jaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+export declare function isFixSubject(subject: string): boolean;
+export interface LineLogCommit {
+    sha: string;
+    subject: string;
+    added: string[];
+    removed: string[];
+    /** Added and removed lines in hunk order, `+`/`-` prefixed. */
+    diff: string[];
+    /** Largest old/new line span of any hunk — how far git's range reached. */
+    span: number;
+    /** Every hunk starts from nothing (`@@ -0,0 …`): the function was created here. */
+    created: boolean;
+}
+/** Parse `git log -L … --format=%x1eC %H%x1f%s` output. */
+export declare function parseLineLog(output: string): LineLogCommit[];
+/** A commit whose removed and added lines differ only in whitespace/line
+ *  endings (a reformat, a CRLF→LF sweep, a re-indent) changed nothing. */
+export declare function isSubstantive(commit: LineLogCommit): boolean;
+/** git follows a line range backwards only while it can map it. A whole-file
+ *  rewrite (a line-ending sweep, a reformat) breaks the mapping: from that
+ *  commit on, every hunk spans the whole file and nothing in it is attributable
+ *  to the function. Keep the history before that commit and report where the
+ *  mapping was lost. */
+export declare function attributable(commits: readonly LineLogCommit[], fnLines: number): {
+    kept: LineLogCommit[];
+    lostAt: string | null;
+};
+/** Candidate scans run (tests: a cache hit must not run one). */
+export declare const siblingCounters: {
+    candidateScans: number;
+    lessonComputes: number;
+};
+/** Sibling-fix lessons for one repo-relative file. */
+export declare function siblingLessonsFor(root: string, file: string, symbols: readonly IndexedSymbol[], options?: SiblingOptions): SiblingLesson[];
+/** Stable identity for hook dedupe: which fixes were surfaced, not the wording. */
+export declare function siblingLessonsIdentity(lessons: readonly SiblingLesson[]): string;
+/** A commit's diff inside the function, blank-only lines dropped, capped
+ *  (a fix commit gets the larger cap). */
+export declare function changeLines(diff: readonly string[], fix?: boolean): string[];
+export declare const SIBLING_HEADING = "## \u26A0 Fix not carried to this function";
+/** Callers of each lesson's function, by lesson symbol: names of functions in
+ *  the same working-tree file whose body calls it. */
+export type SiblingCallers = ReadonlyMap<string, readonly string[]>;
+/** Written to be acted on, not skimmed: an agent reads "possible, heuristic,
+ *  elsewhere" as out of scope and moves on (trap-310: three deliveries, zero
+ *  follow-ups). So the lesson says what this copy lacks, which code here runs
+ *  through it, and asks for an explicit outcome. It stays advisory: "does not
+ *  apply, because …" is always an accepted answer. */
+/** A blocking invariant whose scope covers the lesson's file. */
+export interface SiblingInvariant {
+    id: string;
+    statement: string;
+}
+/** "Pre-existing" and "outside this task" are how an agent that agrees with the
+ *  lesson still leaves it (trap-310 v4: gap confirmed, reported, not fixed).
+ *  The change in hand runs through the copy, so only "cannot reach it" or
+ *  "already handled" count as not applying. */
+export declare const NOT_A_REASON = "\"Pre-existing\" or \"outside this task\" does not count: the change you are making runs through this copy, so leaving it ships the gap again inside your change.";
+export declare function renderSiblingLessons(lessons: readonly SiblingLesson[], callers?: SiblingCallers, invariants?: readonly SiblingInvariant[]): string;
+/** Hash of the function's current body, or null when it cannot be found. A
+ *  changed hash means the agent touched the function after the lesson. */
+export declare function functionBodyHash(root: string, file: string, symbol: string): string | null;
+export interface SiblingGrounding {
+    text: string;
+    identity: string;
+    lessons: SiblingLesson[];
+    callers: SiblingCallers;
+}
+/** Grounding-path entry: the rendered block plus its dedupe identity for one
+ *  repo-relative file. Never throws — a parser load failure or a git error
+ *  means no sibling lessons, not a failed edit hook. */
+export declare function siblingGrounding(root: string, file: string, symbols: readonly IndexedSymbol[], invariants?: readonly SiblingInvariant[]): SiblingGrounding;
+export {};