@davesheffer/hunch 1.41.6 → 1.43.0

package/dist/core/shellwrites.js

@@ -0,0 +1,131 @@
+/** Files a shell command wrote.
+ *
+ * Pre-edit grounding keys on the host's edit tools (Edit/Write/apply_patch).
+ * An agent that edits through the shell — a `python` heredoc, `sed -i`, `perl
+ * -pi`, a PowerShell `Set-Content` — never passes through them, so the file it
+ * changed arrives with no grounding at all. The shell tool's post-execution
+ * hook sees every command, but not what the command touched; parsing arbitrary
+ * shell for write targets is guesswork.
+ *
+ * Instead: fingerprint the working tree's dirty files (`git status`, then
+ * mtime+size) per session, repository and agent. A prompt and every tool call refresh
+ * the fingerprint; after a shell command, a dirty file whose fingerprint moved
+ * was written by that command. Deterministic, shell-agnostic, and bounded by the
+ * dirty set (never a tree walk). Any failure yields no files — never an error. */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Dirty paths fingerprinted; beyond it the rest are ignored (a vendored
+ *  untracked tree must not make every command slow). */
+const MAX_PATHS = 2000;
+/** Hunch's own state: written by the hook itself and by capture tools. */
+const OWN_STATE = /^\.hunch(?:-cache)?\//;
+/** Concurrent subagents share the session but not their commands: each keeps
+ *  its own baseline, keyed by its agent id (hashed with the rest, never kept
+ *  raw) like the pre-edit dedupe. No agent id keeps the session's baseline. */
+function snapshotFile(root, sessionId, agentId) {
+    const key = createHash("sha256").update(`${sessionId}\u0000${root}${agentId ? `\u0000${agentId}` : ""}`).digest("hex").slice(0, 24);
+    // Same directory as the session injection cache: its sweep drops stale files.
+    return join(tmpdir(), "hunch-hookcache", `shell-${key}.json`);
+}
+/** Repo-relative dirty paths (tracked changes and untracked files), NUL-safe. */
+function dirtyPaths(root) {
+    let raw;
+    try {
+        raw = execFileSync("git", ["-C", root, "status", "--porcelain=v1", "-z", "--untracked-files=all"], {
+            encoding: "utf8",
+            timeout: 2_000,
+            maxBuffer: 8_000_000,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
+        });
+    }
+    catch {
+        return null;
+    }
+    // Porcelain paths are relative to the git toplevel, which can sit above the
+    // Hunch root (a package inside a monorepo): re-relativize, drop the outside.
+    let prefix = "";
+    try {
+        prefix = execFileSync("git", ["-C", root, "rev-parse", "--show-prefix"], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    const fields = raw.split("\u0000");
+    for (let i = 0; i < fields.length && out.length < MAX_PATHS; i++) {
+        const entry = fields[i];
+        if (entry.length < 4)
+            continue;
+        const status = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (path.startsWith(prefix))
+            out.push(path.slice(prefix.length));
+        // A rename/copy entry is followed by its source path.
+        if (status.includes("R") || status.includes("C"))
+            i++;
+    }
+    return out;
+}
+function fingerprint(root) {
+    const paths = dirtyPaths(root);
+    if (!paths)
+        return null;
+    const fp = {};
+    for (const p of paths) {
+        if (OWN_STATE.test(p))
+            continue;
+        try {
+            const st = statSync(join(root, p));
+            if (st.isFile())
+                fp[p] = `${st.mtimeMs}:${st.size}`;
+        }
+        catch { /* deleted: nothing to ground */ }
+    }
+    return fp;
+}
+function load(file) {
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+function save(file, fp) {
+    try {
+        mkdirSync(join(tmpdir(), "hunch-hookcache"), { recursive: true });
+        writeFileSync(file, JSON.stringify(fp));
+    }
+    catch { /* the next refresh retries */ }
+}
+/** Record the working tree as it stands, so later shell writes are measured
+ *  from here (a prompt, or any tool call that is not a shell command). */
+export function refreshShellBaseline(root, sessionId, agentId) {
+    if (!sessionId)
+        return;
+    const fp = fingerprint(root);
+    if (fp)
+        save(snapshotFile(root, sessionId, agentId), fp);
+}
+/** Repo-relative files the shell command that just ran wrote (created or
+ *  modified), and the baseline moves forward. Empty without a baseline: a
+ *  session's first observation cannot tell its own writes from earlier ones. */
+export function shellWrittenFiles(root, sessionId, agentId) {
+    if (!sessionId)
+        return [];
+    const file = snapshotFile(root, sessionId, agentId);
+    const before = load(file);
+    const now = fingerprint(root);
+    if (!now)
+        return [];
+    save(file, now);
+    if (!before)
+        return [];
+    return Object.keys(now).filter((p) => before[p] !== now[p]).sort();
+}
+//# sourceMappingURL=shellwrites.js.map

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 {};