@davesheffer/hunch 1.45.1 → 1.46.0

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