@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/core/src/lede.test.ts

@@ -0,0 +1,96 @@
+/**
+ * `computeLede` — the first non-empty paragraph AFTER a note's title line,
+ * used by `expand_mode: "summary"` (core/src/expand.ts) as a fallback when
+ * `metadata.summary` is absent (summaries-as-content, 2026-07-17 dialogue).
+ *
+ * Shares its title-line rule (including the leading-frontmatter skip) with
+ * `computeDisplayTitle` — see `display-title.test.ts` for that function's
+ * own coverage. This file covers only the lede-specific behavior: where the
+ * paragraph starts, how it's collapsed, the length cap, and the
+ * title-only/no-content null cases.
+ */
+import { describe, it, expect } from "bun:test";
+import { computeLede, LEDE_MAX_LEN } from "./notes.js";
+
+describe("computeLede", () => {
+  it("returns the first paragraph after a heading title, blank-line separated", () => {
+    expect(
+      computeLede("# Title\n\nThis is the lede paragraph.\n\nSecond paragraph — not the lede."),
+    ).toBe("This is the lede paragraph.");
+  });
+
+  it("joins a multi-line paragraph into one collapsed line", () => {
+    expect(
+      computeLede("# Title\n\nThis lede paragraph\nspans two lines.\n\nSecond paragraph."),
+    ).toBe("This lede paragraph spans two lines.");
+  });
+
+  it("treats text immediately following the title (no blank line) as the lede", () => {
+    expect(computeLede("Grocery List\nmilk, eggs\ncheese")).toBe("milk, eggs cheese");
+  });
+
+  it("collapses internal whitespace runs to single spaces", () => {
+    expect(computeLede("Title\n\nLine one   with    extra   spaces.")).toBe(
+      "Line one with extra spaces.",
+    );
+  });
+
+  it("returns null for a title-only note (does not repeat the title)", () => {
+    expect(computeLede("Just a title")).toBeNull();
+    expect(computeLede("# Just a title")).toBeNull();
+  });
+
+  it("returns null when only blank lines follow the title", () => {
+    expect(computeLede("# Title\n\n\n   \n")).toBeNull();
+  });
+
+  it("returns null for empty, null, or undefined content", () => {
+    expect(computeLede("")).toBeNull();
+    expect(computeLede(null)).toBeNull();
+    expect(computeLede(undefined)).toBeNull();
+  });
+
+  it("returns null when content is whitespace-only (no title at all)", () => {
+    expect(computeLede("   \n\t\n   ")).toBeNull();
+  });
+
+  describe("leading frontmatter block", () => {
+    it("finds the lede after a closed frontmatter block AND its title line", () => {
+      expect(
+        computeLede("---\ntitle: X\n---\n# Real Title\n\nThe lede text."),
+      ).toBe("The lede text.");
+    });
+
+    it("finds the lede when the title immediately follows frontmatter with no blank line", () => {
+      expect(
+        computeLede("---\ntitle: X\n---\nReal Title\nlede text right after."),
+      ).toBe("lede text right after.");
+    });
+
+    it("returns null for a frontmatter-only note with no body after the title", () => {
+      expect(computeLede("---\ntitle: X\n---\nReal Title")).toBeNull();
+    });
+  });
+
+  describe("length cap", () => {
+    it("truncates to LEDE_MAX_LEN code points", () => {
+      const longParagraph = "a".repeat(1000);
+      const result = computeLede(`# Title\n\n${longParagraph}`)!;
+      expect(result.length).toBe(LEDE_MAX_LEN);
+      expect(result).toBe("a".repeat(LEDE_MAX_LEN));
+    });
+
+    it("does not truncate a lede at or under the cap", () => {
+      const exact = "a".repeat(LEDE_MAX_LEN);
+      expect(computeLede(`# Title\n\n${exact}`)).toBe(exact);
+      const short = "short lede";
+      expect(computeLede(`# Title\n\n${short}`)).toBe(short);
+    });
+
+    it("truncates by Unicode code point, not UTF-16 code unit (no split surrogate pairs)", () => {
+      const emojiParagraph = "😀".repeat(500);
+      const result = computeLede(`# Title\n\n${emojiParagraph}`)!;
+      expect(Array.from(result).length).toBe(LEDE_MAX_LEN);
+    });
+  });
+});

package/core/src/mcp-semantic-search.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { QueryError } from "./query-operators.js";
+import type { EmbeddingProvider, EmbedInput, EmbedResult, ProviderAvailability } from "./embedding/provider.js";
+import { encodeVector, normalize } from "./embedding/vector-codec.js";
+
+const MODEL = "mock-model";
+const DIMS = 4;
+
+class MockEmbeddingProvider implements EmbeddingProvider {
+  readonly name = "mock";
+  readonly model = MODEL;
+  readonly dims = DIMS;
+  available_ = true;
+  reason_: string | undefined;
+  vectorFor: (text: string) => number[];
+
+  constructor(vectorFor?: (text: string) => number[]) {
+    this.vectorFor = vectorFor ?? (() => [1, 0, 0, 0]);
+  }
+
+  async embed(input: EmbedInput): Promise<EmbedResult> {
+    return { vectors: input.texts.map((t) => new Float32Array(this.vectorFor(t))), model: this.model, dims: this.dims };
+  }
+
+  async available(): Promise<ProviderAvailability> {
+    return this.available_ ? { ok: true } : { ok: false, reason: this.reason_ };
+  }
+}
+
+function insertVector(db: Database, noteId: string, vector: number[]): void {
+  const encoded = encodeVector(normalize(new Float32Array(vector)));
+  db.prepare(
+    `INSERT INTO note_vectors (note_id, chunk_ix, vector, dims, model, content_hash, embedded_at) VALUES (?, 0, ?, ?, ?, ?, ?)`,
+  ).run(noteId, encoded, DIMS, MODEL, "hash", new Date().toISOString());
+}
+
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+});
+
+describe("query-notes MCP tool — semantic search (EXPERIMENTAL)", () => {
+  it("throws INVALID_QUERY when semantic:true is passed without near_text", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    await expect(query.execute({ semantic: true })).rejects.toThrow(QueryError);
+  });
+
+  it("throws INVALID_QUERY when semantic:true is combined with search", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    await expect(query.execute({ semantic: true, near_text: "x", search: "y" })).rejects.toThrow(QueryError);
+  });
+
+  it("throws INVALID_QUERY when semantic is combined with aggregate", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    await expect(
+      query.execute({ semantic: true, near_text: "x", aggregate: { group_by: "tag", op: "count" } }),
+    ).rejects.toThrow(QueryError);
+  });
+
+  it("throws INVALID_QUERY when semantic is combined with cursor", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    await expect(query.execute({ semantic: true, near_text: "x", cursor: "" })).rejects.toThrow(QueryError);
+  });
+
+  it("throws a structured semantic_unavailable error when no provider is configured", async () => {
+    const store = new SqliteStore(db); // no embeddingProvider
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    let caught: unknown;
+    try {
+      await query.execute({ semantic: true, near_text: "anything" });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(QueryError);
+    expect((caught as QueryError).error_type).toBe("semantic_unavailable");
+  });
+
+  it("near_text without semantic:true is a no-op that carries an ignored_param warning", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    await store.createNote("hello world", { path: "n" });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ near_text: "hello" })) as { notes: unknown[]; warnings: { code: string }[] };
+    // A plain structured query with no filters returns a bare array UNLESS
+    // warnings are present (vault#550 envelope rule) — here they are.
+    expect(Array.isArray((result as any))).toBe(false);
+    expect(result.warnings.some((w) => w.code === "ignored_param")).toBe(true);
+  });
+
+  it("returns notes ranked by meaning via near_text + semantic:true", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const close = await store.createNote("close note", { path: "close" });
+    const far = await store.createNote("far note", { path: "far" });
+    insertVector(db, close.id, [1, 0, 0, 0]);
+    insertVector(db, far.id, [0, 1, 0, 0]);
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const results = (await query.execute({ semantic: true, near_text: "anything", include_content: true })) as any[];
+    expect(results.map((n: any) => n.id)).toEqual([close.id, far.id]);
+    expect(results[0].score).toBeCloseTo(1, 4);
+  });
+
+  it("composes with tag filters (structured filters narrow the candidate set first)", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const tagged = await store.createNote("tagged", { path: "tagged", tags: ["project"] });
+    const untagged = await store.createNote("untagged", { path: "untagged" });
+    insertVector(db, tagged.id, [1, 0, 0, 0]);
+    insertVector(db, untagged.id, [1, 0, 0, 0]);
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const results = (await query.execute({ semantic: true, near_text: "x", tag: "project" })) as any[];
+    expect(results.map((n: any) => n.id)).toEqual([tagged.id]);
+  });
+
+  it("attaches embeddings_pending warning + still returns real results when some candidates aren't embedded yet", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const embedded = await store.createNote("embedded", { path: "a" });
+    await store.createNote("pending", { path: "b" });
+    insertVector(db, embedded.id, [1, 0, 0, 0]);
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ semantic: true, near_text: "x", include_content: true })) as {
+      notes: any[];
+      warnings: { code: string; pending?: number; total_candidates?: number }[];
+    };
+    expect(result.notes.map((n: any) => n.id)).toEqual([embedded.id]);
+    const pendingWarning = result.warnings.find((w) => w.code === "embeddings_pending");
+    expect(pendingWarning).toBeDefined();
+    expect(pendingWarning!.pending).toBe(1);
+    expect(pendingWarning!.total_candidates).toBe(2);
+  });
+
+  it("no embeddings_pending warning once every candidate has a vector", async () => {
+    const store = new SqliteStore(db, { embeddingProvider: new MockEmbeddingProvider() });
+    const note = await store.createNote("note", { path: "a" });
+    insertVector(db, note.id, [1, 0, 0, 0]);
+
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const results = (await query.execute({ semantic: true, near_text: "x", include_content: true })) as any;
+    // No warnings at all -> bare array (vault#550 envelope rule).
+    expect(Array.isArray(results)).toBe(true);
+  });
+});