@optave/codegraph 3.10.0 → 3.11.1

package/src/ast-analysis/visitors/ast-store-visitor.ts

@@ -181,46 +181,17 @@ function newTypesFor(astTypeMap: Record<string, string>): Set<string> {
   return s;
 }
 
-export function createAstStoreVisitor(
-  astTypeMap: Record<string, string>,
-  defs: Definition[],
-  relPath: string,
-  nodeIdMap: Map<string, number>,
-  stringConfig: AstStringConfig = DEFAULT_STRING_CONFIG,
-  stopRecurseKinds: ReadonlySet<string> = new Set(),
-): Visitor {
-  const rows: AstStoreRow[] = [];
-  const matched = new Set<number>();
-  const newTypes = newTypesFor(astTypeMap);
-  // When nodeIdMap is empty, parentNodeId resolution is wasted work — the
-  // worker passes an empty map and the main thread re-resolves against its
-  // own DB-populated map in features/ast.ts::collectFileAstRows. Skip the
-  // findParentDef linear scan in that case.
-  const skipParentLookup = nodeIdMap.size === 0;
-
-  function findParentDef(line: number): Definition | null {
-    let best: Definition | null = null;
-    for (const def of defs) {
-      if (def.line <= line && (def.endLine == null || def.endLine >= line)) {
-        if (!best || (def.endLine ?? 0) - def.line < (best.endLine ?? 0) - best.line) {
-          best = def;
-        }
-      }
-    }
-    return best;
-  }
-
-  function resolveParentNodeId(line: number): number | null {
-    if (skipParentLookup) return null;
-    const parentDef = findParentDef(line);
-    if (!parentDef) return null;
-    return nodeIdMap.get(`${parentDef.name}|${parentDef.kind}|${parentDef.line}`) || null;
-  }
+type NameTextResult = { name: string | null | undefined; text: string | null; skip?: boolean };
+type KindHandler = (node: TreeSitterNode) => NameTextResult;
 
-  type NameTextResult = { name: string | null | undefined; text: string | null; skip?: boolean };
-  type KindHandler = (node: TreeSitterNode) => NameTextResult;
+const DEFAULT_NAME_TEXT_RESULT: NameTextResult = { name: undefined, text: null };
 
-  const kindHandlers: Record<string, KindHandler> = {
+/** Build the per-kind resolver map for name/text extraction. */
+function buildKindHandlers(
+  newTypes: Set<string>,
+  stringConfig: AstStringConfig,
+): Record<string, KindHandler> {
+  return {
     new: (node) => ({ name: extractConstructorName(node), text: truncate(node.text) }),
     throw: (node) => ({
       name: extractThrowName(node, newTypes),
@@ -234,31 +205,102 @@ export function createAstStoreVisitor(
     },
     regex: (node) => ({ name: node.text || '?', text: truncate(node.text) }),
   };
-  const defaultResult: NameTextResult = { name: undefined, text: null };
+}
 
-  function resolveNameAndText(node: TreeSitterNode, kind: string): NameTextResult {
-    const handler = kindHandlers[kind];
-    return handler ? handler(node) : defaultResult;
+/** Find the innermost definition whose line range contains `line`. */
+function findParentDef(line: number, defs: Definition[]): Definition | null {
+  let best: Definition | null = null;
+  for (const def of defs) {
+    if (def.line <= line && (def.endLine == null || def.endLine >= line)) {
+      if (!best || (def.endLine ?? 0) - def.line < (best.endLine ?? 0) - best.line) {
+        best = def;
+      }
+    }
   }
+  return best;
+}
+
+/** Resolve the parent definition's node id for a given source line. */
+function resolveParentNodeId(
+  line: number,
+  defs: Definition[],
+  nodeIdMap: Map<string, number>,
+  skipParentLookup: boolean,
+): number | null {
+  if (skipParentLookup) return null;
+  const parentDef = findParentDef(line, defs);
+  if (!parentDef) return null;
+  return nodeIdMap.get(`${parentDef.name}|${parentDef.kind}|${parentDef.line}`) || null;
+}
 
-  function collectNode(node: TreeSitterNode, kind: string): void {
-    if (matched.has(node.id)) return;
+interface CollectCtx {
+  rows: AstStoreRow[];
+  matched: Set<number>;
+  relPath: string;
+  defs: Definition[];
+  nodeIdMap: Map<string, number>;
+  skipParentLookup: boolean;
+  kindHandlers: Record<string, KindHandler>;
+}
 
-    const resolved = resolveNameAndText(node, kind);
-    if (resolved.skip) return;
+function collectNode(ctx: CollectCtx, node: TreeSitterNode, kind: string): void {
+  if (ctx.matched.has(node.id)) return;
+
+  const handler = ctx.kindHandlers[kind];
+  const resolved = handler ? handler(node) : DEFAULT_NAME_TEXT_RESULT;
+  if (resolved.skip) return;
+
+  const line = node.startPosition.row + 1;
+  ctx.rows.push({
+    file: ctx.relPath,
+    line,
+    kind,
+    name: resolved.name,
+    text: resolved.text,
+    receiver: null,
+    parentNodeId: resolveParentNodeId(line, ctx.defs, ctx.nodeIdMap, ctx.skipParentLookup),
+  });
+
+  ctx.matched.add(node.id);
+}
 
-    rows.push({
-      file: relPath,
-      line: node.startPosition.row + 1,
-      kind,
-      name: resolved.name,
-      text: resolved.text,
-      receiver: null,
-      parentNodeId: resolveParentNodeId(node.startPosition.row + 1),
-    });
+/**
+ * Resolve the kind for a tree-sitter node, or `null` if the node should be ignored.
+ *
+ * Gate with `hasOwn` because plain-object lookup walks Object.prototype:
+ * tree-sitter node types like `constructor` (Haskell sum-types: Left,
+ * Right) would otherwise resolve to `Object.prototype.constructor` (the
+ * Object() function), which then crashes the worker boundary with
+ * "function Object() { [native code] } could not be cloned" when the
+ * resulting astNodes row is structured-cloned back to the main thread.
+ */
+function resolveAstKind(node: TreeSitterNode, astTypeMap: Record<string, string>): string | null {
+  if (!Object.hasOwn(astTypeMap, node.type)) return null;
+  return astTypeMap[node.type] || null;
+}
 
-    matched.add(node.id);
-  }
+export function createAstStoreVisitor(
+  astTypeMap: Record<string, string>,
+  defs: Definition[],
+  relPath: string,
+  nodeIdMap: Map<string, number>,
+  stringConfig: AstStringConfig = DEFAULT_STRING_CONFIG,
+  stopRecurseKinds: ReadonlySet<string> = new Set(),
+): Visitor {
+  const newTypes = newTypesFor(astTypeMap);
+  // When nodeIdMap is empty, parentNodeId resolution is wasted work — the
+  // worker passes an empty map and the main thread re-resolves against its
+  // own DB-populated map in features/ast.ts::collectFileAstRows. Skip the
+  // findParentDef linear scan in that case.
+  const ctx: CollectCtx = {
+    rows: [],
+    matched: new Set<number>(),
+    relPath,
+    defs,
+    nodeIdMap,
+    skipParentLookup: nodeIdMap.size === 0,
+    kindHandlers: buildKindHandlers(newTypes, stringConfig),
+  };
 
   return {
     name: 'ast-store',
@@ -267,19 +309,12 @@ export function createAstStoreVisitor(
       // Guard: skip re-collection but do NOT skipChildren — node.id (memory address)
       // can be reused by tree-sitter, so a collision would incorrectly suppress an
       // unrelated subtree. The parent call's skipChildren handles the intended case.
-      if (matched.has(node.id)) return;
-
-      // Gate with `hasOwn` because plain-object lookup walks Object.prototype:
-      // tree-sitter node types like `constructor` (Haskell sum-types: Left,
-      // Right) would otherwise resolve to `Object.prototype.constructor` (the
-      // Object() function), which then crashes the worker boundary with
-      // "function Object() { [native code] } could not be cloned" when the
-      // resulting astNodes row is structured-cloned back to the main thread.
-      if (!Object.hasOwn(astTypeMap, node.type)) return;
-      const kind = astTypeMap[node.type];
+      if (ctx.matched.has(node.id)) return;
+
+      const kind = resolveAstKind(node, astTypeMap);
       if (!kind) return;
 
-      collectNode(node, kind);
+      collectNode(ctx, node, kind);
 
       // Mirror the native walker's recursion policy. In JS/TS, the native
       // javascript.rs walker returns after collecting `new` or `throw` to
@@ -293,7 +328,7 @@ export function createAstStoreVisitor(
     },
 
     finish(): AstStoreRow[] {
-      return rows;
+      return ctx.rows;
     },
   };
 }

package/src/ast-analysis/visitors/dataflow-visitor.ts

@@ -405,6 +405,79 @@ function handleReturn(
   }
 }
 
+/** Collect parameter entries for a function and push a new scope onto the stack. */
+function enterFunctionScope(
+  funcNode: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  parameters: DataflowParam[],
+): void {
+  const name = functionName(funcNode, rules);
+  const paramsNode = funcNode.childForFieldName(rules.paramListField);
+  const paramList = extractParams(paramsNode, rules);
+  const paramMap = new Map<string, number>();
+  for (const p of paramList) {
+    paramMap.set(p.name, p.index);
+    if (name) {
+      parameters.push({
+        funcName: name,
+        paramName: p.name,
+        paramIndex: p.index,
+        line: (paramsNode?.startPosition?.row ?? funcNode.startPosition.row) + 1,
+      });
+    }
+  }
+  scopeStack.push({ funcName: name, funcNode, params: paramMap, locals: new Map() });
+}
+
+interface DataflowDispatchCtx {
+  rules: AnyRules;
+  scopeStack: ScopeEntry[];
+  returns: DataflowReturnEntry[];
+  assignments: DataflowAssignment[];
+  argFlows: DataflowArgFlow[];
+  mutations: DataflowMutation[];
+  isCallNode: (t: string) => boolean;
+}
+
+/**
+ * Route a node to the appropriate dataflow handler based on its type.
+ * Function-definition nodes are short-circuited with an early return.
+ */
+function dispatchDataflowNode(ctx: DataflowDispatchCtx, node: TreeSitterNode): void {
+  const { rules } = ctx;
+  const t = node.type;
+
+  if (rules.functionNodes.has(t)) return;
+
+  if (rules.returnNode && t === rules.returnNode) {
+    handleReturn(node, rules, ctx.scopeStack, ctx.returns);
+    return;
+  }
+
+  if (
+    (rules.varDeclaratorNode && t === rules.varDeclaratorNode) ||
+    rules.varDeclaratorNodes?.has(t)
+  ) {
+    handleVarDeclarator(node, rules, ctx.scopeStack, ctx.assignments, ctx.isCallNode);
+    return;
+  }
+
+  if (ctx.isCallNode(t)) {
+    handleCallExpr(node, rules, ctx.scopeStack, ctx.argFlows);
+    return;
+  }
+
+  if (rules.assignmentNode && t === rules.assignmentNode) {
+    handleAssignment(node, rules, ctx.scopeStack, ctx.assignments, ctx.mutations, ctx.isCallNode);
+    return;
+  }
+
+  if (rules.expressionStmtNode && t === rules.expressionStmtNode) {
+    handleExprStmtMutation(node, rules, ctx.scopeStack, ctx.mutations, ctx.isCallNode);
+  }
+}
+
 export function createDataflowVisitor(rules: AnyRules): Visitor {
   const isCallNode: (t: string) => boolean = rules.callNodes
     ? (t: string) => rules.callNodes.has(t)
@@ -417,6 +490,16 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
   const mutations: DataflowMutation[] = [];
   const scopeStack: ScopeEntry[] = [];
 
+  const dispatchCtx: DataflowDispatchCtx = {
+    rules,
+    scopeStack,
+    returns,
+    assignments,
+    argFlows,
+    mutations,
+    isCallNode,
+  };
+
   return {
     name: 'dataflow',
     functionNodeTypes: rules.functionNodes,
@@ -426,22 +509,7 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
       _funcName: string | null,
       _context: VisitorContext,
     ): void {
-      const name = functionName(funcNode, rules);
-      const paramsNode = funcNode.childForFieldName(rules.paramListField);
-      const paramList = extractParams(paramsNode, rules);
-      const paramMap = new Map<string, number>();
-      for (const p of paramList) {
-        paramMap.set(p.name, p.index);
-        if (name) {
-          parameters.push({
-            funcName: name,
-            paramName: p.name,
-            paramIndex: p.index,
-            line: (paramsNode?.startPosition?.row ?? funcNode.startPosition.row) + 1,
-          });
-        }
-      }
-      scopeStack.push({ funcName: name, funcNode, params: paramMap, locals: new Map() });
+      enterFunctionScope(funcNode, rules, scopeStack, parameters);
     },
 
     exitFunction(
@@ -453,37 +521,8 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
     },
 
     enterNode(node: TreeSitterNode, _context: VisitorContext): EnterNodeResult | undefined {
-      const t = node.type;
-
-      if (rules.functionNodes.has(t)) return;
-
-      if (rules.returnNode && t === rules.returnNode) {
-        handleReturn(node, rules, scopeStack, returns);
-        return;
-      }
-
-      if (rules.varDeclaratorNode && t === rules.varDeclaratorNode) {
-        handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode);
-        return;
-      }
-      if (rules.varDeclaratorNodes?.has(t)) {
-        handleVarDeclarator(node, rules, scopeStack, assignments, isCallNode);
-        return;
-      }
-
-      if (isCallNode(t)) {
-        handleCallExpr(node, rules, scopeStack, argFlows);
-        return;
-      }
-
-      if (rules.assignmentNode && t === rules.assignmentNode) {
-        handleAssignment(node, rules, scopeStack, assignments, mutations, isCallNode);
-        return;
-      }
-
-      if (rules.expressionStmtNode && t === rules.expressionStmtNode) {
-        handleExprStmtMutation(node, rules, scopeStack, mutations, isCallNode);
-      }
+      dispatchDataflowNode(dispatchCtx, node);
+      return undefined;
     },
 
     finish(): DataflowResultInternal {

package/src/cli/commands/audit.ts

@@ -17,7 +17,7 @@ export const command: CommandDefinition = {
     ['-T, --no-tests', 'Exclude test/spec files from results'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
     ['-j, --json', 'Output as JSON'],
-    ['--limit <number>', 'Max results to return (quick mode)'],
+    ['-n, --limit <number>', 'Max results to return (quick mode)'],
     ['--offset <number>', 'Skip N results (quick mode)'],
     ['--ndjson', 'Newline-delimited JSON output (quick mode)'],
   ],

package/src/cli/commands/build.ts

@@ -7,6 +7,7 @@ export const command: CommandDefinition = {
   name: 'build [dir]',
   description: 'Parse repo and build graph in .codegraph/graph.db',
   options: [
+    ['-d, --db <path>', 'Path to graph.db (default: <dir>/.codegraph/graph.db)'],
     ['--no-incremental', 'Force full rebuild (ignore file hashes)'],
     ['--no-ast', 'Skip AST node extraction (calls, new, string, regex, throw, await)'],
     ['--no-complexity', 'Skip complexity metrics computation'],
@@ -23,6 +24,7 @@ export const command: CommandDefinition = {
       engine: engine as EngineMode,
       dataflow: opts.dataflow as boolean,
       cfg: opts.cfg as boolean,
+      dbPath: opts.db ? path.resolve(opts.db as string) : undefined,
     });
   },
 };

package/src/cli/commands/check.ts

@@ -38,7 +38,7 @@ export const command: CommandDefinition = {
     ['-T, --no-tests', 'Exclude test/spec files from results'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
     ['-j, --json', 'Output as JSON'],
-    ['--limit <number>', 'Max results to return (manifesto mode)'],
+    ['-n, --limit <number>', 'Max results to return (manifesto mode)'],
     ['--offset <number>', 'Skip N results (manifesto mode)'],
     ['--ndjson', 'Newline-delimited JSON output (manifesto mode)'],
   ],

package/src/cli/commands/children.ts

@@ -16,7 +16,7 @@ export const command: CommandDefinition = {
     ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
     ['-T, --no-tests', 'Exclude test/spec files from results'],
     ['-j, --json', 'Output as JSON'],
-    ['--limit <number>', 'Max results to return'],
+    ['-n, --limit <number>', 'Max results to return'],
     ['--offset <number>', 'Skip N results (default: 0)'],
   ],
   validate([_name], opts) {

package/src/cli/commands/diff-impact.ts

@@ -8,7 +8,7 @@ export const command: CommandDefinition = {
     ['-d, --db <path>', 'Path to graph.db'],
     ['-T, --no-tests', 'Exclude test/spec files from results'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
-    ['--limit <number>', 'Max results to return'],
+    ['-n, --limit <number>', 'Max results to return'],
     ['--offset <number>', 'Skip N results (default: 0)'],
     ['--ndjson', 'Newline-delimited JSON output'],
     ['--staged', 'Analyze staged changes instead of unstaged'],

package/src/cli/commands/embed.ts

@@ -1,7 +1,37 @@
 import path from 'node:path';
-import { buildEmbeddings, DEFAULT_MODEL, EMBEDDING_STRATEGIES } from '../../domain/search/index.js';
+import { openReadonlyOrFail } from '../../db/index.js';
+import { getEmbeddingMeta } from '../../db/repository/embeddings.js';
+import {
+  buildEmbeddings,
+  DEFAULT_MODEL,
+  EMBEDDING_STRATEGIES,
+  MODELS,
+} from '../../domain/search/index.js';
+import { info, warn } from '../../infrastructure/logger.js';
 import type { CommandDefinition } from '../types.js';
 
+function resolveStickyModel(dbPath: string | undefined): string | null {
+  try {
+    const db = openReadonlyOrFail(dbPath);
+    try {
+      const storedName = getEmbeddingMeta(db, 'model');
+      if (!storedName) return null;
+      for (const [key, cfg] of Object.entries(MODELS)) {
+        if (cfg.name === storedName) return key;
+      }
+      warn(
+        `Stored embedding model "${storedName}" is no longer recognised — falling back to default. ` +
+          'Embeddings will be rebuilt with the new model.',
+      );
+      return null;
+    } finally {
+      db.close();
+    }
+  } catch {
+    return null;
+  }
+}
+
 export const command: CommandDefinition = {
   name: 'embed [dir]',
   description:
@@ -9,7 +39,7 @@ export const command: CommandDefinition = {
   options: [
     [
       '-m, --model <name>',
-      'Embedding model (default from config or minilm). Run `codegraph models` for details',
+      'Embedding model. Defaults to config, then the model used by existing embeddings, then the built-in default. Run `codegraph models` for options',
     ],
     [
       '-s, --strategy <name>',
@@ -25,8 +55,28 @@ export const command: CommandDefinition = {
   },
   async execute([dir], opts, ctx) {
     const root = path.resolve(dir || '.');
+    const dbPath = opts.db as string | undefined;
     const embeddingsConfig = ctx.config.embeddings;
-    const model = (opts.model as string) || (embeddingsConfig?.model as string) || DEFAULT_MODEL;
-    await buildEmbeddings(root, model, opts.db as string | undefined, { strategy: opts.strategy });
+    const flagModel = opts.model as string | undefined;
+    const configModel = (embeddingsConfig?.model as string | null | undefined) ?? null;
+
+    let model: string;
+    if (flagModel) {
+      model = flagModel;
+    } else if (configModel) {
+      model = configModel;
+    } else {
+      const sticky = resolveStickyModel(dbPath);
+      if (sticky) {
+        info(
+          `Reusing previously-stored embedding model "${sticky}". Pass --model to switch, or set embeddings.model in your config.`,
+        );
+        model = sticky;
+      } else {
+        model = DEFAULT_MODEL;
+      }
+    }
+
+    await buildEmbeddings(root, model, dbPath, { strategy: opts.strategy });
   },
 };

package/src/cli/commands/roles.ts

@@ -14,7 +14,7 @@ export const command: CommandDefinition = {
     ['-T, --no-tests', 'Exclude test/spec files'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
     ['-j, --json', 'Output as JSON'],
-    ['--limit <number>', 'Max results to return'],
+    ['-n, --limit <number>', 'Max results to return'],
     ['--offset <number>', 'Skip N results (default: 0)'],
     ['--ndjson', 'Newline-delimited JSON output'],
   ],

package/src/cli/commands/structure.ts

@@ -12,7 +12,7 @@ export const command: CommandDefinition = {
     ['-T, --no-tests', 'Exclude test/spec files'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
     ['-j, --json', 'Output as JSON'],
-    ['--limit <number>', 'Max results to return'],
+    ['-n, --limit <number>', 'Max results to return'],
     ['--offset <number>', 'Skip N results (default: 0)'],
     ['--ndjson', 'Newline-delimited JSON output'],
     ['--modules', 'Show module boundaries (directories with high cohesion)'],

package/src/cli/shared/options.ts

@@ -13,7 +13,7 @@ export function applyQueryOpts(cmd: Command): Command {
     .option('-T, --no-tests', 'Exclude test/spec files from results')
     .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
     .option('-j, --json', 'Output as JSON')
-    .option('--limit <number>', 'Max results to return')
+    .option('-n, --limit <number>', 'Max results to return')
     .option('--offset <number>', 'Skip N results (default: 0)')
     .option('--ndjson', 'Newline-delimited JSON output')
     .option('--table', 'Output as aligned table')

package/src/db/connection.ts

@@ -292,6 +292,14 @@ export function findDbPath(customPath?: string): string {
       debug(`findDbPath: stopped at git ceiling ${ceiling}`);
       break;
     }
+    // Outside a git repo, cwd is the first (and only) directory we'll check.
+    // Walking past it risks attaching to a stale .codegraph/ in an unrelated
+    // parent — e.g. /private/tmp/.codegraph/ leaking into every /tmp/foo/ run,
+    // or $HOME/.codegraph/ leaking into every scratch dir under $HOME.
+    if (!ceiling) {
+      debug(`findDbPath: no git ceiling, stopping at ${dir}`);
+      break;
+    }
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;