@mneme-ai/core 0.8.4 → 0.10.0

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

package/dist/insights/suggest.js.map

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

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

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

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

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

package/dist/insights/suggest.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { suggestFollowUps, extractTopicWord } from "./suggest.js";
+const cmt = (hash, subject, author = "alice", files = []) => ({
+    hash,
+    shortHash: hash.slice(0, 7),
+    authorName: author,
+    authorEmail: `${author}@example.com`,
+    authorDate: "2024-08-12T00:00:00Z",
+    committerDate: "2024-08-12T00:00:00Z",
+    subject,
+    body: "",
+    parents: [],
+    files,
+});
+const result = (hash, score, files = []) => ({
+    commit: cmt(hash, "subj", "alice", files),
+    score,
+    matchedChunks: [],
+});
+describe("extractTopicWord", () => {
+    it("returns camelCase identifier when present", () => {
+        expect(extractTopicWord("why does parseAmount throw?")).toBe("parseAmount");
+    });
+    it("returns path-like token when present", () => {
+        expect(extractTopicWord("what about src/payment changes?")).toBe("src/payment");
+    });
+    it("returns the longest meaningful word otherwise", () => {
+        expect(extractTopicWord("why is authentication broken")).toBe("authentication");
+    });
+    it("filters stop-words and code-noise words", () => {
+        // 'the', 'how', 'does', 'use' filtered → longest remaining is "function"
+        expect(extractTopicWord("how does the function use this")).toBe("function");
+    });
+    it("returns undefined when nothing concrete remains", () => {
+        expect(extractTopicWord("why")).toBeUndefined();
+        expect(extractTopicWord("the and or")).toBeUndefined();
+    });
+});
+describe("suggestFollowUps", () => {
+    it("returns no suggestions when results are empty", () => {
+        expect(suggestFollowUps("anything", [])).toEqual([]);
+    });
+    it("suggests `mneme why <file>` when top result has files", () => {
+        const out = suggestFollowUps("why does X exist?", [result("a", 0.05, ["src/payment.ts"])]);
+        expect(out.find((s) => s.command.startsWith("mneme why"))).toBeDefined();
+    });
+    it("suggests `mneme story <topic>` when topic word is extractable", () => {
+        const out = suggestFollowUps("how does authentication work?", [result("a", 0.05)]);
+        expect(out.find((s) => s.command.startsWith("mneme story"))).toBeDefined();
+    });
+    it("suggests `mneme who-knows <topic>` with the topic", () => {
+        const out = suggestFollowUps("authentication question", [result("a", 0.05)]);
+        expect(out.find((s) => s.command.startsWith("mneme who-knows"))).toBeDefined();
+    });
+    it("suggests `mneme blast <commit>` when there are 2+ results", () => {
+        const out = suggestFollowUps("auth", [result("abc1234", 0.05), result("def5678", 0.04)]);
+        expect(out.find((s) => s.command.includes("blast"))).toBeDefined();
+    });
+    it("caps suggestions at 3", () => {
+        const out = suggestFollowUps("authentication question", [result("abc1234", 0.05, ["src/auth.ts"]), result("def5678", 0.04)]);
+        expect(out.length).toBeLessThanOrEqual(3);
+    });
+    it("every suggestion has a non-empty command and reason", () => {
+        const out = suggestFollowUps("stripe webhook bigint", [result("a", 0.05, ["src/webhook.ts"]), result("b", 0.04)]);
+        for (const s of out) {
+            expect(s.command.length).toBeGreaterThan(5);
+            expect(s.reason.length).toBeGreaterThan(10);
+        }
+    });
+});
+//# sourceMappingURL=suggest.test.js.map

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

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

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

@@ -0,0 +1,66 @@
+/**
+ * `who-knows` — surface the people most likely to answer a question about
+ * a topic, ranked by their git activity on commits/files matching that topic.
+ *
+ * Why this exists: every team has tribal knowledge. "Ask alice about Stripe"
+ * is institutional memory. Mneme already indexes commits — making the
+ * institutional memory queryable is a small step from the engine the project
+ * already has.
+ *
+ * Scoring is intentionally simple and explainable. We avoid any "rank by
+ * cosine similarity of author embedding" trickery: this is a counting
+ * problem, and the user should be able to verify by running `git log
+ * --author=alice -- <files>`.
+ */
+import type { MnemeStore } from "../store/sqlite.js";
+export interface ExpertCandidate {
+    /** Author name as it appears in git. */
+    name: string;
+    email: string;
+    /** Number of commits authored that match the topic. */
+    commitCount: number;
+    /** Last commit author-date in ISO; lets the caller flag stale experts. */
+    lastTouch: string;
+    /** Distinct files touched (capped at 1000 for memory hygiene). */
+    filesTouched: number;
+    /** Score: log(commits + 1) × recency bonus. Higher = more authoritative. */
+    score: number;
+    /** Tier label derived from score + recency. */
+    tier: "definitive" | "active" | "stale" | "occasional";
+}
+export interface WhoKnowsOptions {
+    topic: string;
+    /** Cap on candidates returned (default 5). */
+    topN?: number;
+    /** ISO date — ignore commits older than this for the recency bonus. */
+    since?: string;
+    /** Today, in ISO format. Lets tests inject a deterministic clock. */
+    now?: Date;
+}
+/**
+ * Find people likely to know about `topic`. Searches commit messages,
+ * subjects, bodies, and PR titles via FTS, then aggregates by author.
+ */
+export declare function whoKnows(store: MnemeStore, opts: WhoKnowsOptions): ExpertCandidate[];
+/** 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

@@ -0,0 +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;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"}

package/dist/insights/who-knows.js

@@ -0,0 +1,125 @@
+/**
+ * `who-knows` — surface the people most likely to answer a question about
+ * a topic, ranked by their git activity on commits/files matching that topic.
+ *
+ * Why this exists: every team has tribal knowledge. "Ask alice about Stripe"
+ * is institutional memory. Mneme already indexes commits — making the
+ * institutional memory queryable is a small step from the engine the project
+ * already has.
+ *
+ * Scoring is intentionally simple and explainable. We avoid any "rank by
+ * cosine similarity of author embedding" trickery: this is a counting
+ * problem, and the user should be able to verify by running `git log
+ * --author=alice -- <files>`.
+ */
+const STALE_DAYS = 180;
+const ACTIVE_DAYS = 90;
+/**
+ * Find people likely to know about `topic`. Searches commit messages,
+ * subjects, bodies, and PR titles via FTS, then aggregates by author.
+ */
+export function whoKnows(store, opts) {
+    const topN = opts.topN ?? 5;
+    const now = opts.now ?? new Date();
+    // Pull commits whose chunks match the topic via FTS.
+    const ftsHits = store.ftsSearch(opts.topic, 200);
+    if (ftsHits.length === 0)
+        return [];
+    // Aggregate by commit hash (one chunk per commit can appear multiple times).
+    const commitHashes = new Set(ftsHits.map((h) => h.commitHash));
+    const buckets = new Map();
+    for (const hash of commitHashes) {
+        const c = store.getCommit(hash);
+        if (!c)
+            continue;
+        if (opts.since && c.authorDate < opts.since)
+            continue;
+        const key = `${c.authorName}|${c.authorEmail}`;
+        if (!buckets.has(key)) {
+            buckets.set(key, {
+                name: c.authorName,
+                email: c.authorEmail,
+                commitCount: 0,
+                lastTouch: c.authorDate,
+                files: new Set(),
+            });
+        }
+        const b = buckets.get(key);
+        b.commitCount += 1;
+        if (c.authorDate > b.lastTouch)
+            b.lastTouch = c.authorDate;
+        for (const f of (c.files ?? []).slice(0, 50))
+            b.files.add(f);
+        if (b.files.size > 1000) {
+            // Hygiene cap — extremely active authors on huge repos.
+            const arr = [...b.files];
+            b.files = new Set(arr.slice(0, 1000));
+        }
+    }
+    const candidates = [];
+    for (const b of buckets.values()) {
+        const score = scoreCandidate(b.commitCount, b.lastTouch, now);
+        candidates.push({
+            name: b.name,
+            email: b.email,
+            commitCount: b.commitCount,
+            lastTouch: b.lastTouch,
+            filesTouched: b.files.size,
+            score,
+            tier: tierOf(b.commitCount, b.lastTouch, now),
+        });
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    return candidates.slice(0, topN);
+}
+/** log-based commit weight × recency multiplier. Pure function, easy to test. */
+export function scoreCandidate(commitCount, lastTouchIso, now) {
+    const lastTouch = new Date(lastTouchIso);
+    const daysAgo = Math.max(0, (now.getTime() - lastTouch.getTime()) / (1000 * 60 * 60 * 24));
+    // Recency bonus: 1.0 within 30 days, decays linearly to 0.3 at 365 days, then floor 0.3.
+    const recency = daysAgo < 30 ? 1.0 : Math.max(0.3, 1.0 - (daysAgo - 30) / 480);
+    // Volume: log scale to avoid one mega-contributor dominating.
+    const volume = Math.log2(commitCount + 1);
+    return volume * recency;
+}
+export function tierOf(commitCount, lastTouchIso, now) {
+    const lastTouch = new Date(lastTouchIso);
+    const daysAgo = (now.getTime() - lastTouch.getTime()) / (1000 * 60 * 60 * 24);
+    if (commitCount >= 10 && daysAgo <= ACTIVE_DAYS)
+        return "definitive";
+    if (commitCount >= 3 && daysAgo <= ACTIVE_DAYS)
+        return "active";
+    if (daysAgo > STALE_DAYS)
+        return "stale";
+    return "occasional";
+}
+export function whoKnowsVerdict(candidates) {
+    if (candidates.length === 0) {
+        return { confidencePct: 0, totalCommits: 0 };
+    }
+    const sorted = [...candidates].sort((a, b) => b.score - a.score);
+    const top = sorted[0];
+    const total = candidates.reduce((s, c) => s + c.commitCount, 0);
+    const pct = total === 0 ? 0 : Math.round((top.commitCount / total) * 100);
+    const backup = sorted[1];
+    let risk;
+    if (top.tier === "stale") {
+        risk = `Top expert is STALE — last touched ${formatDaysAgo(top.lastTouch)} ago. Consider asking ${backup?.name ?? "someone with recent activity"} instead.`;
+    }
+    else if (pct < 30 && candidates.length >= 3) {
+        risk = `No single dominant expert — ${candidates.length} people share the work. Knowledge is well-distributed but no one will know everything.`;
+    }
+    else if (top.commitCount === 1) {
+        risk = "Top expert touched the topic only once — treat as weak signal.";
+    }
+    return { topExpert: top, confidencePct: pct, backup, risk, totalCommits: total };
+}
+function formatDaysAgo(iso) {
+    const d = (Date.now() - new Date(iso).getTime()) / 86_400_000;
+    if (d < 30)
+        return `${Math.round(d)}d`;
+    if (d < 365)
+        return `${Math.round(d / 30)}mo`;
+    return `${(d / 365).toFixed(1)}y`;
+}
+//# sourceMappingURL=who-knows.js.map

package/dist/insights/who-knows.js.map

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

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

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

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

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