knodin 0.5.0

package/dist/src/engine/perf.js

@@ -0,0 +1,115 @@
+/** Opt-in phase timing used by the R43 benchmark harness. */
+export const PERF_PHASES = [
+    "db_open_migration",
+    "file_collection",
+    "parser_wasm_init",
+    "read",
+    "parse_extract",
+    "sqlite_write",
+    "model_load",
+    "embedding_inference_write",
+    "search_row_fetch_decode",
+    "similarity",
+    "fts",
+    "map_community",
+    "fusion",
+    "freshness_probe",
+    "graph_analytics",
+    "traversal_snapshot",
+    "architecture_facets",
+    "architecture_edge_materialization",
+    "context_composition",
+    "status_audit",
+    "pack_walk",
+    "pack_serialize",
+    "artifact_read",
+    "artifact_grep",
+    "review_diff_discovery",
+    "review_churn",
+    "review_parsing",
+    "review_flow_lookup",
+    "review_serialization",
+];
+let active = null;
+function emptyPhases() {
+    return Object.fromEntries(PERF_PHASES.map((phase) => [phase, 0]));
+}
+function peakRss() {
+    try {
+        const kilobytes = process.resourceUsage().maxRSS;
+        return Number.isFinite(kilobytes) && kilobytes >= 0 ? kilobytes * 1024 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Start a measurement explicitly. Starting while active resets that measurement. */
+export function beginPerfSession() {
+    active = { startedAt: performance.now(), phases: emptyPhases(), peakRssBytes: peakRss() };
+}
+/** Finish the active measurement, or return null when instrumentation is disabled. */
+export function endPerfSession() {
+    const session = active;
+    if (!session)
+        return null;
+    active = null;
+    const currentRss = peakRss();
+    if (currentRss !== undefined) {
+        session.peakRssBytes = Math.max(session.peakRssBytes ?? 0, currentRss);
+    }
+    return {
+        phases: { ...session.phases },
+        totalMs: Math.max(0, performance.now() - session.startedAt),
+        ...(session.peakRssBytes === undefined ? {} : { peakRssBytes: session.peakRssBytes }),
+    };
+}
+function record(phase, startedAt) {
+    const session = active;
+    if (!session)
+        return;
+    session.phases[phase] += Math.max(0, performance.now() - startedAt);
+    const currentRss = peakRss();
+    if (currentRss !== undefined)
+        session.peakRssBytes = Math.max(session.peakRssBytes ?? 0, currentRss);
+}
+/** Start a phase that spans an existing try/finally block. The returned closer is idempotent. */
+export function beginPerfPhase(phase) {
+    if (!active)
+        return () => undefined;
+    const startedAt = performance.now();
+    let closed = false;
+    return () => {
+        if (closed)
+            return;
+        closed = true;
+        record(phase, startedAt);
+    };
+}
+/** Time an async phase. Nested phases are retained independently and errors still close timers. */
+export async function measurePerfPhase(phase, work) {
+    if (!active)
+        return work();
+    const startedAt = performance.now();
+    try {
+        return await work();
+    }
+    finally {
+        record(phase, startedAt);
+    }
+}
+/** Synchronous counterpart for filesystem, parsing, and SQLite calls. */
+export function measurePerfPhaseSync(phase, work) {
+    if (!active)
+        return work();
+    const startedAt = performance.now();
+    try {
+        return work();
+    }
+    finally {
+        record(phase, startedAt);
+    }
+}
+/** Test-only state reset; deliberately does not enable timing. */
+export function resetPerfForTests() {
+    active = null;
+}

package/dist/src/engine/prune.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+/**
+ * Single source of truth for "which directories does knodin ignore" (R14).
+ *
+ * Before this module, the same intent — skip node_modules, .git, .reckon,
+ * build output, caches, VCS internals — was encoded THREE separate times:
+ *   1. src/__tests__/setup.ts's `PRUNE_DIRS` regex (glob-shim exclude filter)
+ *   2. the indexer's own directory filter (`EXCLUDED_DIR_SEGMENTS` / `isIndexablePath`)
+ *   3. the chokidar watcher's `makeWatchIgnorePredicate` (added by R13)
+ *
+ * They drifted. R13's bug was exactly this shape: the watcher's copy silently
+ * stopped matching anything for an entire chokidar major version while the
+ * indexer's copy kept working, so indexing looked correct and only the
+ * watcher melted (it registered ~12.6k files and starved the event loop under
+ * Bun). This module is the ONE list; every consumer below is a thin adapter
+ * over it, so a future drift is structurally impossible rather than merely
+ * discouraged.
+ */
+/**
+ * Directory segments never worth indexing or watching: build output, deps,
+ * VCS/tool state, caches. Matched by whole path SEGMENT, never substring, so
+ * a real file/dir like `distributor.ts` or `build-graph.ts` is never wrongly
+ * pruned.
+ */
+export const PRUNE_DIR_NAMES = new Set([
+    "node_modules",
+    ".git",
+    ".reckon",
+    // Local state maintained by other code-intelligence tools. It is neither
+    // repository source nor stable project configuration, and indexing it makes
+    // a healthy checkout look perpetually stale as those tools update databases
+    // and caches in the background.
+    ".gitnexus",
+    ".codegraph",
+    ".code-review-graph",
+    ".aider.tags.cache.v4",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".svelte-kit",
+    "vendor",
+    "__pycache__",
+]);
+/** True when a single path segment (one directory name) is a pruned directory. */
+export function isPrunedSegment(segment) {
+    return PRUNE_DIR_NAMES.has(segment);
+}
+/**
+ * Agent worktrees are checkouts of this same repo living under
+ * `.claude/worktrees/*`; indexing/watching them would double-count every
+ * symbol. `segments` is the full split relative path; `i` is the segment
+ * index currently being tested against the two-segment `.claude/worktrees`
+ * pattern.
+ */
+function isClaudeWorktreeSegment(segments, i) {
+    return segments[i] === ".claude" && segments[i + 1] === "worktrees";
+}
+/**
+ * True when ANY segment of an already-split repo-relative path trips the
+ * ignore policy (a pruned directory name, or the `.claude/worktrees` root).
+ * This is the one walk both `isIndexablePath` (indexer) and
+ * `makeWatchIgnorePredicate` (watcher) run — the code that used to be
+ * duplicated between them.
+ */
+export function pathSegmentsAreIgnored(segments) {
+    for (let i = 0; i < segments.length; i++) {
+        if (isPrunedSegment(segments[i]))
+            return true;
+        if (isClaudeWorktreeSegment(segments, i))
+            return true;
+    }
+    return false;
+}
+/**
+ * Indexer adapter: true when a repo-relative path (either OS separator)
+ * should be indexed.
+ */
+export function isIndexablePath(relPath) {
+    return !pathSegmentsAreIgnored(relPath.split(/[/\\]/));
+}
+/**
+ * Watcher adapter: builds chokidar's `ignored` predicate for a given repo
+ * root.
+ *
+ * chokidar v4 removed glob support; v5 accepts only a function, a regex, or a
+ * literal path. Matching here is done on the path RELATIVE to the repo, so a
+ * repo that happens to live under a directory named e.g. `build/` does not
+ * prune its own root (the R13 fix this preserves).
+ */
+export function makeWatchIgnorePredicate(repoPath) {
+    return (targetPath) => {
+        const relative = path.relative(repoPath, targetPath);
+        // The watch root itself ("") and anything outside it are never pruned.
+        if (relative === "" || relative.startsWith(".."))
+            return false;
+        return pathSegmentsAreIgnored(relative.split(path.sep));
+    };
+}
+/**
+ * Policy-test adapter: a regex equivalent to the segment-based policy above.
+ * Anchored on `/` boundaries so it only matches whole segments — same guarantee
+ * as `isPrunedSegment` — never a substring inside an unrelated name.
+ */
+export function makePruneDirsRegex() {
+    const escaped = [...PRUNE_DIR_NAMES].map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    // `.claude/worktrees` is a two-segment pattern, expressed directly rather
+    // than through the single-segment name list.
+    escaped.push("\\.claude/worktrees");
+    return new RegExp(`(?:^|/)(?:${escaped.join("|")})(?:/|$)`);
+}

package/dist/src/engine/source-policy.js

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { isIndexablePath } from "./prune.js";
+const SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".cls",
+    ".trigger",
+    ".page",
+    ".component",
+    ".app",
+    ".cmp",
+    ".design",
+    ".docs",
+    ".evt",
+    ".intf",
+    ".svg",
+    ".sql",
+    ".pkb",
+    ".pks",
+    ".prisma",
+    ".java",
+    ".cs",
+    ".go",
+    ".rs",
+    ".clp",
+    ".ws",
+    ".xml",
+    ".tf",
+    ".tfvars",
+    ".hcl",
+    ".dockerfile",
+    ".lsif",
+]);
+function isSalesforceBundleMarkup(normalized) {
+    return (/^force-app\/main\/default\/lwc\/([A-Za-z][A-Za-z0-9_]*)\/\1\.(?:html|css)$/.test(normalized) ||
+        /^force-app\/main\/default\/aura\/([A-Za-z][A-Za-z0-9_]*)\/\1\.(?:css)$/.test(normalized));
+}
+function isSalesforceExperienceJson(normalized) {
+    return (normalized === "lwr.config.json" ||
+        /^force-app\/main\/default\/experiences\/[A-Za-z][A-Za-z0-9_]*\/(?:routes|views|themes)\/[^/]+\.json$/.test(normalized));
+}
+/**
+ * Canonical, path-only candidate policy shared by full-repository collection,
+ * file watching, repair selection, and Git-hook refresh. Content-sensitive
+ * formats (currently dbt manifest.json) are accepted as candidates here and
+ * validated by the parser before symbols are persisted.
+ */
+export function isIndexableSourcePath(relativePath) {
+    if (!isIndexablePath(relativePath))
+        return false;
+    const normalized = relativePath.replaceAll("\\", "/");
+    const base = path.posix.basename(normalized);
+    if (base === "Dockerfile")
+        return true;
+    if (normalized.endsWith(".json")) {
+        return base === "manifest.json" || isSalesforceExperienceJson(normalized);
+    }
+    if (normalized.endsWith(".html") || normalized.endsWith(".css")) {
+        return isSalesforceBundleMarkup(normalized);
+    }
+    return SOURCE_EXTENSIONS.has(path.posix.extname(normalized));
+}

package/dist/src/engine/sqlite.js

@@ -0,0 +1,71 @@
+/**
+ * Production SQLite adapter for the Node runtime.
+ *
+ * knodin's engine was originally written against the compact `bun:sqlite`
+ * surface. Node 24 ships `node:sqlite` without a runtime flag, so this adapter
+ * preserves the engine's existing typed `query<Row, Params>()` contract while
+ * using Node's native `DatabaseSync` implementation underneath.
+ */
+import { DatabaseSync } from "node:sqlite";
+/**
+ * knodin's call sites pass bind params either spread (`stmt.all(a, b)`) or as a
+ * single array (`db.run(sql, [a, b])`). node:sqlite wants them spread — normalize a
+ * lone array argument back into a spread list. SQLite has no array column type,
+ * so a single array can only ever mean "the parameter list", never one value.
+ */
+function normalize(params) {
+    if (params.length === 1 && Array.isArray(params[0]))
+        return params[0];
+    return params;
+}
+class Statement {
+    // node:sqlite's parameter union is intentionally narrower than the engine's
+    // generic call-site contract. Runtime validation still belongs to SQLite.
+    // biome-ignore lint/suspicious/noExplicitAny: adapter boundary around native bindings.
+    stmt;
+    // biome-ignore lint/suspicious/noExplicitAny: adapter boundary around native bindings.
+    constructor(stmt) {
+        this.stmt = stmt;
+    }
+    all(...params) {
+        return this.stmt.all(...normalize(params));
+    }
+    get(...params) {
+        return (this.stmt.get(...normalize(params)) ?? null);
+    }
+    run(...params) {
+        return this.stmt.run(...normalize(params));
+    }
+    finalize() {
+        // node:sqlite statements are released on GC; there is nothing to finalize.
+    }
+}
+export class Database {
+    db;
+    constructor(databasePath, options = {}) {
+        this.db = new DatabaseSync(databasePath, { readOnly: options.readonly === true });
+    }
+    query(sql) {
+        return new Statement(this.db.prepare(sql));
+    }
+    prepare(sql) {
+        return new Statement(this.db.prepare(sql));
+    }
+    run(sql, ...params) {
+        if (params.length === 0) {
+            // DDL / PRAGMA / BEGIN / COMMIT / multi-statement schema — `exec` avoids
+            // prepare() edge cases and handles more-than-one statement in one string.
+            this.db.exec(sql);
+            return { changes: 0, lastInsertRowid: 0 };
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: adapter boundary around native bindings.
+        const statement = this.db.prepare(sql);
+        return statement.run(...normalize(params));
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/src/engine/symbol-delete.js

@@ -0,0 +1,58 @@
+/**
+ * Single source of truth for "delete symbols, and everything keyed off them" (R17).
+ *
+ * `symbol_embeddings.symbolId` declares
+ * `REFERENCES symbols(id) ON DELETE CASCADE`, but SQLite disables foreign-key
+ * enforcement per connection by default, so for the life of the project that
+ * cascade never fired: `symbols.id` is AUTOINCREMENT, every re-index of a file
+ * deletes its symbols and reinserts them under NEW ids, and the embeddings
+ * pointing at the old ids were stranded forever. On `/path/to/large-repository` that had
+ * reached 37,258 orphans against 18,629 live symbols — 67% of the table, all
+ * of it scanned by semantic search's exact cosine pass.
+ *
+ * `getOrInitDb` now sets `PRAGMA foreign_keys = ON`, which makes the declared
+ * cascade real. These helpers are the second layer: they delete the embeddings
+ * EXPLICITLY, so correctness does not depend on a per-connection pragma that
+ * some future connection path forgets to set. Every `DELETE FROM symbols` site
+ * in the engine goes through here — the R14 lesson (one policy, many thin
+ * adapters) applied to deletion instead of ignore rules.
+ */
+/**
+ * Shared predicate for "this embedding's symbol no longer exists" — the
+ * single source of truth for both the DELETE below and the `stats` orphan
+ * COUNT in `src/engine/index.ts`, which previously hardcoded the identical
+ * SQL as an independent string literal.
+ */
+export const ORPHANED_EMBEDDING_PREDICATE = "symbolId NOT IN (SELECT id FROM symbols)";
+/**
+ * Purge embeddings whose symbol no longer exists.
+ *
+ * Idempotent and cheap — a single correlated DELETE. Used by the 13 → 14
+ * migration to clean indexes polluted before the cascade worked, and safe to
+ * call on an empty or freshly-created table.
+ *
+ * Deliberately does NOT touch live embeddings: re-embedding a real corpus is
+ * ~40 minutes of CPU, so this must stay a purge and never become a wipe.
+ */
+export function purgeOrphanEmbeddings(db) {
+    db.run(`DELETE FROM symbol_embeddings WHERE ${ORPHANED_EMBEDDING_PREDICATE}`);
+}
+/** Delete every symbol declared in one repo-relative file, plus its embeddings. */
+export function deleteSymbolsForFile(db, filePath) {
+    db.run("DELETE FROM symbol_embeddings WHERE symbolId IN (SELECT id FROM symbols WHERE filePath = ?)", [filePath]);
+    db.run("DELETE FROM symbols WHERE filePath = ?", [filePath]);
+}
+/**
+ * Delete every symbol whose file path matches a LIKE pattern, plus its
+ * embeddings. Used by the dbt path, whose symbols live under synthetic
+ * `.reckon/dbt/%` paths rather than one real file.
+ */
+export function deleteSymbolsMatchingPath(db, likePattern) {
+    db.run("DELETE FROM symbol_embeddings WHERE symbolId IN (SELECT id FROM symbols WHERE filePath LIKE ?)", [likePattern]);
+    db.run("DELETE FROM symbols WHERE filePath LIKE ?", [likePattern]);
+}
+/** Delete every symbol in the index, plus every embedding. Full re-index only. */
+export function deleteAllSymbols(db) {
+    db.run("DELETE FROM symbol_embeddings;");
+    db.run("DELETE FROM symbols;");
+}