@optave/codegraph 3.3.1 → 3.4.0

package/src/graph/{model.js → model.ts}

@@ -5,31 +5,40 @@
  * Node IDs are always strings. DB integer IDs should be stringified before use.
  */
 
-import Graph from 'graphology';
+export interface NodeAttrs {
+  [key: string]: unknown;
+}
+
+export interface EdgeAttrs {
+  [key: string]: unknown;
+}
+
+export interface CodeGraphOpts {
+  directed?: boolean;
+}
 
 export class CodeGraph {
-  /**
-   * @param {{ directed?: boolean }} [opts]
-   */
-  constructor(opts = {}) {
+  private _directed: boolean;
+  private _nodes: Map<string, NodeAttrs>;
+  private _successors: Map<string, Map<string, EdgeAttrs>>;
+  private _predecessors: Map<string, Map<string, EdgeAttrs>>;
+
+  constructor(opts: CodeGraphOpts = {}) {
     this._directed = opts.directed !== false;
-    /** @type {Map<string, object>} */
     this._nodes = new Map();
-    /** @type {Map<string, Map<string, object>>} node → (target → edgeAttrs) */
     this._successors = new Map();
-    /** @type {Map<string, Map<string, object>>} node → (source → edgeAttrs) */
     this._predecessors = new Map();
   }
 
-  get directed() {
+  get directed(): boolean {
     return this._directed;
   }
 
-  get nodeCount() {
+  get nodeCount(): number {
     return this._nodes.size;
   }
 
-  get edgeCount() {
+  get edgeCount(): number {
     let count = 0;
     for (const targets of this._successors.values()) count += targets.size;
     // Undirected graphs store each edge twice (a→b and b→a)
@@ -38,7 +47,7 @@ export class CodeGraph {
 
   // ─── Node operations ────────────────────────────────────────────
 
-  addNode(id, attrs = {}) {
+  addNode(id: string | number, attrs: NodeAttrs = {}): this {
     const key = String(id);
     this._nodes.set(key, attrs);
     if (!this._successors.has(key)) this._successors.set(key, new Map());
@@ -46,65 +55,62 @@ export class CodeGraph {
     return this;
   }
 
-  hasNode(id) {
+  hasNode(id: string | number): boolean {
     return this._nodes.has(String(id));
   }
 
-  getNodeAttrs(id) {
+  getNodeAttrs(id: string | number): NodeAttrs | undefined {
     return this._nodes.get(String(id));
   }
 
-  /** @returns {IterableIterator<[string, object]>} */
-  nodes() {
+  nodes(): IterableIterator<[string, NodeAttrs]> {
     return this._nodes.entries();
   }
 
-  /** @returns {string[]} */
-  nodeIds() {
+  nodeIds(): string[] {
     return [...this._nodes.keys()];
   }
 
   // ─── Edge operations ────────────────────────────────────────────
 
-  addEdge(source, target, attrs = {}) {
+  addEdge(source: string | number, target: string | number, attrs: EdgeAttrs = {}): this {
     const src = String(source);
     const tgt = String(target);
     // Auto-add nodes if missing
     if (!this._nodes.has(src)) this.addNode(src);
     if (!this._nodes.has(tgt)) this.addNode(tgt);
 
-    this._successors.get(src).set(tgt, attrs);
-    this._predecessors.get(tgt).set(src, attrs);
+    this._successors.get(src)!.set(tgt, attrs);
+    this._predecessors.get(tgt)!.set(src, attrs);
 
     if (!this._directed) {
-      this._successors.get(tgt).set(src, attrs);
-      this._predecessors.get(src).set(tgt, attrs);
+      this._successors.get(tgt)!.set(src, attrs);
+      this._predecessors.get(src)!.set(tgt, attrs);
     }
     return this;
   }
 
-  hasEdge(source, target) {
+  hasEdge(source: string | number, target: string | number): boolean {
     const src = String(source);
     const tgt = String(target);
-    return this._successors.has(src) && this._successors.get(src).has(tgt);
+    return this._successors.has(src) && this._successors.get(src)!.has(tgt);
   }
 
-  getEdgeAttrs(source, target) {
+  getEdgeAttrs(source: string | number, target: string | number): EdgeAttrs | undefined {
     const src = String(source);
     const tgt = String(target);
     return this._successors.get(src)?.get(tgt);
   }
 
-  /** @yields {[string, string, object]} source, target, attrs */
-  *edges() {
-    const seen = this._directed ? null : new Set();
+  *edges(): Generator<[string, string, EdgeAttrs]> {
+    const seen = this._directed ? null : new Set<string>();
     for (const [src, targets] of this._successors) {
       for (const [tgt, attrs] of targets) {
         if (!this._directed) {
           // \0 is safe as separator — node IDs are file paths/symbols, never contain null bytes
           const key = src < tgt ? `${src}\0${tgt}` : `${tgt}\0${src}`;
-          if (seen.has(key)) continue;
-          seen.add(key);
+          if (seen!.has(key)) continue;
+          seen!.add(key);
         }
         yield [src, tgt, attrs];
       }
@@ -114,23 +120,23 @@ export class CodeGraph {
   // ─── Adjacency ──────────────────────────────────────────────────
 
   /** Direct successors of a node (outgoing edges). */
-  successors(id) {
+  successors(id: string | number): string[] {
     const key = String(id);
     const map = this._successors.get(key);
     return map ? [...map.keys()] : [];
   }
 
   /** Direct predecessors of a node (incoming edges). */
-  predecessors(id) {
+  predecessors(id: string | number): string[] {
     const key = String(id);
     const map = this._predecessors.get(key);
     return map ? [...map.keys()] : [];
   }
 
   /** All neighbors (union of successors + predecessors). */
-  neighbors(id) {
+  neighbors(id: string | number): string[] {
     const key = String(id);
-    const set = new Set();
+    const set = new Set<string>();
     const succ = this._successors.get(key);
     if (succ) for (const k of succ.keys()) set.add(k);
     const pred = this._predecessors.get(key);
@@ -138,12 +144,12 @@ export class CodeGraph {
     return [...set];
   }
 
-  outDegree(id) {
+  outDegree(id: string | number): number {
     const map = this._successors.get(String(id));
     return map ? map.size : 0;
   }
 
-  inDegree(id) {
+  inDegree(id: string | number): number {
     const map = this._predecessors.get(String(id));
     return map ? map.size : 0;
   }
@@ -151,7 +157,7 @@ export class CodeGraph {
   // ─── Filtering ──────────────────────────────────────────────────
 
   /** Return a new graph containing only nodes matching the predicate. */
-  subgraph(predicate) {
+  subgraph(predicate: (id: string, attrs: NodeAttrs) => boolean): CodeGraph {
     const g = new CodeGraph({ directed: this._directed });
     for (const [id, attrs] of this._nodes) {
       if (predicate(id, attrs)) g.addNode(id, { ...attrs });
@@ -165,7 +171,7 @@ export class CodeGraph {
   }
 
   /** Return a new graph containing only edges matching the predicate. */
-  filterEdges(predicate) {
+  filterEdges(predicate: (source: string, target: string, attrs: EdgeAttrs) => boolean): CodeGraph {
     const g = new CodeGraph({ directed: this._directed });
     for (const [id, attrs] of this._nodes) {
       g.addNode(id, { ...attrs });
@@ -181,32 +187,17 @@ export class CodeGraph {
   // ─── Conversion ─────────────────────────────────────────────────
 
   /** Convert to flat edge array for native Rust interop. */
-  toEdgeArray() {
-    const result = [];
+  toEdgeArray(): { source: string; target: string }[] {
+    const result: { source: string; target: string }[] = [];
     for (const [source, target] of this.edges()) {
       result.push({ source, target });
     }
     return result;
   }
 
-  /** Convert to graphology instance (for Louvain etc). */
-  toGraphology(opts = {}) {
-    const type = opts.type || (this._directed ? 'directed' : 'undirected');
-    const g = new Graph({ type });
-    for (const [id] of this._nodes) {
-      g.addNode(id);
-    }
-
-    for (const [src, tgt] of this.edges()) {
-      if (src === tgt) continue;
-      if (!g.hasEdge(src, tgt)) g.addEdge(src, tgt);
-    }
-    return g;
-  }
-
   // ─── Utilities ──────────────────────────────────────────────────
 
-  clone() {
+  clone(): CodeGraph {
     const g = new CodeGraph({ directed: this._directed });
     for (const [id, attrs] of this._nodes) {
       g.addNode(id, { ...attrs });
@@ -218,7 +209,7 @@ export class CodeGraph {
   }
 
   /** Merge another graph into this one. Nodes/edges from other override on conflict. */
-  merge(other) {
+  merge(other: CodeGraph): this {
     for (const [id, attrs] of other.nodes()) {
       this.addNode(id, attrs);
     }

package/src/index.cjs

@@ -13,4 +13,4 @@
 // Note: if import() rejects (e.g. missing dependency), the rejected Promise is cached
 // by the CJS module system and every subsequent require() call will re-surface the same
 // rejection without re-attempting the load.
-module.exports = import('./index.js');
+module.exports = import('./index.ts');

package/src/infrastructure/{config.js → config.ts}

@@ -1,16 +1,23 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import type { CodegraphConfig } from '../types.js';
 import { debug, warn } from './logger.js';
 
-export const CONFIG_FILES = ['.codegraphrc.json', '.codegraphrc', 'codegraph.config.json'];
+export type { CodegraphConfig } from '../types.js';
+
+export const CONFIG_FILES: readonly string[] = [
+  '.codegraphrc.json',
+  '.codegraphrc',
+  'codegraph.config.json',
+];
 
 export const DEFAULTS = {
-  include: [],
-  exclude: [],
-  ignoreDirs: [],
-  extensions: [],
-  aliases: {},
+  include: [] as string[],
+  exclude: [] as string[],
+  ignoreDirs: [] as string[],
+  extensions: [] as string[],
+  aliases: {} as Record<string, string>,
   build: {
     incremental: true,
     dbPath: '.codegraph/graph.db',
@@ -21,29 +28,35 @@ export const DEFAULTS = {
     defaultLimit: 20,
     excludeTests: false,
   },
-  embeddings: { model: 'nomic-v1.5', llmProvider: null },
-  llm: { provider: null, model: null, baseUrl: null, apiKey: null, apiKeyCommand: null },
+  embeddings: { model: 'nomic-v1.5', llmProvider: null as string | null },
+  llm: {
+    provider: null as string | null,
+    model: null as string | null,
+    baseUrl: null as string | null,
+    apiKey: null as string | null,
+    apiKeyCommand: null as string | null,
+  },
   search: { defaultMinScore: 0.2, rrfK: 60, topK: 15, similarityWarnThreshold: 0.85 },
-  ci: { failOnCycles: false, impactThreshold: null },
+  ci: { failOnCycles: false, impactThreshold: null as number | null },
   manifesto: {
     rules: {
       cognitive: { warn: 15 },
       cyclomatic: { warn: 10 },
       maxNesting: { warn: 4 },
-      maintainabilityIndex: { warn: 20, fail: null },
-      importCount: { warn: null, fail: null },
-      exportCount: { warn: null, fail: null },
-      lineCount: { warn: null, fail: null },
-      fanIn: { warn: null, fail: null },
-      fanOut: { warn: null, fail: null },
-      noCycles: { warn: null, fail: null },
-      boundaries: { warn: null, fail: null },
+      maintainabilityIndex: { warn: 20, fail: null as number | null },
+      importCount: { warn: null as number | null, fail: null as number | null },
+      exportCount: { warn: null as number | null, fail: null as number | null },
+      lineCount: { warn: null as number | null, fail: null as number | null },
+      fanIn: { warn: null as number | null, fail: null as number | null },
+      fanOut: { warn: null as number | null, fail: null as number | null },
+      noCycles: { warn: null as number | null, fail: null as number | null },
+      boundaries: { warn: null as number | null, fail: null as number | null },
     },
-    boundaries: null,
+    boundaries: null as unknown,
   },
   check: {
     cycles: true,
-    blastRadius: null,
+    blastRadius: null as number | null,
     signatures: true,
     boundaries: true,
     depth: 3,
@@ -67,6 +80,9 @@ export const DEFAULTS = {
   },
   community: {
     resolution: 1.0,
+    maxLevels: 50,
+    maxLocalPasses: 20,
+    refinementTheta: 1.0,
   },
   structure: {
     cohesionThreshold: 0.3,
@@ -91,7 +107,7 @@ export const DEFAULTS = {
       'dead-entry': 0.3,
       'dead-ffi': 0.05,
       'dead-unresolved': 0.15,
-    },
+    } as Record<string, number>,
     defaultRoleWeight: 0.5,
   },
   display: {
@@ -126,19 +142,21 @@ export const DEFAULTS = {
       structure: 30,
       triage: 20,
       ast_query: 50,
+      implementations: 50,
+      interfaces: 50,
     },
   },
-};
+} satisfies CodegraphConfig;
 
 // Per-cwd config cache — avoids re-reading the config file on every query call.
 // The config file rarely changes within a single process lifetime.
-const _configCache = new Map();
+const _configCache = new Map<string, CodegraphConfig>();
 
 /**
  * Load project configuration from a .codegraphrc.json or similar file.
  * Returns merged config with defaults. Results are cached per cwd.
  */
-export function loadConfig(cwd) {
+export function loadConfig(cwd?: string): CodegraphConfig {
   cwd = cwd || process.cwd();
   const cached = _configCache.get(cwd);
   if (cached) return structuredClone(cached);
@@ -150,16 +168,18 @@ export function loadConfig(cwd) {
         const raw = fs.readFileSync(filePath, 'utf-8');
         const config = JSON.parse(raw);
         debug(`Loaded config from ${filePath}`);
-        const merged = mergeConfig(DEFAULTS, config);
+        const merged = mergeConfig(DEFAULTS as unknown as Record<string, unknown>, config);
         if ('excludeTests' in config && !(config.query && 'excludeTests' in config.query)) {
-          merged.query.excludeTests = Boolean(config.excludeTests);
+          (merged['query'] as Record<string, unknown>)['excludeTests'] = Boolean(
+            config.excludeTests,
+          );
         }
-        delete merged.excludeTests;
-        const result = resolveSecrets(applyEnvOverrides(merged));
+        delete merged['excludeTests'];
+        const result = resolveSecrets(applyEnvOverrides(merged as unknown as CodegraphConfig));
         _configCache.set(cwd, structuredClone(result));
         return result;
-      } catch (err) {
-        debug(`Failed to parse config ${filePath}: ${err.message}`);
+      } catch (err: unknown) {
+        debug(`Failed to parse config ${filePath}: ${(err as Error).message}`);
       }
     }
   }
@@ -173,43 +193,44 @@ export function loadConfig(cwd) {
  * pick up on-disk config changes, and for test isolation when tests share
  * the same cwd.
  */
-export function clearConfigCache() {
+export function clearConfigCache(): void {
   _configCache.clear();
 }
 
-const ENV_LLM_MAP = {
+const ENV_LLM_MAP: Record<string, string> = {
   CODEGRAPH_LLM_PROVIDER: 'provider',
   CODEGRAPH_LLM_API_KEY: 'apiKey',
   CODEGRAPH_LLM_MODEL: 'model',
 };
 
-export function applyEnvOverrides(config) {
+export function applyEnvOverrides(config: CodegraphConfig): CodegraphConfig {
   for (const [envKey, field] of Object.entries(ENV_LLM_MAP)) {
-    if (process.env[envKey] !== undefined) {
-      config.llm[field] = process.env[envKey];
+    if (process.env[envKey as keyof NodeJS.ProcessEnv] !== undefined) {
+      (config.llm as Record<string, unknown>)[field] =
+        process.env[envKey as keyof NodeJS.ProcessEnv];
     }
   }
   return config;
 }
 
-export function resolveSecrets(config) {
+export function resolveSecrets(config: CodegraphConfig): CodegraphConfig {
   const cmd = config.llm.apiKeyCommand;
   if (typeof cmd !== 'string' || cmd.trim() === '') return config;
 
   const parts = cmd.trim().split(/\s+/);
   const [executable, ...args] = parts;
   try {
-    const result = execFileSync(executable, args, {
+    const result = execFileSync(executable!, args, {
       encoding: 'utf-8',
       timeout: 10_000,
       maxBuffer: 64 * 1024,
       stdio: ['ignore', 'pipe', 'pipe'],
     }).trim();
     if (result) {
-      config.llm.apiKey = result;
+      (config.llm as Record<string, unknown>)['apiKey'] = result;
     }
-  } catch (err) {
-    warn(`apiKeyCommand failed: ${err.message}`);
+  } catch (err: unknown) {
+    warn(`apiKeyCommand failed: ${(err as Error).message}`);
   }
   return config;
 }
@@ -221,7 +242,7 @@ export function resolveSecrets(config) {
  * Supports trailing `/*` or `/**` patterns (e.g. "packages/*").
  * Does not depend on an external glob library — uses fs.readdirSync.
  */
-function expandWorkspaceGlob(pattern, rootDir) {
+function expandWorkspaceGlob(pattern: string, rootDir: string): string[] {
   // Strip trailing /*, /**, or just *
   const clean = pattern.replace(/\/?\*\*?$/, '');
   const baseDir = path.resolve(rootDir, clean);
@@ -240,7 +261,7 @@ function expandWorkspaceGlob(pattern, rootDir) {
 /**
  * Read a package.json and return its name field, or null.
  */
-function readPackageName(pkgDir) {
+function readPackageName(pkgDir: string): string | null {
   try {
     const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
     const pkg = JSON.parse(raw);
@@ -250,11 +271,16 @@ function readPackageName(pkgDir) {
   }
 }
 
+interface WorkspaceEntry {
+  dir: string;
+  entry: string | null;
+}
+
 /**
  * Resolve the entry-point source file for a workspace package.
  * Checks exports → main → index file fallback.
  */
-function resolveWorkspaceEntry(pkgDir) {
+function resolveWorkspaceEntry(pkgDir: string): string | null {
   try {
     const raw = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
     const pkg = JSON.parse(raw);
@@ -297,14 +323,10 @@ function resolveWorkspaceEntry(pkgDir) {
  *   1. pnpm-workspace.yaml — `packages:` array
  *   2. package.json — `workspaces` field (npm/yarn)
  *   3. lerna.json — `packages` array
- *
- * @param {string} rootDir - Project root directory
- * @returns {Map<string, { dir: string, entry: string|null }>}
- *   Map of package name → { absolute dir, resolved entry file }
  */
-export function detectWorkspaces(rootDir) {
-  const workspaces = new Map();
-  const patterns = [];
+export function detectWorkspaces(rootDir: string): Map<string, WorkspaceEntry> {
+  const workspaces = new Map<string, WorkspaceEntry>();
+  const patterns: string[] = [];
 
   // 1. pnpm-workspace.yaml
   const pnpmPath = path.join(rootDir, 'pnpm-workspace.yaml');
@@ -314,11 +336,11 @@ export function detectWorkspaces(rootDir) {
       // Simple YAML parse for `packages:` array — no dependency needed
       const packagesMatch = raw.match(/^packages:\s*\n((?:\s+-\s+.+\n?)*)/m);
       if (packagesMatch) {
-        const lines = packagesMatch[1].match(/^\s+-\s+['"]?([^'"#\n]+)['"]?\s*$/gm);
+        const lines = packagesMatch[1]!.match(/^\s+-\s+['"]?([^'"#\n]+)['"]?\s*$/gm);
         if (lines) {
           for (const line of lines) {
             const m = line.match(/^\s+-\s+['"]?([^'"#\n]+?)['"]?\s*$/);
-            if (m) patterns.push(m[1].trim());
+            if (m) patterns.push(m[1]!.trim());
           }
         }
       }
@@ -390,8 +412,11 @@ export function detectWorkspaces(rootDir) {
   return workspaces;
 }
 
-export function mergeConfig(defaults, overrides) {
-  const result = { ...defaults };
+export function mergeConfig(
+  defaults: Record<string, unknown>,
+  overrides: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...defaults };
   for (const [key, value] of Object.entries(overrides)) {
     if (
       value &&
@@ -401,7 +426,10 @@ export function mergeConfig(defaults, overrides) {
       typeof defaults[key] === 'object' &&
       !Array.isArray(defaults[key])
     ) {
-      result[key] = mergeConfig(defaults[key], value);
+      result[key] = mergeConfig(
+        defaults[key] as Record<string, unknown>,
+        value as Record<string, unknown>,
+      );
     } else {
       result[key] = value;
     }

package/src/infrastructure/{logger.js → logger.ts}

@@ -1,24 +1,24 @@
 let verbose = false;
 
-export function setVerbose(v) {
+export function setVerbose(v: boolean): void {
   verbose = v;
 }
-export function isVerbose() {
+export function isVerbose(): boolean {
   return verbose;
 }
 
-export function warn(msg) {
+export function warn(msg: string): void {
   process.stderr.write(`[codegraph WARN] ${msg}\n`);
 }
 
-export function debug(msg) {
+export function debug(msg: string): void {
   if (verbose) process.stderr.write(`[codegraph DEBUG] ${msg}\n`);
 }
 
-export function info(msg) {
+export function info(msg: string): void {
   process.stderr.write(`[codegraph] ${msg}\n`);
 }
 
-export function error(msg) {
+export function error(msg: string): void {
   process.stderr.write(`[codegraph ERROR] ${msg}\n`);
 }

package/src/infrastructure/{native.js → native.ts}

@@ -9,20 +9,21 @@
 import { createRequire } from 'node:module';
 import os from 'node:os';
 import { EngineError } from '../shared/errors.js';
+import type { NativeAddon } from '../types.js';
 
-let _cached; // undefined = not yet tried, null = failed, object = module
-let _loadError = null;
+let _cached: NativeAddon | null | undefined; // undefined = not yet tried, null = failed, NativeAddon = module
+let _loadError: Error | null = null;
 const _require = createRequire(import.meta.url);
 
 /**
  * Detect whether the current Linux environment uses glibc or musl.
  * Returns 'gnu' for glibc, 'musl' for musl, 'gnu' as fallback.
  */
-function detectLibc() {
+function detectLibc(): 'gnu' | 'musl' {
   try {
-    const { readdirSync } = _require('node:fs');
+    const { readdirSync } = _require('node:fs') as typeof import('node:fs');
     const files = readdirSync('/lib');
-    if (files.some((f) => f.startsWith('ld-musl-') && f.endsWith('.so.1'))) {
+    if (files.some((f: string) => f.startsWith('ld-musl-') && f.endsWith('.so.1'))) {
       return 'musl';
     }
   } catch {}
@@ -30,7 +31,7 @@ function detectLibc() {
 }
 
 /** Map of (platform-arch[-libc]) → npm package name. */
-const PLATFORM_PACKAGES = {
+const PLATFORM_PACKAGES: Record<string, string> = {
   'linux-x64-gnu': '@optave/codegraph-linux-x64-gnu',
   'linux-x64-musl': '@optave/codegraph-linux-x64-musl',
   'linux-arm64-gnu': '@optave/codegraph-linux-arm64-gnu',
@@ -44,7 +45,7 @@ const PLATFORM_PACKAGES = {
  * Resolve the platform-specific npm package name for the native addon.
  * Returns null if the current platform is not supported.
  */
-function resolvePlatformPackage() {
+function resolvePlatformPackage(): string | null {
   const platform = os.platform();
   const arch = os.arch();
   const key = platform === 'linux' ? `${platform}-${arch}-${detectLibc()}` : `${platform}-${arch}`;
@@ -55,16 +56,16 @@ function resolvePlatformPackage() {
  * Try to load the native napi addon.
  * Returns the module on success, null on failure.
  */
-export function loadNative() {
+export function loadNative(): NativeAddon | null {
   if (_cached !== undefined) return _cached;
 
   const pkg = resolvePlatformPackage();
   if (pkg) {
     try {
-      _cached = _require(pkg);
+      _cached = _require(pkg) as NativeAddon;
       return _cached;
     } catch (err) {
-      _loadError = err;
+      _loadError = err as Error;
     }
   } else {
     _loadError = new Error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
@@ -77,7 +78,7 @@ export function loadNative() {
 /**
  * Check whether the native engine is available on this platform.
  */
-export function isNativeAvailable() {
+export function isNativeAvailable(): boolean {
   return loadNative() !== null;
 }
 
@@ -85,11 +86,11 @@ export function isNativeAvailable() {
  * Read the version from the platform-specific npm package.json.
  * Returns null if the package is not installed or has no version.
  */
-export function getNativePackageVersion() {
+export function getNativePackageVersion(): string | null {
   const pkg = resolvePlatformPackage();
   if (!pkg) return null;
   try {
-    const pkgJson = _require(`${pkg}/package.json`);
+    const pkgJson = _require(`${pkg}/package.json`) as { version?: string };
     return pkgJson.version || null;
   } catch {
     return null;
@@ -99,13 +100,13 @@ export function getNativePackageVersion() {
 /**
  * Return the native module or throw if not available.
  */
-export function getNative() {
+export function getNative(): NativeAddon {
   const mod = loadNative();
   if (!mod) {
     throw new EngineError(
       `Native codegraph-core not available: ${_loadError?.message || 'unknown error'}. ` +
         'Install the platform package or use --engine wasm.',
-      { cause: _loadError },
+      { cause: _loadError ?? undefined },
     );
   }
   return mod;