akm-cli 0.6.0 → 0.7.0-rc1

package/dist/tests/memory-inference.test.js

@@ -0,0 +1,299 @@
+/**
+ * Tests for the memory-inference pass (#201).
+ *
+ * The LLM client is never called for real — `splitMemoryIntoAtomicFacts` is
+ * mocked via `mock.module` to return deterministic atomic-fact splits. These
+ * tests cover:
+ *   - pending detection (parent vs already-inferred vs already-processed)
+ *   - the disabled-by-default path (no `akm.llm` configured)
+ *   - the `index.memory.llm = false` opt-out
+ *   - children written with `inferred: true` + `source:` backref
+ *   - re-running the pass is idempotent (no duplicate children, parent stays
+ *     processed, inferred children are not deleted when toggled off)
+ */
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseFrontmatter } from "../src/core/frontmatter";
+// ── Module-level LLM stub ───────────────────────────────────────────────────
+//
+// `mock.module` must run before the module under test is imported, so we set
+// up the stub here at the top of the file. The behaviour is controlled by
+// the mutable `splitter` variable — each test sets it to whatever
+// deterministic split it wants.
+let splitter = () => [];
+mock.module("../src/llm/memory-infer", () => ({
+    splitMemoryIntoAtomicFacts: async (_config, body) => splitter(body),
+}));
+// Import AFTER mock.module so the pass picks up the stub.
+const { runMemoryInferencePass, isPendingMemory, collectPendingMemories } = await import("../src/indexer/memory-inference");
+// ── Test fixtures ───────────────────────────────────────────────────────────
+let tmpStash = "";
+beforeEach(() => {
+    tmpStash = fs.mkdtempSync(path.join(os.tmpdir(), "akm-memory-infer-"));
+    fs.mkdirSync(path.join(tmpStash, "memories"), { recursive: true });
+    splitter = () => [];
+});
+afterEach(() => {
+    if (tmpStash) {
+        fs.rmSync(tmpStash, { recursive: true, force: true });
+        tmpStash = "";
+    }
+});
+function writeMemory(name, frontmatter, body) {
+    const fmLines = ["---"];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        fmLines.push(`${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+    }
+    fmLines.push("---");
+    const content = `${fmLines.join("\n")}\n\n${body}\n`;
+    const filePath = path.join(tmpStash, "memories", `${name}.md`);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, "utf8");
+    return filePath;
+}
+const SAMPLE_LLM = {
+    endpoint: "http://localhost:11434/v1/chat/completions",
+    model: "llama3.2",
+};
+function configWithLlm() {
+    return {
+        semanticSearchMode: "auto",
+        llm: { ...SAMPLE_LLM },
+    };
+}
+function configOptedOut() {
+    return {
+        semanticSearchMode: "auto",
+        llm: { ...SAMPLE_LLM },
+        index: { memory: { llm: false } },
+    };
+}
+function sources() {
+    return [{ path: tmpStash }];
+}
+// ── isPendingMemory predicate ───────────────────────────────────────────────
+describe("isPendingMemory", () => {
+    test("plain memory with no inference markers is pending", () => {
+        expect(isPendingMemory({ description: "anything" })).toBe(true);
+    });
+    test("inferred children are not pending", () => {
+        expect(isPendingMemory({ inferred: true, source: "memory:parent" })).toBe(false);
+    });
+    test("memory already marked processed is not pending", () => {
+        expect(isPendingMemory({ inferenceProcessed: true })).toBe(false);
+    });
+    test("inference markers must be literal `true` — non-boolean is treated as not-set", () => {
+        expect(isPendingMemory({ inferred: "yes" })).toBe(true);
+        expect(isPendingMemory({ inferenceProcessed: 1 })).toBe(true);
+    });
+});
+// ── collectPendingMemories ──────────────────────────────────────────────────
+describe("collectPendingMemories", () => {
+    test("returns empty when memories/ does not exist", () => {
+        const fresh = fs.mkdtempSync(path.join(os.tmpdir(), "akm-mi-empty-"));
+        try {
+            expect(collectPendingMemories(fresh)).toEqual([]);
+        }
+        finally {
+            fs.rmSync(fresh, { recursive: true, force: true });
+        }
+    });
+    test("walks markdown files and filters by predicate", () => {
+        writeMemory("plain", {}, "Plain body, needs splitting.");
+        writeMemory("already-inferred", { inferred: true, source: "memory:plain" }, "Atomic.");
+        writeMemory("already-processed", { inferenceProcessed: true }, "Already split.");
+        writeMemory("nested/sub", {}, "Nested memory body.");
+        // A non-markdown file under memories/ must be ignored.
+        fs.writeFileSync(path.join(tmpStash, "memories", "notes.txt"), "ignore me");
+        const pending = collectPendingMemories(tmpStash);
+        const names = pending.map((p) => p.ref).sort();
+        expect(names).toEqual(["memory:nested/sub", "memory:plain"]);
+    });
+});
+// ── runMemoryInferencePass — disabled paths ─────────────────────────────────
+describe("runMemoryInferencePass — disabled by default", () => {
+    test("returns no-op when no akm.llm is configured", async () => {
+        writeMemory("plain", {}, "Plain body, needs splitting.");
+        splitter = () => ["should not be called"];
+        const result = await runMemoryInferencePass({ semanticSearchMode: "auto" }, sources());
+        expect(result).toEqual({ considered: 0, splitParents: 0, writtenFacts: 0, skippedNoFacts: 0 });
+    });
+    test("returns no-op when index.memory.llm = false", async () => {
+        const filePath = writeMemory("plain", {}, "Plain body, needs splitting.");
+        splitter = () => ["should not be called"];
+        const result = await runMemoryInferencePass(configOptedOut(), sources());
+        expect(result.writtenFacts).toBe(0);
+        // Existing inferred children are NOT deleted — but here we just confirm
+        // the parent file is unchanged, since the toggle should not mutate state.
+        const fm = parseFrontmatter(fs.readFileSync(filePath, "utf8"));
+        expect(fm.data.inferenceProcessed).toBeUndefined();
+    });
+    test("toggling off after a previous run leaves existing inferred children intact", async () => {
+        // First run: enabled. Splits one parent into two facts.
+        writeMemory("parent", {}, "Body.");
+        splitter = () => ["fact 1", "fact 2"];
+        await runMemoryInferencePass(configWithLlm(), sources());
+        const factsDir = path.join(tmpStash, "memories", "parent.facts");
+        expect(fs.existsSync(path.join(factsDir, "fact-1.md"))).toBe(true);
+        expect(fs.existsSync(path.join(factsDir, "fact-2.md"))).toBe(true);
+        // Second run: disabled. Children must remain on disk.
+        splitter = () => {
+            throw new Error("must not be called when disabled");
+        };
+        await runMemoryInferencePass(configOptedOut(), sources());
+        expect(fs.existsSync(path.join(factsDir, "fact-1.md"))).toBe(true);
+        expect(fs.existsSync(path.join(factsDir, "fact-2.md"))).toBe(true);
+    });
+});
+// ── runMemoryInferencePass — orthogonal gating (§14 + #208) ─────────────────
+describe("runMemoryInferencePass — feature flag and per-pass key are orthogonal", () => {
+    test("runs when both gates allow (feature on, per-pass on)", async () => {
+        writeMemory("parent", {}, "Body.");
+        splitter = () => ["fact 1"];
+        const cfg = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM, features: { memory_inference: true } },
+            // index.memory.llm omitted → defaults to enabled.
+        };
+        const result = await runMemoryInferencePass(cfg, sources());
+        expect(result.writtenFacts).toBe(1);
+        expect(result.splitParents).toBe(1);
+    });
+    test("skipped when llm.features.memory_inference = false even with index.memory.llm enabled", async () => {
+        const filePath = writeMemory("parent", {}, "Body.");
+        let invocations = 0;
+        splitter = () => {
+            invocations += 1;
+            return ["should never be called"];
+        };
+        const cfg = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM, features: { memory_inference: false } },
+            index: { memory: { llm: true } },
+        };
+        const result = await runMemoryInferencePass(cfg, sources());
+        expect(result).toEqual({ considered: 0, splitParents: 0, writtenFacts: 0, skippedNoFacts: 0 });
+        expect(invocations).toBe(0);
+        // Parent is not mutated when the feature gate blocks.
+        const fm = parseFrontmatter(fs.readFileSync(filePath, "utf8"));
+        expect(fm.data.inferenceProcessed).toBeUndefined();
+    });
+    test("skipped when index.memory.llm = false even with llm.features.memory_inference = true", async () => {
+        const filePath = writeMemory("parent", {}, "Body.");
+        let invocations = 0;
+        splitter = () => {
+            invocations += 1;
+            return ["should never be called"];
+        };
+        const cfg = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM, features: { memory_inference: true } },
+            index: { memory: { llm: false } },
+        };
+        const result = await runMemoryInferencePass(cfg, sources());
+        expect(result.writtenFacts).toBe(0);
+        expect(invocations).toBe(0);
+        const fm = parseFrontmatter(fs.readFileSync(filePath, "utf8"));
+        expect(fm.data.inferenceProcessed).toBeUndefined();
+    });
+});
+// ── runMemoryInferencePass — enabled path ───────────────────────────────────
+describe("runMemoryInferencePass — enabled", () => {
+    test("writes atomic children with `inferred: true` and `source:` backref", async () => {
+        writeMemory("parent", { description: "before" }, "Two facts in one body.");
+        splitter = () => ["First atomic fact.", "Second atomic fact."];
+        const result = await runMemoryInferencePass(configWithLlm(), sources());
+        expect(result).toEqual({
+            considered: 1,
+            splitParents: 1,
+            writtenFacts: 2,
+            skippedNoFacts: 0,
+        });
+        const factsDir = path.join(tmpStash, "memories", "parent.facts");
+        const child1 = parseFrontmatter(fs.readFileSync(path.join(factsDir, "fact-1.md"), "utf8"));
+        expect(child1.data.inferred).toBe(true);
+        expect(child1.data.source).toBe("memory:parent");
+        expect(child1.content.trim()).toBe("First atomic fact.");
+        const child2 = parseFrontmatter(fs.readFileSync(path.join(factsDir, "fact-2.md"), "utf8"));
+        expect(child2.data.inferred).toBe(true);
+        expect(child2.data.source).toBe("memory:parent");
+        expect(child2.content.trim()).toBe("Second atomic fact.");
+    });
+    test("marks parent with inferenceProcessed: true and preserves prior frontmatter", async () => {
+        const filePath = writeMemory("parent", { description: "preserve me", tags: "[a, b]" }, "Body.");
+        splitter = () => ["only fact"];
+        await runMemoryInferencePass(configWithLlm(), sources());
+        const parentFm = parseFrontmatter(fs.readFileSync(filePath, "utf8"));
+        expect(parentFm.data.inferenceProcessed).toBe(true);
+        expect(parentFm.data.description).toBe("preserve me");
+    });
+    test("re-running the pass is idempotent — no duplicate splits", async () => {
+        writeMemory("parent", {}, "Body.");
+        let calls = 0;
+        splitter = () => {
+            calls += 1;
+            return ["fact A", "fact B"];
+        };
+        await runMemoryInferencePass(configWithLlm(), sources());
+        await runMemoryInferencePass(configWithLlm(), sources());
+        // Second invocation must not call the splitter — the parent is already
+        // marked `inferenceProcessed: true`.
+        expect(calls).toBe(1);
+        const factsDir = path.join(tmpStash, "memories", "parent.facts");
+        const childFiles = fs
+            .readdirSync(factsDir)
+            .filter((f) => f.endsWith(".md"))
+            .sort();
+        expect(childFiles).toEqual(["fact-1.md", "fact-2.md"]);
+    });
+    test("inferred children are themselves filtered out — they don't get re-split", async () => {
+        writeMemory("parent", {}, "Body.");
+        splitter = () => ["c1", "c2"];
+        await runMemoryInferencePass(configWithLlm(), sources());
+        // Now reset the splitter to verify a second run finds no pending memories.
+        let secondRunInvocations = 0;
+        splitter = () => {
+            secondRunInvocations += 1;
+            return ["should not happen"];
+        };
+        const second = await runMemoryInferencePass(configWithLlm(), sources());
+        expect(secondRunInvocations).toBe(0);
+        expect(second.considered).toBe(0);
+        expect(second.writtenFacts).toBe(0);
+    });
+    test("LLM returning zero facts leaves the parent unprocessed (retried next run)", async () => {
+        const filePath = writeMemory("parent", {}, "Body.");
+        splitter = () => [];
+        const result = await runMemoryInferencePass(configWithLlm(), sources());
+        expect(result.skippedNoFacts).toBe(1);
+        expect(result.splitParents).toBe(0);
+        expect(result.writtenFacts).toBe(0);
+        // Parent must NOT be marked processed — a transient empty response
+        // should be retried on the next `akm index`.
+        const fm = parseFrontmatter(fs.readFileSync(filePath, "utf8"));
+        expect(fm.data.inferenceProcessed).toBeUndefined();
+    });
+    test("does not write under cache-only sources (only the primary stash)", async () => {
+        // Add a second source dir simulating a read-only cache. The pass must
+        // ignore it: only sources[0] (primary stash) is writable.
+        const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-mi-cache-"));
+        fs.mkdirSync(path.join(cacheDir, "memories"), { recursive: true });
+        const cacheParent = path.join(cacheDir, "memories", "cache-parent.md");
+        fs.writeFileSync(cacheParent, "---\n---\n\nCache body.\n");
+        try {
+            writeMemory("primary", {}, "Primary body.");
+            splitter = () => ["primary fact"];
+            const result = await runMemoryInferencePass(configWithLlm(), [{ path: tmpStash }, { path: cacheDir }]);
+            // Only the primary parent was considered.
+            expect(result.considered).toBe(1);
+            expect(result.writtenFacts).toBe(1);
+            // No `cache-parent.facts` directory should have been created.
+            expect(fs.existsSync(path.join(cacheDir, "memories", "cache-parent.facts"))).toBe(false);
+        }
+        finally {
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/tests/merge-scoring.test.js

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import { mergeSearchHits } from "../src/commands/search";
+// Local test helper — mirrors the pre-v1 mergeStashHits logic that was removed
+// from production code when the OpenViking provider was dropped (Phase 1).
+function mergeStashHits(localHits, additionalHits, limit) {
+    if (additionalHits.length === 0)
+        return localHits.slice(0, limit);
+    const localKeys = new Set();
+    for (const h of localHits)
+        localKeys.add(h.path ?? h.ref ?? h.name);
+    const providerOnly = additionalHits.filter((h) => !localKeys.has(h.path ?? h.ref ?? h.name));
+    return [...localHits, ...providerOnly].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, limit);
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function makeStashHit(name, score) {
+    return {
+        type: "script",
+        name,
+        path: `/stash/scripts/${name}`,
+        ref: `script:${name}`,
+        score,
+    };
+}
+function makeRegistryHit(name, score) {
+    return {
+        type: "registry",
+        name,
+        id: `npm:${name}`,
+        description: `${name} package`,
+        score,
+    };
+}
+// ── mergeStashHits ──────────────────────────────────────────────────────────
+describe("mergeStashHits — fair score merge", () => {
+    test("returns local hits when additionalHits is empty", () => {
+        const local = [makeStashHit("a", 0.03), makeStashHit("b", 0.02)];
+        const result = mergeStashHits(local, [], 10);
+        expect(result).toHaveLength(2);
+        expect(result[0].name).toBe("a");
+        expect(result[1].name).toBe("b");
+    });
+    test("respects limit when additionalHits is empty", () => {
+        const local = [makeStashHit("a", 0.03), makeStashHit("b", 0.02), makeStashHit("c", 0.01)];
+        const result = mergeStashHits(local, [], 2);
+        expect(result).toHaveLength(2);
+    });
+    test("provider hits keep original scores and sort alongside local hits", () => {
+        const local = [makeStashHit("local-1", 0.85), makeStashHit("local-2", 0.65), makeStashHit("local-3", 0.4)];
+        const additional = [makeStashHit("remote-1", 0.9), makeStashHit("remote-2", 0.5)];
+        const result = mergeStashHits(local, additional, 6);
+        expect(result).toHaveLength(5);
+        // Sorted by score descending — remote-1 (0.9) ranks above local-1 (0.85)
+        expect(result[0].name).toBe("remote-1");
+        expect(result[0].score).toBe(0.9);
+        expect(result[1].name).toBe("local-1");
+        expect(result[1].score).toBe(0.85);
+        expect(result[2].name).toBe("local-2");
+        expect(result[2].score).toBe(0.65);
+        expect(result[3].name).toBe("remote-2");
+        expect(result[3].score).toBe(0.5);
+        expect(result[4].name).toBe("local-3");
+        expect(result[4].score).toBe(0.4);
+    });
+    test("duplicate items: local version wins, provider copy dropped", () => {
+        const local = [makeStashHit("shared-item", 0.85), makeStashHit("local-only", 0.6)];
+        const additional = [makeStashHit("shared-item", 0.95), makeStashHit("remote-only", 0.7)];
+        const result = mergeStashHits(local, additional, 10);
+        // shared-item appears once with local score, not duplicated
+        expect(result.filter((h) => h.name === "shared-item")).toHaveLength(1);
+        expect(result.find((h) => h.name === "shared-item")?.score).toBe(0.85);
+        // remote-only keeps its original score and sorts by score
+        const remoteOnly = result.find((h) => h.name === "remote-only");
+        expect(remoteOnly).toBeDefined();
+        expect(remoteOnly?.score).toBe(0.7);
+    });
+    test("respects limit parameter", () => {
+        const local = [makeStashHit("a", 0.03), makeStashHit("b", 0.02)];
+        const additional = [makeStashHit("c", 0.5), makeStashHit("d", 0.4)];
+        const result = mergeStashHits(local, additional, 2);
+        expect(result).toHaveLength(2);
+    });
+    test("provider hits retain their scores unmodified", () => {
+        const local = [makeStashHit("local-1", 0.85)];
+        const additional = [makeStashHit("remote-1", 0.7), makeStashHit("remote-2", 0.3)];
+        const result = mergeStashHits(local, additional, 10);
+        expect(result).toHaveLength(3);
+        expect(result[0].name).toBe("local-1");
+        expect(result[0].score).toBe(0.85);
+        // Provider scores are preserved exactly
+        expect(result[1].name).toBe("remote-1");
+        expect(result[1].score).toBe(0.7);
+        expect(result[2].name).toBe("remote-2");
+        expect(result[2].score).toBe(0.3);
+    });
+    test("empty localHits: provider hits keep their scores", () => {
+        const additional = [makeStashHit("remote-1", 0.8), makeStashHit("remote-2", 0.5)];
+        const result = mergeStashHits([], additional, 10);
+        expect(result).toHaveLength(2);
+        expect(result[0].name).toBe("remote-1");
+        expect(result[0].score).toBe(0.8);
+        expect(result[1].name).toBe("remote-2");
+        expect(result[1].score).toBe(0.5);
+    });
+});
+// ── mergeSearchHits ─────────────────────────────────────────────────────────
+describe("mergeSearchHits — simple concatenation", () => {
+    test("returns local hits when registryHits is empty", () => {
+        const local = [makeStashHit("a", 0.85)];
+        const result = mergeSearchHits(local, [], 10);
+        expect(result).toHaveLength(1);
+        expect(result[0].name).toBe("a");
+        expect(result[0].score).toBe(0.85);
+    });
+    test("returns registry hits when localHits is empty", () => {
+        const registry = [makeRegistryHit("pkg-a", 0.9)];
+        const result = mergeSearchHits([], registry, 10);
+        expect(result).toHaveLength(1);
+        expect(result[0].name).toBe("pkg-a");
+    });
+    test("concatenates local and registry hits", () => {
+        const local = [makeStashHit("local-1", 0.85), makeStashHit("local-2", 0.65)];
+        const registry = [makeRegistryHit("pkg-1", 0.95), makeRegistryHit("pkg-2", 0.8)];
+        const result = mergeSearchHits(local, registry, 10);
+        expect(result).toHaveLength(4);
+        expect(result[0].name).toBe("local-1");
+        expect(result[1].name).toBe("local-2");
+        expect(result[2].name).toBe("pkg-1");
+        expect(result[3].name).toBe("pkg-2");
+    });
+    test("respects limit parameter", () => {
+        const local = [makeStashHit("a", 0.85), makeStashHit("b", 0.65)];
+        const registry = [makeRegistryHit("c", 0.9), makeRegistryHit("d", 0.8)];
+        const result = mergeSearchHits(local, registry, 2);
+        expect(result).toHaveLength(2);
+    });
+});