@optave/codegraph 3.3.0 → 3.4.0

package/src/cli/commands/{where.js → where.ts}

@@ -1,6 +1,7 @@
 import { where } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'where [name]',
   description: 'Find where a symbol is defined and used (minimal, fast lookup)',
   queryOpts: true,
@@ -11,7 +12,7 @@ export const command = {
     }
   },
   execute([name], opts, ctx) {
-    const target = opts.file || name;
+    const target = (opts.file || name) as string;
     where(target, opts.db, {
       file: !!opts.file,
       ...ctx.resolveQueryOpts(opts),

package/src/cli/{index.js → index.ts}

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Command } from 'commander';
 import { setVerbose } from '../infrastructure/logger.js';
 import { checkForUpdates, printUpdateNotification } from '../infrastructure/update-check.js';
@@ -13,8 +13,9 @@ import {
   resolveQueryOpts,
 } from './shared/options.js';
 import { outputResult } from './shared/output.js';
+import type { CliContext, CommandDefinition, CommandOpts } from './types.js';
 
-const __cliDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
+const __cliDir = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__cliDir, '..', '..', 'package.json'), 'utf-8'));
 
 const program = new Command();
@@ -26,12 +27,12 @@ program
   .option('--engine <engine>', 'Parser engine: native, wasm, or auto (default: auto)', 'auto')
   .hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
-    if (opts.verbose) setVerbose(true);
+    if (opts['verbose']) setVerbose(true);
   })
   .hook('postAction', async (_thisCommand, actionCommand) => {
     const name = actionCommand.name();
     if (name === 'mcp' || name === 'watch') return;
-    if (actionCommand.opts().json) return;
+    if (actionCommand.opts()['json']) return;
     try {
       const result = await checkForUpdates(pkg.version);
       if (result) printUpdateNotification(result.current, result.latest);
@@ -41,7 +42,14 @@ program
   });
 
 /** Shared context passed to every command's execute(). */
-const ctx = { config, resolveNoTests, resolveQueryOpts, formatSize, outputResult, program };
+const ctx: CliContext = {
+  config,
+  resolveNoTests,
+  resolveQueryOpts,
+  formatSize,
+  outputResult: outputResult as CliContext['outputResult'],
+  program,
+};
 
 /**
  * Register a command definition onto a Commander parent.
@@ -56,21 +64,21 @@ const ctx = { config, resolveNoTests, resolveQueryOpts, formatSize, outputResult
  * - `execute(args, opts, ctx)` — the action handler
  * - `subcommands` — nested command definitions (for groups like registry, snapshot)
  */
-function registerCommand(parent, def) {
+function registerCommand(parent: Command, def: CommandDefinition): Command {
   const cmd = parent.command(def.name).description(def.description);
 
   if (def.queryOpts) applyQueryOpts(cmd);
 
   for (const opt of def.options || []) {
-    cmd.option(...opt);
+    cmd.option(...(opt as Parameters<Command['option']>));
   }
 
   if (def.execute) {
     const argCount = (def.name.match(/<[^>]+>|\[[^\]]+\]/g) || []).length;
 
-    cmd.action((...actionArgs) => {
-      const args = actionArgs.slice(0, argCount);
-      const opts = actionArgs[argCount];
+    cmd.action((...actionArgs: unknown[]) => {
+      const args = actionArgs.slice(0, argCount) as string[];
+      const opts = actionArgs[argCount] as CommandOpts;
 
       if (def.validate) {
         const err = def.validate(args, opts, ctx);
@@ -79,7 +87,7 @@ function registerCommand(parent, def) {
         }
       }
 
-      return def.execute(args, opts, ctx);
+      return def.execute!(args, opts, ctx);
     });
   }
 
@@ -96,15 +104,32 @@ function registerCommand(parent, def) {
  * Auto-discover and register all command modules from src/cli/commands/.
  * Each module must export a `command` (single definition) or `commands` (array).
  */
-async function discoverCommands() {
+async function discoverCommands(): Promise<void> {
   const commandsDir = path.join(__cliDir, 'commands');
   const files = fs
     .readdirSync(commandsDir)
-    .filter((f) => f.endsWith('.js'))
+    .filter((f) => f.endsWith('.js') || f.endsWith('.ts'))
+    .filter((f) => !f.endsWith('.d.ts'))
     .sort();
 
+  // Deduplicate: prefer .ts over .js when both exist
+  const fileSet = new Set(files);
+  const seen = new Set<string>();
+  const deduped: string[] = [];
   for (const file of files) {
-    const mod = await import(pathToFileURL(path.join(commandsDir, file)).href);
+    const base = file.replace(/\.[jt]s$/, '');
+    if (!seen.has(base)) {
+      seen.add(base);
+      const tsVariant = `${base}.ts`;
+      deduped.push(fileSet.has(tsVariant) ? tsVariant : file);
+    }
+  }
+
+  for (const file of deduped) {
+    const mod = (await import(pathToFileURL(path.join(commandsDir, file)).href)) as {
+      command?: CommandDefinition;
+      commands?: CommandDefinition[];
+    };
     if (mod.command) {
       registerCommand(program, mod.command);
     }
@@ -116,7 +141,7 @@ async function discoverCommands() {
   }
 }
 
-export async function run() {
+export async function run(): Promise<void> {
   await discoverCommands();
   await program.parseAsync();
 }

package/src/cli/shared/{open-graph.js → open-graph.ts}

@@ -1,13 +1,13 @@
+import type Database from 'better-sqlite3';
 import { openReadonlyOrFail } from '../../db/index.js';
 
 /**
  * Open the graph database in readonly mode with a clean close() handle.
- *
- * @param {object} [opts]
- * @param {string} [opts.db] - Custom path to graph.db
- * @returns {{ db: import('better-sqlite3').Database, close: () => void }}
  */
-export function openGraph(opts = {}) {
+export function openGraph(opts: { db?: string } = {}): {
+  db: Database.Database;
+  close: () => void;
+} {
   const db = openReadonlyOrFail(opts.db);
   return { db, close: () => db.close() };
 }

package/src/cli/shared/{options.js → options.ts}

@@ -1,13 +1,13 @@
+import type { Command } from 'commander';
 import { loadConfig } from '../../infrastructure/config.js';
+import type { CommandOpts } from '../types.js';
 
 const config = loadConfig(process.cwd());
 
 /**
  * Attach the common query options shared by most analysis commands.
- * @param {import('commander').Command} cmd
- * @returns {import('commander').Command}
  */
-export function applyQueryOpts(cmd) {
+export function applyQueryOpts(cmd: Command): Command {
   return cmd
     .option('-d, --db <path>', 'Path to graph.db')
     .option('-T, --no-tests', 'Exclude test/spec files from results')
@@ -26,7 +26,7 @@ export function applyQueryOpts(cmd) {
  * When --include-tests is passed, always return false (include tests).
  * Otherwise, fall back to config.query.excludeTests.
  */
-export function resolveNoTests(opts) {
+export function resolveNoTests(opts: CommandOpts): boolean {
   if (opts.includeTests) return false;
   if (opts.tests === false) return true;
   return config.query?.excludeTests || false;
@@ -38,7 +38,7 @@ export function resolveNoTests(opts) {
  * Spreads cleanly into per-command option objects:
  *   `{ ...resolveQueryOpts(opts), depth: parseInt(opts.depth, 10) }`
  */
-export function resolveQueryOpts(opts) {
+export function resolveQueryOpts(opts: CommandOpts): CommandOpts {
   return {
     noTests: resolveNoTests(opts),
     json: opts.json,
@@ -50,7 +50,7 @@ export function resolveQueryOpts(opts) {
   };
 }
 
-export function formatSize(bytes) {
+export function formatSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;

package/src/cli/types.ts

@@ -0,0 +1,33 @@
+import type { Command } from 'commander';
+
+/**
+ * Commander options are inherently dynamic — the set of keys depends on
+ * how each command defines its `.option()` calls at runtime.  Using a
+ * concrete index-signature type (`Record<string, …>`) triggers
+ * `noPropertyAccessFromIndexSignature` and forces bracket notation
+ * everywhere, which hurts readability for no safety gain.  A dedicated
+ * opaque alias keeps the intent clear while allowing dot access.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CommandOpts = any;
+
+/** Shape of the shared context passed to every command's execute(). */
+export interface CliContext {
+  config: CommandOpts;
+  resolveNoTests: (opts: CommandOpts) => boolean;
+  resolveQueryOpts: (opts: CommandOpts) => CommandOpts;
+  formatSize: (bytes: number) => string;
+  outputResult: (data: unknown, key: string, opts: CommandOpts) => boolean;
+  program: Command;
+}
+
+/** Shape of a command definition registered via registerCommand(). */
+export interface CommandDefinition {
+  name: string;
+  description: string;
+  queryOpts?: boolean;
+  options?: Array<[string, string, ...unknown[]]>;
+  validate?(args: string[], opts: CommandOpts, ctx: CliContext): string | void;
+  execute?(args: string[], opts: CommandOpts, ctx: CliContext): void | Promise<void>;
+  subcommands?: CommandDefinition[];
+}

package/src/{cli.js → cli.ts}

@@ -3,12 +3,13 @@
 import { run } from './cli/index.js';
 import { CodegraphError } from './shared/errors.js';
 
-run().catch((err) => {
+run().catch((err: unknown) => {
   if (err instanceof CodegraphError) {
     console.error(`codegraph [${err.code}]: ${err.message}`);
     if (err.file) console.error(`  file: ${err.file}`);
   } else {
-    console.error(`codegraph: fatal error — ${err.message || err}`);
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`codegraph: fatal error — ${message}`);
   }
   process.exit(1);
 });

package/src/db/{connection.js → connection.ts}

@@ -4,11 +4,15 @@ import path from 'node:path';
 import Database from 'better-sqlite3';
 import { debug, warn } from '../infrastructure/logger.js';
 import { DbError } from '../shared/errors.js';
+import type { BetterSqlite3Database } from '../types.js';
 import { Repository } from './repository/base.js';
 import { SqliteRepository } from './repository/sqlite-repository.js';
 
-let _cachedRepoRoot; // undefined = not computed, null = not a git repo
-let _cachedRepoRootCwd; // cwd at the time the cache was populated
+/** DB instance with optional advisory lock path. */
+export type LockedDatabase = BetterSqlite3Database & { __lockPath?: string };
+
+let _cachedRepoRoot: string | null | undefined; // undefined = not computed, null = not a git repo
+let _cachedRepoRootCwd: string | undefined; // cwd at the time the cache was populated
 
 /**
  * Return the git worktree/repo root for the given directory (or cwd).
@@ -17,15 +21,13 @@ let _cachedRepoRootCwd; // cwd at the time the cache was populated
  * Results are cached per-process when called without arguments.
  * The cache is keyed on cwd so it invalidates if the working directory changes
  * (e.g. MCP server serving multiple sessions).
- * @param {string} [fromDir] - Directory to resolve from (defaults to cwd)
- * @returns {string | null} Absolute path to repo root, or null if not in a git repo
  */
-export function findRepoRoot(fromDir) {
+export function findRepoRoot(fromDir?: string): string | null {
   const dir = fromDir || process.cwd();
   if (!fromDir && _cachedRepoRoot !== undefined && _cachedRepoRootCwd === dir) {
     return _cachedRepoRoot;
   }
-  let root = null;
+  let root: string | null = null;
   try {
     const raw = execFileSync('git', ['rev-parse', '--show-toplevel'], {
       cwd: dir,
@@ -38,11 +40,11 @@ export function findRepoRoot(fromDir) {
     try {
       root = fs.realpathSync(raw);
     } catch (e) {
-      debug(`realpathSync failed for git root "${raw}", using resolve: ${e.message}`);
+      debug(`realpathSync failed for git root "${raw}", using resolve: ${(e as Error).message}`);
       root = path.resolve(raw);
     }
   } catch (e) {
-    debug(`git rev-parse failed for "${dir}": ${e.message}`);
+    debug(`git rev-parse failed for "${dir}": ${(e as Error).message}`);
     root = null;
   }
   if (!fromDir) {
@@ -53,22 +55,22 @@ export function findRepoRoot(fromDir) {
 }
 
 /** Reset the cached repo root (for testing). */
-export function _resetRepoRootCache() {
+export function _resetRepoRootCache(): void {
   _cachedRepoRoot = undefined;
   _cachedRepoRootCwd = undefined;
 }
 
-function isProcessAlive(pid) {
+function isProcessAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
     return true;
   } catch (e) {
-    debug(`PID ${pid} not alive: ${e.code || e.message}`);
+    debug(`PID ${pid} not alive: ${(e as NodeJS.ErrnoException).code || (e as Error).message}`);
     return false;
   }
 }
 
-function acquireAdvisoryLock(dbPath) {
+function acquireAdvisoryLock(dbPath: string): void {
   const lockPath = `${dbPath}.lock`;
   try {
     if (fs.existsSync(lockPath)) {
@@ -79,23 +81,23 @@ function acquireAdvisoryLock(dbPath) {
       }
     }
   } catch (e) {
-    debug(`Advisory lock read failed: ${e.message}`);
+    debug(`Advisory lock read failed: ${(e as Error).message}`);
   }
   try {
     fs.writeFileSync(lockPath, String(process.pid), 'utf-8');
   } catch (e) {
-    debug(`Advisory lock write failed: ${e.message}`);
+    debug(`Advisory lock write failed: ${(e as Error).message}`);
   }
 }
 
-function releaseAdvisoryLock(lockPath) {
+function releaseAdvisoryLock(lockPath: string): void {
   try {
     const content = fs.readFileSync(lockPath, 'utf-8').trim();
     if (Number(content) === process.pid) {
       fs.unlinkSync(lockPath);
     }
   } catch (e) {
-    debug(`Advisory lock release failed for ${lockPath}: ${e.message}`);
+    debug(`Advisory lock release failed for ${lockPath}: ${(e as Error).message}`);
   }
 }
 
@@ -104,58 +106,64 @@ function releaseAdvisoryLock(lockPath) {
  * Handles Windows 8.3 short names (RUNNER~1 vs runneradmin) and macOS
  * symlinks (/tmp vs /private/tmp) where string comparison fails.
  */
-function isSameDirectory(a, b) {
+function isSameDirectory(a: string, b: string): boolean {
   if (path.resolve(a) === path.resolve(b)) return true;
   try {
     const sa = fs.statSync(a);
     const sb = fs.statSync(b);
     return sa.dev === sb.dev && sa.ino === sb.ino;
   } catch (e) {
-    debug(`isSameDirectory stat failed: ${e.message}`);
+    debug(`isSameDirectory stat failed: ${(e as Error).message}`);
     return false;
   }
 }
 
-export function openDb(dbPath) {
+export function openDb(dbPath: string): LockedDatabase {
   const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   acquireAdvisoryLock(dbPath);
-  const db = new Database(dbPath);
+  // vendor.d.ts declares Database as a callable; cast through unknown for construct usage
+  const db = new (
+    Database as unknown as new (
+      path: string,
+      opts?: Record<string, unknown>,
+    ) => LockedDatabase
+  )(dbPath);
   db.pragma('journal_mode = WAL');
   db.pragma('busy_timeout = 5000');
   db.__lockPath = `${dbPath}.lock`;
   return db;
 }
 
-export function closeDb(db) {
+export function closeDb(db: LockedDatabase): void {
   db.close();
   if (db.__lockPath) releaseAdvisoryLock(db.__lockPath);
 }
 
-export function findDbPath(customPath) {
+export function findDbPath(customPath?: string): string {
   if (customPath) return path.resolve(customPath);
   const rawCeiling = findRepoRoot();
   // Normalize ceiling with realpathSync to resolve 8.3 short names (Windows
   // RUNNER~1 → runneradmin) and symlinks (macOS /var → /private/var).
   // findRepoRoot already applies realpathSync internally, but the git output
   // may still contain short names on some Windows CI environments.
-  let ceiling;
+  let ceiling: string | null;
   if (rawCeiling) {
     try {
       ceiling = fs.realpathSync(rawCeiling);
     } catch (e) {
-      debug(`realpathSync failed for ceiling "${rawCeiling}": ${e.message}`);
+      debug(`realpathSync failed for ceiling "${rawCeiling}": ${(e as Error).message}`);
       ceiling = rawCeiling;
     }
   } else {
     ceiling = null;
   }
   // Resolve symlinks (e.g. macOS /var → /private/var) so dir matches ceiling from git
-  let dir;
+  let dir: string;
   try {
     dir = fs.realpathSync(process.cwd());
   } catch (e) {
-    debug(`realpathSync failed for cwd: ${e.message}`);
+    debug(`realpathSync failed for cwd: ${(e as Error).message}`);
     dir = process.cwd();
   }
   while (true) {
@@ -173,10 +181,8 @@ export function findDbPath(customPath) {
   return path.join(base, '.codegraph', 'graph.db');
 }
 
-/**
- * Open a database in readonly mode, with a user-friendly error if the DB doesn't exist.
- */
-export function openReadonlyOrFail(customPath) {
+/** Open a database in readonly mode, with a user-friendly error if the DB doesn't exist. */
+export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
   const dbPath = findDbPath(customPath);
   if (!fs.existsSync(dbPath)) {
     throw new DbError(
@@ -184,7 +190,12 @@ export function openReadonlyOrFail(customPath) {
       { file: dbPath },
     );
   }
-  return new Database(dbPath, { readonly: true });
+  return new (
+    Database as unknown as new (
+      path: string,
+      opts?: Record<string, unknown>,
+    ) => BetterSqlite3Database
+  )(dbPath, { readonly: true });
 }
 
 /**
@@ -192,13 +203,11 @@ export function openReadonlyOrFail(customPath) {
  *
  * When `opts.repo` is a Repository instance, returns it directly (no DB opened).
  * Otherwise opens a readonly SQLite DB and wraps it in SqliteRepository.
- *
- * @param {string} [customDbPath] - Path to graph.db (ignored when opts.repo is set)
- * @param {object} [opts]
- * @param {Repository} [opts.repo] - Pre-built Repository to use instead of SQLite
- * @returns {{ repo: Repository, close(): void }}
  */
-export function openRepo(customDbPath, opts = {}) {
+export function openRepo(
+  customDbPath?: string,
+  opts: { repo?: Repository } = {},
+): { repo: Repository; close(): void } {
   if (opts.repo != null) {
     if (!(opts.repo instanceof Repository)) {
       throw new TypeError(

package/src/db/{index.js → index.ts}

@@ -1,4 +1,6 @@
 // Barrel re-export — keeps all existing `import { ... } from '…/db/index.js'` working.
+
+export type { LockedDatabase } from './connection.js';
 export {
   closeDb,
   findDbPath,
@@ -56,6 +58,8 @@ export {
   getFileNodesAll,
   getFunctionNodeId,
   getImportEdges,
+  getLineCountForNode,
+  getMaxEndLineForFile,
   getNodeId,
   hasCfgTables,
   hasCoChanges,

package/src/db/{migrations.js → migrations.ts}

@@ -1,7 +1,14 @@
 import { debug } from '../infrastructure/logger.js';
+import type { BetterSqlite3Database } from '../types.js';
 
 // ─── Schema Migrations ─────────────────────────────────────────────────
-export const MIGRATIONS = [
+
+interface Migration {
+  version: number;
+  up: string;
+}
+
+export const MIGRATIONS: Migration[] = [
   {
     version: 1,
     up: `
@@ -242,28 +249,43 @@ export const MIGRATIONS = [
   },
 ];
 
-function hasColumn(db, table, column) {
-  const cols = db.pragma(`table_info(${table})`);
+interface PragmaColumnInfo {
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: unknown;
+  pk: number;
+}
+
+function hasColumn(db: BetterSqlite3Database, table: string, column: string): boolean {
+  const cols = db.pragma(`table_info(${table})`) as PragmaColumnInfo[];
   return cols.some((c) => c.name === column);
 }
 
-function hasTable(db, table) {
-  const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table);
+function hasTable(db: BetterSqlite3Database, table: string): boolean {
+  const row = db
+    .prepare<{ '1': number }>("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?")
+    .get(table);
   return !!row;
 }
 
-export function getBuildMeta(db, key) {
+export function getBuildMeta(db: BetterSqlite3Database, key: string): string | null {
   if (!hasTable(db, 'build_meta')) return null;
   try {
-    const row = db.prepare('SELECT value FROM build_meta WHERE key = ?').get(key);
+    const row = db
+      .prepare<{ value: string }>('SELECT value FROM build_meta WHERE key = ?')
+      .get(key);
     return row ? row.value : null;
   } catch (e) {
-    debug(`getBuildMeta failed for key "${key}": ${e.message}`);
+    debug(`getBuildMeta failed for key "${key}": ${(e as Error).message}`);
     return null;
   }
 }
 
-export function setBuildMeta(db, entries) {
+export function setBuildMeta(
+  db: BetterSqlite3Database,
+  entries: Record<string, string | number>,
+): void {
   const upsert = db.prepare('INSERT OR REPLACE INTO build_meta (key, value) VALUES (?, ?)');
   const tx = db.transaction(() => {
     for (const [key, value] of Object.entries(entries)) {
@@ -273,10 +295,10 @@ export function setBuildMeta(db, entries) {
   tx();
 }
 
-export function initSchema(db) {
+export function initSchema(db: BetterSqlite3Database): void {
   db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL DEFAULT 0)`);
 
-  const row = db.prepare('SELECT version FROM schema_version').get();
+  const row = db.prepare<{ version: number }>('SELECT version FROM schema_version').get();
   let currentVersion = row ? row.version : 0;
 
   if (!row) {