akm-cli 0.6.1 → 0.7.0

package/dist/tests/graph-extraction.test.js

@@ -0,0 +1,282 @@
+/**
+ * Tests for the graph-extraction pass (#207).
+ *
+ * `extractGraphFromBody` is mocked via `mock.module` so no real LLM call
+ * is ever made. These tests cover:
+ *   - eligible-file detection (memory + knowledge .md, inferred children skipped)
+ *   - the disabled-by-default path (no `akm.llm` configured)
+ *   - the `index.graph.llm = false` per-pass opt-out
+ *   - the `llm.features.graph_extraction = false` feature-gate opt-out
+ *   - graph.json is written under `<stashRoot>/.akm/`
+ *   - toggling off after a successful run leaves the existing graph.json on disk
+ *   - read-only cache sources are not extracted (only the primary stash)
+ */
+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";
+// ── Module-level LLM stub ───────────────────────────────────────────────────
+let extractor = () => ({
+    entities: [],
+    relations: [],
+});
+mock.module("../src/llm/graph-extract", () => ({
+    extractGraphFromBody: async (_config, body) => extractor(body),
+}));
+// Import AFTER mock.module so the pass picks up the stub.
+const { runGraphExtractionPass, collectEligibleFiles, getGraphFilePath, GRAPH_FILE_SCHEMA_VERSION } = await import("../src/indexer/graph-extraction");
+// ── Fixture helpers ─────────────────────────────────────────────────────────
+let tmpStash = "";
+beforeEach(() => {
+    tmpStash = fs.mkdtempSync(path.join(os.tmpdir(), "akm-graph-ext-"));
+    fs.mkdirSync(path.join(tmpStash, "memories"), { recursive: true });
+    fs.mkdirSync(path.join(tmpStash, "knowledge"), { recursive: true });
+    extractor = () => ({ entities: [], relations: [] });
+});
+afterEach(() => {
+    if (tmpStash) {
+        fs.rmSync(tmpStash, { recursive: true, force: true });
+        tmpStash = "";
+    }
+});
+function writeFile(rel, 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, rel);
+    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(overrides) {
+    return {
+        semanticSearchMode: "auto",
+        llm: { ...SAMPLE_LLM },
+        ...overrides,
+    };
+}
+function sources() {
+    return [{ path: tmpStash }];
+}
+// ── collectEligibleFiles ────────────────────────────────────────────────────
+describe("collectEligibleFiles", () => {
+    test("returns empty when neither memories/ nor knowledge/ exists", () => {
+        const fresh = fs.mkdtempSync(path.join(os.tmpdir(), "akm-graph-empty-"));
+        try {
+            expect(collectEligibleFiles(fresh)).toEqual([]);
+        }
+        finally {
+            fs.rmSync(fresh, { recursive: true, force: true });
+        }
+    });
+    test("walks memories/ and knowledge/ markdown files", () => {
+        writeFile("memories/m1.md", {}, "Memory body about ServiceA and ServiceB.");
+        writeFile("knowledge/k1.md", {}, "Knowledge body about ServiceB.");
+        writeFile("memories/sub/m2.md", {}, "Nested memory body.");
+        const eligible = collectEligibleFiles(tmpStash);
+        const names = eligible.map((e) => path.relative(tmpStash, e.absPath)).sort();
+        expect(names).toEqual([
+            path.join("knowledge", "k1.md"),
+            path.join("memories", "m1.md"),
+            path.join("memories", "sub", "m2.md"),
+        ]);
+    });
+    test("skips inferred memory children", () => {
+        writeFile("memories/parent.md", {}, "Parent body.");
+        writeFile("memories/parent.facts/fact-1.md", { inferred: true, source: "memory:parent" }, "Atomic.");
+        const eligible = collectEligibleFiles(tmpStash);
+        const names = eligible.map((e) => path.relative(tmpStash, e.absPath));
+        expect(names).toContain(path.join("memories", "parent.md"));
+        expect(names).not.toContain(path.join("memories", "parent.facts", "fact-1.md"));
+    });
+    test("skips empty bodies", () => {
+        // File with parseable frontmatter and a whitespace-only body. The
+        // empty `{}` frontmatter form is degenerate (no delimiters with
+        // contents between them), so we use a single key to force a real
+        // frontmatter block.
+        writeFile("memories/empty.md", { type: "memory" }, "   \n\n   ");
+        expect(collectEligibleFiles(tmpStash)).toEqual([]);
+    });
+});
+// ── runGraphExtractionPass — disabled paths ────────────────────────────────
+describe("runGraphExtractionPass — disabled paths", () => {
+    test("no-op when no akm.llm is configured", async () => {
+        writeFile("memories/m1.md", {}, "Body.");
+        extractor = () => {
+            throw new Error("must not be called when no llm is configured");
+        };
+        const result = await runGraphExtractionPass({ semanticSearchMode: "auto" }, sources());
+        expect(result.written).toBe(false);
+        expect(result.considered).toBe(0);
+        expect(fs.existsSync(getGraphFilePath(tmpStash))).toBe(false);
+    });
+    test("no-op when index.graph.llm = false", async () => {
+        writeFile("memories/m1.md", {}, "Body.");
+        extractor = () => {
+            throw new Error("must not be called when per-pass disabled");
+        };
+        const cfg = configWithLlm({ index: { graph: { llm: false } } });
+        const result = await runGraphExtractionPass(cfg, sources());
+        expect(result.written).toBe(false);
+        expect(fs.existsSync(getGraphFilePath(tmpStash))).toBe(false);
+    });
+    test("no-op when llm.features.graph_extraction = false", async () => {
+        writeFile("memories/m1.md", {}, "Body.");
+        extractor = () => {
+            throw new Error("must not be called when feature-gated off");
+        };
+        const cfg = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM, features: { graph_extraction: false } },
+            index: { graph: { llm: true } },
+        };
+        const result = await runGraphExtractionPass(cfg, sources());
+        expect(result.written).toBe(false);
+        expect(fs.existsSync(getGraphFilePath(tmpStash))).toBe(false);
+    });
+    test("toggling off after a successful run preserves the existing graph.json", async () => {
+        writeFile("memories/m1.md", {}, "Body.");
+        extractor = () => ({ entities: ["ServiceA"], relations: [] });
+        await runGraphExtractionPass(configWithLlm(), sources());
+        const graphPath = getGraphFilePath(tmpStash);
+        expect(fs.existsSync(graphPath)).toBe(true);
+        const beforeBytes = fs.readFileSync(graphPath, "utf8");
+        extractor = () => {
+            throw new Error("must not be called when disabled");
+        };
+        await runGraphExtractionPass(configWithLlm({ index: { graph: { llm: false } } }), sources());
+        expect(fs.existsSync(graphPath)).toBe(true);
+        expect(fs.readFileSync(graphPath, "utf8")).toBe(beforeBytes);
+    });
+});
+// ── runGraphExtractionPass — orthogonal gating (§14 + #208) ────────────────
+describe("runGraphExtractionPass — feature flag and per-pass key are orthogonal", () => {
+    test("runs when both gates allow", async () => {
+        writeFile("memories/m1.md", {}, "Body.");
+        extractor = () => ({ entities: ["E"], relations: [] });
+        const cfg = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM, features: { graph_extraction: true } },
+        };
+        const result = await runGraphExtractionPass(cfg, sources());
+        expect(result.written).toBe(true);
+        expect(result.considered).toBe(1);
+        expect(result.extracted).toBe(1);
+    });
+    test("no-op cleanly when feature + per-pass gates allow but akm.llm is absent (third precondition)", async () => {
+        // Three preconditions must ALL hold for the pass to run:
+        //   1. `akm.llm` configured  (this test removes it)
+        //   2. `llm.features.graph_extraction !== false`  (true here)
+        //   3. `index.graph.llm !== false`  (true here)
+        // With #1 missing, the pass must short-circuit silently — no error
+        // thrown, no graph.json written, no existing graph.json modified.
+        writeFile("memories/m1.md", {}, "Body.");
+        extractor = () => {
+            throw new Error("must not be called when akm.llm is absent");
+        };
+        const cfg = {
+            semanticSearchMode: "auto",
+            // No `llm` block at all.
+            index: { graph: { llm: true } },
+        };
+        const graphPath = getGraphFilePath(tmpStash);
+        expect(fs.existsSync(graphPath)).toBe(false);
+        const result = await runGraphExtractionPass(cfg, sources());
+        expect(result.written).toBe(false);
+        expect(result.considered).toBe(0);
+        expect(result.extracted).toBe(0);
+        expect(fs.existsSync(graphPath)).toBe(false);
+    });
+    test("either gate set to false short-circuits", async () => {
+        writeFile("memories/m1.md", {}, "Body.");
+        extractor = () => ({ entities: ["E"], relations: [] });
+        const featureOff = await runGraphExtractionPass({
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM, features: { graph_extraction: false } },
+        }, sources());
+        expect(featureOff.written).toBe(false);
+        const passOff = await runGraphExtractionPass({
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM, features: { graph_extraction: true } },
+            index: { graph: { llm: false } },
+        }, sources());
+        expect(passOff.written).toBe(false);
+    });
+});
+// ── runGraphExtractionPass — enabled path ──────────────────────────────────
+describe("runGraphExtractionPass — enabled", () => {
+    test("writes graph.json with schema version + canonicalised entities", async () => {
+        writeFile("memories/parent.md", {}, "Body about ServiceA and ServiceB.");
+        writeFile("knowledge/k1.md", {}, "Body about ServiceB and ServiceC.");
+        extractor = (body) => {
+            if (body.includes("ServiceA"))
+                return {
+                    entities: ["ServiceA", "ServiceB"],
+                    relations: [{ from: "ServiceA", to: "ServiceB", type: "uses" }],
+                };
+            return {
+                entities: ["ServiceB", "ServiceC"],
+                relations: [{ from: "ServiceB", to: "ServiceC" }],
+            };
+        };
+        const result = await runGraphExtractionPass(configWithLlm(), sources());
+        expect(result.written).toBe(true);
+        expect(result.considered).toBe(2);
+        expect(result.extracted).toBe(2);
+        expect(result.totalEntities).toBe(4);
+        expect(result.totalRelations).toBe(2);
+        const raw = fs.readFileSync(getGraphFilePath(tmpStash), "utf8");
+        const parsed = JSON.parse(raw);
+        expect(parsed.schemaVersion).toBe(GRAPH_FILE_SCHEMA_VERSION);
+        expect(parsed.stashRoot).toBe(tmpStash);
+        expect(parsed.files).toHaveLength(2);
+        // Entities are lower-cased at write time so the search-time boost
+        // doesn't have to re-canonicalise on every query.
+        for (const node of parsed.files) {
+            for (const e of node.entities)
+                expect(e).toBe(e.toLowerCase());
+            for (const r of node.relations) {
+                expect(r.from).toBe(r.from.toLowerCase());
+                expect(r.to).toBe(r.to.toLowerCase());
+            }
+        }
+    });
+    test("files with no extracted entities are omitted but still considered", async () => {
+        writeFile("memories/m1.md", {}, "Empty graph body.");
+        writeFile("memories/m2.md", {}, "Has entities.");
+        extractor = (body) => {
+            if (body.includes("Has entities"))
+                return { entities: ["X"], relations: [] };
+            return { entities: [], relations: [] };
+        };
+        const result = await runGraphExtractionPass(configWithLlm(), sources());
+        expect(result.considered).toBe(2);
+        expect(result.extracted).toBe(1);
+        expect(result.written).toBe(true);
+        const parsed = JSON.parse(fs.readFileSync(getGraphFilePath(tmpStash), "utf8"));
+        expect(parsed.files).toHaveLength(1);
+    });
+    test("does not extract from cache-only sources (only the primary stash)", async () => {
+        const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-graph-cache-"));
+        try {
+            fs.mkdirSync(path.join(cacheDir, "memories"), { recursive: true });
+            fs.writeFileSync(path.join(cacheDir, "memories", "cache.md"), "---\n---\n\nCache body about X.\n");
+            writeFile("memories/m1.md", {}, "Primary body.");
+            extractor = () => ({ entities: ["X"], relations: [] });
+            const result = await runGraphExtractionPass(configWithLlm(), [{ path: tmpStash }, { path: cacheDir }]);
+            expect(result.considered).toBe(1);
+            expect(fs.existsSync(getGraphFilePath(cacheDir))).toBe(false);
+            expect(fs.existsSync(getGraphFilePath(tmpStash))).toBe(true);
+        }
+        finally {
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/tests/helpers/usage-events.js

@@ -0,0 +1,8 @@
+import { ensureUsageEventsSchema } from "../../src/indexer/usage-events";
+/**
+ * Record a usage event (test-only helper for M-2 utility scoring tests).
+ */
+export function recordUsageEvent(db, event) {
+    ensureUsageEventsSchema(db);
+    db.prepare("INSERT INTO usage_events (event_type, entry_id, query, created_at) VALUES (?, ?, ?, ?)").run(event.eventType, event.entryId, event.query ?? null, event.timestamp ?? new Date().toISOString());
+}

package/dist/tests/index-pass-llm.test.js

@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getConfigPath, loadUserConfig, resetConfigCache } from "../src/core/config";
+import { ConfigError } from "../src/core/errors";
+import { resolveIndexPassLLM } from "../src/llm/index-passes";
+// Tests for #208 — unified `akm.llm` config across all index-time passes.
+function makeTmpDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "akm-index-pass-llm-"));
+}
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+let tmpHome = "";
+beforeEach(() => {
+    tmpHome = makeTmpDir();
+    process.env.XDG_CONFIG_HOME = tmpHome;
+    resetConfigCache();
+});
+afterEach(() => {
+    if (originalXdgConfigHome === undefined) {
+        delete process.env.XDG_CONFIG_HOME;
+    }
+    else {
+        process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
+    }
+    if (tmpHome) {
+        fs.rmSync(tmpHome, { recursive: true, force: true });
+        tmpHome = "";
+    }
+    resetConfigCache();
+});
+function writeUserConfig(raw) {
+    const configPath = getConfigPath();
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(raw, null, 2));
+}
+const SAMPLE_LLM = {
+    endpoint: "http://localhost:11434/v1/chat/completions",
+    model: "llama3.2",
+};
+describe("resolveIndexPassLLM", () => {
+    test("returns undefined when no top-level llm is configured", () => {
+        const config = { semanticSearchMode: "auto" };
+        expect(resolveIndexPassLLM("enrichment", config)).toBeUndefined();
+        expect(resolveIndexPassLLM("graph", config)).toBeUndefined();
+    });
+    test("returns the shared akm.llm by default for any pass", () => {
+        const config = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM },
+        };
+        expect(resolveIndexPassLLM("enrichment", config)).toEqual(SAMPLE_LLM);
+        // A future pass plugs in for free — same default, no per-pass wiring.
+        expect(resolveIndexPassLLM("memory", config)).toEqual(SAMPLE_LLM);
+        expect(resolveIndexPassLLM("graph", config)).toEqual(SAMPLE_LLM);
+    });
+    test("per-pass `llm: false` opts that pass out, leaving siblings intact", () => {
+        const config = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM },
+            index: {
+                enrichment: { llm: false },
+                graph: { llm: true },
+            },
+        };
+        expect(resolveIndexPassLLM("enrichment", config)).toBeUndefined();
+        expect(resolveIndexPassLLM("graph", config)).toEqual(SAMPLE_LLM);
+        // Pass not mentioned at all still defaults to akm.llm.
+        expect(resolveIndexPassLLM("memory", config)).toEqual(SAMPLE_LLM);
+    });
+    test("per-pass `llm: true` is equivalent to default", () => {
+        const config = {
+            semanticSearchMode: "auto",
+            llm: { ...SAMPLE_LLM },
+            index: { enrichment: { llm: true } },
+        };
+        expect(resolveIndexPassLLM("enrichment", config)).toEqual(SAMPLE_LLM);
+    });
+});
+describe("config loader: `index` block parsing", () => {
+    test("loads valid `index.<pass>.llm` boolean values", () => {
+        writeUserConfig({
+            llm: SAMPLE_LLM,
+            index: {
+                enrichment: { llm: false },
+                graph: { llm: true },
+            },
+        });
+        const config = loadUserConfig();
+        expect(config.index).toEqual({
+            enrichment: { llm: false },
+            graph: { llm: true },
+        });
+    });
+    test("rejects per-pass provider configuration (duplicate provider path)", () => {
+        writeUserConfig({
+            llm: SAMPLE_LLM,
+            index: {
+                enrichment: {
+                    endpoint: "http://other-host/v1/chat/completions",
+                    model: "other-model",
+                },
+            },
+        });
+        expect(() => loadUserConfig()).toThrow(ConfigError);
+        try {
+            loadUserConfig();
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ConfigError);
+            expect(err.code).toBe("INVALID_CONFIG_FILE");
+            expect(err.message).toContain("Duplicate LLM provider configuration");
+            expect(err.message).toContain("index.enrichment.endpoint");
+        }
+    });
+    test("rejects per-pass `provider`, `apiKey`, `temperature`, etc.", () => {
+        for (const key of ["provider", "apiKey", "temperature", "maxTokens", "baseUrl", "capabilities"]) {
+            writeUserConfig({
+                llm: SAMPLE_LLM,
+                index: { enrichment: { [key]: "anything" } },
+            });
+            resetConfigCache();
+            expect(() => loadUserConfig()).toThrow(/Duplicate LLM provider configuration/);
+        }
+    });
+    test("rejects non-boolean `llm` value under a pass", () => {
+        writeUserConfig({
+            llm: SAMPLE_LLM,
+            index: { enrichment: { llm: "off" } },
+        });
+        expect(() => loadUserConfig()).toThrow(/expected a boolean/);
+    });
+    test("rejects unknown keys under a pass entry", () => {
+        writeUserConfig({
+            llm: SAMPLE_LLM,
+            index: { enrichment: { foo: true } },
+        });
+        expect(() => loadUserConfig()).toThrow(/Unknown key `index\.enrichment\.foo`/);
+    });
+    test("rejects array-shaped `index` block", () => {
+        writeUserConfig({
+            llm: SAMPLE_LLM,
+            // biome-ignore lint/suspicious/noExplicitAny: testing invalid runtime input
+            index: [{ llm: false }],
+        });
+        expect(() => loadUserConfig()).toThrow(/expected an object keyed by pass name/);
+    });
+    test("rejects non-object pass entry", () => {
+        writeUserConfig({
+            llm: SAMPLE_LLM,
+            index: { enrichment: false },
+        });
+        expect(() => loadUserConfig()).toThrow(/expected an object like/);
+    });
+    test("missing `index` block is fine", () => {
+        writeUserConfig({ llm: SAMPLE_LLM });
+        const config = loadUserConfig();
+        expect(config.index).toBeUndefined();
+        expect(resolveIndexPassLLM("enrichment", config)).toEqual(SAMPLE_LLM);
+    });
+});