@mneme-ai/core 0.9.0 → 0.11.0

package/dist/insights/regret.test.js

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest";
+import { detectRegrets, summarizeRegrets } from "./regret.js";
+const cmt = (hash, date, subject, body = "", files = []) => ({
+    hash,
+    shortHash: hash.slice(0, 7),
+    authorName: "alice",
+    authorEmail: "alice@x",
+    authorDate: `${date}T12:00:00Z`,
+    committerDate: `${date}T12:00:00Z`,
+    subject,
+    body,
+    parents: [],
+    files,
+});
+describe("detectRegrets — revert (strongest signal)", () => {
+    it("detects explicit revert that names the shipped commit hash", () => {
+        const commits = [
+            cmt("a1b2c3d", "2024-08-01", "feat: enable HTTP/3", "", ["src/edge.ts"]),
+            cmt("e4f5g6h", "2024-08-03", "Revert \"feat: enable HTTP/3\"", "Reverts a1b2c3d — broke mobile", ["src/edge.ts"]),
+        ];
+        const regrets = detectRegrets(commits, { windowDays: 7 });
+        expect(regrets).toHaveLength(1);
+        expect(regrets[0].kind).toBe("revert");
+        expect(regrets[0].daysToFix).toBeCloseTo(2, 0);
+    });
+    it("detects revert from shared-files heuristic when subject is generic", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: new caching", "", ["src/cache.ts"]),
+            cmt("a2", "2024-08-04", "revert caching change", "", ["src/cache.ts"]),
+        ];
+        expect(detectRegrets(commits)[0].kind).toBe("revert");
+    });
+});
+describe("detectRegrets — hotfix and fix kinds", () => {
+    it("flags hotfix when follow-up has 'hotfix' marker AND shares files", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "refactor: simplify session middleware", "", ["src/auth.ts"]),
+            cmt("a2", "2024-08-01", "hotfix: CSRF check disappeared in refactor", "", ["src/auth.ts"]),
+        ];
+        expect(detectRegrets(commits)[0].kind).toBe("hotfix");
+    });
+    it("flags 'fix' kind when follow-up is a generic fix touching same files", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "perf: cache user lookup", "", ["src/users.ts"]),
+            cmt("a2", "2024-08-04", "fix: cache invalidation race", "", ["src/users.ts"]),
+        ];
+        expect(detectRegrets(commits)[0].kind).toBe("fix");
+    });
+    it("doesn't double-flag commits that ARE themselves fixes", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "fix: typo", "", ["README.md"]),
+            cmt("a2", "2024-08-02", "fix: another typo", "", ["README.md"]),
+        ];
+        // Neither is a regret — both are fix-shaped subjects.
+        expect(detectRegrets(commits)).toEqual([]);
+    });
+});
+describe("detectRegrets — window enforcement", () => {
+    it("respects the windowDays cutoff", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-15", "fix: thing broke", "", ["x.ts"]), // 14 days later
+        ];
+        expect(detectRegrets(commits, { windowDays: 7 })).toEqual([]);
+        expect(detectRegrets(commits, { windowDays: 30 })).toHaveLength(1);
+    });
+    it("respects minDaysToFix lower bound (filter out same-day micro-fixes)", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-01", "fix: typo", "", ["x.ts"]),
+        ];
+        expect(detectRegrets(commits, { minDaysToFix: 1 })).toEqual([]);
+        expect(detectRegrets(commits, { minDaysToFix: 0 })).toHaveLength(1);
+    });
+});
+describe("detectRegrets — only one regret per shipped commit", () => {
+    it("returns the first follow-up only (avoids double-counting)", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "fix: first attempt at fix", "", ["x.ts"]),
+            cmt("a3", "2024-08-04", "fix: second attempt", "", ["x.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        expect(regrets).toHaveLength(1);
+        expect(regrets[0].followup.shortHash).toBe("a2");
+    });
+});
+describe("detectRegrets — output ordering and content", () => {
+    it("sorts results by ship date descending (newest regret first)", () => {
+        const commits = [
+            cmt("old1", "2024-01-01", "feat: a", "", ["x.ts"]),
+            cmt("old2", "2024-01-02", "fix: a broke", "", ["x.ts"]),
+            cmt("new1", "2024-08-01", "feat: b", "", ["y.ts"]),
+            cmt("new2", "2024-08-03", "fix: b broke", "", ["y.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        expect(regrets).toHaveLength(2);
+        expect(regrets[0].shipped.shortHash).toBe("new1");
+        expect(regrets[1].shipped.shortHash).toBe("old1");
+    });
+    it("attaches a lesson string when the follow-up body has explanatory text", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: thing", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "fix: thing crashed", "the cache invalidation was racing with the eviction sweep", ["x.ts"]),
+        ];
+        const r = detectRegrets(commits)[0];
+        expect(r.lesson).toContain("cache invalidation");
+    });
+});
+describe("summarizeRegrets — repo-level metrics", () => {
+    it("computes regretRate over non-fix shipped commits", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: A", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "fix: A broke", "", ["x.ts"]),
+            cmt("a3", "2024-08-03", "feat: B", "", ["y.ts"]),
+            cmt("a4", "2024-08-04", "feat: C", "", ["z.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        const summary = summarizeRegrets(commits, regrets);
+        // Non-fix shipped: a1, a3, a4 → 3 candidates. 1 regret. → 1/3 ≈ 0.33
+        expect(summary.totalShipped).toBe(3);
+        expect(summary.totalRegrets).toBe(1);
+        expect(summary.regretRate).toBeCloseTo(1 / 3, 2);
+    });
+    it("counts byKind correctly", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: A", "", ["x.ts"]),
+            cmt("a2", "2024-08-02", "Revert \"feat: A\"", "", ["x.ts"]),
+            cmt("a3", "2024-08-03", "feat: B", "", ["y.ts"]),
+            cmt("a4", "2024-08-04", "hotfix: B explosion", "", ["y.ts"]),
+        ];
+        const regrets = detectRegrets(commits);
+        const summary = summarizeRegrets(commits, regrets);
+        expect(summary.byKind.revert).toBe(1);
+        expect(summary.byKind.hotfix).toBe(1);
+    });
+    it("reports averageDaysToFix", () => {
+        const commits = [
+            cmt("a1", "2024-08-01", "feat: A", "", ["x.ts"]),
+            cmt("a2", "2024-08-03", "fix: A", "", ["x.ts"]), // 2 days
+            cmt("a3", "2024-08-10", "feat: B", "", ["y.ts"]),
+            cmt("a4", "2024-08-14", "fix: B", "", ["y.ts"]), // 4 days
+        ];
+        const summary = summarizeRegrets(commits, detectRegrets(commits));
+        expect(summary.averageDaysToFix).toBeCloseTo(3, 1);
+    });
+    it("returns 0 metrics when there are no regrets", () => {
+        const summary = summarizeRegrets([cmt("a", "2024-08-01", "feat: stable", "", ["x"])], []);
+        expect(summary.regretRate).toBe(0);
+        expect(summary.averageDaysToFix).toBe(0);
+    });
+});
+//# sourceMappingURL=regret.test.js.map

package/dist/insights/regret.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regret.test.js","sourceRoot":"","sources":["../../src/insights/regret.test.ts"],"names":[],"mappings":"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"}

package/dist/insights/time-machine.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `mneme time-machine <file>` — narrate a file's evolution as discrete
+ * epochs, not a flat diff log. Each epoch is a meaningful era in the
+ * file's life: when it was born, when it was rewritten, when it stabilized,
+ * when it broke things, when it was abandoned.
+ *
+ * What makes this novel:
+ *   - Most tools show `git log file.ts` — a flat list. Time Machine
+ *     groups commits into ERAS based on intent (rewrite, fix, polish,
+ *     stable plateau).
+ *   - Detects "rewrite events" (large simultaneous insertions+deletions)
+ *     vs. "polish events" (small surgical changes) vs. "stable plateaus"
+ *     (long quiet stretches).
+ *   - Surfaces the WHY for each epoch by extracting the most informative
+ *     commit message of that era.
+ *   - Computes "narrative health" — how much of the history is rewrite
+ *     vs. evolution vs. firefight.
+ *
+ * Pure data extraction. The CLI renders the timeline; an LLM (optional)
+ * can polish the prose.
+ */
+import type { Commit, FileChange } from "../types.js";
+export type EpochKind = "birth" | "rewrite" | "evolution" | "firefight" | "polish" | "plateau" | "twilight";
+export interface FileEpoch {
+    kind: EpochKind;
+    /** Sequential number, 1-indexed. */
+    index: number;
+    /** Commits defining this epoch (chronological). */
+    commits: Commit[];
+    /** The most informative commit of the epoch — used for narration. */
+    defining: Commit;
+    fromDate: string;
+    toDate: string;
+    /** Total insertions across the epoch. */
+    insertions: number;
+    /** Total deletions across the epoch. */
+    deletions: number;
+    /** Days spanned by this epoch. */
+    spanDays: number;
+    /** A short prose label — the WHY of this epoch. */
+    label: string;
+}
+export interface TimeMachineResult {
+    filePath: string;
+    totalCommits: number;
+    totalSpanDays: number;
+    epochs: FileEpoch[];
+    /**
+     * Health balance across epochs:
+     *   - rewriteRatio: fraction of commits in rewrite epochs (high = unstable)
+     *   - firefightRatio: fraction in firefight epochs (high = pain)
+     *   - polishRatio: fraction in polish/plateau (high = mature)
+     */
+    health: {
+        rewriteRatio: number;
+        firefightRatio: number;
+        polishRatio: number;
+    };
+}
+/**
+ * Compute file epochs from a chronological list of commits + per-commit
+ * file changes for the target file. Caller is responsible for filtering
+ * commits to ones that actually touched `filePath`.
+ */
+export declare function buildTimeMachine(filePath: string, commits: Commit[], changes: Map<string, FileChange>, // commitHash -> file change for filePath
+opts?: {
+    plateauDays?: number;
+    rewriteChurnLines?: number;
+}): TimeMachineResult;
+//# sourceMappingURL=time-machine.d.ts.map

package/dist/insights/time-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-machine.d.ts","sourceRoot":"","sources":["../../src/insights/time-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB;;;;;OAKG;IACH,MAAM,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAMD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,yCAAyC;AAC3E,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9D,iBAAiB,CAgJnB"}

package/dist/insights/time-machine.js

@@ -0,0 +1,177 @@
+const FIRE_RE = /\b(fix(?:es|ed)?|hotfix|revert|rollback|broken|crash|regression|emergency|urgent|critical|p[01])\b/i;
+const REWRITE_RE = /\b(rewrite|refactor|overhaul|redesign|migrate|replace[ds]?|move(?:d)? to)\b/i;
+const POLISH_RE = /\b(typo|format|lint|rename|comment|whitespace|cleanup|style|chore)\b/i;
+/**
+ * Compute file epochs from a chronological list of commits + per-commit
+ * file changes for the target file. Caller is responsible for filtering
+ * commits to ones that actually touched `filePath`.
+ */
+export function buildTimeMachine(filePath, commits, changes, // commitHash -> file change for filePath
+opts = {}) {
+    const plateauDays = opts.plateauDays ?? 60;
+    const rewriteChurnLines = opts.rewriteChurnLines ?? 80;
+    const sorted = [...commits].sort((a, b) => a.authorDate.localeCompare(b.authorDate));
+    if (sorted.length === 0) {
+        return {
+            filePath,
+            totalCommits: 0,
+            totalSpanDays: 0,
+            epochs: [],
+            health: { rewriteRatio: 0, firefightRatio: 0, polishRatio: 0 },
+        };
+    }
+    const flavorOf = (c) => {
+        const text = `${c.subject}\n${c.body || ""}`;
+        const fc = changes.get(c.hash);
+        const churn = fc ? fc.insertions + fc.deletions : 0;
+        if (REWRITE_RE.test(text) || churn >= rewriteChurnLines)
+            return "rewrite";
+        if (FIRE_RE.test(text))
+            return "firefight";
+        if (POLISH_RE.test(text) || churn <= 5)
+            return "polish";
+        return "evolution";
+    };
+    const epochs = [];
+    let buf = [sorted[0]];
+    let bufFlavor = sorted[0].parents.length === 0 || epochs.length === 0 ? "birth" : flavorOf(sorted[0]);
+    // birth applies only to the very first commit
+    bufFlavor = "birth";
+    let prevDate = new Date(sorted[0].authorDate).getTime();
+    const flush = (kind) => {
+        const commitsInEpoch = buf;
+        if (commitsInEpoch.length === 0)
+            return;
+        let ins = 0;
+        let del = 0;
+        for (const c of commitsInEpoch) {
+            const fc = changes.get(c.hash);
+            if (fc) {
+                ins += fc.insertions;
+                del += fc.deletions;
+            }
+        }
+        const fromDate = commitsInEpoch[0].authorDate.slice(0, 10);
+        const toDate = commitsInEpoch[commitsInEpoch.length - 1].authorDate.slice(0, 10);
+        const spanDays = Math.max(0, Math.round((new Date(toDate).getTime() - new Date(fromDate).getTime()) / 86_400_000));
+        const defining = pickDefiningCommit(commitsInEpoch, kind);
+        epochs.push({
+            kind,
+            index: epochs.length + 1,
+            commits: commitsInEpoch,
+            defining,
+            fromDate,
+            toDate,
+            insertions: ins,
+            deletions: del,
+            spanDays,
+            label: labelEpoch(kind, defining, ins + del),
+        });
+    };
+    for (let i = 1; i < sorted.length; i++) {
+        const c = sorted[i];
+        const cTime = new Date(c.authorDate).getTime();
+        const gapDays = (cTime - prevDate) / 86_400_000;
+        const flavor = flavorOf(c);
+        // Long quiet gap → emit plateau epoch covering the gap
+        if (gapDays >= plateauDays) {
+            flush(bufFlavor);
+            epochs.push({
+                kind: "plateau",
+                index: epochs.length + 1,
+                commits: [],
+                defining: buf[buf.length - 1],
+                fromDate: buf[buf.length - 1].authorDate.slice(0, 10),
+                toDate: c.authorDate.slice(0, 10),
+                insertions: 0,
+                deletions: 0,
+                spanDays: Math.round(gapDays),
+                label: `quiet stretch — ${Math.round(gapDays)} days untouched`,
+            });
+            buf = [c];
+            bufFlavor = flavor;
+        }
+        else if (flavor !== bufFlavor) {
+            // flavor change → close current epoch, start new one
+            flush(bufFlavor);
+            buf = [c];
+            bufFlavor = flavor;
+        }
+        else {
+            buf.push(c);
+        }
+        prevDate = cTime;
+    }
+    flush(bufFlavor);
+    // Mark trailing plateau as "twilight" if file is quiet at end (>plateauDays
+    // since last touch).
+    const last = epochs[epochs.length - 1];
+    if (last && last.kind === "plateau" && last.spanDays >= plateauDays * 2) {
+        last.kind = "twilight";
+        last.label = `twilight — ${last.spanDays} days since last touch`;
+    }
+    // Compute health ratios
+    const totalCommits = sorted.length;
+    let rewrite = 0;
+    let firefight = 0;
+    let polish = 0;
+    for (const e of epochs) {
+        if (e.kind === "rewrite")
+            rewrite += e.commits.length;
+        else if (e.kind === "firefight")
+            firefight += e.commits.length;
+        else if (e.kind === "polish" || e.kind === "plateau")
+            polish += e.commits.length;
+    }
+    const totalSpanDays = Math.max(0, Math.round((new Date(sorted[sorted.length - 1].authorDate).getTime() -
+        new Date(sorted[0].authorDate).getTime()) /
+        86_400_000));
+    return {
+        filePath,
+        totalCommits,
+        totalSpanDays,
+        epochs,
+        health: {
+            rewriteRatio: totalCommits === 0 ? 0 : rewrite / totalCommits,
+            firefightRatio: totalCommits === 0 ? 0 : firefight / totalCommits,
+            polishRatio: totalCommits === 0 ? 0 : polish / totalCommits,
+        },
+    };
+}
+function pickDefiningCommit(commits, kind) {
+    if (commits.length === 0)
+        throw new Error("empty epoch");
+    if (kind === "birth")
+        return commits[0];
+    if (kind === "rewrite") {
+        // longest body / most descriptive subject wins
+        return [...commits].sort((a, b) => (b.body?.length ?? 0) + b.subject.length - ((a.body?.length ?? 0) + a.subject.length))[0];
+    }
+    // For evolution/polish/firefight, pick the commit whose subject is longest
+    // (typically more informative than "fix typo")
+    return [...commits].sort((a, b) => b.subject.length - a.subject.length)[0];
+}
+function labelEpoch(kind, defining, churn) {
+    switch (kind) {
+        case "birth":
+            return `born — "${truncate(defining.subject, 60)}"`;
+        case "rewrite":
+            return `rewrite — "${truncate(defining.subject, 60)}" (${churn} lines)`;
+        case "evolution":
+            return `evolution — "${truncate(defining.subject, 60)}"`;
+        case "firefight":
+            return `firefight — "${truncate(defining.subject, 60)}"`;
+        case "polish":
+            return `polish — "${truncate(defining.subject, 60)}"`;
+        case "plateau":
+            return `plateau — quiet`;
+        case "twilight":
+            return `twilight — possibly abandoned`;
+    }
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, n - 1).trimEnd() + "…";
+}
+//# sourceMappingURL=time-machine.js.map

package/dist/insights/time-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-machine.js","sourceRoot":"","sources":["../../src/insights/time-machine.ts"],"names":[],"mappings":"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"}

package/dist/insights/time-machine.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=time-machine.test.d.ts.map

package/dist/insights/time-machine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-machine.test.d.ts","sourceRoot":"","sources":["../../src/insights/time-machine.test.ts"],"names":[],"mappings":""}

package/dist/insights/time-machine.test.js

@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+import { buildTimeMachine } from "./time-machine.js";
+function mkCommit(p) {
+    return {
+        shortHash: p.hash.slice(0, 7),
+        authorName: "Test",
+        authorEmail: "t@e.com",
+        committerDate: p.authorDate,
+        body: p.body ?? "",
+        files: ["src/x.ts"],
+        parents: p.parents ?? [],
+        ...p,
+    };
+}
+function mkChange(commitHash, ins, del) {
+    return {
+        commitHash,
+        path: "src/x.ts",
+        changeKind: "M",
+        insertions: ins,
+        deletions: del,
+    };
+}
+function chmap(...changes) {
+    const m = new Map();
+    for (const c of changes)
+        m.set(c.commitHash, c);
+    return m;
+}
+describe("buildTimeMachine", () => {
+    it("returns empty result when there are no commits", () => {
+        const result = buildTimeMachine("src/x.ts", [], new Map());
+        expect(result.epochs).toHaveLength(0);
+        expect(result.totalCommits).toBe(0);
+    });
+    it("first commit is always a 'birth' epoch", () => {
+        const commits = [mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "initial" })];
+        const result = buildTimeMachine("src/x.ts", commits, chmap(mkChange("a1", 50, 0)));
+        expect(result.epochs).toHaveLength(1);
+        expect(result.epochs[0].kind).toBe("birth");
+        expect(result.epochs[0].label).toContain("born");
+    });
+    it("detects rewrite epoch from large churn", () => {
+        const commits = [
+            mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "initial" }),
+            mkCommit({ hash: "a2", authorDate: "2024-01-05", subject: "rewrite to use streams" }),
+        ];
+        const changes = chmap(mkChange("a1", 50, 0), mkChange("a2", 200, 180));
+        const result = buildTimeMachine("src/x.ts", commits, changes);
+        const rewriteEpoch = result.epochs.find((e) => e.kind === "rewrite");
+        expect(rewriteEpoch).toBeDefined();
+        expect(rewriteEpoch.insertions + rewriteEpoch.deletions).toBeGreaterThan(100);
+    });
+    it("detects firefight epoch from fix/hotfix keywords", () => {
+        const commits = [
+            mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "initial" }),
+            mkCommit({ hash: "a2", authorDate: "2024-01-02", subject: "evolve feature" }),
+            mkCommit({ hash: "a3", authorDate: "2024-01-03", subject: "hotfix critical bug" }),
+            mkCommit({ hash: "a4", authorDate: "2024-01-04", subject: "fix regression" }),
+        ];
+        const changes = chmap(mkChange("a1", 50, 0), mkChange("a2", 20, 10), mkChange("a3", 5, 2), mkChange("a4", 8, 4));
+        const result = buildTimeMachine("src/x.ts", commits, changes);
+        const firefight = result.epochs.find((e) => e.kind === "firefight");
+        expect(firefight).toBeDefined();
+        expect(firefight.commits.length).toBeGreaterThanOrEqual(2);
+    });
+    it("detects polish epoch from small surgical changes", () => {
+        const commits = [
+            mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "initial" }),
+            mkCommit({ hash: "a2", authorDate: "2024-01-02", subject: "fix typo" }),
+            mkCommit({ hash: "a3", authorDate: "2024-01-03", subject: "format with prettier" }),
+        ];
+        const changes = chmap(mkChange("a1", 50, 0), mkChange("a2", 1, 1), mkChange("a3", 3, 3));
+        const result = buildTimeMachine("src/x.ts", commits, changes);
+        const polish = result.epochs.find((e) => e.kind === "polish");
+        expect(polish).toBeDefined();
+    });
+    it("inserts a plateau epoch when there is a long quiet gap", () => {
+        const commits = [
+            mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "initial" }),
+            mkCommit({ hash: "a2", authorDate: "2024-06-01", subject: "minor tweak" }),
+        ];
+        const changes = chmap(mkChange("a1", 50, 0), mkChange("a2", 5, 2));
+        const result = buildTimeMachine("src/x.ts", commits, changes, { plateauDays: 30 });
+        const plateau = result.epochs.find((e) => e.kind === "plateau" || e.kind === "twilight");
+        expect(plateau).toBeDefined();
+        expect(plateau.spanDays).toBeGreaterThanOrEqual(30);
+    });
+    it("computes health ratios summing to ≤ 1", () => {
+        const commits = Array.from({ length: 6 }, (_, i) => mkCommit({
+            hash: `c${i}`,
+            authorDate: `2024-01-${(i + 1).toString().padStart(2, "0")}`,
+            subject: i === 0 ? "init" : i % 2 === 0 ? "fix bug" : "refactor module",
+        }));
+        const changes = chmap(...commits.map((c, i) => mkChange(c.hash, i % 2 === 1 ? 200 : 5, i % 2 === 1 ? 100 : 5)));
+        const result = buildTimeMachine("src/x.ts", commits, changes);
+        const sum = result.health.rewriteRatio + result.health.firefightRatio + result.health.polishRatio;
+        expect(sum).toBeGreaterThanOrEqual(0);
+        expect(sum).toBeLessThanOrEqual(1);
+    });
+    it("picks defining commit by descriptiveness within an epoch", () => {
+        const commits = [
+            mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "init" }),
+            mkCommit({ hash: "a2", authorDate: "2024-01-02", subject: "x" }),
+            mkCommit({
+                hash: "a3",
+                authorDate: "2024-01-03",
+                subject: "evolve handler with comprehensive validation logic",
+            }),
+        ];
+        const changes = chmap(mkChange("a1", 30, 0), mkChange("a2", 5, 2), mkChange("a3", 20, 8));
+        const result = buildTimeMachine("src/x.ts", commits, changes);
+        // The evolution epoch should pick the longer subject
+        const evo = result.epochs.find((e) => e.kind === "evolution");
+        if (evo) {
+            expect(evo.defining.subject.length).toBeGreaterThanOrEqual(20);
+        }
+    });
+    it("produces non-empty labels for every epoch", () => {
+        const commits = [
+            mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "first" }),
+            mkCommit({ hash: "a2", authorDate: "2024-01-10", subject: "rewrite the parsing pipeline entirely" }),
+        ];
+        const result = buildTimeMachine("src/x.ts", commits, chmap(mkChange("a1", 50, 0), mkChange("a2", 300, 250)));
+        for (const e of result.epochs) {
+            expect(e.label.length).toBeGreaterThan(0);
+        }
+    });
+    it("orders epochs chronologically by index", () => {
+        const commits = [
+            mkCommit({ hash: "a1", authorDate: "2024-01-01", subject: "init" }),
+            mkCommit({ hash: "a2", authorDate: "2024-01-02", subject: "fix bug" }),
+            mkCommit({ hash: "a3", authorDate: "2024-01-03", subject: "refactor heavily" }),
+        ];
+        const result = buildTimeMachine("src/x.ts", commits, chmap(mkChange("a1", 30, 0), mkChange("a2", 5, 2), mkChange("a3", 200, 100)));
+        for (let i = 0; i < result.epochs.length; i++) {
+            expect(result.epochs[i].index).toBe(i + 1);
+        }
+    });
+});
+//# sourceMappingURL=time-machine.test.js.map

package/dist/insights/time-machine.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-machine.test.js","sourceRoot":"","sources":["../../src/insights/time-machine.test.ts"],"names":[],"mappings":"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"}

package/dist/insights/who-knows.d.ts

@@ -45,4 +45,22 @@ export declare function whoKnows(store: MnemeStore, opts: WhoKnowsOptions): Expe
 /** log-based commit weight × recency multiplier. Pure function, easy to test. */
 export declare function scoreCandidate(commitCount: number, lastTouchIso: string, now: Date): number;
 export declare function tierOf(commitCount: number, lastTouchIso: string, now: Date): ExpertCandidate["tier"];
+/**
+ * Verdict-shaped summary built from the full candidate list. Surfaces the
+ * single most likely person to ask + a confidence percentage + a fallback
+ * recommendation, instead of letting the user scan a list of names.
+ */
+export interface ExpertVerdict {
+    /** The single most likely expert (or undefined when no candidates). */
+    topExpert?: ExpertCandidate;
+    /** Confidence percentage 0..100 — share of total commits attributed to the top. */
+    confidencePct: number;
+    /** Backup expert if the top is stale or has insufficient share. */
+    backup?: ExpertCandidate;
+    /** A 1-line risk note when the top expert is stale or shares too thinly. */
+    risk?: string;
+    /** Total commits matched across all candidates (sum of commitCount). */
+    totalCommits: number;
+}
+export declare function whoKnowsVerdict(candidates: ExpertCandidate[]): ExpertVerdict;
 //# sourceMappingURL=who-knows.d.ts.map

package/dist/insights/who-knows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"who-knows.d.ts","sourceRoot":"","sources":["../../src/insights/who-knows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAKD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CA6DpF;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAQ3F;AAED,wBAAgB,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAOpG"}
+{"version":3,"file":"who-knows.d.ts","sourceRoot":"","sources":["../../src/insights/who-knows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAKD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,GAAG,eAAe,EAAE,CA6DpF;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAQ3F;AAED,wBAAgB,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAOpG;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,aAAa,CAoB5E"}