@mneme-ai/core 0.8.3 → 0.9.0

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":""}

package/dist/insights/story.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+import { buildStory } from "./story.js";
+const cmt = (hash, date, subject, body = "") => ({
+    hash,
+    shortHash: hash.slice(0, 7),
+    authorName: "alice",
+    authorEmail: "alice@example.com",
+    authorDate: `${date}T00:00:00Z`,
+    committerDate: `${date}T00:00:00Z`,
+    subject,
+    body,
+    parents: [],
+    files: [],
+});
+describe("buildStory — basic structure", () => {
+    it("returns empty story for empty commit list", () => {
+        const s = buildStory("auth", []);
+        expect(s.acts).toEqual([]);
+        expect(s.totalCommits).toBe(0);
+        expect(s.spanDays).toBe(0);
+    });
+    it("first commit always opens Act I", () => {
+        const s = buildStory("auth", [cmt("a1", "2024-01-01", "feat: add passport.js")]);
+        expect(s.acts[0].id).toBe("initial");
+        expect(s.acts[0].title).toContain("Beginning");
+    });
+    it("totalCommits and spanDays reflect input", () => {
+        const s = buildStory("auth", [
+            cmt("a1", "2024-01-01", "feat: passport"),
+            cmt("a2", "2024-04-01", "refactor: replace passport"),
+        ]);
+        expect(s.totalCommits).toBe(2);
+        expect(s.spanDays).toBeGreaterThanOrEqual(89); // about 90 days between Jan 1 and Apr 1
+    });
+});
+describe("buildStory — act detection", () => {
+    it("groups consecutive refactor-style commits into one Refactor act", () => {
+        const s = buildStory("auth", [
+            cmt("a1", "2024-01-01", "feat: passport"),
+            cmt("a2", "2024-04-01", "refactor: replace passport with custom"),
+            cmt("a3", "2024-04-08", "refactor: switch to JWT signing"),
+            cmt("a4", "2024-04-15", "refactor: migrate session middleware"),
+        ]);
+        const refactorActs = s.acts.filter((a) => a.id === "refactor");
+        expect(refactorActs).toHaveLength(1);
+        expect(refactorActs[0].commits).toHaveLength(3);
+    });
+    it("flags 'hotfix' and 'incident' commits as incident acts", () => {
+        const s = buildStory("auth", [
+            cmt("a1", "2024-01-01", "feat: passport"),
+            cmt("a2", "2024-02-01", "hotfix: CSRF bypass after refactor", ""),
+            cmt("a3", "2024-02-02", "revert: PR #42 caused outage"),
+        ]);
+        expect(s.acts.find((a) => a.id === "incident")).toBeDefined();
+    });
+    it("commits without keywords flagged as evolution", () => {
+        const s = buildStory("auth", [
+            cmt("a1", "2024-01-01", "feat: passport"),
+            cmt("a2", "2024-01-15", "feat: add /me endpoint"),
+            cmt("a3", "2024-02-01", "feat: add /logout endpoint"),
+        ]);
+        expect(s.acts.find((a) => a.id === "evolution")).toBeDefined();
+    });
+    it("transitions across flavors close+open separate acts", () => {
+        const s = buildStory("auth", [
+            cmt("a1", "2024-01-01", "feat: passport"), // initial
+            cmt("a2", "2024-01-10", "feat: add session cookies"), // evolution
+            cmt("a3", "2024-02-01", "refactor: replace passport"), // refactor
+            cmt("a4", "2024-02-15", "feat: add audit logs"), // evolution
+            cmt("a5", "2024-03-01", "hotfix: critical XSS"), // incident
+        ]);
+        const ids = s.acts.map((a) => a.id);
+        expect(ids[0]).toBe("initial");
+        expect(ids).toContain("refactor");
+        expect(ids).toContain("evolution");
+        expect(ids).toContain("incident");
+    });
+    it("appends a Stable State act when the latest commit is > 90 days old", () => {
+        const oneYearAgo = new Date(Date.now() - 400 * 86_400_000).toISOString().slice(0, 10);
+        const s = buildStory("auth", [cmt("a1", oneYearAgo, "feat: passport")]);
+        const stable = s.acts.find((a) => a.id === "stable");
+        expect(stable).toBeDefined();
+    });
+});
+describe("buildStory — date metadata", () => {
+    it("each act records fromDate and toDate", () => {
+        const s = buildStory("auth", [
+            cmt("a1", "2024-01-01", "feat: passport"),
+            cmt("a2", "2024-04-01", "refactor: replace passport"),
+            cmt("a3", "2024-04-15", "refactor: switch to JWT"),
+        ]);
+        for (const act of s.acts) {
+            expect(act.fromDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+            expect(act.toDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+            expect(act.fromDate <= act.toDate).toBe(true);
+        }
+    });
+});
+//# sourceMappingURL=story.test.js.map

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

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

package/dist/insights/suggest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Smart suggestions — given a question and its results, propose 3 follow-up
+ * commands the user might want to run next.
+ *
+ * Pure function. Heuristic, not LLM. Deterministic so tests can verify it.
+ *
+ * Design principle: every suggestion must lead to an actionable command
+ * the user can copy-paste. Vague hints ("explore more", "look around") are
+ * useless; concrete commands compound.
+ */
+import type { SearchResult } from "../types.js";
+export interface Suggestion {
+    /** The CLI command, ready to copy-paste. */
+    command: string;
+    /** One-line "why this is interesting". */
+    reason: string;
+}
+/**
+ * Build follow-up suggestions for an `ask` query.
+ * Returns 0..3 suggestions, ordered by likely usefulness.
+ */
+export declare function suggestFollowUps(question: string, results: SearchResult[]): Suggestion[];
+/**
+ * Extract a "topic word" from a question — the most concrete noun, suitable
+ * for plugging into `story <topic>` or `who-knows <topic>`. Falsy when nothing
+ * concrete is present.
+ */
+export declare function extractTopicWord(question: string): string | undefined;
+//# sourceMappingURL=suggest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.d.ts","sourceRoot":"","sources":["../../src/insights/suggest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,UAAU,EAAE,CAiDxF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA0BrE"}

package/dist/insights/suggest.js

@@ -0,0 +1,93 @@
+/**
+ * Smart suggestions — given a question and its results, propose 3 follow-up
+ * commands the user might want to run next.
+ *
+ * Pure function. Heuristic, not LLM. Deterministic so tests can verify it.
+ *
+ * Design principle: every suggestion must lead to an actionable command
+ * the user can copy-paste. Vague hints ("explore more", "look around") are
+ * useless; concrete commands compound.
+ */
+/**
+ * Build follow-up suggestions for an `ask` query.
+ * Returns 0..3 suggestions, ordered by likely usefulness.
+ */
+export function suggestFollowUps(question, results) {
+    const out = [];
+    if (results.length === 0)
+        return out;
+    const top = results[0];
+    const topAuthor = top.commit.authorName;
+    const topFile = (top.commit.files ?? [])[0];
+    // 1. If the top commit has files, suggest `mneme why <file>:<line>` for the
+    //    most-changed file. Anchor question into a specific location.
+    if (topFile) {
+        out.push({
+            command: `mneme why ${topFile}`,
+            reason: `Walk the blame + history of the file most changed in the top commit`,
+        });
+    }
+    // 2. Story command — narrate the topic across acts.
+    const topicWord = extractTopicWord(question);
+    if (topicWord) {
+        out.push({
+            command: `mneme story ${topicWord}`,
+            reason: `See how "${topicWord}" evolved across acts (initial / refactor / incidents)`,
+        });
+    }
+    // 3. Who-knows — surface the human expert.
+    if (topicWord && topAuthor) {
+        out.push({
+            command: `mneme who-knows ${topicWord}`,
+            reason: `Find people most likely to know about "${topicWord}" (top hit so far: ${topAuthor})`,
+        });
+    }
+    else if (topAuthor) {
+        out.push({
+            command: `mneme who-knows ${topAuthor.split(/\s+/)[0]?.toLowerCase()}`,
+            reason: `See where ${topAuthor} has been most active recently`,
+        });
+    }
+    // 4. Blast radius if the top commit looks recent.
+    if (results.length >= 2 && top.commit.shortHash) {
+        out.push({
+            command: `mneme blast ${top.commit.shortHash}`,
+            reason: `Predict incidents likely to follow shipping the top commit (base-rate verdict)`,
+        });
+    }
+    return out.slice(0, 3);
+}
+/**
+ * Extract a "topic word" from a question — the most concrete noun, suitable
+ * for plugging into `story <topic>` or `who-knows <topic>`. Falsy when nothing
+ * concrete is present.
+ */
+export function extractTopicWord(question) {
+    // 1. Look for camelCase / PascalCase identifiers (case-sensitive on the original).
+    const camel = question.match(/[a-z]+[A-Z][a-zA-Z]+/);
+    if (camel)
+        return camel[0];
+    // 2. Look for path-like tokens (lowercased — paths are usually lowercase anyway).
+    const q = question.toLowerCase();
+    const path = q.match(/[a-z]+\/[a-z]+/);
+    if (path)
+        return path[0];
+    // 3. Strip stop-words and punctuation and pick the longest remaining token.
+    const STOP = new Set([
+        "the", "a", "an", "is", "are", "was", "were", "do", "does", "did",
+        "why", "when", "what", "who", "how", "where", "this", "that",
+        "to", "from", "on", "in", "of", "for", "with", "and", "or", "but",
+        "code", "file", "method", "module", "any",
+        "use", "uses", "used", "using",
+    ]);
+    const words = q
+        .replace(/[?.,!;:'"()[\]{}]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length >= 4 && !STOP.has(w));
+    if (words.length === 0)
+        return undefined;
+    // Prefer longest distinct-looking word.
+    words.sort((a, b) => b.length - a.length);
+    return words[0];
+}
+//# sourceMappingURL=suggest.js.map