@davesheffer/hunch 1.45.1 → 1.45.2

package/dist/core/taskSelection.js

@@ -142,6 +142,55 @@ export function promptPaths(prompt, root) {
     }
     return [...out];
 }
+const ID_PREFIX = "id:";
+const MIN_IDENTIFIER_CHARS = 5;
+const IDENTIFIER_WEIGHT = 2;
+const CAMEL_IDENTIFIER = /(?<![A-Za-z0-9])[A-Za-z0-9]*(?:[a-z][A-Z]|[A-Z]{2,}[a-z])[A-Za-z0-9]*/g;
+const SEPARATED_IDENTIFIER = /(?<![A-Za-z0-9])[A-Za-z][A-Za-z0-9]*(?:[_.\-][A-Za-z0-9]+)+/g;
+const isCompound = (word) => /[a-z][A-Z]|[A-Z]{2,}[a-z]|_/.test(word);
+const camelParts = (word) => word.split(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/).length;
+/** Compound identifiers in raw text (camel/Pascal, snake, dotted, kebab), lowercased with
+ *  separators removed and marked `id:` so they never collide with word tokens. A dotted
+ *  name also yields its last segment when that is itself compound (`dbo.ShowInForms` ->
+ *  `id:dboshowinforms`, `id:showinforms`). `lexicalTokens` splits these into common words
+ *  that the rare-term filter discards; the whole identifier is the rare, discriminating term.
+ *  STRONG identifiers (3+ camel parts, or `_`/`.` between alphanumerics) may qualify a record
+ *  alone; two-part camel words (GitHub, useEffect) are common prose and count as one word. */
+function scanIdentifiers(text) {
+    const out = new Map();
+    const add = (raw, strong) => {
+        const id = raw.replace(/[_.\-]/g, "").toLowerCase();
+        if (id.length >= MIN_IDENTIFIER_CHARS)
+            out.set(ID_PREFIX + id, (out.get(ID_PREFIX + id) ?? false) || strong);
+    };
+    for (const m of text.match(CAMEL_IDENTIFIER) ?? [])
+        add(m, camelParts(m) >= 3);
+    for (const m of text.match(SEPARATED_IDENTIFIER) ?? []) {
+        if (/^v?\d+(?:\.\d+)+/i.test(m))
+            continue; // version numbers
+        if (m.includes(".")) {
+            const last = m.slice(m.lastIndexOf(".") + 1);
+            if (/^[a-z0-9]{1,8}$/.test(last))
+                continue; // file extension: paths own those
+            add(m, true);
+            if (isCompound(last))
+                add(last, true);
+        }
+        else if (m.includes("_")) {
+            const parts = m.split(/[_\-]/);
+            if (m.replace(/[_\-]/g, "").length >= 6 && parts.some((part) => part.length >= 3))
+                add(m, true);
+        }
+        else if (/(?<!^|-)[A-Z0-9]/.test(m)) {
+            add(m, false); // kebab: a capital/digit past the first letter of a part; plain prose ("Pre-commit") is not an identifier
+        }
+    }
+    return out;
+}
+export function identifierTokens(text) {
+    return new Set(scanIdentifiers(text).keys());
+}
+const termTokens = (text) => new Set([...lexicalTokens(text), ...identifierTokens(text)]);
 /** Score live records against one prompt. Text fields per kind (title + rationale):
  *  decision title/context/decision; bug title/symptom/root_cause; constraint
  *  statement/rationale; finding title/observation. Path anchors: decision
@@ -149,7 +198,10 @@ export function promptPaths(prompt, root) {
  *  ties break on the builder profile's kind/severity score in delivery.ts. */
 export function selectForTask(records, promptText, opts = {}) {
     const k = Math.max(0, opts.k ?? DEFAULT_K);
-    const taskTerms = lexicalTokens(promptText ?? "");
+    // Stack-frame lines name library APIs (writeFileSync, processTicksAndRejections), not the task:
+    // keep their words, but extract no identifiers from them.
+    const promptIdentifiers = (promptText ?? "").split(/\r?\n/).filter((line) => !/^\s*at\s+\S/.test(line) && !/node:internal|\(node:/.test(line)).join("\n");
+    const taskTerms = new Set([...lexicalTokens(promptText ?? ""), ...identifierTokens(promptIdentifiers)]);
     // Without an existence check (pure/offline) only a slashed token is trusted as a
     // path: "e.g.", "Node.js" or "v1.2" would otherwise match a broad glob.
     const paths = promptPaths(promptText ?? "", opts.root).filter((p) => opts.pathExists ? opts.pathExists(p) : p.includes("/"));
@@ -159,7 +211,7 @@ export function selectForTask(records, promptText, opts = {}) {
     // Tokenize every record once: the same tokens feed the document frequency and the score.
     const candidates = [];
     const consider = (id, kind, title, text, anchors, priority, listable) => {
-        candidates.push({ id, kind, title, tokens: lexicalTokens(text.join(" ")), anchors, priority, listable });
+        candidates.push({ id, kind, title, tokens: termTokens(text.join(" ")), anchors, priority, listable });
     };
     for (const c of records.constraints) {
         consider(c.id, "constraint", c.statement, [c.statement, c.rationale], c.scope, base.constraints + SEVERITY[c.severity] * 10 + (c.provenance.confidence ?? 0), c.severity !== "blocking");
@@ -174,20 +226,47 @@ export function selectForTask(records, promptText, opts = {}) {
         consider(f.id, "finding", f.title, [f.title, f.observation], f.affected_files, base.findings + SEVERITY[f.severity] * 10, true);
     }
     const dfCap = Math.max(MIN_DF_CAP, Math.ceil(DF_CAP_RATIO * candidates.length));
-    const rareTerms = [...taskTerms].filter((term) => candidates.filter((c) => c.tokens.has(term)).length <= dfCap);
+    const df = new Map();
+    for (const c of candidates)
+        for (const term of c.tokens)
+            df.set(term, (df.get(term) ?? 0) + 1);
+    const strongIds = new Set([...scanIdentifiers(promptIdentifiers)].filter(([, strong]) => strong).map(([term]) => term));
+    const rareTerms = new Map();
+    for (const term of taskTerms) {
+        const n = df.get(term) ?? 0;
+        if (n > dfCap)
+            continue;
+        // Integer weights so equal sums tie exactly and fall through to the priority tiebreak.
+        const idf = Math.round(Math.log(1 + candidates.length / Math.max(1, n)) * 1000);
+        // Only a strong identifier that is near-unique (df <= MIN_DF_CAP) counts, at x2, and qualifies alone.
+        // Weak ones (GitHub, useEffect) add nothing: their parts are already counted as words.
+        const strong = strongIds.has(term) && n <= MIN_DF_CAP;
+        if (term.startsWith(ID_PREFIX) && !strong)
+            continue;
+        rareTerms.set(term, { weight: strong ? idf * IDENTIFIER_WEIGHT : idf, strong });
+    }
     const scored = [];
     for (const { tokens, anchors, ...rest } of candidates) {
-        let terms = 0;
-        for (const term of rareTerms)
-            if (tokens.has(term))
-                terms++;
+        let words = 0;
+        let identifiers = 0;
+        let termScore = 0;
+        for (const [term, { weight, strong }] of rareTerms) {
+            if (!tokens.has(term))
+                continue;
+            if (strong)
+                identifiers++;
+            else
+                words++;
+            termScore += weight;
+        }
         const pathHits = paths.filter((p) => anchors.some((anchor) => pathMatchesGlob(p, anchor))).length;
-        if (pathHits > 0 || terms >= MIN_DISTINCT_TERMS)
-            scored.push({ ...rest, pathHits, terms });
+        // One rare identifier alone qualifies (it counts double); a lone rare word does not.
+        if (pathHits > 0 || words + IDENTIFIER_WEIGHT * identifiers >= MIN_DISTINCT_TERMS)
+            scored.push({ ...rest, pathHits, termScore });
     }
     // A record anchored to more of the files the prompt names outranks one that
-    // shares a single (often hub) file with it; rare terms break the remaining ties.
-    scored.sort((a, b) => b.pathHits - a.pathHits || b.terms - a.terms || b.priority - a.priority || a.id.localeCompare(b.id));
+    // shares a single (often hub) file with it; idf-weighted rare terms break the remaining ties.
+    scored.sort((a, b) => b.pathHits - a.pathHits || b.termScore - a.termScore || b.priority - a.priority || a.id.localeCompare(b.id));
     return {
         qualifying: scored.map((s) => s.id),
         top: scored.filter((s) => s.listable).slice(0, k).map(({ id, kind, title }) => ({ id, kind, title })),

package/dist/core/whyRecord.d.ts

@@ -0,0 +1,47 @@
+/** `hunch_why(<record id>)` (issue #474): every brief line Hunch delivers ends in
+ *  `hunch_why("dec_…")`, so why() must resolve a record id, not only a path/symbol.
+ *  The lookup lives in HunchStore.why(); this module holds the id shape and the one
+ *  renderer the MCP tool and the CLI share, so the two surfaces cannot drift apart. */
+import type { Bug, Component, Constraint, Decision, Finding } from "./types.js";
+/** Targets why() tries as a record id first. Generated ids are `<prefix>_<hex>`
+ *  (shortHash), but hand-written/imported ids (`dec_session_transport`) are valid too. */
+export declare const WHY_RECORD_ID: RegExp;
+/** The generated id shape: only a miss on THIS shape is reported as "No record <id>";
+ *  any other miss (e.g. a symbol named `bug_handler`) falls through to path/symbol lookup. */
+export declare const WHY_GENERATED_ID: RegExp;
+/** One link of a decision's supersession chain, oldest first. */
+export interface WhyChainLink {
+    id: string;
+    status: string;
+    title: string;
+}
+export type WhyRecord = {
+    kind: "decision";
+    record: Decision;
+    chain: WhyChainLink[];
+} | {
+    kind: "constraint";
+    record: Constraint;
+} | {
+    kind: "bug";
+    record: Bug;
+} | {
+    kind: "finding";
+    record: Finding;
+} | {
+    kind: "component";
+    record: Component;
+};
+/** The by-id half of a WhyResult: `record` is null when no visible record has the id
+ *  (or, with `asOf`, none was in force at that instant). */
+export interface WhyById {
+    id: string;
+    record: WhyRecord | null;
+    asOf?: string;
+}
+/** Per-list cap in hunch_why output, and the "what was withheld" note after a capped
+ *  list — shared with the path/symbol view in the MCP server. */
+export declare const WHY_CAP = 6;
+export declare const more: (total: number, cap: number, hint?: string) => string;
+/** Plain-text detail lines for a record looked up by id. */
+export declare function formatWhyRecord(byId: WhyById): string[];

package/dist/core/whyRecord.js

@@ -0,0 +1,105 @@
+/** Targets why() tries as a record id first. Generated ids are `<prefix>_<hex>`
+ *  (shortHash), but hand-written/imported ids (`dec_session_transport`) are valid too. */
+export const WHY_RECORD_ID = /^(dec|con|bug|cmp|fnd)_[A-Za-z0-9_-]+$/;
+/** The generated id shape: only a miss on THIS shape is reported as "No record <id>";
+ *  any other miss (e.g. a symbol named `bug_handler`) falls through to path/symbol lookup. */
+export const WHY_GENERATED_ID = /^(dec|con|bug|cmp|fnd)_[0-9a-f]{6,}$/;
+/** Per-list cap in hunch_why output, and the "what was withheld" note after a capped
+ *  list — shared with the path/symbol view in the MCP server. */
+export const WHY_CAP = 6;
+export const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} more${hint ? ` — ${hint}` : ""})` : "";
+const PROSE_CHARS = 600;
+const ITEM_CHARS = 240;
+const clip = (text, max = PROSE_CHARS) => {
+    const flat = text.replace(/\s+/g, " ").trim();
+    // By code point, so a cut never splits a surrogate pair (emoji, astral CJK).
+    const chars = Array.from(flat);
+    return chars.length > max ? `${chars.slice(0, max - 1).join("")}…` : flat;
+};
+const list = (label, items) => items.length ? [`  ${label}:`, ...items.slice(0, WHY_CAP).map((i) => `    - ${clip(i, ITEM_CHARS)}`), ...(items.length > WHY_CAP ? [`    ${more(items.length, WHY_CAP).trim()}`] : [])] : [];
+const files = (label, items) => items.length ? [`  ${label}: ${items.slice(0, WHY_CAP).join(", ")}${items.length > WHY_CAP ? ` …(+${items.length - WHY_CAP} more)` : ""}`] : [];
+/** Plain-text detail lines for a record looked up by id. */
+export function formatWhyRecord(byId) {
+    const hit = byId.record;
+    if (!hit) {
+        return [byId.asOf
+                ? `No record ${byId.id} as of ${byId.asOf} (it did not exist or was not in force then).`
+                : `No record ${byId.id} (no decision, constraint, bug, finding, or component has that id).`];
+    }
+    const out = [];
+    switch (hit.kind) {
+        case "decision": {
+            const d = hit.record;
+            out.push(`DECISION ${d.id} [${d.status}] ${d.title}`);
+            if (d.topic)
+                out.push(`  topic: ${d.topic}`);
+            if (d.decision)
+                out.push(`  decision: ${clip(d.decision)}`);
+            if (d.context)
+                out.push(`  context: ${clip(d.context)}`);
+            out.push(...list("rejected alternatives", d.alternatives_rejected), ...list("consequences", d.consequences));
+            out.push(...files("files", d.related_files));
+            if (d.supersedes)
+                out.push(`  supersedes: ${d.supersedes}`);
+            if (d.superseded_by)
+                out.push(`  superseded by: ${d.superseded_by}`);
+            if (hit.chain.length > 1) {
+                // A WHY_CAP window that always holds the queried decision: the newest links
+                // when it is near the end, otherwise starting at it.
+                const at = Math.max(0, hit.chain.findIndex((c) => c.id === d.id));
+                const start = Math.max(0, Math.min(at, hit.chain.length - WHY_CAP));
+                const end = Math.min(hit.chain.length, start + WHY_CAP);
+                out.push("  chain (oldest first):");
+                if (start > 0)
+                    out.push(`    …(+${start} earlier)`);
+                out.push(...hit.chain.slice(start, end).map((c) => `    - ${c.id} [${c.status}] ${clip(c.title, ITEM_CHARS)}${c.id === d.id ? " ←" : ""}`));
+                if (end < hit.chain.length)
+                    out.push(`    …(+${hit.chain.length - end} later)`);
+            }
+            break;
+        }
+        case "constraint": {
+            const c = hit.record;
+            out.push(`CONSTRAINT ${c.id} [${c.severity}/${c.status}] ${clip(c.statement)}`);
+            out.push(...(c.scope.length ? files("scope", c.scope) : ["  scope: repo"]));
+            if (c.rationale)
+                out.push(`  rationale: ${clip(c.rationale)}`);
+            if (c.source_decision)
+                out.push(`  source decision: ${c.source_decision}`);
+            break;
+        }
+        case "bug": {
+            const b = hit.record;
+            out.push(`BUG ${b.id} [${b.status}/${b.severity}] ${b.title}`);
+            if (b.symptom)
+                out.push(`  symptom: ${clip(b.symptom)}`);
+            if (b.root_cause)
+                out.push(`  root cause: ${clip(b.root_cause)}`);
+            if (b.lineage.fixed_commit)
+                out.push(`  fixed in: ${b.lineage.fixed_commit}`);
+            out.push(...files("files", b.affected_files));
+            break;
+        }
+        case "finding": {
+            const f = hit.record;
+            out.push(`FINDING ${f.id} [${f.triage}/${f.severity}] ${f.title}`);
+            if (f.observation)
+                out.push(`  observation: ${clip(f.observation)}`);
+            out.push(...list("evidence", f.evidence));
+            out.push(...files("files", f.affected_files));
+            break;
+        }
+        case "component": {
+            const c = hit.record;
+            out.push(`COMPONENT ${c.id} [${c.kind}/${c.status}] ${c.name}`);
+            if (c.responsibility)
+                out.push(`  responsibility: ${clip(c.responsibility)}`);
+            out.push(...files("paths", c.paths));
+            break;
+        }
+    }
+    const p = hit.record.provenance;
+    out.push(`  provenance: ${p.source}, confidence ${p.confidence}`);
+    return out;
+}
+//# sourceMappingURL=whyRecord.js.map

package/dist/extractors/git.d.ts

@@ -19,6 +19,29 @@ export declare function gitWorktreeRoot(cwd: string): string | null;
  * `.hunch-private/.hunch` can never stage or commit into the code repository. */
 export declare function isGitRepoRoot(cwd: string): boolean;
 export declare function gitNullDevice(): string;
+export interface HunchPullFailureDetail {
+    /** The mergeRemote/pull step that failed (e.g. "ls-remote", "fetch", "worktree-clean"). */
+    step: string;
+    /** Node error code (ETIMEDOUT), killing signal, or `exit <status>`. */
+    code?: string;
+    /** Last 400 characters of git's stderr, when captured. */
+    stderr?: string;
+}
+/** Captured git stderr can echo a remote URL with embedded credentials; strip the
+ *  userinfo (`://user:pass@`, `://token@`) before it is stored or printed. */
+export declare function redactUrlUserinfo(text: string): string;
+/** One-line rendering for logs and refusal messages: `step: fetch, ETIMEDOUT, fatal: ...`. */
+export declare function describePullFailure(detail: HunchPullFailureDetail | undefined): string;
+/** HUNCH_PULL_GIT_TIMEOUT_MS: per-process override of the read-side pull's DEFAULT
+ *  remote budget (ls-remote/fetch/merge) for slow runners — a caller's explicit
+ *  timeoutMs still wins; ignored unless a positive integer. */
+export declare function pullGitTimeoutOverride(): number | undefined;
+/** Remote budget for one read-side pull: an explicit caller budget always wins;
+ *  HUNCH_PULL_GIT_TIMEOUT_MS only replaces the 5s default. */
+export declare function pullRemoteTimeoutMs(callerMs?: number): number;
+/** Budget for the bounded local git helpers (status, rev-parse, ls-tree): 2s by
+ *  default, scaled with HUNCH_PULL_GIT_TIMEOUT_MS to max(2s, override / 2.5). */
+export declare function pullLocalGitTimeoutMs(): number;
 /** Compare physical directory identity before path text. Git for Windows can
  * return an 8.3/short or differently-cased spelling for the same top-level
  * directory that Node reached through its long path. A nonzero file ID keeps
@@ -111,6 +134,7 @@ export interface HunchRemoteContract {
     ref: string;
     verify: () => boolean;
 }
+export declare const DEFAULT_READ_REMOTE_TIMEOUT_MS = 5000;
 export declare function commitAndPushHunch(hunchDir: string, message: string, opts: HunchCommitOptions): "pushed" | "committed" | null;
 /** True when `rel` is tracked with no staged or unstaged changes (untracked counts as
  *  dirty, so a doc the user never committed is never swept into a memory commit). */
@@ -138,6 +162,14 @@ export interface PullHunchOptions {
     allowUnrelatedHistories?: boolean;
 }
 export declare function pullHunchStatus(hunchDir: string, opts?: PullHunchOptions): HunchPullStatus;
+export interface HunchPullResult {
+    status: HunchPullStatus;
+    /** Present on "failed": which step failed and git's own reason (issue #482). */
+    detail?: HunchPullFailureDetail;
+}
+/** pullHunchStatus plus a diagnosable reason for a "failed" pull. The remote budget is
+ *  the caller's (default 5s) unless HUNCH_PULL_GIT_TIMEOUT_MS overrides it. */
+export declare function pullHunchStatusDetailed(hunchDir: string, opts?: PullHunchOptions): HunchPullResult;
 export declare function pullHunch(hunchDir: string): boolean;
 /** Explicit retry path for a clean overlay that already has a local memory commit
  *  stranded by an earlier offline/rejected push. Unlike commitAndPushHunch this