@optave/codegraph 3.11.2 → 3.13.0

package/src/infrastructure/native.ts

@@ -6,11 +6,13 @@
  * to the existing WASM pipeline.
  */
 
+import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { EngineError, toErrorMessage } from '../shared/errors.js';
 import type { NativeAddon } from '../types.js';
-import { debug } from './logger.js';
+import { debug, warn } from './logger.js';
 
 let _cached: NativeAddon | null | undefined; // undefined = not yet tried, null = failed, NativeAddon = module
 let _loadError: Error | null = null;
@@ -44,31 +46,107 @@ const PLATFORM_PACKAGES: Record<string, string> = {
   'win32-x64': '@optave/codegraph-win32-x64-msvc',
 };
 
+/**
+ * Map of (platform-arch[-libc]) → locally compiled binary filename.
+ * Checked before the npm package so that locally compiled Rust changes
+ * are picked up immediately in development without publishing a new release.
+ */
+const PLATFORM_LOCAL_BINARIES: Record<string, string> = {
+  'linux-x64-gnu': 'codegraph-core.linux-x64-gnu.node',
+  'linux-x64-musl': 'codegraph-core.linux-x64-musl.node',
+  'linux-arm64-gnu': 'codegraph-core.linux-arm64-gnu.node',
+  'linux-arm64-musl': 'codegraph-core.linux-arm64-musl.node',
+  'darwin-arm64': 'codegraph-core.darwin-arm64.node',
+  'darwin-x64': 'codegraph-core.darwin-x64.node',
+  'win32-x64': 'codegraph-core.win32-x64-msvc.node',
+};
+
+/** Compute the platform key used to index PLATFORM_PACKAGES / PLATFORM_LOCAL_BINARIES. */
+function resolvePlatformKey(): string {
+  const platform = os.platform();
+  const arch = os.arch();
+  return platform === 'linux' ? `${platform}-${arch}-${detectLibc()}` : `${platform}-${arch}`;
+}
+
 /**
  * Resolve the platform-specific npm package name for the native addon.
  * Returns null if the current platform is not supported.
  */
 function resolvePlatformPackage(): string | null {
-  const platform = os.platform();
-  const arch = os.arch();
-  const key = platform === 'linux' ? `${platform}-${arch}-${detectLibc()}` : `${platform}-${arch}`;
-  return PLATFORM_PACKAGES[key] || null;
+  return PLATFORM_PACKAGES[resolvePlatformKey()] ?? null;
 }
 
 /**
  * Try to load the native napi addon.
  * Returns the module on success, null on failure.
+ *
+ * Load order:
+ *   1. NAPI_RS_NATIVE_LIBRARY_PATH env var (explicit override)
+ *   2. locally compiled binary in crates/codegraph-core/ (dev mode — preferred
+ *      over the npm package so that Rust changes are picked up immediately
+ *      without publishing a new release)
+ *   3. npm platform package (production path)
  */
 export function loadNative(): NativeAddon | null {
   if (_cached !== undefined) return _cached;
 
+  const platformKey = resolvePlatformKey();
+
+  // 1. Explicit path override — highest priority. Failure is fatal: if the
+  //    operator set this variable, silently loading a different binary would
+  //    be harder to diagnose than an explicit error.
+  const envPath = process.env.NAPI_RS_NATIVE_LIBRARY_PATH;
+  if (envPath) {
+    try {
+      _cached = _require(envPath) as NativeAddon;
+      debug(`loadNative: loaded from NAPI_RS_NATIVE_LIBRARY_PATH: ${envPath}`);
+      return _cached;
+    } catch (err) {
+      _loadError = err as Error;
+      warn(
+        `loadNative: NAPI_RS_NATIVE_LIBRARY_PATH is set but failed to load "${envPath}": ${toErrorMessage(err as Error)}`,
+      );
+      _cached = null;
+      return null;
+    }
+  }
+
+  // 2. Locally compiled dev binary — preferred over npm package so that Rust
+  //    changes are visible without publishing. Only used when the file exists.
+  //    If the file exists but fails to load (e.g. stale ABI), we warn and halt
+  //    rather than silently falling through to the npm package — that would
+  //    defeat the purpose of this priority order.
+  const localFile = PLATFORM_LOCAL_BINARIES[platformKey];
+  if (localFile) {
+    const localPath = fileURLToPath(
+      new URL(`../../crates/codegraph-core/${localFile}`, import.meta.url),
+    );
+    if (existsSync(localPath)) {
+      try {
+        _cached = _require(localPath) as NativeAddon;
+        debug(`loadNative: loaded local dev binary: ${localPath}`);
+        return _cached;
+      } catch (err) {
+        _loadError = err as Error;
+        warn(
+          `loadNative: local dev binary exists but failed to load "${localPath}": ${toErrorMessage(err as Error)}`,
+        );
+        _cached = null;
+        return null;
+      }
+    }
+  }
+
+  // 3. Published npm platform package — production path.
   const pkg = resolvePlatformPackage();
   if (pkg) {
     try {
       _cached = _require(pkg) as NativeAddon;
+      debug(`loadNative: loaded npm package: ${pkg}`);
       return _cached;
     } catch (err) {
       _loadError = err as Error;
+      debug(`loadNative: npm package ${pkg} not available: ${toErrorMessage(err as Error)}`);
     }
   } else {
     _loadError = new Error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
@@ -88,6 +166,10 @@ export function isNativeAvailable(): boolean {
 /**
  * Read the version from the platform-specific npm package.json.
  * Returns null if the package is not installed or has no version.
+ *
+ * Note: always reports the npm package version. When the local dev binary or
+ * NAPI_RS_NATIVE_LIBRARY_PATH is loaded instead, this version may not match
+ * the running binary.
  */
 export function getNativePackageVersion(): string | null {
   const pkg = resolvePlatformPackage();

package/src/infrastructure/registry.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import type { ConsentDecision } from '../types.js';
 import { debug, warn } from './logger.js';
 
 export const REGISTRY_PATH: string =
@@ -16,8 +17,15 @@ interface RegistryEntry {
   lastAccessedAt?: string;
 }
 
+interface UserConfigSection {
+  /** Per-repo consent decisions keyed by absolute repo path. */
+  consent: Record<string, ConsentDecision>;
+}
+
 interface Registry {
   repos: Record<string, RegistryEntry>;
+  /** User-level global config consent store — separate from MCP repo listings. */
+  userConfig?: UserConfigSection;
 }
 
 /**
@@ -160,6 +168,67 @@ export function resolveRepoDbPath(
   return entry.dbPath;
 }
 
+// ── User-config consent ────────────────────────────────────────────────
+
+/**
+ * Read the per-repo consent decision for the global user config.
+ * Returns `undefined` when the repo is undecided (no recorded decision).
+ */
+export function getUserConfigConsent(
+  rootDir: string,
+  registryPath: string = REGISTRY_PATH,
+): ConsentDecision | undefined {
+  const registry = loadRegistry(registryPath);
+  const absRoot = path.resolve(rootDir);
+  return registry.userConfig?.consent?.[absRoot];
+}
+
+/**
+ * Persist a per-repo consent decision. Atomic write via temp+rename.
+ */
+export function setUserConfigConsent(
+  rootDir: string,
+  decision: ConsentDecision,
+  registryPath: string = REGISTRY_PATH,
+): void {
+  const registry = loadRegistry(registryPath);
+  const absRoot = path.resolve(rootDir);
+  if (!registry.userConfig) registry.userConfig = { consent: {} };
+  if (!registry.userConfig.consent) registry.userConfig.consent = {};
+  registry.userConfig.consent[absRoot] = decision;
+  saveRegistry(registry, registryPath);
+  debug(`User-config consent for "${absRoot}" set to "${decision}"`);
+}
+
+/**
+ * List every repo with a recorded consent decision, sorted by path.
+ */
+export function listUserConfigConsent(
+  registryPath: string = REGISTRY_PATH,
+): Array<{ path: string; decision: ConsentDecision }> {
+  const registry = loadRegistry(registryPath);
+  const consent = registry.userConfig?.consent ?? {};
+  return Object.entries(consent)
+    .map(([p, decision]) => ({ path: p, decision }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Revert a repo to undecided state. Returns true if a decision was removed.
+ */
+export function clearUserConfigConsent(
+  rootDir: string,
+  registryPath: string = REGISTRY_PATH,
+): boolean {
+  const registry = loadRegistry(registryPath);
+  const absRoot = path.resolve(rootDir);
+  const consent = registry.userConfig?.consent;
+  if (!consent || !(absRoot in consent)) return false;
+  delete consent[absRoot];
+  saveRegistry(registry, registryPath);
+  return true;
+}
+
 interface PrunedEntry {
   name: string;
   path: string;
@@ -200,7 +269,19 @@ export function pruneRegistry(
     }
   }
 
-  if (!dryRun && pruned.length > 0) {
+  // Prune consent entries whose repo paths no longer exist on disk.
+  // Consent entries are TTL-exempt — only the missing-path rule applies.
+  let consentChanged = false;
+  if (!dryRun && registry.userConfig?.consent) {
+    for (const p of Object.keys(registry.userConfig.consent)) {
+      if (!fs.existsSync(p)) {
+        delete registry.userConfig.consent[p];
+        consentChanged = true;
+      }
+    }
+  }
+
+  if (!dryRun && (pruned.length > 0 || consentChanged)) {
     saveRegistry(registry, registryPath);
   }
 

package/src/presentation/queries-cli/overview.ts

@@ -54,7 +54,13 @@ interface EmbeddingsInfo {
 
 interface QualityInfo {
   score: number;
-  callerCoverage: { ratio: number; covered: number; total: number };
+  callerCoverage: {
+    ratio: number;
+    percentage: number;
+    covered: number;
+    total: number;
+    byTechnique?: Record<string, number>;
+  };
   callConfidence: { ratio: number; highConf: number; total: number };
   falsePositiveWarnings: { name: string; callerCount: number; file: string; line: number }[];
 }
@@ -189,6 +195,14 @@ function printQuality(data: StatsData): void {
     console.log(
       `  Caller coverage:  ${(cc.ratio * 100).toFixed(1)}% (${cc.covered}/${cc.total} functions have >=1 caller)`,
     );
+    if (cc.byTechnique && Object.keys(cc.byTechnique).length > 0) {
+      const entries = Object.entries(cc.byTechnique).sort((a, b) => b[1] - a[1]) as [
+        string,
+        number,
+      ][];
+      const parts = entries.map(([k, v]) => `${k} ${v}`).join('  ');
+      console.log(`    by technique:  ${parts}`);
+    }
     console.log(
       `  Call confidence:  ${(cf.ratio * 100).toFixed(1)}% (${cf.highConf}/${cf.total} call edges are high-confidence)`,
     );

package/src/presentation/structure.ts

@@ -53,15 +53,15 @@ interface HotspotsResult {
   metric: string;
   level: string;
   limit: number;
-  hotspots: any[];
+  items: any[];
 }
 
 export function formatHotspots(data: HotspotsResult): string {
-  if (data.hotspots.length === 0) return 'No hotspots found. Run "codegraph build" first.';
+  if (data.items.length === 0) return 'No hotspots found. Run "codegraph build" first.';
 
   const lines = [`\nHotspots by ${data.metric} (${data.level}-level, top ${data.limit}):\n`];
   let rank = 1;
-  for (const h of data.hotspots) {
+  for (const h of data.items) {
     const extra =
       h.kind === 'directory'
         ? `${h.fileCount} files, cohesion=${h.cohesion !== null ? h.cohesion!.toFixed(2) : 'n/a'}`

package/src/types.ts

@@ -523,6 +523,125 @@ export interface TypeMapEntry {
   confidence: number;
 }
 
+/**
+ * A variable assignment from a call expression, recorded during extraction for
+ * cross-file return-type propagation (Phase 8.2).
+ */
+export interface CallAssignment {
+  /** Variable being assigned to. */
+  varName: string;
+  /** Name of the function or method being called. */
+  calleeName: string;
+  /** Resolved receiver type, if the call is a method call (e.g. service.getRepo()). */
+  receiverTypeName?: string;
+}
+
+/**
+ * A function-reference binding recorded during extraction for points-to analysis (Phase 8.3).
+ * Captures `const fn = handler` or `const fn = obj.method` patterns where the right-hand
+ * side is a named function reference (not a call expression or literal).
+ */
+export interface FnRefBinding {
+  /** Variable being assigned (the left-hand side identifier). */
+  lhs: string;
+  /** Named function/property on the right-hand side. */
+  rhs: string;
+  /** If rhs is a member expression (obj.method), the receiver object name. */
+  rhsReceiver?: string;
+}
+
+/**
+ * An argument-to-parameter binding at a call site, recorded for parameter-flow
+ * points-to analysis (Phase 8.3c). Captures `f(x)` where `x` is an identifier
+ * that may carry a function reference into `f`'s parameter.
+ */
+export interface ParamBinding {
+  /** The function being called at the call site. */
+  callee: string;
+  /** Zero-based index of the argument. */
+  argIndex: number;
+  /** Identifier name of the argument being passed. */
+  argName: string;
+}
+
+/**
+ * A this-context binding recorded when `fn.call(namedCtx, ...)` or
+ * `fn.apply(namedCtx, ...)` is seen. Seeds `fn::this → namedCtx` in the
+ * points-to map so that `this()` calls inside `fn` resolve to `namedCtx`.
+ */
+export interface ThisCallBinding {
+  /** The function being invoked via .call() or .apply(). */
+  callee: string;
+  /** The identifier passed as the `this` context (first argument). */
+  thisArg: string;
+}
+
+/**
+ * An array-element binding: `const arr = [fn1, fn2]` records each named function
+ * stored at a specific index. Phase 8.3e: array-element pts tracking.
+ */
+export interface ArrayElemBinding {
+  arrayName: string;
+  index: number;
+  elemName: string;
+}
+
+/**
+ * A spread-argument binding: `f(...arr)` records that `arr` is spread into `f`'s
+ * parameter list starting at `startIndex`. Phase 8.3e.
+ */
+export interface SpreadArgBinding {
+  callee: string;
+  arrayName: string;
+  startIndex: number;
+}
+
+/**
+ * A for-of iteration binding: `for (const x of arr)` records that `x` receives
+ * each element of `arr` within `enclosingFunc`. Phase 8.3e.
+ */
+export interface ForOfBinding {
+  varName: string;
+  sourceName: string;
+  enclosingFunc: string;
+}
+
+/**
+ * An array-callback binding: `Array.from(arr, cb)` records that `cb`'s first
+ * parameter receives each element of `arr`. Phase 8.3e.
+ */
+export interface ArrayCallbackBinding {
+  sourceName: string;
+  calleeName: string;
+}
+
+/**
+ * An object-rest parameter binding: `function f({ a, ...rest })` records that
+ * `rest` is the rest of the object passed as argument `argIndex` to `f`.
+ * Phase 8.3f: object destructuring rest dispatch.
+ */
+export interface ObjectRestParamBinding {
+  /** Function that owns this rest parameter, e.g. "f3" */
+  callee: string;
+  /** Name of the rest binding, e.g. "eerest" */
+  restName: string;
+  /** Zero-based index of the argument whose rest is bound, e.g. 0 */
+  argIndex: number;
+}
+
+/**
+ * An object-property binding: `const obj = { e4 }` or `const obj = { e4: fn }` records
+ * that `obj.e4` points to the named function `fn`. Phase 8.3f.
+ */
+export interface ObjectPropBinding {
+  /** Variable holding the object, e.g. "obj" */
+  objectName: string;
+  /** Property name, e.g. "e4" */
+  propName: string;
+  /** Named function value, e.g. "e4" or "fn" */
+  valueName: string;
+}
+
 /** The normalized output shape returned by every language extractor. */
 export interface ExtractorOutput {
   definitions: Definition[];
@@ -531,6 +650,63 @@ export interface ExtractorOutput {
   classes: ClassRelation[];
   exports: Export[];
   typeMap: Map<string, TypeMapEntry>;
+  /**
+   * Maps function/method names to their declared or inferred return types.
+   * Keys: plain name (e.g. "createUser") or qualified name (e.g. "UserService.getUser").
+   * Populated by JS/TS extractor; used for inter-procedural type propagation (Phase 8.2).
+   */
+  returnTypeMap?: Map<string, TypeMapEntry>;
+  /**
+   * Variable assignments from call expressions that could not be resolved from the
+   * per-file returnTypeMap. Consumed by build-edges.ts to propagate cross-file return types.
+   */
+  callAssignments?: CallAssignment[];
+  /**
+   * Function-reference bindings for points-to analysis (Phase 8.3).
+   * Records `const fn = handler` and `const fn = obj.method` patterns so the
+   * edge builder can follow aliases when a call target has no direct definition.
+   */
+  fnRefBindings?: FnRefBinding[];
+  /**
+   * Argument-to-parameter bindings for parameter-flow points-to analysis (Phase 8.3c).
+   * Records `f(x)` call sites where `x` is an identifier, enabling the pts solver
+   * to propagate function references through function parameters.
+   */
+  paramBindings?: ParamBinding[];
+  /** Phase 8.3e: array-element bindings from `const arr = [fn1, fn2]` patterns. */
+  arrayElemBindings?: ArrayElemBinding[];
+  /** Phase 8.3e: spread-argument bindings from `f(...arr)` call sites. */
+  spreadArgBindings?: SpreadArgBinding[];
+  /** Phase 8.3e: for-of iteration variable bindings. */
+  forOfBindings?: ForOfBinding[];
+  /** Phase 8.3e: array callback bindings from Array.from/forEach/etc. */
+  arrayCallbackBindings?: ArrayCallbackBinding[];
+  /** Phase 8.3f: object-rest parameter bindings from `function f({ ...rest })` patterns. */
+  objectRestParamBindings?: ObjectRestParamBinding[];
+  /** Phase 8.3f: object-property bindings from `const obj = { fn }` patterns. */
+  objectPropBindings?: ObjectPropBinding[];
+  /**
+   * This-context bindings from `fn.call(namedCtx, ...)` / `fn.apply(namedCtx, ...)`.
+   * Seeds `fn::this → namedCtx` in the points-to map so that `this()` calls inside
+   * `fn` resolve to `namedCtx` when `fn` is invoked via `.call()`/`.apply()`.
+   */
+  thisCallBindings?: ThisCallBinding[];
+  /**
+   * Phase 8.5 (RTA): constructor names from all `new X()` expressions in the file,
+   * including unassigned ones (e.g. `doSomething(new Foo())`). Used to build the
+   * project-wide instantiated-types set for Rapid Type Analysis filtering.
+   */
+  newExpressions?: readonly string[];
+  /**
+   * Object.defineProperty receiver bindings: maps function name → target object name.
+   * Records `Object.defineProperty(obj, "bar", { get: getter })` so the edge builder
+   * can resolve `this.X()` calls inside `getter` as `obj.X()` (this === obj when the
+   * accessor is invoked through the property).
+   *
+   * Example: `Object.defineProperty(obj, "bar", { get: getter })` emits
+   * `definePropertyReceivers.set("getter", "obj")`.
+   */
+  definePropertyReceivers?: Map<string, string>;
   /** WASM tree retained for downstream analysis (complexity, CFG, dataflow). */
   _tree?: TreeSitterTree;
   /** Language identifier. */
@@ -1078,6 +1254,20 @@ export interface BuildGraphOpts {
    * `findDbPath` for every other DB-scoped command.
    */
   dbPath?: string;
+  /**
+   * User-config override for this build (from --user-config / --no-user-config).
+   * - false          → --no-user-config: skip global layer for this run
+   * - string         → --user-config <path>: apply the given file
+   * - true           → --user-config (bare): apply the default global file
+   * - undefined      → honour per-repo consent from the registry (normal)
+   */
+  userConfig?: string | boolean;
+  /**
+   * When true, an interactive consent prompt may fire on first build for
+   * repos whose global-config consent is undecided. Only set by the CLI
+   * build command when stdin/stdout are TTYs and CI is not set.
+   */
+  promptForConsent?: boolean;
 }
 
 /** Build timing result from buildGraph. */
@@ -1092,6 +1282,16 @@ export interface BuildResult {
     edgesMs: number;
     structureMs: number;
     rolesMs: number;
+    /** Wall-clock time for the CHA expansion post-pass (native path only). */
+    chaMs?: number;
+    /** Wall-clock time for the this/super dispatch WASM post-pass (native path only). */
+    thisDispatchMs?: number;
+    /** Wall-clock time for the dropped-language gap detection + backfill (native path only). */
+    gapDetectMs?: number;
+    /** Wall-clock time for role re-classification after JS edge-writing post-passes (native path only). */
+    reclassifyMs?: number;
+    /** Wall-clock time for the technique-column backfill on native-written edges (native path only). */
+    techniqueBackfillMs?: number;
     astMs: number;
     complexityMs: number;
     cfgMs: number;
@@ -1119,6 +1319,14 @@ export interface CodegraphConfig {
     dbPath: string;
     driftThreshold: number;
     smallFilesThreshold: number;
+    /**
+     * Use the TypeScript compiler API to enrich typeMap for .ts/.tsx files.
+     * Improves method-call edge accuracy for patterns like `const svc = container.get<MyService>()`.
+     * Disabled by default because `ts.createProgram` adds ~1s overhead per build;
+     * enable in `.codegraphrc.json` when you need accurate type-resolved call edges.
+     * Default: false.
+     */
+    typescriptResolver: boolean;
   };
 
   query: {
@@ -1189,6 +1397,14 @@ export interface CodegraphConfig {
     briefImporterDepth: number;
     briefHighRiskCallers: number;
     briefMediumRiskCallers: number;
+    /** Maximum chain depth for inter-procedural return-type propagation (Phase 8.2). */
+    typePropagationDepth: number;
+    /**
+     * Maximum fixed-point iterations for the Phase 8.3 points-to solver.
+     * @reserved — currently not wired to either solver; both use a hardcoded
+     * constant of 50.  See TODO in `src/infrastructure/config.ts`.
+     */
+    pointsToMaxIterations: number;
   };
 
   community: {
@@ -1275,6 +1491,25 @@ export interface McpDefaults {
   interfaces: number;
 }
 
+/** Per-repo consent decision for the user-level global config. */
+export type ConsentDecision = 'enabled' | 'disabled';
+
+/** Which layer contributed a resolved config value. */
+export type ConfigSource = 'default' | 'user' | 'project' | 'env';
+
+/** Maps config key paths (dot notation) to the layer that supplied the value. */
+export type ConfigProvenance = Record<string, ConfigSource>;
+
+/** Result of loadConfigWithProvenance. */
+export interface ConfigWithProvenance {
+  config: CodegraphConfig;
+  provenance: ConfigProvenance;
+  /** Absolute path of the applied global file, or null if none was applied. */
+  appliedGlobalPath: string | null;
+  /** This repo's recorded consent decision (may be undefined if undecided). */
+  consentDecision: ConsentDecision | undefined;
+}
+
 // ════════════════════════════════════════════════════════════════════════
 // §12  Pagination
 // ════════════════════════════════════════════════════════════════════════