ralph-hero-knowledge-index 0.1.21 → 0.1.23

package/dist/search.js

@@ -66,8 +66,18 @@ export class FtsSearch {
             return '""';
         return tokens.map(t => '"' + t.replace(/"/g, '""') + '"').join(" ");
     }
+    /**
+     * Returns true when the `documents.memory_tier` column exists (schema v3+).
+     * On v2 schemas this is false and the memoryTier filter is silently ignored.
+     */
+    memoryTierColumnExists() {
+        const rows = this.db.db
+            .prepare("PRAGMA table_info(documents)")
+            .all();
+        return rows.some((r) => r.name === "memory_tier");
+    }
     search(query, options = {}) {
-        const { type, tags, includeSuperseded = false, limit = 20 } = options;
+        const { type, tags, includeSuperseded = false, limit = 20, memoryTier } = options;
         const conditions = ["documents_fts MATCH @query"];
         const params = { query: this.escapeFts5Query(query), limit };
         if (!includeSuperseded) {
@@ -77,6 +87,10 @@ export class FtsSearch {
             conditions.push("d.type = @type");
             params.type = type;
         }
+        if (memoryTier && memoryTier !== "any" && this.memoryTierColumnExists()) {
+            conditions.push("d.memory_tier = @memoryTier");
+            params.memoryTier = memoryTier;
+        }
         let joinClause = "";
         if (tags && tags.length > 0) {
             joinClause = "JOIN tags t ON t.doc_id = d.id";

package/dist/search.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-knowledge-index",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -31,6 +31,7 @@
     "graphology-simple-path": "^0.2.0",
     "graphology-traversal": "^0.3.1",
     "graphology-types": "^0.24.8",
+    "ignore": "^5.3.2",
     "sqlite-vec": "^0.1.7-alpha.10",
     "yaml": "^2.7.0",
     "zod": "^3.25.0"

package/src/__tests__/config.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir, homedir } from "node:os";
+import { loadConfig, expandHome, resolveConfigPath } from "../config.js";
+
+describe("expandHome", () => {
+  it("returns input unchanged when it does not start with ~", () => {
+    expect(expandHome("/absolute/path")).toBe("/absolute/path");
+    expect(expandHome("relative/path")).toBe("relative/path");
+    expect(expandHome("")).toBe("");
+  });
+
+  it("expands a lone ~", () => {
+    expect(expandHome("~")).toBe(homedir());
+  });
+
+  it("expands ~/ prefix to homedir/rest", () => {
+    expect(expandHome("~/thoughts")).toBe(join(homedir(), "thoughts"));
+    expect(expandHome("~/foo/bar")).toBe(join(homedir(), "foo/bar"));
+  });
+});
+
+describe("loadConfig", () => {
+  let originalEnv: string | undefined;
+  let tmpDir: string;
+
+  beforeEach(() => {
+    originalEnv = process.env.RALPH_KNOWLEDGE_CONFIG;
+    tmpDir = mkdtempSync(join(tmpdir(), "ralph-config-"));
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.RALPH_KNOWLEDGE_CONFIG;
+    } else {
+      process.env.RALPH_KNOWLEDGE_CONFIG = originalEnv;
+    }
+    if (existsSync(tmpDir)) {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns {} when the config file is missing", () => {
+    // Point env var at a nonexistent path so we don't read the real ~/.ralph file.
+    process.env.RALPH_KNOWLEDGE_CONFIG = join(tmpDir, "nope.json");
+    expect(loadConfig()).toEqual({});
+  });
+
+  it("returns {} and warns on malformed JSON", () => {
+    const configPath = join(tmpDir, "broken.json");
+    writeFileSync(configPath, "{ not: valid json");
+    process.env.RALPH_KNOWLEDGE_CONFIG = configPath;
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = loadConfig();
+    expect(result).toEqual({});
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0][0] as string;
+    expect(msg).toContain("Malformed JSON");
+    warn.mockRestore();
+  });
+
+  it("returns {} and warns when top-level is not an object", () => {
+    const configPath = join(tmpDir, "array.json");
+    writeFileSync(configPath, JSON.stringify(["not", "an", "object"]));
+    process.env.RALPH_KNOWLEDGE_CONFIG = configPath;
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(loadConfig()).toEqual({});
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+
+  it("expands ~ prefixes in roots[] to absolute paths", () => {
+    const configPath = join(tmpDir, "tilde.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({ roots: ["~/thoughts", "/absolute/dir"] }),
+    );
+    process.env.RALPH_KNOWLEDGE_CONFIG = configPath;
+    const cfg = loadConfig();
+    expect(cfg.roots).toEqual([
+      join(homedir(), "thoughts"),
+      "/absolute/dir",
+    ]);
+  });
+
+  it("expands ~ in dbPath", () => {
+    const configPath = join(tmpDir, "db.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({ dbPath: "~/.ralph-hero/knowledge.db" }),
+    );
+    process.env.RALPH_KNOWLEDGE_CONFIG = configPath;
+    const cfg = loadConfig();
+    expect(cfg.dbPath).toBe(join(homedir(), ".ralph-hero/knowledge.db"));
+  });
+
+  it("loads ignorePatterns as provided (no expansion)", () => {
+    const configPath = join(tmpDir, "ignore.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({ ignorePatterns: ["**/drafts/**", "*.bak"] }),
+    );
+    process.env.RALPH_KNOWLEDGE_CONFIG = configPath;
+    const cfg = loadConfig();
+    expect(cfg.ignorePatterns).toEqual(["**/drafts/**", "*.bak"]);
+  });
+
+  it("honors RALPH_KNOWLEDGE_CONFIG env var override", () => {
+    const configPath = join(tmpDir, "override.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({ roots: ["/x"], ignorePatterns: ["y/**"], dbPath: "/z.db" }),
+    );
+    process.env.RALPH_KNOWLEDGE_CONFIG = configPath;
+    const cfg = loadConfig();
+    expect(cfg).toEqual({
+      roots: ["/x"],
+      ignorePatterns: ["y/**"],
+      dbPath: "/z.db",
+    });
+  });
+
+  it("drops non-string roots and ignorePatterns entries", () => {
+    const configPath = join(tmpDir, "mixed.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        roots: ["/a", 42, null, "/b"],
+        ignorePatterns: ["good", 7, "more"],
+      }),
+    );
+    process.env.RALPH_KNOWLEDGE_CONFIG = configPath;
+    const cfg = loadConfig();
+    expect(cfg.roots).toEqual(["/a", "/b"]);
+    expect(cfg.ignorePatterns).toEqual(["good", "more"]);
+  });
+});
+
+describe("resolveConfigPath", () => {
+  let originalEnv: string | undefined;
+
+  beforeEach(() => {
+    originalEnv = process.env.RALPH_KNOWLEDGE_CONFIG;
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.RALPH_KNOWLEDGE_CONFIG;
+    } else {
+      process.env.RALPH_KNOWLEDGE_CONFIG = originalEnv;
+    }
+  });
+
+  it("defaults to ~/.ralph/knowledge.config.json when env var is unset", () => {
+    delete process.env.RALPH_KNOWLEDGE_CONFIG;
+    expect(resolveConfigPath()).toBe(
+      join(homedir(), ".ralph", "knowledge.config.json"),
+    );
+  });
+
+  it("expands ~ prefix in RALPH_KNOWLEDGE_CONFIG", () => {
+    process.env.RALPH_KNOWLEDGE_CONFIG = "~/custom/knowledge.json";
+    expect(resolveConfigPath()).toBe(
+      join(homedir(), "custom/knowledge.json"),
+    );
+  });
+
+  it("uses RALPH_KNOWLEDGE_CONFIG absolute path verbatim", () => {
+    process.env.RALPH_KNOWLEDGE_CONFIG = "/etc/ralph/knowledge.json";
+    expect(resolveConfigPath()).toBe("/etc/ralph/knowledge.json");
+  });
+});

package/src/__tests__/file-scanner.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { findMarkdownFiles } from "../file-scanner.js";
+import { loadIgnoreForRoot } from "../ignore.js";
+
+describe("findMarkdownFiles with IgnoreMatcher", () => {
+  it("excludes files matched by a .ralphignore entry", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fs-ignore-"));
+    writeFileSync(join(dir, "a.md"), "# A");
+    writeFileSync(join(dir, "b.md"), "# B");
+    writeFileSync(join(dir, "c.md"), "# C");
+    writeFileSync(join(dir, ".ralphignore"), "b.md\n");
+
+    const matcher = loadIgnoreForRoot(dir);
+    const files = findMarkdownFiles(dir, matcher);
+    expect(files).toHaveLength(2);
+    expect(files.some(f => f.endsWith("a.md"))).toBe(true);
+    expect(files.some(f => f.endsWith("c.md"))).toBe(true);
+    expect(files.some(f => f.endsWith("b.md"))).toBe(false);
+  });
+
+  it("skips a whole subdirectory covered by subdir/** pattern", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fs-ignore-"));
+    writeFileSync(join(dir, "keep.md"), "# keep");
+    mkdirSync(join(dir, "subdir"));
+    writeFileSync(join(dir, "subdir", "skip.md"), "# skip");
+    writeFileSync(join(dir, "subdir", "also-skip.md"), "# skip2");
+    writeFileSync(join(dir, ".ralphignore"), "subdir/**\n");
+
+    const matcher = loadIgnoreForRoot(dir);
+    const files = findMarkdownFiles(dir, matcher);
+    expect(files).toHaveLength(1);
+    expect(files[0].endsWith("keep.md")).toBe(true);
+  });
+
+  it("honors caller-supplied global patterns via loadIgnoreForRoot", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fs-ignore-"));
+    writeFileSync(join(dir, "readme.md"), "# r");
+    mkdirSync(join(dir, "drafts"));
+    writeFileSync(join(dir, "drafts", "wip.md"), "# wip");
+
+    const matcher = loadIgnoreForRoot(dir, ["drafts/**"]);
+    const files = findMarkdownFiles(dir, matcher);
+    expect(files).toHaveLength(1);
+    expect(files[0].endsWith("readme.md")).toBe(true);
+  });
+
+  it("preserves back-compat when called without a matcher", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fs-ignore-"));
+    writeFileSync(join(dir, "a.md"), "# A");
+    writeFileSync(join(dir, "b.md"), "# B");
+    mkdirSync(join(dir, "nested"));
+    writeFileSync(join(dir, "nested", "c.md"), "# C");
+
+    const files = findMarkdownFiles(dir);
+    expect(files).toHaveLength(3);
+    expect(files.every(f => f.endsWith(".md"))).toBe(true);
+  });
+
+  it("still skips dot- and underscore-prefixed directories even without a matcher", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fs-ignore-"));
+    writeFileSync(join(dir, "top.md"), "# top");
+    mkdirSync(join(dir, ".hidden"));
+    writeFileSync(join(dir, ".hidden", "hidden.md"), "# h");
+    mkdirSync(join(dir, "_private"));
+    writeFileSync(join(dir, "_private", "private.md"), "# p");
+
+    const files = findMarkdownFiles(dir);
+    expect(files).toHaveLength(1);
+    expect(files[0].endsWith("top.md")).toBe(true);
+  });
+
+  it("applies default ignore globals (node_modules/, dist/) via loadIgnoreForRoot", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fs-ignore-"));
+    writeFileSync(join(dir, "root.md"), "# root");
+    mkdirSync(join(dir, "node_modules"));
+    writeFileSync(join(dir, "node_modules", "pkg.md"), "# pkg");
+    mkdirSync(join(dir, "dist"));
+    writeFileSync(join(dir, "dist", "out.md"), "# out");
+
+    const matcher = loadIgnoreForRoot(dir);
+    const files = findMarkdownFiles(dir, matcher);
+    expect(files).toHaveLength(1);
+    expect(files[0].endsWith("root.md")).toBe(true);
+  });
+});

package/src/__tests__/hybrid-search.test.ts

@@ -73,6 +73,34 @@ beforeEach(() => {
   hybrid = new HybridSearch(db, fts, vec, mockEmbedFn);
 });
 
+/**
+ * Ensure the v3 schema extensions (memory_tier column, chunks table) exist.
+ * Phase 1 (GH-762) owns the production migration; tests add them so Phase 8
+ * features can be exercised independently of Phase 1's merge order.
+ */
+function ensureV3Schema(targetDb: KnowledgeDB): void {
+  const rows = targetDb.db
+    .prepare("PRAGMA table_info(documents)")
+    .all() as Array<{ name: string }>;
+  if (!rows.some((r) => r.name === "memory_tier")) {
+    targetDb.db.exec(
+      "ALTER TABLE documents ADD COLUMN memory_tier TEXT NOT NULL DEFAULT 'doc' CHECK(memory_tier IN ('doc','raw','reflection'))",
+    );
+  }
+  targetDb.db.exec(
+    `CREATE TABLE IF NOT EXISTS chunks (
+       id TEXT PRIMARY KEY,
+       document_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+       chunk_index INTEGER NOT NULL,
+       content TEXT NOT NULL,
+       char_start INTEGER NOT NULL,
+       char_end INTEGER NOT NULL,
+       context_prefix TEXT NOT NULL DEFAULT '',
+       UNIQUE(document_id, chunk_index)
+     )`,
+  );
+}
+
 describe("HybridSearch", () => {
   it("returns results combining FTS and vector scores", async () => {
     const results = await hybrid.search("cache");
@@ -110,3 +138,82 @@ describe("HybridSearch", () => {
     expect(ids).not.toContain("cache-doc");
   });
 });
+
+describe("HybridSearch memory_tier filter", () => {
+  it("filters to reflection when memoryTier='reflection'", async () => {
+    // Rebuild fixture with memory_tier column populated
+    ensureV3Schema(db);
+    db.db.prepare("UPDATE documents SET memory_tier = ? WHERE id = ?").run("doc", "cache-doc");
+    db.db.prepare("UPDATE documents SET memory_tier = ? WHERE id = ?").run("reflection", "auth-doc");
+    // FTS must be rebuilt to pick up the new column for its JOIN
+    fts.rebuildIndex();
+
+    const results = await hybrid.search("cache OR auth", { memoryTier: "reflection" });
+    const ids = results.map((r) => r.id);
+    expect(ids).toContain("auth-doc");
+    expect(ids).not.toContain("cache-doc");
+  });
+
+  it("returns all tiers when memoryTier='any' (default)", async () => {
+    ensureV3Schema(db);
+    db.db.prepare("UPDATE documents SET memory_tier = ? WHERE id = ?").run("raw", "cache-doc");
+    db.db.prepare("UPDATE documents SET memory_tier = ? WHERE id = ?").run("reflection", "auth-doc");
+    fts.rebuildIndex();
+
+    const results = await hybrid.search("cache OR auth", { memoryTier: "any" });
+    const ids = results.map((r) => r.id);
+    expect(ids).toContain("cache-doc");
+    expect(ids).toContain("auth-doc");
+  });
+
+  it("passes silently on v2 DB where memory_tier column is absent", async () => {
+    // Do NOT call ensureV3Schema — simulate v2 schema.
+    const results = await hybrid.search("cache", { memoryTier: "reflection" });
+    // Schema has no tier info; filter treats all docs as 'doc', so reflection
+    // filter drops everything on a v2 DB — no error thrown.
+    expect(Array.isArray(results)).toBe(true);
+  });
+});
+
+describe("HybridSearch chunk metadata enrichment", () => {
+  it("populates bestChunkId + chunk meta when vec returns chunk ids", async () => {
+    ensureV3Schema(db);
+
+    // Seed a chunk row for cache-doc and mirror its id in the vec table
+    db.db
+      .prepare(
+        `INSERT INTO chunks (id, document_id, chunk_index, content, char_start, char_end, context_prefix)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        "cache-doc#c0",
+        "cache-doc",
+        0,
+        "Analysis of cache invalidation patterns...",
+        0,
+        40,
+        "Research: cache-invalidation context.",
+      );
+    // Replace the doc-level vec entry with a chunk-level one.
+    vec.deleteEmbedding("cache-doc");
+    vec.upsertEmbedding("cache-doc#c0", mockEmbedding(1));
+
+    const results = await hybrid.search("cache");
+    const hit = results.find((r) => r.id === "cache-doc");
+    expect(hit).toBeDefined();
+    expect(hit!.bestChunkId).toBe("cache-doc#c0");
+    expect(hit!.chunkIndex).toBe(0);
+    expect(hit!.charStart).toBe(0);
+    expect(hit!.charEnd).toBe(40);
+    expect(hit!.contextPrefix).toBe("Research: cache-invalidation context.");
+  });
+
+  it("does not populate chunk meta when vec returns doc-level ids", async () => {
+    // Fixture as-is: vec stores doc ids, not chunk ids.
+    const results = await hybrid.search("cache");
+    const hit = results.find((r) => r.id === "cache-doc");
+    expect(hit).toBeDefined();
+    expect(hit!.bestChunkId).toBeUndefined();
+    expect(hit!.chunkIndex).toBeUndefined();
+  });
+});

package/src/__tests__/ignore.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadIgnoreForRoot, DEFAULT_IGNORE_PATTERNS } from "../ignore.js";
+
+describe("loadIgnoreForRoot", () => {
+  it("applies default globals when no .ralphignore and no caller globals are provided", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    const matcher = loadIgnoreForRoot(dir);
+    expect(matcher.isIgnored("node_modules/foo.js")).toBe(true);
+    expect(matcher.isIgnored(".claude/settings.json")).toBe(true);
+    expect(matcher.isIgnored("dist/index.js")).toBe(true);
+    expect(matcher.isIgnored("debug.log")).toBe(true);
+    expect(matcher.isIgnored("thoughts/research/doc.md")).toBe(false);
+  });
+
+  it("honors glob pattern **/node_modules/** against nested paths", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    writeFileSync(join(dir, ".ralphignore"), "**/node_modules/**\n");
+    const matcher = loadIgnoreForRoot(dir);
+    expect(matcher.isIgnored("foo/node_modules/bar.js")).toBe(true);
+  });
+
+  it("honors negation that overrides an earlier *.md pattern", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    writeFileSync(join(dir, ".ralphignore"), "*.md\n!keep-me.md\n");
+    const matcher = loadIgnoreForRoot(dir);
+    expect(matcher.isIgnored("foo.md")).toBe(true);
+    expect(matcher.isIgnored("keep-me.md")).toBe(false);
+  });
+
+  it("treats directory-only patterns as directories", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    writeFileSync(join(dir, ".ralphignore"), "dist/\n");
+    const matcher = loadIgnoreForRoot(dir);
+    // `dist/file.js` matches the directory pattern
+    expect(matcher.isIgnored("dist/file.js")).toBe(true);
+    // A file literally named `dist` should NOT be matched by the directory-only pattern
+    expect(matcher.isIgnored("dist")).toBe(false);
+  });
+
+  it("honors caller-provided globals when .ralphignore is absent", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    const matcher = loadIgnoreForRoot(dir, ["custom/**"]);
+    expect(matcher.isIgnored("custom/inside.md")).toBe(true);
+    expect(matcher.isIgnored("other/inside.md")).toBe(false);
+  });
+
+  it("does not throw when the .ralphignore file is missing", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    expect(() => loadIgnoreForRoot(dir)).not.toThrow();
+    const matcher = loadIgnoreForRoot(dir);
+    // Baseline defaults still apply
+    expect(matcher.isIgnored("node_modules/x.js")).toBe(true);
+  });
+
+  it("combines default globals, caller globals, and .ralphignore file together", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    writeFileSync(join(dir, ".ralphignore"), "local/**\n");
+    const matcher = loadIgnoreForRoot(dir, ["global/**"]);
+    // From defaults
+    expect(matcher.isIgnored("node_modules/y.js")).toBe(true);
+    // From caller globals
+    expect(matcher.isIgnored("global/a.md")).toBe(true);
+    // From per-root file
+    expect(matcher.isIgnored("local/b.md")).toBe(true);
+    // Unmatched
+    expect(matcher.isIgnored("thoughts/keep.md")).toBe(false);
+  });
+
+  it("returns false for empty or root-level relative paths", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ralph-ignore-"));
+    const matcher = loadIgnoreForRoot(dir);
+    expect(matcher.isIgnored("")).toBe(false);
+    expect(matcher.isIgnored("/")).toBe(false);
+  });
+
+  it("exports the documented default patterns", () => {
+    expect(DEFAULT_IGNORE_PATTERNS).toContain(".claude/");
+    expect(DEFAULT_IGNORE_PATTERNS).toContain("node_modules/");
+    expect(DEFAULT_IGNORE_PATTERNS).toContain("dist/");
+    expect(DEFAULT_IGNORE_PATTERNS).toContain(".git/");
+    expect(DEFAULT_IGNORE_PATTERNS).toContain("*.log");
+  });
+});