@copperbox/why 1.0.0

package/dist/dig-state.js

@@ -0,0 +1,146 @@
+// Incremental dig state (DESIGN.md §6): the
+// high-water mark under <bundle>/.dig-state.json that lets routine
+// `why dig --episodes` runs process only new history. The contract, in
+// priority order:
+//
+//   - The mark advances only after a successful episode emission, atomically
+//     (write-temp-rename), so a killed or failed run never moves it.
+//   - Deleting the file is always safe: extraction is deterministic and the
+//     dig skills update rather than duplicate, so absent state just means
+//     "re-dig everything".
+//   - A file this build cannot read (corrupt, or a newer schema version) is
+//     an explicit error and is never overwritten — even under `--full`.
+//   - A mark the repository cannot verify (unresolvable, or orphaned by a
+//     history rewrite) never yields a range; the error names the ways out.
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isPlainMap } from "./bundle.js";
+import { git, gitOrThrow } from "./git.js";
+export const DIG_STATE_FILENAME = ".dig-state.json";
+export const DIG_STATE_VERSION = 1;
+export class DigStateError extends Error {
+}
+export function digStatePath(bundleRoot) {
+    return join(bundleRoot, DIG_STATE_FILENAME);
+}
+const DELETE_HINT = "delete it to re-dig everything (extraction is deterministic; synthesis dedupes)";
+/** Parse the state file; absent → undefined, unreadable → DigStateError. */
+export async function readDigState(bundleRoot) {
+    const path = digStatePath(bundleRoot);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new DigStateError(`dig state ${path} is not valid JSON — inspect it, or ${DELETE_HINT}`);
+    }
+    if (!isPlainMap(parsed)) {
+        throw new DigStateError(`dig state ${path} is not a JSON object — inspect it, or ${DELETE_HINT}`);
+    }
+    if (parsed.version !== DIG_STATE_VERSION) {
+        throw new DigStateError(`dig state ${path} has schema version ${JSON.stringify(parsed.version)}; this build reads version ` +
+            `${DIG_STATE_VERSION} — a newer why may have written it. Inspect it, or ${DELETE_HINT}`);
+    }
+    if (!isPlainMap(parsed.branches)) {
+        throw new DigStateError(`dig state ${path} has no branches map — inspect it, or ${DELETE_HINT}`);
+    }
+    const branches = {};
+    for (const [branch, mark] of Object.entries(parsed.branches)) {
+        if (!isPlainMap(mark) || typeof mark.lastProcessed !== "string") {
+            throw new DigStateError(`dig state ${path} entry for branch "${branch}" has no lastProcessed sha — inspect it, or ${DELETE_HINT}`);
+        }
+        branches[branch] = { lastProcessed: mark.lastProcessed };
+    }
+    return { version: DIG_STATE_VERSION, branches };
+}
+/** Write the state atomically (temp + same-directory rename), branches sorted. */
+export async function writeDigState(bundleRoot, state) {
+    const path = digStatePath(bundleRoot);
+    const branches = {};
+    for (const branch of Object.keys(state.branches).sort()) {
+        branches[branch] = state.branches[branch];
+    }
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, `${JSON.stringify({ version: state.version, branches }, null, 2)}\n`, "utf8");
+    await rename(tmp, path); // atomic: readers see the old file or the new, never a partial write
+}
+/** Resolve the range a dig run should process: mark → HEAD unless overridden. */
+export function resolveDigRange(repo, state, overrides = {}) {
+    if (overrides.from !== undefined && overrides.full === true) {
+        throw new DigStateError("pass --from <rev> or --full, not both");
+    }
+    if (git(repo, ["rev-parse", "--show-toplevel"]).status !== 0) {
+        throw new DigStateError(`${repo} is not inside a git work tree — nothing to dig`);
+    }
+    const headResult = git(repo, ["rev-parse", "HEAD"]);
+    if (headResult.status !== 0) {
+        throw new DigStateError(`${repo} has no commits yet — nothing to dig`);
+    }
+    const head = headResult.stdout.trim();
+    const branch = gitOrThrow(repo, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    let from;
+    if (overrides.from !== undefined) {
+        const r = git(repo, ["rev-parse", "--verify", "--quiet", `${overrides.from}^{commit}`]);
+        if (r.status !== 0) {
+            throw new DigStateError(`--from "${overrides.from}" does not resolve to a commit`);
+        }
+        from = r.stdout.trim();
+    }
+    else if (overrides.full !== true) {
+        const mark = state?.branches[branch]?.lastProcessed;
+        if (mark !== undefined) {
+            const recovery = `pass --full or --from <rev>, or delete ${DIG_STATE_FILENAME} to re-dig everything (synthesis dedupes)`;
+            const r = git(repo, ["rev-parse", "--verify", "--quiet", `${mark}^{commit}`]);
+            if (r.status !== 0) {
+                throw new DigStateError(`dig state records last processed commit ${mark} on branch ${branch}, which does not resolve ` +
+                    `in this repository — ${recovery}`);
+            }
+            from = r.stdout.trim();
+            if (git(repo, ["merge-base", "--is-ancestor", from, head]).status !== 0) {
+                throw new DigStateError(`dig state records last processed commit ${mark} on branch ${branch}, which is not an ancestor ` +
+                    `of HEAD (history rewritten?) — ${recovery}`);
+            }
+        }
+    }
+    const commits = gitOrThrow(repo, [
+        "rev-list",
+        "--reverse",
+        from === undefined ? head : `${from}..${head}`,
+    ])
+        .split("\n")
+        .filter((line) => line.length > 0);
+    const range = { branch, head, commits };
+    if (from !== undefined)
+        range.from = from;
+    return range;
+}
+/**
+ * The only-on-success wrapper around an episode emission (the seam
+ * `why dig --episodes` extraction plugs into): resolve the range, call `emit`
+ * if there is anything in it, and advance the mark to HEAD only after `emit`
+ * returns. A throwing `emit` propagates with the state file untouched.
+ */
+export async function withDigState(repo, bundleRoot, overrides, emit) {
+    // Read up front even when --full/--from ignore the mark: a state file this
+    // build cannot read must fail the run before any work, or the success path
+    // below would overwrite it.
+    const state = await readDigState(bundleRoot);
+    const range = resolveDigRange(repo, state, overrides);
+    if (range.commits.length === 0)
+        return { ...range, emitted: false };
+    await emit(range);
+    await writeDigState(bundleRoot, {
+        version: DIG_STATE_VERSION,
+        branches: { ...state?.branches, [range.branch]: { lastProcessed: range.head } },
+    });
+    return { ...range, emitted: true };
+}

package/dist/dig.d.ts

@@ -0,0 +1,125 @@
+/** Operational failure (bad repo, bad range) — the CLI reports it and exits 1. */
+export declare class DigError extends Error {
+}
+export declare const EPISODES_SCHEMA = "why-dig-episodes";
+export declare const EPISODES_SCHEMA_VERSION = 1;
+export interface DigCommit {
+    sha: string;
+    /** First line of the message. */
+    subject: string;
+    /** Full commit message, trailing whitespace trimmed. */
+    message: string;
+    author: {
+        name: string;
+        email: string;
+    };
+    /** Author date, strict ISO 8601. */
+    date: string;
+}
+export interface FileChurn {
+    path: string;
+    additions: number;
+    deletions: number;
+}
+/** How the episode boundary was found. */
+export type EpisodeKind = "merge" | "squash" | "direct";
+export interface RevertTell {
+    sha: string;
+    subject: string;
+}
+export interface FixChainTell {
+    path: string;
+    /** The fix-prefixed commits touching the path, oldest first. */
+    shas: string[];
+}
+export interface SuddenChurnTell {
+    path: string;
+    /** additions + deletions on the path in this episode. */
+    churn: number;
+    zScore: number;
+}
+export interface CommentTell {
+    sha: string;
+    path: string;
+    /** The added line, `+` stripped and trimmed. */
+    line: string;
+}
+export interface EpisodeTells {
+    reverts: RevertTell[];
+    fixChains: FixChainTell[];
+    suddenChurn: SuddenChurnTell[];
+    /** `count` is always the true total; `sample` is capped (never silently). */
+    commentTells: {
+        count: number;
+        sample: CommentTell[];
+    };
+}
+export interface Episode {
+    /** Unique, stable: the episode's newest commit sha, abbreviated to 12. */
+    id: string;
+    kind: EpisodeKind;
+    /** PR number parsed from the merge/squash boundary commit, if any. */
+    pr: number | null;
+    /** Oldest first; for `merge` episodes the merge commit itself is last. */
+    commits: DigCommit[];
+    /** Per-path churn summed over the episode's commits, sorted by path. */
+    files: FileChurn[];
+    /** PR/issue numbers referenced in commit messages, sorted unique. */
+    refs: number[];
+    /** Min/max author date over the episode's commits. */
+    dates: {
+        start: string;
+        end: string;
+    };
+    tells: EpisodeTells;
+}
+export interface TellCounts {
+    count: number;
+    /** Ids of episodes carrying at least one tell of this kind. */
+    episodes: string[];
+}
+export interface TellsSummary {
+    reverts: TellCounts;
+    fixChains: TellCounts;
+    suddenChurn: TellCounts;
+    commentTells: TellCounts;
+}
+export interface EpisodesReport {
+    schema: typeof EPISODES_SCHEMA;
+    version: typeof EPISODES_SCHEMA_VERSION;
+    /** Repository the walk ran in (git toplevel). */
+    repo: string;
+    /** Resolved range: commits in `from..to`; from null = full history to `to`. */
+    range: {
+        from: string | null;
+        to: string;
+    };
+    /** Oldest first (first-parent order) — synthesis wants causal order. */
+    episodes: Episode[];
+    tells: TellsSummary;
+}
+/** Direct commits by the same author within this window may share an episode. */
+export declare const CLUSTER_WINDOW_MS: number;
+/** Trailing episodes considered when scoring a file's churn. */
+export declare const CHURN_WINDOW = 20;
+/** A file must be at least this many episodes old before churn can be "sudden". */
+export declare const CHURN_MIN_AGE = 5;
+/** z-score at or above which churn on an old-quiet file is flagged. */
+export declare const CHURN_Z_THRESHOLD = 3;
+/** Comment-tell samples kept per episode (count stays exact). */
+export declare const COMMENT_TELL_SAMPLE_CAP = 20;
+/** Added diff lines matching this are comment tells (issue-defined pattern). */
+export declare const COMMENT_TELL_RE: RegExp;
+export interface DigOptions {
+    /** Exclusive start of the range; omitted = full history. */
+    from?: string;
+    /** Inclusive end of the range; default HEAD. */
+    to?: string;
+}
+/**
+ * Extract episodes + tells over `from..to` (full history to `to` when `from`
+ * is omitted). `repo` must be inside a git work tree with at least one commit.
+ */
+export declare function extractEpisodes(repo: string, options?: DigOptions): EpisodesReport;
+export declare function plural(n: number, noun: string): string;
+export declare function renderEpisodesReport(report: EpisodesReport): string[];

package/dist/dig.js

@@ -0,0 +1,380 @@
+// `why dig --episodes` (DESIGN.md §6 step 1): the deterministic half of
+// archaeology. Walks git history over a ref range and clusters commits into
+// candidate episodes — merge/PR boundaries first, then temporal + file-overlap
+// clustering for direct commits — and flags *tells* (reverts, fix-chains,
+// sudden churn on old-quiet files, comment tells) that mark high-value dig
+// sites. Emits a stable JSON report (schema: docs/dig-episodes.md).
+//
+// Everything here is deterministic over (repo state, range): no wall-clock
+// timestamps, stable ordering everywhere — reports get cached and diffed.
+// Judgment (what an episode *means*) belongs to the agent steps, never here.
+import { git, gitOrThrow } from "./git.js";
+/** Operational failure (bad repo, bad range) — the CLI reports it and exits 1. */
+export class DigError extends Error {
+}
+// --- Report shape (the stable JSON surface; see docs/dig-episodes.md) -------
+export const EPISODES_SCHEMA = "why-dig-episodes";
+export const EPISODES_SCHEMA_VERSION = 1;
+// --- Tunables (documented in docs/dig-episodes.md; changing one is a
+// --- schema-version conversation, not a quiet edit) --------------------------
+/** Direct commits by the same author within this window may share an episode. */
+export const CLUSTER_WINDOW_MS = 48 * 60 * 60 * 1000;
+/** Trailing episodes considered when scoring a file's churn. */
+export const CHURN_WINDOW = 20;
+/** A file must be at least this many episodes old before churn can be "sudden". */
+export const CHURN_MIN_AGE = 5;
+/** z-score at or above which churn on an old-quiet file is flagged. */
+export const CHURN_Z_THRESHOLD = 3;
+/** Comment-tell samples kept per episode (count stays exact). */
+export const COMMENT_TELL_SAMPLE_CAP = 20;
+const MERGE_PR_RE = /^Merge pull request #(\d+)/;
+const SQUASH_PR_RE = /\(#(\d+)\)\s*$/;
+const REVERT_RE = /^Revert "/;
+const FIX_RE = /^fix/i;
+/** Added diff lines matching this are comment tells (issue-defined pattern). */
+export const COMMENT_TELL_RE = /\b(hack|workaround|do not|don't|because|temporarily)\b/i;
+const REF_RE = /(?:^|[^\w&])#(\d+)\b|(?:issues|pull)\/(\d+)\b/g;
+const C = "\x01"; // commit separator
+const F = "\x1f"; // field separator
+const E = "\x1e"; // end of header
+function resolveCommit(repo, rev, what) {
+    const r = git(repo, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]);
+    if (r.status !== 0) {
+        throw new DigError(`${what} "${rev}" does not resolve to a commit`);
+    }
+    return r.stdout.trim();
+}
+/** Read every commit in the range: metadata + per-file churn, one git call. */
+function readCommits(repo, range) {
+    const out = gitOrThrow(repo, [
+        "log",
+        "--no-renames",
+        "--numstat",
+        `--format=${C}%H${F}%an${F}%ae${F}%aI${F}%B${E}`,
+        ...range,
+    ]);
+    const commits = new Map();
+    for (const chunk of out.split(C).slice(1)) {
+        const end = chunk.indexOf(E);
+        const [sha, name, email, date, message] = chunk.slice(0, end).split(F);
+        const files = [];
+        for (const line of chunk.slice(end + 1).split("\n")) {
+            const m = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line);
+            if (m === null)
+                continue;
+            // Binary files numstat as "-"; count their churn as 0 but keep the path.
+            files.push({
+                path: m[3],
+                additions: m[1] === "-" ? 0 : Number(m[1]),
+                deletions: m[2] === "-" ? 0 : Number(m[2]),
+            });
+        }
+        const trimmed = message.trimEnd();
+        commits.set(sha, {
+            sha,
+            subject: trimmed.split("\n", 1)[0],
+            message: trimmed,
+            author: { name, email },
+            date,
+            files,
+            commentTells: [],
+        });
+    }
+    return commits;
+}
+/** Second pass: scan added diff lines for comment tells. */
+function scanCommentTells(repo, range, commits) {
+    const out = gitOrThrow(repo, ["log", "--no-renames", "-p", `--format=${C}%H`, ...range]);
+    for (const chunk of out.split(C).slice(1)) {
+        const lines = chunk.split("\n");
+        const commit = commits.get(lines[0].trim());
+        if (commit === undefined)
+            continue;
+        let path = null;
+        for (const line of lines.slice(1)) {
+            const target = /^\+\+\+ (?:b\/(.*)|\/dev\/null)$/.exec(line);
+            if (target !== null) {
+                path = target[1] ?? null;
+                continue;
+            }
+            if (path === null || !line.startsWith("+") || line.startsWith("+++"))
+                continue;
+            if (COMMENT_TELL_RE.test(line)) {
+                commit.commentTells.push({ sha: commit.sha, path, line: line.slice(1).trim() });
+            }
+        }
+    }
+}
+/** Cluster a contiguous run of direct commits: same author, <48h, shared paths. */
+function clusterDirectRun(run) {
+    const clusters = [];
+    let current = [];
+    let paths = new Set();
+    let lastMs = 0;
+    const flush = () => {
+        if (current.length > 0)
+            clusters.push({ kind: "direct", pr: null, commits: current });
+        current = [];
+        paths = new Set();
+        lastMs = 0; // author dates are not monotonic (rebases) — never leak across clusters
+    };
+    for (const commit of run) {
+        const ms = Date.parse(commit.date);
+        // abs(): walk order is topological, so a rebased commit can carry an
+        // author date older than the cluster tip — "apart" cuts both ways.
+        const joins = current.length > 0 &&
+            commit.author.email === current[0].author.email &&
+            Math.abs(ms - lastMs) < CLUSTER_WINDOW_MS &&
+            commit.files.some((f) => paths.has(f.path));
+        if (!joins)
+            flush();
+        current.push(commit);
+        for (const f of commit.files)
+            paths.add(f.path);
+        lastMs = Math.max(lastMs, ms);
+    }
+    flush();
+    return clusters;
+}
+/** Walk the first-parent chain of the range and group commits into episodes. */
+function groupEpisodes(repo, range, commits) {
+    const walk = gitOrThrow(repo, ["rev-list", "--first-parent", "--reverse", "--parents", ...range])
+        .split("\n")
+        .filter((l) => l !== "")
+        .map((l) => l.split(" "));
+    const episodes = [];
+    const assigned = new Set();
+    let directRun = [];
+    const flushRun = () => {
+        episodes.push(...clusterDirectRun(directRun));
+        directRun = [];
+    };
+    const take = (sha) => {
+        const c = commits.get(sha);
+        if (c === undefined || assigned.has(sha))
+            return undefined;
+        assigned.add(sha);
+        return c;
+    };
+    for (const [sha, ...parents] of walk) {
+        const commit = take(sha);
+        if (commit === undefined)
+            continue;
+        if (parents.length >= 2) {
+            flushRun();
+            // Side-branch commits: reachable from the merged parents, not mainline.
+            const side = gitOrThrow(repo, [
+                "rev-list",
+                "--reverse",
+                ...parents.slice(1),
+                "--not",
+                parents[0],
+            ])
+                .split("\n")
+                .filter((s) => s !== "")
+                .map(take)
+                .filter((c) => c !== undefined);
+            const pr = MERGE_PR_RE.exec(commit.subject)?.[1];
+            episodes.push({
+                kind: "merge",
+                pr: pr === undefined ? null : Number(pr),
+                commits: [...side, commit],
+            });
+            continue;
+        }
+        const squash = SQUASH_PR_RE.exec(commit.subject)?.[1];
+        if (squash !== undefined) {
+            flushRun();
+            episodes.push({ kind: "squash", pr: Number(squash), commits: [commit] });
+            continue;
+        }
+        directRun.push(commit);
+    }
+    flushRun();
+    return episodes;
+}
+function extractRefs(commits) {
+    const refs = new Set();
+    for (const c of commits) {
+        for (const m of c.message.matchAll(REF_RE))
+            refs.add(Number(m[1] ?? m[2]));
+    }
+    return [...refs].sort((a, b) => a - b);
+}
+function sumChurn(commits) {
+    const byPath = new Map();
+    for (const c of commits) {
+        for (const f of c.files) {
+            const entry = byPath.get(f.path) ?? { path: f.path, additions: 0, deletions: 0 };
+            entry.additions += f.additions;
+            entry.deletions += f.deletions;
+            byPath.set(f.path, entry);
+        }
+    }
+    return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+function fixChains(commits) {
+    const byPath = new Map();
+    for (const c of commits) {
+        if (!FIX_RE.test(c.subject))
+            continue;
+        for (const f of c.files) {
+            byPath.set(f.path, [...(byPath.get(f.path) ?? []), c.sha]);
+        }
+    }
+    return [...byPath.entries()]
+        .filter(([, shas]) => shas.length >= 2)
+        .map(([path, shas]) => ({ path, shas }))
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Sudden churn on old-quiet files: for each (episode, file), z-score the
+ * episode's churn against the file's churn over the trailing CHURN_WINDOW
+ * episodes (0 when untouched). Only files first seen at least CHURN_MIN_AGE
+ * episodes earlier qualify — brand-new files are always "sudden" and never
+ * interesting. The stddev floor of 1 keeps a dead-quiet history from making
+ * every touch infinitely surprising.
+ */
+function markSuddenChurn(episodes) {
+    const firstSeen = new Map();
+    const history = [];
+    episodes.forEach((ep, i) => {
+        const churn = new Map();
+        for (const f of ep.files) {
+            churn.set(f.path, f.additions + f.deletions);
+            if (!firstSeen.has(f.path))
+                firstSeen.set(f.path, i);
+        }
+        history.push(churn);
+    });
+    episodes.forEach((ep, i) => {
+        for (const f of ep.files) {
+            if (i - firstSeen.get(f.path) < CHURN_MIN_AGE)
+                continue;
+            const window = [];
+            for (let j = Math.max(0, i - CHURN_WINDOW); j < i; j++) {
+                window.push(history[j].get(f.path) ?? 0);
+            }
+            const mean = window.reduce((a, b) => a + b, 0) / window.length;
+            const variance = window.reduce((a, b) => a + (b - mean) ** 2, 0) / window.length;
+            const sigma = Math.max(Math.sqrt(variance), 1);
+            const churn = f.additions + f.deletions;
+            const z = (churn - mean) / sigma;
+            if (z >= CHURN_Z_THRESHOLD) {
+                ep.tells.suddenChurn.push({ path: f.path, churn, zScore: Number(z.toFixed(2)) });
+            }
+        }
+    });
+}
+function buildEpisode(proto) {
+    const commits = proto.commits;
+    // Chronological, not lexicographic — ISO dates carry varying UTC offsets.
+    const dates = commits.map((c) => c.date).sort((a, b) => Date.parse(a) - Date.parse(b));
+    const allTells = commits.flatMap((c) => c.commentTells);
+    return {
+        id: commits[commits.length - 1].sha.slice(0, 12),
+        kind: proto.kind,
+        pr: proto.pr,
+        commits: commits.map(({ sha, subject, message, author, date }) => ({
+            sha,
+            subject,
+            message,
+            author,
+            date,
+        })),
+        files: sumChurn(commits),
+        refs: extractRefs(commits),
+        dates: { start: dates[0], end: dates[dates.length - 1] },
+        tells: {
+            reverts: commits
+                .filter((c) => REVERT_RE.test(c.subject))
+                .map((c) => ({ sha: c.sha, subject: c.subject })),
+            fixChains: fixChains(commits),
+            suddenChurn: [],
+            commentTells: { count: allTells.length, sample: allTells.slice(0, COMMENT_TELL_SAMPLE_CAP) },
+        },
+    };
+}
+function summarizeTells(episodes) {
+    const summarize = (count) => ({
+        count: episodes.reduce((n, e) => n + count(e), 0),
+        episodes: episodes.filter((e) => count(e) > 0).map((e) => e.id),
+    });
+    return {
+        reverts: summarize((e) => e.tells.reverts.length),
+        fixChains: summarize((e) => e.tells.fixChains.length),
+        suddenChurn: summarize((e) => e.tells.suddenChurn.length),
+        commentTells: summarize((e) => e.tells.commentTells.count),
+    };
+}
+/**
+ * Extract episodes + tells over `from..to` (full history to `to` when `from`
+ * is omitted). `repo` must be inside a git work tree with at least one commit.
+ */
+export function extractEpisodes(repo, options = {}) {
+    const toplevel = git(repo, ["rev-parse", "--show-toplevel"]);
+    if (toplevel.status !== 0) {
+        throw new DigError(`${repo} is not inside a git repository`);
+    }
+    const root = toplevel.stdout.trim();
+    const to = resolveCommit(root, options.to ?? "HEAD", "range end");
+    let from = null;
+    if (options.from !== undefined) {
+        from = resolveCommit(root, options.from, "range start");
+        if (git(root, ["merge-base", "--is-ancestor", from, to]).status !== 0) {
+            throw new DigError(`range start ${options.from} is not an ancestor of ${options.to ?? "HEAD"}`);
+        }
+    }
+    const range = from === null ? [to] : [`${from}..${to}`];
+    const commits = readCommits(root, range);
+    scanCommentTells(root, range, commits);
+    const episodes = groupEpisodes(root, range, commits).map(buildEpisode);
+    markSuddenChurn(episodes);
+    return {
+        schema: EPISODES_SCHEMA,
+        version: EPISODES_SCHEMA_VERSION,
+        repo: root,
+        range: { from, to },
+        episodes,
+        tells: summarizeTells(episodes),
+    };
+}
+// --- Rendering ---------------------------------------------------------------
+function day(iso) {
+    return iso.slice(0, 10);
+}
+export function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+function tellBadges(e) {
+    const badges = [];
+    if (e.tells.reverts.length > 0)
+        badges.push(`revert×${e.tells.reverts.length}`);
+    if (e.tells.fixChains.length > 0)
+        badges.push(`fix-chain×${e.tells.fixChains.length}`);
+    if (e.tells.suddenChurn.length > 0)
+        badges.push(`sudden-churn×${e.tells.suddenChurn.length}`);
+    if (e.tells.commentTells.count > 0)
+        badges.push(`comment×${e.tells.commentTells.count}`);
+    return badges.length === 0 ? "" : `  tells: ${badges.join(", ")}`;
+}
+export function renderEpisodesReport(report) {
+    const lines = [];
+    const commits = report.episodes.reduce((n, e) => n + e.commits.length, 0);
+    const from = report.range.from === null ? "full history" : `${report.range.from.slice(0, 12)}..`;
+    lines.push(`why dig --episodes: ${plural(report.episodes.length, "episode")}, ` +
+        `${plural(commits, "commit")} (${from} → ${report.range.to.slice(0, 12)})`);
+    lines.push("");
+    for (const e of report.episodes) {
+        const span = e.dates.start === e.dates.end ? day(e.dates.start) : `${day(e.dates.start)}..${day(e.dates.end)}`;
+        const pr = e.pr === null ? "" : ` #${e.pr}`;
+        lines.push(`  ${e.id}  ${e.kind}${pr}  ${span}  ${plural(e.commits.length, "commit")}, ` +
+            `${plural(e.files.length, "file")}${tellBadges(e)}`);
+    }
+    lines.push("");
+    const t = report.tells;
+    lines.push(`tells: ${plural(t.reverts.count, "revert")}, ${plural(t.fixChains.count, "fix-chain")}, ` +
+        `${t.suddenChurn.count} sudden-churn, ${plural(t.commentTells.count, "comment tell")}`);
+    lines.push("(full data: --json or --out <file>; schema: docs/dig-episodes.md)");
+    return lines;
+}

package/dist/discover.d.ts

@@ -0,0 +1,11 @@
+export declare const BUNDLE_DIRNAME = ".why";
+/** A command needed a bundle and none could be found. Rendered, not a crash. */
+export declare class BundleNotFoundError extends Error {
+}
+/** Walk up from startDir to the filesystem root; nearest `.why/` wins. */
+export declare function findBundleRoot(startDir: string): string | undefined;
+/**
+ * The bundle root a command should use: an explicit `--bundle` path (resolved
+ * against cwd, must exist) or the nearest `.why/` above cwd.
+ */
+export declare function resolveBundleRoot(cwd: string, override?: string): string;