@danielsimonjr/memoryjs 2.3.0 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
 # MemoryJS
 
-[![Version](https://img.shields.io/badge/version-2.3.0-blue.svg)](https://github.com/danielsimonjr/memoryjs)
+[![Version](https://img.shields.io/badge/version-2.5.0-blue.svg)](https://github.com/danielsimonjr/memoryjs)
 [![NPM](https://img.shields.io/npm/v/@danielsimonjr/memoryjs.svg)](https://www.npmjs.com/package/@danielsimonjr/memoryjs)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

package/dist/cli/index.js

@@ -959,12 +959,34 @@ var init_indexes = __esm({
 });
 
 // src/utils/searchCache.ts
+var searchCache_exports = {};
+__export(searchCache_exports, {
+  SearchCache: () => SearchCache,
+  cleanupAllCaches: () => cleanupAllCaches,
+  clearAllSearchCaches: () => clearAllSearchCaches,
+  getAllCacheStats: () => getAllCacheStats,
+  searchCaches: () => searchCaches
+});
 function clearAllSearchCaches() {
   searchCaches.basic.clear();
   searchCaches.ranked.clear();
   searchCaches.boolean.clear();
   searchCaches.fuzzy.clear();
 }
+function getAllCacheStats() {
+  return {
+    basic: searchCaches.basic.getStats(),
+    ranked: searchCaches.ranked.getStats(),
+    boolean: searchCaches.boolean.getStats(),
+    fuzzy: searchCaches.fuzzy.getStats()
+  };
+}
+function cleanupAllCaches() {
+  searchCaches.basic.cleanupExpired();
+  searchCaches.ranked.cleanupExpired();
+  searchCaches.boolean.cleanupExpired();
+  searchCaches.fuzzy.cleanupExpired();
+}
 var SearchCache, searchCaches;
 var init_searchCache = __esm({
   "src/utils/searchCache.ts"() {
@@ -35763,6 +35785,105 @@ var init_inspect = __esm({
   }
 });
 
+// src/cli/commands/check.ts
+var check_exports = {};
+__export(check_exports, {
+  applyFixes: () => applyFixes,
+  detectIssues: () => detectIssues,
+  registerCheckCommand: () => registerCheckCommand
+});
+async function detectIssues(ctx) {
+  const graph = await ctx.storage.loadGraph();
+  const names = new Set(graph.entities.map((e) => e.name));
+  const orphans = [];
+  for (const r of graph.relations) {
+    const fromMissing = !names.has(r.from);
+    const toMissing = !names.has(r.to);
+    if (fromMissing || toMissing) {
+      orphans.push({
+        from: r.from,
+        to: r.to,
+        relationType: r.relationType,
+        reason: fromMissing && toMissing ? "both-missing" : fromMissing ? "from-missing" : "to-missing"
+      });
+    }
+  }
+  const missing = [];
+  const cycles = [];
+  const byName = /* @__PURE__ */ new Map();
+  for (const e of graph.entities) byName.set(e.name, { name: e.name, parentId: e.parentId });
+  for (const e of graph.entities) {
+    if (!e.parentId) continue;
+    if (!byName.has(e.parentId)) {
+      missing.push({ entity: e.name, parentId: e.parentId });
+      continue;
+    }
+    const visited = /* @__PURE__ */ new Set([e.name]);
+    let cur = byName.get(e.parentId);
+    while (cur && cur.parentId) {
+      if (visited.has(cur.name)) {
+        cycles.push({ entityInCycle: e.name, cycleThrough: cur.name });
+        break;
+      }
+      visited.add(cur.name);
+      cur = byName.get(cur.parentId);
+    }
+  }
+  return { orphans, missing, cycles };
+}
+async function applyFixes(ctx, orphans, missing) {
+  let deleted = 0;
+  let cleared = 0;
+  if (orphans.length > 0) {
+    await ctx.relationManager.deleteRelations(
+      orphans.map((o) => ({ from: o.from, to: o.to, relationType: o.relationType }))
+    );
+    deleted = orphans.length;
+  }
+  for (const m of missing) {
+    try {
+      await ctx.hierarchyManager.setEntityParent(m.entity, null);
+      cleared += 1;
+    } catch {
+    }
+  }
+  return { orphanRelationsDeleted: deleted, missingParentsCleared: cleared };
+}
+function registerCheckCommand(program2) {
+  program2.command("check").description("Detect orphan relations + missing parents + hierarchy cycles. Dry-run by default.").option("--apply", "Actually delete orphan relations + clear missing parentIds (cycles always left for human review)").action(async (opts) => {
+    const options = getOptions(program2);
+    const logger2 = createLogger(options);
+    const ctx = createContext(options);
+    try {
+      const { orphans, missing, cycles } = await detectIssues(ctx);
+      const ok = orphans.length === 0 && missing.length === 0 && cycles.length === 0;
+      const report = {
+        ok,
+        applied: Boolean(opts.apply),
+        orphanRelations: orphans,
+        missingParents: missing,
+        hierarchyCycles: cycles
+      };
+      if (opts.apply && (orphans.length > 0 || missing.length > 0)) {
+        report.actions = await applyFixes(ctx, orphans, missing);
+      }
+      console.log(JSON.stringify(report, null, 2));
+      if (!ok && !opts.apply) process.exit(1);
+    } catch (error) {
+      logger2.error(formatError(error.message));
+      process.exit(1);
+    }
+  });
+}
+var init_check = __esm({
+  "src/cli/commands/check.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_helpers();
+    init_formatters2();
+  }
+});
+
 // src/cli/interactive.ts
 var interactive_exports = {};
 __export(interactive_exports, {
@@ -36071,6 +36192,57 @@ Path (${pathResult.length} hops): ${pathResult.path.join(" -> ")}`);
       console.log(JSON.stringify(report, null, 2));
       break;
     }
+    case "check": {
+      const apply = args[0] === "--apply";
+      const { detectIssues: detectIssues2, applyFixes: applyFixes2 } = await Promise.resolve().then(() => (init_check(), check_exports));
+      const { orphans, missing, cycles } = await detectIssues2(ctx);
+      const ok = orphans.length === 0 && missing.length === 0 && cycles.length === 0;
+      const result = {
+        ok,
+        applied: apply,
+        orphanRelations: orphans,
+        missingParents: missing,
+        hierarchyCycles: cycles
+      };
+      if (apply && (orphans.length > 0 || missing.length > 0)) {
+        result.actions = await applyFixes2(ctx, orphans, missing);
+      }
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+    case "heuristics": {
+      const heuristics = await ctx.heuristicManager.list();
+      console.log(JSON.stringify({ heuristics, count: heuristics.length }, null, 2));
+      break;
+    }
+    case "spell": {
+      const query = args.join(" ");
+      if (!query) {
+        console.log(chalk2.yellow("Usage: spell <query>"));
+        break;
+      }
+      const suggestions = await ctx.spellChecker.suggest(query);
+      console.log(JSON.stringify({ query, suggestions, count: suggestions.length }, null, 2));
+      break;
+    }
+    case "cache": {
+      const sub = args[0];
+      const { getAllCacheStats: getAllCacheStats2, clearAllSearchCaches: clearAllSearchCaches2 } = await Promise.resolve().then(() => (init_searchCache(), searchCache_exports));
+      if (sub === "clear") {
+        clearAllSearchCaches2();
+        console.log(JSON.stringify({ cleared: true }, null, 2));
+      } else {
+        console.log(JSON.stringify({ stats: getAllCacheStats2() }, null, 2));
+      }
+      break;
+    }
+    case "reindex": {
+      const t = Date.now();
+      await ctx.rankedSearch.buildIndex();
+      await ctx.spellChecker.rebuild();
+      console.log(JSON.stringify({ ok: true, ranked: "rebuilt", spell: "rebuilt", durationMs: Date.now() - t }, null, 2));
+      break;
+    }
     default:
       console.log(chalk2.yellow(`Unknown command: ${command}. Type "help" for available commands.`));
   }
@@ -36094,6 +36266,11 @@ ${chalk2.green("Available Commands:")}
   ${chalk2.cyan("neighbors <name>")}   Incoming + outgoing relations + degree counts
   ${chalk2.cyan("diag")} / ${chalk2.cyan("health")}     Quick integrity summary
   ${chalk2.cyan("size")}               Graph + storage footprint
+  ${chalk2.cyan("check [--apply]")}    Orphan + missing-parent + cycle detect/repair
+  ${chalk2.cyan("heuristics")}         List all heuristics
+  ${chalk2.cyan("spell <query>")}      Spell suggestions for a query
+  ${chalk2.cyan("cache [clear]")}      Search-cache stats; "cache clear" to bust
+  ${chalk2.cyan("reindex")}            Rebuild ranked-search + spell vocabulary
   ${chalk2.cyan("history")}            Show command history
   ${chalk2.cyan("clear")}              Clear screen
   ${chalk2.cyan("help")}               Show this help
@@ -38036,89 +38213,100 @@ function registerSpellCommands(program2) {
   });
 }
 
-// src/cli/commands/check.ts
+// src/cli/commands/index.ts
+init_check();
+
+// src/cli/commands/cache.ts
 init_esm_shims();
+init_searchCache();
 init_helpers();
 init_formatters2();
-async function detectIssues(ctx) {
-  const graph = await ctx.storage.loadGraph();
-  const names = new Set(graph.entities.map((e) => e.name));
-  const orphans = [];
-  for (const r of graph.relations) {
-    const fromMissing = !names.has(r.from);
-    const toMissing = !names.has(r.to);
-    if (fromMissing || toMissing) {
-      orphans.push({
-        from: r.from,
-        to: r.to,
-        relationType: r.relationType,
-        reason: fromMissing && toMissing ? "both-missing" : fromMissing ? "from-missing" : "to-missing"
-      });
-    }
-  }
-  const missing = [];
-  const cycles = [];
-  const byName = /* @__PURE__ */ new Map();
-  for (const e of graph.entities) byName.set(e.name, { name: e.name, parentId: e.parentId });
-  for (const e of graph.entities) {
-    if (!e.parentId) continue;
-    if (!byName.has(e.parentId)) {
-      missing.push({ entity: e.name, parentId: e.parentId });
-      continue;
+function emitJson4(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+function registerCacheCommands(program2) {
+  const cache = program2.command("cache").description("Inspect or bust the per-tier search caches (basic / ranked / boolean / fuzzy)");
+  cache.command("stats").description("Per-cache hits/misses/size/hitRate snapshot. Stats are process-local \u2014 fresh CLI invocations start at zero.").action(() => {
+    try {
+      const stats = getAllCacheStats();
+      emitJson4({ stats });
+    } catch (error) {
+      const logger2 = createLogger(getOptions(program2));
+      logger2.error(formatError(error.message));
+      process.exit(1);
     }
-    const visited = /* @__PURE__ */ new Set([e.name]);
-    let cur = byName.get(e.parentId);
-    while (cur && cur.parentId) {
-      if (visited.has(cur.name)) {
-        cycles.push({ entityInCycle: e.name, cycleThrough: cur.name });
-        break;
-      }
-      visited.add(cur.name);
-      cur = byName.get(cur.parentId);
+  });
+  cache.command("clear").description("Clear all four search caches. Idempotent; safe to call any time.").action(() => {
+    try {
+      clearAllSearchCaches();
+      emitJson4({ cleared: true, caches: ["basic", "ranked", "boolean", "fuzzy"] });
+    } catch (error) {
+      const logger2 = createLogger(getOptions(program2));
+      logger2.error(formatError(error.message));
+      process.exit(1);
     }
-  }
-  return { orphans, missing, cycles };
-}
-async function applyFixes(ctx, orphans, missing) {
-  let deleted = 0;
-  let cleared = 0;
-  if (orphans.length > 0) {
-    await ctx.relationManager.deleteRelations(
-      orphans.map((o) => ({ from: o.from, to: o.to, relationType: o.relationType }))
-    );
-    deleted = orphans.length;
-  }
-  for (const m of missing) {
+  });
+  cache.command("cleanup").description("Sweep expired entries (TTL) across all caches without dropping live entries.").action(() => {
     try {
-      await ctx.hierarchyManager.setEntityParent(m.entity, null);
-      cleared += 1;
-    } catch {
+      cleanupAllCaches();
+      emitJson4({ cleaned: true, caches: ["basic", "ranked", "boolean", "fuzzy"] });
+    } catch (error) {
+      const logger2 = createLogger(getOptions(program2));
+      logger2.error(formatError(error.message));
+      process.exit(1);
     }
-  }
-  return { orphanRelationsDeleted: deleted, missingParentsCleared: cleared };
+  });
 }
-function registerCheckCommand(program2) {
-  program2.command("check").description("Detect orphan relations + missing parents + hierarchy cycles. Dry-run by default.").option("--apply", "Actually delete orphan relations + clear missing parentIds (cycles always left for human review)").action(async (opts) => {
+
+// src/cli/commands/reindex.ts
+init_esm_shims();
+init_RankedSearch();
+init_helpers();
+init_formatters2();
+import { dirname as dirname10 } from "path";
+import { performance as performance3 } from "perf_hooks";
+function emitJson5(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+function registerReindexCommand(program2) {
+  program2.command("reindex").description("Rebuild search-side indexes (TF-IDF/BM25 ranked + spell vocabulary).").option("--ranked", "Rebuild only the ranked-search (TF-IDF/BM25) index").option("--spell", "Rebuild only the spell-checker vocabulary").action(async (opts) => {
     const options = getOptions(program2);
     const logger2 = createLogger(options);
     const ctx = createContext(options);
-    try {
-      const { orphans, missing, cycles } = await detectIssues(ctx);
-      const ok = orphans.length === 0 && missing.length === 0 && cycles.length === 0;
-      const report = {
-        ok,
-        applied: Boolean(opts.apply),
-        orphanRelations: orphans,
-        missingParents: missing,
-        hierarchyCycles: cycles
-      };
-      if (opts.apply && (orphans.length > 0 || missing.length > 0)) {
-        report.actions = await applyFixes(ctx, orphans, missing);
+    const targets = opts.ranked === true || opts.spell === true ? { ranked: Boolean(opts.ranked), spell: Boolean(opts.spell) } : { ranked: true, spell: true };
+    const result = {};
+    if (targets.ranked) {
+      const t = performance3.now();
+      try {
+        const storageDir = dirname10(options.storage);
+        const ranked = new RankedSearch(ctx.storage, storageDir);
+        await ranked.buildIndex();
+        result.ranked = { ok: true, durationMs: performance3.now() - t };
+      } catch (e) {
+        result.ranked = {
+          ok: false,
+          durationMs: performance3.now() - t,
+          detail: e instanceof Error ? e.message : String(e)
+        };
       }
-      console.log(JSON.stringify(report, null, 2));
-      if (!ok && !opts.apply) process.exit(1);
-    } catch (error) {
-      logger2.error(formatError(error.message));
+    }
+    if (targets.spell) {
+      const t = performance3.now();
+      try {
+        await ctx.spellChecker.rebuild();
+        result.spell = { ok: true, durationMs: performance3.now() - t };
+      } catch (e) {
+        result.spell = {
+          ok: false,
+          durationMs: performance3.now() - t,
+          detail: e instanceof Error ? e.message : String(e)
+        };
+      }
+    }
+    const failed = Object.values(result).filter((r) => !r.ok).length;
+    emitJson5({ ok: failed === 0, failed, result });
+    if (failed > 0) {
+      logger2.error(formatError(`${failed} index(es) failed to rebuild`));
       process.exit(1);
     }
   });
@@ -38146,6 +38334,8 @@ function registerCommands(program2) {
   registerObservationDedupCommands(program2);
   registerSpellCommands(program2);
   registerCheckCommand(program2);
+  registerCacheCommands(program2);
+  registerReindexCommand(program2);
 }
 
 // src/cli/index.ts
@@ -38153,7 +38343,7 @@ init_logger();
 import { readFileSync as readFileSync5 } from "fs";
 import { createInterface as createInterface2 } from "readline";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import { dirname as dirname10, join as join10 } from "path";
+import { dirname as dirname11, join as join10 } from "path";
 process.on("unhandledRejection", (reason) => {
   logger.error("Unhandled promise rejection:", reason);
 });
@@ -38163,7 +38353,7 @@ process.on("uncaughtException", (err) => {
 function getVersion() {
   try {
     const __filename2 = fileURLToPath4(import.meta.url);
-    const __dirname2 = dirname10(__filename2);
+    const __dirname2 = dirname11(__filename2);
     const pkgPath = join10(__dirname2, "..", "..", "package.json");
     const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
     return pkg.version;