@optave/codegraph 3.3.0 → 3.4.0

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

@@ -1,8 +1,9 @@
 import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { implementations } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'implementations <name>',
   description: 'List all concrete types implementing a given interface or trait',
   queryOpts: true,
@@ -15,12 +16,12 @@ export const command = {
     ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
   ],
   validate([_name], opts) {
-    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
       return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
     }
   },
   execute([name], opts, ctx) {
-    implementations(name, opts.db, {
+    implementations(name!, opts.db, {
       file: opts.file,
       kind: opts.kind,
       ...ctx.resolveQueryOpts(opts),

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

@@ -1,4 +1,6 @@
-export const command = {
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
   name: 'info',
   description: 'Show codegraph engine info and diagnostics',
   async execute(_args, _opts, ctx) {
@@ -7,7 +9,7 @@ export const command = {
     );
     const { getActiveEngine } = await import('../../domain/parser.js');
 
-    const engine = ctx.program.opts().engine;
+    const engine = ctx.program.opts()['engine'];
     const { name: activeName, version: activeVersion } = getActiveEngine({ engine });
     const nativeAvailable = isNativeAvailable();
 
@@ -18,7 +20,7 @@ export const command = {
     console.log(`  Platform      : ${process.platform}-${process.arch}`);
     console.log(`  Native engine : ${nativeAvailable ? 'available' : 'unavailable'}`);
     if (nativeAvailable) {
-      const native = loadNative();
+      const native = loadNative()!;
       const binaryVersion =
         typeof native.engineVersion === 'function' ? native.engineVersion() : 'unknown';
       const pkgVersion = getNativePackageVersion();
@@ -36,11 +38,12 @@ export const command = {
     console.log();
 
     try {
-      const { findDbPath, getBuildMeta } = await import('../../db.js');
+      const { findDbPath, getBuildMeta } = await import('../../db/index.js');
       const Database = (await import('better-sqlite3')).default;
       const dbPath = findDbPath();
       const fs = await import('node:fs');
       if (fs.existsSync(dbPath)) {
+        // @ts-expect-error -- better-sqlite3 default export typing
         const db = new Database(dbPath, { readonly: true });
         const buildEngine = getBuildMeta(db, 'engine');
         const buildVersion = getBuildMeta(db, 'codegraph_version');

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

@@ -1,8 +1,9 @@
 import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { interfaces } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'interfaces <name>',
   description: 'List all interfaces and traits that a class or struct implements',
   queryOpts: true,
@@ -15,12 +16,12 @@ export const command = {
     ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
   ],
   validate([_name], opts) {
-    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
       return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
     }
   },
   execute([name], opts, ctx) {
-    interfaces(name, opts.db, {
+    interfaces(name!, opts.db, {
       file: opts.file,
       kind: opts.kind,
       ...ctx.resolveQueryOpts(opts),

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

@@ -1,6 +1,7 @@
 import { moduleMap } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'map',
   description: 'High-level module overview with most-connected nodes',
   options: [
@@ -11,7 +12,7 @@ export const command = {
     ['-j, --json', 'Output as JSON'],
   ],
   execute(_args, opts, ctx) {
-    moduleMap(opts.db, parseInt(opts.limit, 10), {
+    moduleMap(opts.db, parseInt(opts.limit as string, 10), {
       noTests: ctx.resolveNoTests(opts),
       json: opts.json,
     });

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

@@ -1,4 +1,6 @@
-export const command = {
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
   name: 'mcp',
   description: 'Start MCP (Model Context Protocol) server for AI assistant integration',
   options: [
@@ -8,11 +10,10 @@ export const command = {
   ],
   async execute(_args, opts) {
     const { startMCPServer } = await import('../../mcp/index.js');
-    const mcpOpts = {};
-    mcpOpts.multiRepo = opts.multiRepo || !!opts.repos;
-    if (opts.repos) {
-      mcpOpts.allowedRepos = opts.repos.split(',').map((s) => s.trim());
-    }
-    await startMCPServer(opts.db, mcpOpts);
+    const mcpOpts = {
+      multiRepo: opts.multiRepo || !!opts.repos,
+      allowedRepos: opts.repos ? (opts.repos as string).split(',').map((s) => s.trim()) : undefined,
+    };
+    await startMCPServer(opts.db as string | undefined, mcpOpts);
   },
 };

package/src/cli/commands/models.ts

@@ -0,0 +1,29 @@
+import { DEFAULT_MODEL, MODELS } from '../../domain/search/index.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'models',
+  description: 'List available embedding models',
+  execute(_args, _opts, ctx) {
+    const embeddingsConfig = ctx.config.embeddings;
+    const defaultModel = (embeddingsConfig?.model as string) || DEFAULT_MODEL;
+    console.log('\nAvailable embedding models:\n');
+
+    interface ModelEntry {
+      dim: number;
+      desc: string;
+      contextWindow?: number;
+    }
+
+    for (const [key, cfg] of Object.entries(MODELS)) {
+      const def = key === defaultModel ? ' (default)' : '';
+      const modelCfg = cfg as ModelEntry;
+      const ctxWindow = modelCfg.contextWindow ? `${modelCfg.contextWindow} ctx` : '';
+      console.log(
+        `  ${key.padEnd(12)} ${String(modelCfg.dim).padStart(4)}d  ${ctxWindow.padEnd(9)} ${modelCfg.desc}${def}`,
+      );
+    }
+    console.log('\nUsage: codegraph embed --model <name> --strategy <structured|source>');
+    console.log('       codegraph search "query" --model <name>\n');
+  },
+};

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

@@ -1,6 +1,7 @@
 import { collectFile } from '../../db/query-builder.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'owners [target]',
   description: 'Show CODEOWNERS mapping for files and functions',
   options: [
@@ -18,7 +19,7 @@ export const command = {
     owners(opts.db, {
       owner: opts.owner,
       boundary: opts.boundary,
-      file: opts.file && opts.file.length > 0 ? opts.file : target,
+      file: opts.file && (opts.file as unknown[]).length > 0 ? opts.file : target,
       kind: opts.kind,
       noTests: ctx.resolveNoTests(opts),
       json: opts.json,

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

@@ -1,7 +1,8 @@
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { symbolPath } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'path <from> <to>',
   description: 'Find shortest path between two symbols',
   options: [
@@ -17,14 +18,14 @@ export const command = {
     ['-j, --json', 'Output as JSON'],
   ],
   validate([_from, _to], opts) {
-    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
       return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
     }
   },
   execute([from, to], opts, ctx) {
-    symbolPath(from, to, opts.db, {
-      maxDepth: opts.depth ? parseInt(opts.depth, 10) : 10,
-      edgeKinds: opts.kinds ? opts.kinds.split(',').map((s) => s.trim()) : undefined,
+    symbolPath(from!, to!, opts.db, {
+      maxDepth: opts.depth ? parseInt(opts.depth as string, 10) : 10,
+      edgeKinds: opts.kinds ? (opts.kinds as string).split(',').map((s) => s.trim()) : undefined,
       reverse: opts.reverse,
       fromFile: opts.fromFile,
       toFile: opts.toFile,

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

@@ -1,8 +1,26 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { openGraph } from '../shared/open-graph.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+interface PlotConfig {
+  layout?: { algorithm?: string; direction?: string };
+  physics?: { enabled?: boolean; nodeDistance?: number };
+  nodeColors?: Record<string, string>;
+  roleColors?: Record<string, string>;
+  colorBy?: string;
+  edgeStyle?: { color?: string; smooth?: boolean };
+  filter?: { kinds?: string[] | null; roles?: string[] | null; files?: string[] | null };
+  title?: string;
+  seedStrategy?: string;
+  seedCount?: number;
+  clusterBy?: string;
+  sizeBy?: string;
+  overlays?: { complexity?: boolean; risk?: boolean };
+  riskThresholds?: { highBlastRadius?: number; lowMI?: number };
+}
+
+export const command: CommandDefinition = {
   name: 'plot',
   description: 'Generate an interactive HTML dependency graph viewer',
   options: [
@@ -24,30 +42,31 @@ export const command = {
   async execute(_args, opts, ctx) {
     const { generatePlotHTML, loadPlotConfig } = await import('../../features/graph-enrichment.js');
     const os = await import('node:os');
-    const { db, close } = openGraph(opts);
+    const { db, close } = openGraph(opts as { db?: string });
 
-    let plotCfg;
-    let html;
+    let plotCfg: PlotConfig;
+    let html: string;
     try {
       if (opts.config) {
         try {
-          plotCfg = JSON.parse(fs.readFileSync(opts.config, 'utf-8'));
-        } catch (e) {
-          console.error(`Failed to load config: ${e.message}`);
+          plotCfg = JSON.parse(fs.readFileSync(opts.config as string, 'utf-8')) as PlotConfig;
+        } catch (e: unknown) {
+          const message = e instanceof Error ? e.message : String(e);
+          console.error(`Failed to load config: ${message}`);
           process.exitCode = 1;
           return;
         }
       } else {
-        plotCfg = loadPlotConfig(process.cwd());
+        plotCfg = loadPlotConfig(process.cwd()) as PlotConfig;
       }
 
       if (opts.cluster) plotCfg.clusterBy = opts.cluster;
       if (opts.colorBy) plotCfg.colorBy = opts.colorBy;
       if (opts.sizeBy) plotCfg.sizeBy = opts.sizeBy;
       if (opts.seed) plotCfg.seedStrategy = opts.seed;
-      if (opts.seedCount) plotCfg.seedCount = parseInt(opts.seedCount, 10);
+      if (opts.seedCount) plotCfg.seedCount = parseInt(opts.seedCount as string, 10);
       if (opts.overlay) {
-        const parts = opts.overlay.split(',').map((s) => s.trim());
+        const parts = (opts.overlay as string).split(',').map((s) => s.trim());
         if (!plotCfg.overlays) plotCfg.overlays = {};
         if (parts.includes('complexity')) plotCfg.overlays.complexity = true;
         if (parts.includes('risk')) plotCfg.overlays.risk = true;
@@ -56,8 +75,9 @@ export const command = {
       html = generatePlotHTML(db, {
         fileLevel: !opts.functions,
         noTests: ctx.resolveNoTests(opts),
-        minConfidence: parseFloat(opts.minConfidence),
-        config: plotCfg,
+        minConfidence: parseFloat(opts.minConfidence as string),
+        // PlotConfig shapes are structurally compatible; bridge the two declarations
+        config: plotCfg as never,
       });
     } finally {
       close();
@@ -69,13 +89,14 @@ export const command = {
       return;
     }
 
-    const outPath = opts.output || path.join(os.tmpdir(), `codegraph-plot-${Date.now()}.html`);
+    const outPath =
+      (opts.output as string) || path.join(os.tmpdir(), `codegraph-plot-${Date.now()}.html`);
     fs.writeFileSync(outPath, html, 'utf-8');
     console.log(`Plot written to ${outPath}`);
 
     if (opts.open !== false) {
       const { execFile } = await import('node:child_process');
-      const args =
+      const args: [string, string[]] =
         process.platform === 'win32'
           ? ['cmd', ['/c', 'start', '', outPath]]
           : process.platform === 'darwin'

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

@@ -1,8 +1,9 @@
 import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { fnDeps, symbolPath } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'query <name>',
   description: 'Function-level dependency chain or shortest path between symbols',
   queryOpts: true,
@@ -21,16 +22,16 @@ export const command = {
     ['--to-file <path>', 'Path mode: disambiguate target symbol by file'],
   ],
   validate([_name], opts) {
-    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
       return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
     }
   },
   execute([name], opts, ctx) {
     if (opts.path) {
       console.error('Note: "query --path" is deprecated, use "codegraph path <from> <to>" instead');
-      symbolPath(name, opts.path, opts.db, {
-        maxDepth: opts.depth ? parseInt(opts.depth, 10) : 10,
-        edgeKinds: opts.kinds ? opts.kinds.split(',').map((s) => s.trim()) : undefined,
+      symbolPath(name!, opts.path as string, opts.db, {
+        maxDepth: opts.depth ? parseInt(opts.depth as string, 10) : 10,
+        edgeKinds: opts.kinds ? (opts.kinds as string).split(',').map((s) => s.trim()) : undefined,
         reverse: opts.reverse,
         fromFile: opts.fromFile,
         toFile: opts.toFile,
@@ -39,8 +40,8 @@ export const command = {
         json: opts.json,
       });
     } else {
-      fnDeps(name, opts.db, {
-        depth: parseInt(opts.depth, 10),
+      fnDeps(name!, opts.db, {
+        depth: parseInt(opts.depth as string, 10),
         file: opts.file,
         kind: opts.kind,
         ...ctx.resolveQueryOpts(opts),

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

@@ -8,8 +8,9 @@ import {
   unregisterRepo,
 } from '../../infrastructure/registry.js';
 import { ConfigError } from '../../shared/errors.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'registry',
   description: 'Manage the multi-repo project registry',
   subcommands: [
@@ -42,8 +43,8 @@ export const command = {
       description: 'Register a project directory',
       options: [['-n, --name <name>', 'Custom name (defaults to directory basename)']],
       execute([dir], opts) {
-        const absDir = path.resolve(dir);
-        const { name, entry } = registerRepo(absDir, opts.name);
+        const absDir = path.resolve(dir!);
+        const { name, entry } = registerRepo(absDir, opts.name as string | undefined);
         console.log(`Registered "${name}" → ${entry.path}`);
       },
     },
@@ -51,7 +52,7 @@ export const command = {
       name: 'remove <name>',
       description: 'Unregister a repository by name',
       execute([name]) {
-        const removed = unregisterRepo(name);
+        const removed = unregisterRepo(name!);
         if (removed) {
           console.log(`Removed "${name}" from registry.`);
         } else {
@@ -69,13 +70,18 @@ export const command = {
       ],
       execute(_args, opts) {
         const excludeNames = opts.exclude
-          ? opts.exclude
+          ? (opts.exclude as string)
               .split(',')
               .map((s) => s.trim())
               .filter((s) => s.length > 0)
           : [];
         const dryRun = !!opts.dryRun;
-        const pruned = pruneRegistry(undefined, parseInt(opts.ttl, 10), excludeNames, dryRun);
+        const pruned = pruneRegistry(
+          undefined,
+          parseInt(opts.ttl as string, 10),
+          excludeNames,
+          dryRun,
+        );
         if (pruned.length === 0) {
           console.log('No stale entries found.');
         } else {

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

@@ -1,8 +1,9 @@
 import { collectFile } from '../../db/query-builder.js';
 import { VALID_ROLES } from '../../domain/queries.js';
 import { roles } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'roles',
   description:
     'Show node role classification: entry, core, utility, adapter, dead (dead-leaf, dead-entry, dead-ffi, dead-unresolved), leaf',
@@ -18,7 +19,7 @@ export const command = {
     ['--ndjson', 'Newline-delimited JSON output'],
   ],
   validate(_args, opts) {
-    if (opts.role && !VALID_ROLES.includes(opts.role)) {
+    if (opts.role && !(VALID_ROLES as readonly string[]).includes(opts.role)) {
       return `Invalid role "${opts.role}". Valid roles: ${VALID_ROLES.join(', ')}`;
     }
   },

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

@@ -1,7 +1,8 @@
 import { collectFile } from '../../db/query-builder.js';
 import { search } from '../../domain/search/index.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'search <query>',
   description: 'Semantic search: find functions by natural language description',
   options: [
@@ -21,28 +22,24 @@ export const command = {
   ],
   validate([_query], opts) {
     const validModes = ['hybrid', 'semantic', 'keyword'];
-    if (opts.mode && !validModes.includes(opts.mode)) {
+    if (opts.mode && !validModes.includes(opts.mode as string)) {
       return `Invalid mode "${opts.mode}". Valid: ${validModes.join(', ')}`;
     }
   },
   async execute([query], opts, ctx) {
-    // --file collects into an array; pass single element unwrapped for single
-    // value, or pass the raw array for multi-file scoping.
-    const fileArr = opts.file || [];
+    const fileArr = (opts.file || []) as string[];
     const filePattern =
       fileArr.length === 1 ? fileArr[0] : fileArr.length > 1 ? fileArr : undefined;
-    await search(query, opts.db, {
-      limit: parseInt(opts.limit, 10),
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+    await search(query!, opts.db as string | undefined, {
+      limit: parseInt(opts.limit as string, 10),
       noTests: ctx.resolveNoTests(opts),
-      minScore: parseFloat(opts.minScore),
-      model: opts.model,
-      kind: opts.kind,
+      minScore: parseFloat(opts.minScore as string),
+      model: opts.model as string | undefined,
+      kind: opts.kind as string | undefined,
       filePattern,
-      rrfK: parseInt(opts.rrfK, 10),
-      mode: opts.mode,
-      json: opts.json,
-      ndjson: opts.ndjson,
+      rrfK: parseInt(opts.rrfK as string, 10),
+      mode: opts.mode as 'hybrid' | 'semantic' | 'keyword' | undefined,
+      json: opts.json as boolean | undefined,
     });
   },
 };

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

@@ -1,7 +1,8 @@
 import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'sequence <name>',
   description: 'Generate a Mermaid sequence diagram from call graph edges (participants = files)',
   queryOpts: true,
@@ -12,14 +13,14 @@ export const command = {
     ['-k, --kind <kind>', 'Filter by symbol kind'],
   ],
   validate([_name], opts) {
-    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
       return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
     }
   },
   async execute([name], opts, ctx) {
     const { sequence } = await import('../../presentation/sequence.js');
-    sequence(name, opts.db, {
-      depth: parseInt(opts.depth, 10),
+    sequence(name!, opts.db, {
+      depth: parseInt(opts.depth as string, 10),
       file: opts.file,
       kind: opts.kind,
       dataflow: opts.dataflow,

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

@@ -4,8 +4,9 @@ import {
   snapshotRestore,
   snapshotSave,
 } from '../../features/snapshot.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'snapshot',
   description: 'Save and restore graph database snapshots',
   subcommands: [
@@ -17,7 +18,7 @@ export const command = {
         ['--force', 'Overwrite existing snapshot'],
       ],
       execute([name], opts, ctx) {
-        const result = snapshotSave(name, { dbPath: opts.db, force: opts.force });
+        const result = snapshotSave(name!, { dbPath: opts.db, force: opts.force });
         console.log(`Snapshot saved: ${result.name} (${ctx.formatSize(result.size)})`);
       },
     },
@@ -26,7 +27,7 @@ export const command = {
       description: 'Restore a snapshot over the current graph database',
       options: [['-d, --db <path>', 'Path to graph.db']],
       execute([name], opts) {
-        snapshotRestore(name, { dbPath: opts.db });
+        snapshotRestore(name!, { dbPath: opts.db });
         console.log(`Snapshot "${name}" restored.`);
       },
     },
@@ -58,7 +59,7 @@ export const command = {
       description: 'Delete a saved snapshot',
       options: [['-d, --db <path>', 'Path to graph.db']],
       execute([name], opts) {
-        snapshotDelete(name, { dbPath: opts.db });
+        snapshotDelete(name!, { dbPath: opts.db });
         console.log(`Snapshot "${name}" deleted.`);
       },
     },

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

@@ -1,6 +1,7 @@
 import { stats } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'stats',
   description: 'Show graph health overview: nodes, edges, languages, cycles, hotspots, embeddings',
   options: [

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

@@ -1,4 +1,6 @@
-export const command = {
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
   name: 'structure [dir]',
   description:
     'Show project directory structure with hierarchy, cohesion scores, and per-file metrics',
@@ -19,7 +21,7 @@ export const command = {
     const qOpts = ctx.resolveQueryOpts(opts);
     const data = structureData(opts.db, {
       directory: dir,
-      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      depth: opts.depth ? parseInt(opts.depth as string, 10) : undefined,
       sort: opts.sort,
       full: opts.full,
       noTests: qOpts.noTests,

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

@@ -1,33 +1,34 @@
 import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND, VALID_ROLES } from '../../domain/queries.js';
 import { ConfigError } from '../../shared/errors.js';
+import type { CliContext, CommandDefinition, CommandOpts } from '../types.js';
 
-function validateFilters(opts) {
-  if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+function validateFilters(opts: CommandOpts): void {
+  if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
     throw new ConfigError(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
   }
-  if (opts.role && !VALID_ROLES.includes(opts.role)) {
+  if (opts.role && !(VALID_ROLES as readonly string[]).includes(opts.role)) {
     throw new ConfigError(`Invalid role "${opts.role}". Valid: ${VALID_ROLES.join(', ')}`);
   }
 }
 
-function parseWeights(raw) {
+function parseWeights(raw: unknown): Record<string, number> | undefined {
   if (!raw) return undefined;
   try {
-    return JSON.parse(raw);
-  } catch (err) {
-    throw new ConfigError('Invalid --weights JSON', { cause: err });
+    return JSON.parse(raw as string);
+  } catch (err: unknown) {
+    throw new ConfigError('Invalid --weights JSON', { cause: err as Error });
   }
 }
 
-async function runHotspots(opts, ctx) {
+async function runHotspots(opts: CommandOpts, ctx: CliContext): Promise<void> {
   const { hotspotsData, formatHotspots } = await import('../../presentation/structure.js');
   const metric = opts.sort === 'risk' ? 'fan-in' : opts.sort;
   const data = hotspotsData(opts.db, {
     metric,
     level: opts.level,
-    limit: parseInt(opts.limit, 10),
-    offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+    limit: parseInt(opts.limit as string, 10),
+    offset: opts.offset ? parseInt(opts.offset as string, 10) : undefined,
     noTests: ctx.resolveNoTests(opts),
   });
   if (!ctx.outputResult(data, 'hotspots', opts)) {
@@ -35,7 +36,7 @@ async function runHotspots(opts, ctx) {
   }
 }
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'triage',
   description:
     'Ranked audit queue by composite risk score (connectivity + complexity + churn + role)',
@@ -76,8 +77,8 @@ export const command = {
     const weights = parseWeights(opts.weights);
     const { triage } = await import('../../presentation/triage.js');
     triage(opts.db, {
-      limit: parseInt(opts.limit, 10),
-      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      limit: parseInt(opts.limit as string, 10),
+      offset: opts.offset ? parseInt(opts.offset as string, 10) : undefined,
       sort: opts.sort,
       minScore: opts.minScore,
       role: opts.role,

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

@@ -1,12 +1,13 @@
 import path from 'node:path';
 import { watchProject } from '../../domain/graph/watcher.js';
+import type { CommandDefinition } from '../types.js';
 
-export const command = {
+export const command: CommandDefinition = {
   name: 'watch [dir]',
   description: 'Watch project for file changes and incrementally update the graph',
   async execute([dir], _opts, ctx) {
     const root = path.resolve(dir || '.');
-    const engine = ctx.program.opts().engine;
+    const engine = ctx.program.opts()['engine'];
     await watchProject(root, { engine });
   },
 };