@mneme-ai/core 0.8.4 → 0.10.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/stack-trace.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `stack-trace` — given an error / stack trace, find the commits that
+ * touched each frame and any past incidents at the same locations.
+ *
+ * Why this exists: when a prod bug fires, the most useful question is
+ * "have we seen this here before?" Mneme already indexes git + incidents.
+ * Parsing a stack trace and querying both is a small composition of pieces
+ * we already have.
+ *
+ * Supported formats (frame parser):
+ *   - JS/TS:  "    at functionName (path/to/file.ts:42:15)"
+ *   - Python: "  File "path/to/file.py", line 42, in functionName"
+ *   - Go:     "goroutine 1 [running]: ... path/to/file.go:42 +0x..."
+ *   - Java:   "    at com.example.Foo.bar(Foo.java:42)"
+ *
+ * Pure parsing — no I/O. Composing with retrieval lives in the CLI command.
+ */
+export interface StackFrame {
+    /** File path as it appears in the trace. May be absolute, relative, or module-qualified. */
+    file: string;
+    /** Line number where the frame is. 0 when absent. */
+    line: number;
+    /** Function/method name when extractable; may be empty. */
+    function?: string;
+    /** Programming language detected from the frame format. */
+    language: "js" | "python" | "go" | "java" | "unknown";
+}
+/**
+ * Parse a multi-line stack trace into ordered frames. Frames are deduped
+ * when the same (file, line) appears consecutively. Languages that share
+ * patterns (e.g. .ts files might also match the python file regex if
+ * weirdly formatted) are disambiguated by extension first.
+ */
+export declare function parseStackTrace(text: string): StackFrame[];
+/**
+ * Heuristic: detect whether the trace appears to be from a particular
+ * language. Useful when displaying frame analysis ("Python traceback").
+ */
+export declare function detectLanguage(text: string): StackFrame["language"];
+//# sourceMappingURL=stack-trace.d.ts.map

package/dist/insights/stack-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-trace.d.ts","sourceRoot":"","sources":["../../src/insights/stack-trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,UAAU;IACzB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,QAAQ,EAAE,IAAI,GAAG,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;CACvD;AA2DD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAyB1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CASnE"}

package/dist/insights/stack-trace.js

@@ -0,0 +1,127 @@
+/**
+ * `stack-trace` — given an error / stack trace, find the commits that
+ * touched each frame and any past incidents at the same locations.
+ *
+ * Why this exists: when a prod bug fires, the most useful question is
+ * "have we seen this here before?" Mneme already indexes git + incidents.
+ * Parsing a stack trace and querying both is a small composition of pieces
+ * we already have.
+ *
+ * Supported formats (frame parser):
+ *   - JS/TS:  "    at functionName (path/to/file.ts:42:15)"
+ *   - Python: "  File "path/to/file.py", line 42, in functionName"
+ *   - Go:     "goroutine 1 [running]: ... path/to/file.go:42 +0x..."
+ *   - Java:   "    at com.example.Foo.bar(Foo.java:42)"
+ *
+ * Pure parsing — no I/O. Composing with retrieval lives in the CLI command.
+ */
+const PATTERNS = [
+    // JS/TS — V8 / Node.js / browser
+    // "    at functionName (path/to/file.ts:42:15)"
+    // "    at path/to/file.ts:42:15"
+    {
+        language: "js",
+        re: /\bat\s+(?:(?<fn>[\w$.<>[\]\s]+?)\s+\()?(?<file>[^():\n]+\.[a-zA-Z]+):(?<line>\d+)(?::\d+)?\)?/g,
+        map: (m) => {
+            const file = m.groups?.file?.trim();
+            if (!file)
+                return null;
+            return {
+                file,
+                line: Number(m.groups?.line ?? 0),
+                function: m.groups?.fn?.trim() || undefined,
+                language: "js",
+            };
+        },
+    },
+    // Python — CPython tracebacks
+    // '  File "path/to/file.py", line 42, in functionName'
+    {
+        language: "python",
+        re: /File\s+"(?<file>[^"]+\.py[i]?)",\s+line\s+(?<line>\d+)(?:,\s+in\s+(?<fn>\w+))?/g,
+        map: (m) => ({
+            file: m.groups.file,
+            line: Number(m.groups.line),
+            function: m.groups?.fn || undefined,
+            language: "python",
+        }),
+    },
+    // Go — runtime panic format
+    // "    /home/x/main.go:42 +0x..."
+    // "main.foo(0x0, 0x0)"
+    // "    /home/x/foo.go:42"
+    {
+        language: "go",
+        re: /(?<file>[^\s():]+\.go):(?<line>\d+)/g,
+        map: (m) => ({
+            file: m.groups.file,
+            line: Number(m.groups.line),
+            language: "go",
+        }),
+    },
+    // Java
+    // "    at com.example.Foo.bar(Foo.java:42)"
+    {
+        language: "java",
+        re: /\bat\s+(?<fn>[\w.$]+)\((?<file>[^()]+\.java):(?<line>\d+)\)/g,
+        map: (m) => ({
+            file: m.groups.file,
+            line: Number(m.groups.line),
+            function: m.groups?.fn || undefined,
+            language: "java",
+        }),
+    },
+];
+/**
+ * Parse a multi-line stack trace into ordered frames. Frames are deduped
+ * when the same (file, line) appears consecutively. Languages that share
+ * patterns (e.g. .ts files might also match the python file regex if
+ * weirdly formatted) are disambiguated by extension first.
+ */
+export function parseStackTrace(text) {
+    if (!text || !text.trim())
+        return [];
+    const seen = new Set();
+    const frames = [];
+    for (const p of PATTERNS) {
+        const re = new RegExp(p.re.source, p.re.flags);
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            const frame = p.map(m);
+            if (!frame)
+                continue;
+            // Skip language-mismatch (e.g. js regex matching a Java line).
+            const ext = frame.file.split(".").pop()?.toLowerCase();
+            if (frame.language === "js" && ext && !["js", "ts", "jsx", "tsx", "mjs", "cjs"].includes(ext))
+                continue;
+            const key = `${frame.file}:${frame.line}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            frames.push(frame);
+        }
+    }
+    // Sort by appearance order in original text (so most-recent-frame-first
+    // for languages where the trace is bottom-up like Python).
+    // Detection: count file paths — the first frame in the input is what we keep first.
+    return frames.sort((a, b) => text.indexOf(a.file) - text.indexOf(b.file));
+}
+/**
+ * Heuristic: detect whether the trace appears to be from a particular
+ * language. Useful when displaying frame analysis ("Python traceback").
+ */
+export function detectLanguage(text) {
+    const t = text.toLowerCase();
+    if (t.includes("traceback") || t.includes('file "') || t.includes(".py"))
+        return t.includes(".py") ? "python" : "unknown";
+    if (t.includes("goroutine") || /\.go:\d+/.test(t))
+        return "go";
+    if (/\.java:\d+/.test(t))
+        return "java";
+    if (/\b(typeerror|referenceerror|syntaxerror|rangeerror)\b/.test(t))
+        return "js";
+    if (/\.[jt]sx?:\d+/.test(t))
+        return "js";
+    return "unknown";
+}
+//# sourceMappingURL=stack-trace.js.map

package/dist/insights/stack-trace.js.map

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

package/dist/insights/stack-trace.test.d.ts

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

package/dist/insights/stack-trace.test.d.ts.map

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

package/dist/insights/stack-trace.test.js

@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest";
+import { parseStackTrace, detectLanguage } from "./stack-trace.js";
+describe("parseStackTrace — JavaScript/TypeScript", () => {
+    it("parses V8-style frames with function name", () => {
+        const trace = `TypeError: Cannot read property 'amount' of undefined
+    at parseAmount (src/payment.ts:42:15)
+    at processCharge (src/payment.ts:78:9)
+    at Object.<anonymous> (src/index.ts:5:1)`;
+        const frames = parseStackTrace(trace);
+        expect(frames).toHaveLength(3);
+        expect(frames[0]).toMatchObject({ file: "src/payment.ts", line: 42, function: "parseAmount", language: "js" });
+        expect(frames[1].function).toBe("processCharge");
+    });
+    it("parses anonymous frames (no function name)", () => {
+        const trace = `Error: kaboom
+    at /app/dist/main.js:1:42`;
+        const frames = parseStackTrace(trace);
+        expect(frames[0]?.file).toBe("/app/dist/main.js");
+        expect(frames[0]?.function).toBeUndefined();
+    });
+});
+describe("parseStackTrace — Python", () => {
+    it("parses CPython tracebacks", () => {
+        const trace = `Traceback (most recent call last):
+  File "/app/main.py", line 42, in process_charge
+    amount = parse_amount(payload["amount"])
+  File "/app/payment.py", line 17, in parse_amount
+    return Decimal(value)
+ValueError: not a number`;
+        const frames = parseStackTrace(trace);
+        expect(frames.length).toBeGreaterThanOrEqual(2);
+        const main = frames.find((f) => f.file.endsWith("main.py"));
+        expect(main).toMatchObject({ line: 42, function: "process_charge", language: "python" });
+    });
+});
+describe("parseStackTrace — Go", () => {
+    it("parses Go panic file:line references", () => {
+        const trace = `goroutine 1 [running]:
+main.foo(0x0)
+	/home/dev/app/main.go:42 +0x12
+runtime.main()
+	/usr/local/go/src/runtime/proc.go:250`;
+        const frames = parseStackTrace(trace);
+        expect(frames.length).toBeGreaterThanOrEqual(2);
+        expect(frames.find((f) => f.file === "/home/dev/app/main.go")?.line).toBe(42);
+    });
+});
+describe("parseStackTrace — Java", () => {
+    it("parses Java stack frames with class.method(File.java:line)", () => {
+        const trace = `Exception in thread "main" java.lang.NullPointerException
+    at com.example.Foo.bar(Foo.java:42)
+    at com.example.App.main(App.java:7)`;
+        const frames = parseStackTrace(trace);
+        expect(frames).toHaveLength(2);
+        expect(frames[0]).toMatchObject({ file: "Foo.java", line: 42, language: "java" });
+        expect(frames[0].function).toContain("Foo.bar");
+    });
+});
+describe("parseStackTrace — edge cases", () => {
+    it("returns empty array for empty input", () => {
+        expect(parseStackTrace("")).toEqual([]);
+        expect(parseStackTrace("   \n  \n")).toEqual([]);
+    });
+    it("dedupes consecutive identical (file, line) frames", () => {
+        const trace = `at a (foo.ts:42:1)
+at a (foo.ts:42:1)
+at a (foo.ts:42:1)`;
+        expect(parseStackTrace(trace)).toHaveLength(1);
+    });
+    it("filters out non-matching language extensions", () => {
+        // ".java" file should not match the JS regex even if the format looks similar.
+        const trace = `at com.x.Foo.bar(Foo.java:42)`;
+        const frames = parseStackTrace(trace);
+        expect(frames.every((f) => f.language === "java")).toBe(true);
+    });
+    it("handles a mixed trace (multiple languages in one input)", () => {
+        const trace = `TypeError: kaboom
+    at handler (src/api.ts:42:1)
+And in the worker:
+  File "/app/worker.py", line 7, in run_job`;
+        const frames = parseStackTrace(trace);
+        expect(frames.find((f) => f.language === "js")).toBeDefined();
+        expect(frames.find((f) => f.language === "python")).toBeDefined();
+    });
+});
+describe("detectLanguage — heuristic top-level detection", () => {
+    it("python (Traceback header)", () => {
+        expect(detectLanguage("Traceback (most recent call last):\n  File \"x.py\", line 1, in f")).toBe("python");
+    });
+    it("go (goroutine header)", () => {
+        expect(detectLanguage("goroutine 1 [running]:\n/x/main.go:1 +0x")).toBe("go");
+    });
+    it("java (.java:N pattern)", () => {
+        expect(detectLanguage("at com.x.Foo.bar(Foo.java:42)")).toBe("java");
+    });
+    it("js (TypeError keyword)", () => {
+        expect(detectLanguage("TypeError: Cannot read property 'x' of undefined")).toBe("js");
+    });
+    it("unknown when no marker", () => {
+        expect(detectLanguage("just some random text")).toBe("unknown");
+    });
+});
+//# sourceMappingURL=stack-trace.test.js.map

package/dist/insights/stack-trace.test.js.map

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

package/dist/insights/story.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `story <topic>` — narrative generation. Take a topic, find every commit
+ * that touched it, group into "acts" (initial / refactor / incidents /
+ * stable), and emit a structured timeline. The LLM (when available) can
+ * polish the act labels and write a short prose summary.
+ *
+ * Pure data extraction in this file. The CLI command renders + optionally
+ * pipes through an LLM for prose.
+ */
+import type { Commit } from "../types.js";
+export interface StoryAct {
+    /** Stable id used for the section header. */
+    id: "initial" | "refactor" | "incident" | "evolution" | "stable";
+    /** Human-readable title — "Act I — The Beginning" etc. */
+    title: string;
+    /** Commits in chronological order (oldest first). */
+    commits: Commit[];
+    /** Date range of the act. */
+    fromDate: string;
+    toDate: string;
+}
+export interface Story {
+    topic: string;
+    acts: StoryAct[];
+    totalCommits: number;
+    spanDays: number;
+}
+/**
+ * Build a Story from a list of commits matching the topic. Commits should
+ * already be filtered by relevance (e.g. via FTS) and sorted chronologically
+ * by the caller.
+ */
+export declare function buildStory(topic: string, commits: Commit[]): Story;
+//# sourceMappingURL=story.d.ts.map

package/dist/insights/story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/insights/story.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,EAAE,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;IACjE,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAqElE"}

package/dist/insights/story.js

@@ -0,0 +1,100 @@
+/**
+ * `story <topic>` — narrative generation. Take a topic, find every commit
+ * that touched it, group into "acts" (initial / refactor / incidents /
+ * stable), and emit a structured timeline. The LLM (when available) can
+ * polish the act labels and write a short prose summary.
+ *
+ * Pure data extraction in this file. The CLI command renders + optionally
+ * pipes through an LLM for prose.
+ */
+const REFACTOR_KEYWORDS = /\b(refactor|rewrite|migrate|switch(?:ed)?|replace[ds]?|deprecate)\b/i;
+const INCIDENT_KEYWORDS = /\b(incident|outage|hotfix|revert|rollback|broken|critical|emergency|p[01])\b/i;
+/**
+ * Build a Story from a list of commits matching the topic. Commits should
+ * already be filtered by relevance (e.g. via FTS) and sorted chronologically
+ * by the caller.
+ */
+export function buildStory(topic, commits) {
+    const sorted = [...commits].sort((a, b) => a.authorDate.localeCompare(b.authorDate));
+    if (sorted.length === 0) {
+        return { topic, acts: [], totalCommits: 0, spanDays: 0 };
+    }
+    const acts = [];
+    // Act I — Initial: the very first commit on the topic.
+    const initial = sorted[0];
+    acts.push({
+        id: "initial",
+        title: "Act I — The Beginning",
+        commits: [initial],
+        fromDate: initial.authorDate.slice(0, 10),
+        toDate: initial.authorDate.slice(0, 10),
+    });
+    const remaining = sorted.slice(1);
+    let currentFlavor = null;
+    let currentBucket = [];
+    const flush = () => {
+        if (currentBucket.length === 0 || !currentFlavor)
+            return;
+        acts.push({
+            id: currentFlavor,
+            title: titleFor(currentFlavor, acts.length),
+            commits: [...currentBucket],
+            fromDate: currentBucket[0].authorDate.slice(0, 10),
+            toDate: currentBucket[currentBucket.length - 1].authorDate.slice(0, 10),
+        });
+        currentBucket = [];
+        currentFlavor = null;
+    };
+    for (const c of remaining) {
+        const flavor = detectFlavor(c);
+        if (flavor !== currentFlavor)
+            flush();
+        currentFlavor = flavor;
+        currentBucket.push(c);
+    }
+    flush();
+    // Final act — if the most recent commit is older than 90 days, consider
+    // the topic "stable" (no recent change).
+    const last = sorted[sorted.length - 1];
+    const ageDays = (Date.now() - new Date(last.authorDate).getTime()) / 86_400_000;
+    if (ageDays > 90 && acts[acts.length - 1].id !== "stable") {
+        acts.push({
+            id: "stable",
+            title: `${acts.length === 0 ? "Act I" : romanFor(acts.length + 1)} — The Stable State`,
+            commits: [last],
+            fromDate: last.authorDate.slice(0, 10),
+            toDate: new Date().toISOString().slice(0, 10),
+        });
+    }
+    const span = Math.round((new Date(last.authorDate).getTime() - new Date(initial.authorDate).getTime()) / 86_400_000);
+    return {
+        topic,
+        acts,
+        totalCommits: sorted.length,
+        spanDays: span,
+    };
+}
+function detectFlavor(c) {
+    const text = `${c.subject}\n${c.body || ""}`;
+    if (INCIDENT_KEYWORDS.test(text))
+        return "incident";
+    if (REFACTOR_KEYWORDS.test(text))
+        return "refactor";
+    return "evolution";
+}
+function titleFor(flavor, actIndex) {
+    const roman = romanFor(actIndex + 1);
+    switch (flavor) {
+        case "refactor":
+            return `${roman} — The Refactor`;
+        case "incident":
+            return `${roman} — Incidents Strike`;
+        case "evolution":
+            return `${roman} — Steady Evolution`;
+    }
+}
+function romanFor(n) {
+    const roman = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"];
+    return n <= 10 ? `Act ${roman[n - 1]}` : `Act ${n}`;
+}
+//# sourceMappingURL=story.js.map

package/dist/insights/story.js.map

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

package/dist/insights/story.test.d.ts

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

package/dist/insights/story.test.d.ts.map

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