@davesheffer/hunch 1.38.0 → 1.39.0

package/dist/core/workspace.js

@@ -0,0 +1,335 @@
+/**
+ * Workspace ledger — one record per MACHINE per repository describing that machine's
+ * git worktrees and local branches, with deterministic merged verdicts
+ * (docs/workspace-ledger.md). A LEAF module (zod + ids + provenance only) so types.ts
+ * can register the kind without a cycle, like stateRecords.ts.
+ *
+ * Security posture, in code: the schema is `.strict()` with bounded lengths, every
+ * branch name must be a git-valid ref component, every free-text field passes the
+ * credential filter, and NOTHING here reads a record back as authority — the
+ * aggregation below produces DISPLAY rows and a recommended action; `prune --apply`
+ * (Phase 3) re-snapshots live git and never acts on a stored record.
+ */
+import { z } from "zod";
+import { shortHash } from "./ids.js";
+import { ProvenanceSchema, isCredentialFreeValue } from "./provenance.js";
+export const WORKSPACE_SCHEMA_VERSION = "hunch.workspace/1";
+/** Record bounds. The extractor keeps the most recently committed entries and says so in
+ *  provenance, so a huge repository degrades to a truncated record, never to a crash. */
+export const MAX_WORKTREES = 512;
+export const MAX_BRANCHES = 4096;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+export const MACHINE_ID = /^mac_[0-9a-f]{32}$/;
+export const MACHINE_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A branch name git would accept (`git check-ref-format --branch`), fail-closed: no
+ *  leading `-` (flag smuggling), no control/whitespace characters, no `..`, `@{`,
+ *  `.lock` suffix, leading/trailing `.` or `/`, and bounded length. Every real branch
+ *  from `for-each-ref` passes; a crafted record cannot smuggle an argument. */
+export function isSafeBranchName(name) {
+    if (!name || name.length > 256)
+        return false;
+    if (name.startsWith("-") || name.startsWith("/") || name.endsWith("/") || name.startsWith(".") || name.endsWith("."))
+        return false;
+    if (name.includes("..") || name.includes("@{") || name.includes("//") || name.endsWith(".lock") || name === "@")
+        return false;
+    if (/[\s~^:?*[\\\x00-\x1f\x7f]/.test(name))
+        return false;
+    return !name.split("/").some((part) => part.startsWith(".") || part.endsWith(".lock"));
+}
+const BranchName = z.string().refine(isSafeBranchName, { message: "branch name must be a git-valid, flag-free ref" });
+/** `origin/feature` — a remote-tracking short ref: remote name plus a safe branch name. */
+const UpstreamName = z.string().max(320).refine((v) => {
+    const slash = v.indexOf("/");
+    return slash > 0 && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(v.slice(0, slash)) && isSafeBranchName(v.slice(slash + 1));
+}, { message: "upstream must be <remote>/<branch>" });
+const credentialFree = (label, max) => z.string().min(1).max(max).refine(isCredentialFreeValue, { message: `${label} must not carry credential material` });
+export const WorkspaceWorktreeSchema = z.object({
+    /** Stable, path-free handle (hash of the path) so branches can point at a worktree in
+     *  `branches` publish mode, where the path itself is omitted. */
+    id: z.string().regex(/^wt_[0-9a-f]{8}$/),
+    path: credentialFree("worktree path", 1024).nullable(),
+    branch: BranchName.nullable(),
+    head: z.string().regex(SHA),
+    is_main: z.boolean(),
+    /** null = could not be determined (the path no longer exists). */
+    dirty: z.boolean().nullable(),
+    locked: z.boolean(),
+    prunable: z.boolean(),
+    last_commit_at: z.string().regex(ISO).nullable(),
+}).strict();
+export const MERGED_STATUSES = ["merged", "unmerged", "unknown"];
+export const MERGED_METHODS = ["ancestry", "squash", "rebase"];
+export const MergedVerdictSchema = z.object({
+    status: z.enum(MERGED_STATUSES),
+    method: z.enum(MERGED_METHODS).nullable(),
+    evidence: z.array(z.string().max(256).refine(isCredentialFreeValue, { message: "verdict evidence must not carry credential material" })).max(8),
+    /** The pull request that landed a merged branch, read from the LOCAL merge / squash commit
+     *  subject ("Merge pull request #N from …", "… (#N)") — never fetched from a forge. */
+    pr: z.number().int().min(1).max(100_000_000).optional(),
+}).strict().superRefine((v, ctx) => {
+    if ((v.status === "merged") !== (v.method !== null)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a merged verdict names its method; any other verdict has none" });
+    }
+    if (v.pr !== undefined && v.status !== "merged") {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["pr"], message: "only a merged verdict can name a pull request" });
+    }
+});
+export const WorkspaceBranchSchema = z.object({
+    name: BranchName,
+    head: z.string().regex(SHA),
+    is_default: z.boolean(),
+    upstream: UpstreamName.nullable(),
+    upstream_gone: z.boolean(),
+    ahead: z.number().int().min(0).max(1_000_000).nullable(),
+    behind: z.number().int().min(0).max(1_000_000).nullable(),
+    last_commit_at: z.string().regex(ISO).nullable(),
+    /** The worktree (by id) checked out on this branch, if any. */
+    worktree: z.string().regex(/^wt_[0-9a-f]{8}$/).nullable(),
+    merged: MergedVerdictSchema,
+}).strict();
+export const WorkspaceSchema = z.object({
+    schema: z.literal(WORKSPACE_SCHEMA_VERSION),
+    id: z.string().regex(/^ws_[0-9a-f]{12}$/),
+    machine: z.object({
+        id: z.string().regex(MACHINE_ID),
+        label: z.string().regex(MACHINE_LABEL),
+        platform: z.string().regex(/^[a-z0-9]{1,16}$/),
+    }).strict(),
+    /** The existing privacy-safe repository label (`stableRepositoryName`): a digest of the
+     *  canonical fetch remote, never a URL or a path. */
+    repository: credentialFree("repository label", 256),
+    publish: z.enum(["full", "branches"]),
+    observed_at: z.string().regex(ISO),
+    fetched_at: z.string().regex(ISO).nullable(),
+    default_branch: z.object({ name: BranchName, ref: UpstreamName.or(BranchName), head: z.string().regex(SHA) }).strict().nullable(),
+    worktrees: z.array(WorkspaceWorktreeSchema).max(MAX_WORKTREES),
+    branches: z.array(WorkspaceBranchSchema).max(MAX_BRANCHES),
+    provenance: ProvenanceSchema,
+}).strict().superRefine((record, ctx) => {
+    if (record.id !== workspaceId(record.machine.id)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["id"], message: "workspace id must derive from the machine id" });
+    }
+    if (record.publish === "branches" && record.worktrees.some((w) => w.path !== null)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["worktrees"], message: "branches publish mode carries no worktree paths" });
+    }
+    const worktreeIds = new Set(record.worktrees.map((w) => w.id));
+    if (worktreeIds.size !== record.worktrees.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["worktrees"], message: "worktree ids must be unique" });
+    }
+    const names = new Set();
+    for (const [index, branch] of record.branches.entries()) {
+        if (names.has(branch.name))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["branches", index], message: "branch names must be unique" });
+        names.add(branch.name);
+        if (branch.worktree !== null && !worktreeIds.has(branch.worktree)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["branches", index, "worktree"], message: "branch points at a worktree this record does not carry" });
+        }
+    }
+    if (record.provenance.evidence.length > 64 || record.provenance.evidence.some((e) => e.length > 512 || !isCredentialFreeValue(e))) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance"], message: "workspace provenance must remain bounded and credential-free" });
+    }
+});
+/** One record per machine: the id derives from the machine id, so a re-snapshot
+ *  UPDATES the machine's record and two machines can never collide on a file. */
+export function workspaceId(machineId) {
+    return "ws_" + machineId.replace(/^mac_/, "").slice(0, 12);
+}
+/** Path-free worktree handle. */
+export function worktreeId(path) {
+    return "wt_" + shortHash(path, 8);
+}
+/** The same observation, published under `publish`: `branches` drops every worktree path
+ *  (the default), `full` keeps them. Pure, so a caller that already took a live snapshot
+ *  (paths included, for its own display) can publish it without re-running git. */
+export function withPublishMode(record, publish) {
+    if (record.publish === publish)
+        return record;
+    return WorkspaceSchema.parse({
+        ...record,
+        publish,
+        worktrees: record.worktrees.map((w) => ({ ...w, path: publish === "full" ? w.path : null })),
+    });
+}
+/** True when two snapshots of the same machine describe the same workspace, ignoring the
+ *  observation stamps — so an idle machine's hook does not commit a new record per
+ *  checkout. Provenance is constant per build and is compared too. */
+export function sameWorkspaceContent(a, b) {
+    const strip = (w) => JSON.stringify({ ...w, observed_at: null, fetched_at: null });
+    return strip(a) === strip(b);
+}
+export const DEFAULT_STALE_AFTER_DAYS = 7;
+export function isUnverified(record, opts = {}) {
+    const now = (opts.now ?? new Date()).getTime();
+    const days = opts.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+    const observed = Date.parse(record.observed_at);
+    return !Number.isFinite(observed) || now - observed > days * 86_400_000;
+}
+/** Same machine id → the newest observation wins; a stale duplicate never shadows a fresh one. */
+export function latestPerMachine(records) {
+    const byMachine = new Map();
+    for (const r of records) {
+        const prev = byMachine.get(r.machine.id);
+        if (!prev || Date.parse(r.observed_at) > Date.parse(prev.observed_at))
+            byMachine.set(r.machine.id, r);
+    }
+    return [...byMachine.values()].sort((a, b) => a.machine.label.localeCompare(b.machine.label));
+}
+export function worktreeRows(records, opts = {}) {
+    const rows = [];
+    for (const r of latestPerMachine(records)) {
+        const unverified = isUnverified(r, opts);
+        for (const w of r.worktrees) {
+            rows.push({
+                machine: r.machine.label, worktree_id: w.id, path: w.path, branch: w.branch, head: w.head,
+                dirty: w.dirty, locked: w.locked, prunable: w.prunable, last_commit_at: w.last_commit_at,
+                seen_at: r.observed_at, unverified,
+            });
+        }
+    }
+    return rows;
+}
+function daysIdle(iso, now) {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? Math.floor((now.getTime() - t) / 86_400_000) : null;
+}
+/** The recommendation rules from docs/workspace-ledger.md — deterministic text an agent
+ *  or a human reads; nothing executes it. */
+export function recommendAction(row, opts = {}) {
+    const now = opts.now ?? new Date();
+    const staleDays = opts.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+    const suffix = row.unverified_on.length ? ` (unverified: ${row.unverified_on.join(", ")})` : "";
+    if (row.is_default)
+        return "keep: default branch";
+    if (row.heads.length > 1)
+        return `review: local heads differ across ${row.machines.join(", ")}${suffix}`;
+    if (row.merged.status === "merged") {
+        if (row.dirty_on.length)
+            return `keep: dirty worktree on ${row.dirty_on.join(", ")}${suffix}`;
+        const parts = [`delete local on ${row.machines.join(", ")}`];
+        if (row.worktree_on.length)
+            parts.push(`prune worktree on ${row.worktree_on.join(", ")}`);
+        return parts.join("; ") + suffix;
+    }
+    // Unmerged: a dirty worktree is not a reason to keep (the branch is kept anyway) but
+    // it is what the reader needs to know before touching the branch on that machine.
+    const dirty = row.dirty_on.length ? `; dirty worktree on ${row.dirty_on.join(", ")}` : "";
+    if (row.merged.status === "unknown")
+        return `review: merge state unknown${dirty}${suffix}`;
+    if (row.upstream === null || row.upstream_gone) {
+        const idle = daysIdle(row.last_commit_at, now);
+        const why = row.upstream_gone ? "upstream deleted, unmerged work" : "unpushed";
+        if (idle !== null && idle > staleDays)
+            return `review: ${why}, ${idle}d idle${dirty}${suffix}`;
+        return `keep: ${why}${dirty}${suffix}`;
+    }
+    return `keep${dirty}${suffix}`;
+}
+/** Merge verdicts across machines for one branch at one head: any machine that PROVED a
+ *  merge (with evidence) wins over machines that could not tell; `unknown` never
+ *  outranks `unmerged`, so an offline machine cannot mask real unmerged work. */
+function bestVerdict(verdicts) {
+    return verdicts.find((v) => v.status === "merged")
+        ?? verdicts.find((v) => v.status === "unmerged")
+        ?? verdicts[0]
+        ?? { status: "unknown", method: null, evidence: [] };
+}
+export function branchRows(records, opts = {}) {
+    const latest = latestPerMachine(records);
+    const byName = new Map();
+    for (const record of latest) {
+        const unverified = isUnverified(record, opts);
+        for (const branch of record.branches) {
+            const list = byName.get(branch.name) ?? [];
+            list.push({ record, branch, unverified });
+            byName.set(branch.name, list);
+        }
+    }
+    const rows = [];
+    for (const [name, entries] of [...byName.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const worktreeOf = (e) => e.branch.worktree ? e.record.worktrees.find((w) => w.id === e.branch.worktree) : undefined;
+        const withUpstream = entries.find((e) => e.branch.upstream !== null) ?? entries[0];
+        const partial = {
+            name,
+            machines: entries.map((e) => e.record.machine.label),
+            worktree_on: entries.filter((e) => worktreeOf(e)).map((e) => e.record.machine.label),
+            dirty_on: entries.filter((e) => worktreeOf(e)?.dirty === true).map((e) => e.record.machine.label),
+            heads: [...new Set(entries.map((e) => e.branch.head))],
+            is_default: entries.some((e) => e.branch.is_default),
+            upstream: withUpstream.branch.upstream,
+            upstream_gone: entries.some((e) => e.branch.upstream_gone),
+            ahead: withUpstream.branch.ahead,
+            behind: withUpstream.branch.behind,
+            last_commit_at: entries.map((e) => e.branch.last_commit_at).filter((d) => !!d).sort().at(-1) ?? null,
+            merged: bestVerdict(entries.map((e) => e.branch.merged)),
+            unverified_on: entries.filter((e) => e.unverified).map((e) => e.record.machine.label),
+        };
+        rows.push({ ...partial, action: recommendAction(partial, opts) });
+    }
+    return rows;
+}
+/** "2h ago" / "9d ago" for the SEEN column. */
+export function ago(iso, now = new Date()) {
+    const ms = now.getTime() - Date.parse(iso);
+    if (!Number.isFinite(ms) || ms < 0)
+        return "just now";
+    const m = Math.floor(ms / 60_000);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 48)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+function pruneStepsFor(record, opts) {
+    const steps = [];
+    const skipped = [];
+    for (const b of record.branches) {
+        const wt = b.worktree ? record.worktrees.find((w) => w.id === b.worktree) : undefined;
+        const reason = opts.skip(b, wt);
+        if (reason) {
+            if (b.merged.status === "merged" && !b.is_default)
+                skipped.push({ branch: b.name, reason });
+            continue;
+        }
+        const commands = [];
+        if (wt)
+            commands.push(`git worktree remove -- ${wt.path ?? "<its worktree>"}`);
+        commands.push(`git branch -d -- ${b.name}`);
+        steps.push({
+            branch: b.name, head: b.head, worktree: wt ? { id: wt.id, path: wt.path } : null, commands,
+            why: `${b.merged.method}${b.merged.pr ? ` (PR #${b.merged.pr})` : ""}: ${b.merged.evidence[0] ?? ""}`,
+        });
+    }
+    return { steps, skipped };
+}
+/** Why a branch must not be pruned, or null when it may. The rules are the documented ones:
+ *  proven merged, not the default branch, worktree (if any) clean, unlocked and present. */
+export function pruneRefusal(b, wt) {
+    if (b.is_default)
+        return "default branch";
+    if (b.merged.status !== "merged")
+        return b.merged.status === "unknown" ? "merge state unknown" : "not merged";
+    if (wt?.is_main)
+        return "checked out in the main worktree (switch away first)";
+    if (wt?.locked)
+        return "worktree is locked";
+    if (wt?.prunable)
+        return "worktree path is missing (git worktree prune first)";
+    if (wt && wt.dirty !== false)
+        return wt.dirty === null ? "worktree state could not be read" : "worktree has uncommitted or untracked changes";
+    return null;
+}
+export function planPrune(live, others) {
+    const mine = pruneStepsFor(live, { skip: pruneRefusal });
+    const plan = { local: mine.steps, others: {}, skipped: mine.skipped };
+    for (const record of latestPerMachine(others.filter((r) => r.machine.id !== live.machine.id))) {
+        const theirs = pruneStepsFor(record, { skip: pruneRefusal });
+        if (theirs.steps.length)
+            plan.others[record.machine.label] = theirs.steps;
+    }
+    return plan;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/extractors/helm.d.ts

@@ -1,31 +1,20 @@
-/**
- * Deterministic text scan for Helm's `define`/`include`/`template` Go-template
- * actions — NOT a Go-template parser, and NOT a tree-sitter query. tree-sitter-yaml
- * has no notion of `{{ }}` content: parsing `{{ include "x" . }}` inside a real
- * YAML mapping value produces only stray `{` flow-mapping-open tokens, with the
- * enclosed text lost to ERROR recovery (verified directly against this repo's
- * tree-sitter-yaml bundle). There is nothing for a tree-sitter query to capture,
- * so this runs as a sidecar text scan over the raw source — invoked only for
- * files under a Helm chart (indexer.ts's chart-root detection), never for
- * arbitrary YAML.
- *
- * Known bounded limitation: this is a token scan, not a full parser. A literal
- * `}}` inside a quoted argument, or an include/define-shaped string inside a
- * `{{/* comment *}}`, can misattribute a byte range or produce a phantom call.
- * Both are bounded failure modes (a stray reference to a real symbol name, or a
- * slightly-long symbol range) — the same class of accepted limitation
- * `toleratedErrorScopes` documents for the tree-sitter grammars, not a silent gap.
- * The chart-wide `importedFiles` widening this module's output flows through
- * (indexer.ts) also lets a YAML alias resolve to an anchor in a sibling chart
- * file, even though YAML anchors are properly document-scoped; this only fires
- * when the alias has no matching anchor in its own file (i.e. only on input
- * that's already invalid YAML on its own terms), so it's bounded, but it's a
- * real, disclosed side effect of the chart-scoping mechanism, not something to
- * silently rely on.
- */
-import { type ParsedSymbol, type ParsedCall } from "./parse.js";
+import type { ParsedSymbolKind } from "./languages.js";
+export interface HelmSymbol {
+    name: string;
+    kind: ParsedSymbolKind;
+    startChar: number;
+    endChar: number;
+    loc: number;
+    bodyText: string;
+}
+export interface HelmCall {
+    callee: string;
+    atChar: number;
+    endChar: number;
+    member: boolean;
+}
 export interface HelmExtraction {
-    symbols: ParsedSymbol[];
-    calls: ParsedCall[];
+    symbols: HelmSymbol[];
+    calls: HelmCall[];
 }
 export declare function extractHelmDirectives(source: string): HelmExtraction;

package/dist/extractors/helm.js

@@ -11,7 +11,7 @@
  *
  * Known bounded limitation: this is a token scan, not a full parser. A literal
  * `}}` inside a quoted argument, or an include/define-shaped string inside a
- * `{{/* comment *}}`, can misattribute a byte range or produce a phantom call.
+ * `{{/* comment *}}`, can misattribute a char range or produce a phantom call.
  * Both are bounded failure modes (a stray reference to a real symbol name, or a
  * slightly-long symbol range) — the same class of accepted limitation
  * `toleratedErrorScopes` documents for the tree-sitter grammars, not a silent gap.
@@ -39,20 +39,20 @@ export function extractHelmDirectives(source) {
     const stack = [];
     for (const m of source.matchAll(ACTION)) {
         const raw = m[1];
-        // "{{" is 2 chars; a trim-marker "{{-" is 3 — this is the byte offset of
-        // `raw`'s first character within `source`, needed for call-site atByte math.
+        // "{{" is 2 chars; a trim-marker "{{-" is 3 — this is the char offset of
+        // `raw`'s first character within `source`, needed for call-site atChar math.
         const innerStart = m.index + (source[m.index + 2] === "-" ? 3 : 2);
-        const endByte = m.index + m[0].length;
+        const endChar = m.index + m[0].length;
         const body = raw.trim();
         const spaceIdx = body.search(/\s/);
         const keyword = spaceIdx === -1 ? body : body.slice(0, spaceIdx);
         if (keyword === "define") {
             const name = NAME_ARG.exec(body.slice(spaceIdx + 1).trim())?.[1];
-            stack.push({ name, startByte: m.index });
+            stack.push({ name, startChar: m.index });
         }
         else if (BLOCK_OPEN.has(keyword)) {
             // if/range/with/block: depth marker only, no symbol on its own.
-            stack.push({ startByte: m.index });
+            stack.push({ startChar: m.index });
         }
         else if (keyword === "end") {
             const open = stack.pop();
@@ -60,16 +60,16 @@ export function extractHelmDirectives(source) {
                 symbols.push({
                     name: open.name,
                     kind: "variable",
-                    startByte: open.startByte,
-                    endByte,
-                    loc: source.slice(open.startByte, endByte).split("\n").length,
-                    bodyText: source.slice(open.startByte, endByte).slice(0, MAX_BODY_TEXT_CHARS),
+                    startChar: open.startChar,
+                    endChar,
+                    loc: source.slice(open.startChar, endChar).split("\n").length,
+                    bodyText: source.slice(open.startChar, endChar).slice(0, MAX_BODY_TEXT_CHARS),
                 });
             }
         }
         for (const call of raw.matchAll(CALL_SITE)) {
-            const atByte = innerStart + call.index;
-            calls.push({ callee: call[1], atByte, endByte: atByte + call[0].length, member: false });
+            const atChar = innerStart + call.index;
+            calls.push({ callee: call[1], atChar, endChar: atChar + call[0].length, member: false });
         }
     }
     return { symbols, calls };