@optave/codegraph 3.12.0 → 3.13.0

package/src/cli/commands/config.ts

@@ -0,0 +1,353 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  clearConfigCache,
+  DEFAULTS,
+  getDefaultUserConfigPath,
+  loadConfig,
+  loadConfigWithProvenance,
+  resolveUserConfigPath,
+} from '../../infrastructure/config.js';
+import {
+  getUserConfigConsent,
+  listUserConfigConsent,
+  REGISTRY_PATH,
+  setUserConfigConsent,
+} from '../../infrastructure/registry.js';
+import { formatTable } from '../../presentation/table.js';
+import type { ConfigSource } from '../../types.js';
+import type { CommandDefinition } from '../types.js';
+
+/**
+ * Recursively flatten a nested config object to dot-notation key/value pairs.
+ * Arrays and null values are serialised to strings.
+ */
+function flattenConfig(
+  obj: Record<string, unknown>,
+  prefix = '',
+): Array<{ key: string; value: string }> {
+  const out: Array<{ key: string; value: string }> = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      out.push(...flattenConfig(v as Record<string, unknown>, fullKey));
+    } else if (Array.isArray(v)) {
+      out.push({ key: fullKey, value: v.length === 0 ? '[]' : JSON.stringify(v) });
+    } else {
+      out.push({ key: fullKey, value: v === null ? 'null' : String(v) });
+    }
+  }
+  return out;
+}
+
+/**
+ * Expand a top-level provenance map (e.g. { build: 'project' }) to cover every
+ * flattened dot-notation key (e.g. 'build.incremental' → 'project').
+ */
+function expandProvenance(
+  flatEntries: Array<{ key: string; value: string }>,
+  provenance: Record<string, ConfigSource>,
+): Map<string, ConfigSource> {
+  const map = new Map<string, ConfigSource>();
+  for (const { key } of flatEntries) {
+    // Provenance is keyed by top-level section (e.g. 'build', 'llm'), so
+    // extract the first segment to find the governing provenance entry.
+    const topLevel = key.split('.')[0] ?? key;
+    map.set(key, provenance[topLevel] ?? 'default');
+  }
+  return map;
+}
+
+/**
+ * Render the effective config as a human-readable Key/Value/Source table.
+ * All rows are shown, sorted so non-default overrides appear first, then
+ * remaining defaults alphabetically.
+ */
+function renderConfigTable(
+  config: Record<string, unknown>,
+  provenance: Record<string, ConfigSource>,
+): string {
+  const flat = flattenConfig(config);
+  const sourceMap = expandProvenance(flat, provenance);
+
+  // Show all entries — sorting non-defaults first, then alphabetically
+  const rows = flat
+    .slice()
+    .sort((a, b) => {
+      const sa = sourceMap.get(a.key) ?? 'default';
+      const sb = sourceMap.get(b.key) ?? 'default';
+      // Non-defaults first
+      if (sa !== 'default' && sb === 'default') return -1;
+      if (sa === 'default' && sb !== 'default') return 1;
+      return a.key.localeCompare(b.key);
+    })
+    .map(({ key, value }) => [key, value, sourceMap.get(key) ?? 'default']);
+
+  const keyWidth = Math.max(3, ...rows.map((r) => r[0]!.length));
+  const valWidth = Math.max(5, ...rows.map((r) => r[1]!.length));
+  // Source column is always short ('default', 'user', 'project', 'env')
+  const srcWidth = 7;
+
+  return `${formatTable({
+    columns: [
+      { header: 'Key', width: keyWidth },
+      { header: 'Value', width: valWidth },
+      { header: 'Source', width: srcWidth },
+    ],
+    rows: rows as string[][],
+    indent: 0,
+  })}\n`;
+}
+
+/**
+ * Build a scaffolded global config JSON file.
+ * Produces valid JSON with common sections pre-populated at their defaults.
+ * Uses DEFAULTS so the values always reflect the current schema.
+ *
+ * All keys are optional — users can delete sections they don't need.
+ */
+function buildInitTemplate(): string {
+  // Build a plain object — no comments in JSON, but keep it self-explanatory.
+  // Unknown top-level keys are silently ignored by mergeConfig.
+  const template: Record<string, unknown> = {
+    // LLM provider for AI features (codegraph explain, context, etc.)
+    // Use apiKeyCommand to pull the key from a secret manager at runtime.
+    // Scope to specific repos with:
+    //   { "appliesTo": ["~/projects/*"], "config": { ... } }
+    llm: {
+      provider: DEFAULTS.llm.provider,
+      model: DEFAULTS.llm.model,
+      baseUrl: DEFAULTS.llm.baseUrl,
+      apiKey: DEFAULTS.llm.apiKey,
+      apiKeyCommand: DEFAULTS.llm.apiKeyCommand,
+    },
+
+    query: {
+      defaultDepth: DEFAULTS.query.defaultDepth,
+      defaultLimit: DEFAULTS.query.defaultLimit,
+      excludeTests: DEFAULTS.query.excludeTests,
+    },
+
+    build: {
+      incremental: DEFAULTS.build.incremental,
+      typescriptResolver: DEFAULTS.build.typescriptResolver,
+    },
+
+    ci: {
+      failOnCycles: DEFAULTS.ci.failOnCycles,
+      impactThreshold: DEFAULTS.ci.impactThreshold,
+    },
+
+    search: {
+      defaultMinScore: DEFAULTS.search.defaultMinScore,
+      topK: DEFAULTS.search.topK,
+    },
+  };
+
+  return `${JSON.stringify(template, null, 2)}\n`;
+}
+
+export const command: CommandDefinition = {
+  name: 'config',
+  description: 'Show or manage codegraph configuration (project + user-level global config)',
+  options: [
+    ['-j, --json', 'Output as JSON'],
+    ['--explain', 'Show per-key provenance (default / user / project / env)'],
+    ['--enable-global', 'Record consent to apply the global config to this repo'],
+    ['--disable-global', 'Record consent to skip the global config for this repo'],
+    ['--list-global', 'List all repos with a recorded consent decision'],
+    [
+      '--init',
+      'Scaffold a global config file at the default XDG location with all sections pre-populated',
+    ],
+    ['--edit', 'Open the global config file in $EDITOR (prints the path if $EDITOR is unset)'],
+  ],
+  execute(_args, opts, ctx) {
+    const rootDir = path.resolve('.');
+
+    // ── Init: scaffold global config ───────────────────────────────────
+
+    if (opts.init) {
+      const targetPath = getDefaultUserConfigPath();
+      if (fs.existsSync(targetPath)) {
+        process.stderr.write(
+          `Global config already exists at ${targetPath}\n` +
+            `Run \`codegraph config --edit\` to open it, or delete it and re-run --init.\n`,
+        );
+        process.exit(1);
+      }
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.writeFileSync(targetPath, buildInitTemplate(), 'utf-8');
+      process.stdout.write(`Created global config at ${targetPath}\n`);
+      process.stdout.write(
+        `Next steps:\n` +
+          `  1. Edit the file: codegraph config --edit\n` +
+          `  2. Enable it for this repo: codegraph config --enable-global\n`,
+      );
+      return;
+    }
+
+    // ── Edit: open global config in $EDITOR ────────────────────────────
+
+    if (opts.edit) {
+      // Prefer the existing file; fall back to the default path so the user
+      // can create-and-edit in one step even before running --init.
+      const filePath = resolveUserConfigPath() ?? getDefaultUserConfigPath();
+
+      const editor = process.env.EDITOR || process.env.VISUAL;
+      if (!editor) {
+        process.stdout.write(`${filePath}\n`);
+        process.stderr.write(
+          `$EDITOR is not set. Set it in your shell profile (e.g. export EDITOR=nano)\n` +
+            `or open the file manually at the path printed above.\n`,
+        );
+        return;
+      }
+
+      // Ensure the directory exists so the editor can create the file
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+      const result = spawnSync(editor, [filePath], { stdio: 'inherit' });
+      if (result.error) {
+        process.stderr.write(`Failed to launch editor "${editor}": ${result.error.message}\n`);
+        process.exit(1);
+      }
+      if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+      }
+      return;
+    }
+
+    // ── Consent management ─────────────────────────────────────────────
+
+    if (opts.enableGlobal) {
+      setUserConfigConsent(rootDir, 'enabled');
+      clearConfigCache();
+      const globalPath = resolveUserConfigPath();
+      if (!globalPath) {
+        process.stderr.write(
+          `Consent recorded: "enabled" for ${rootDir}\n` +
+            `Note: no global config file found. Create one at ~/.config/codegraph/config.json\n`,
+        );
+      } else {
+        process.stderr.write(
+          `Consent recorded: "enabled" for ${rootDir}\n` + `Global config: ${globalPath}\n`,
+        );
+      }
+      return;
+    }
+
+    if (opts.disableGlobal) {
+      setUserConfigConsent(rootDir, 'disabled');
+      clearConfigCache();
+      process.stderr.write(`Consent recorded: "disabled" for ${rootDir}\n`);
+      return;
+    }
+
+    if (opts.listGlobal) {
+      const entries = listUserConfigConsent(REGISTRY_PATH);
+      if (opts.json) {
+        process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+        return;
+      }
+      if (entries.length === 0) {
+        process.stdout.write('No repos have a recorded global-config consent decision.\n');
+        return;
+      }
+      process.stdout.write('Global config consent decisions:\n\n');
+      for (const { path: p, decision } of entries) {
+        process.stdout.write(
+          `  ${decision === 'enabled' ? '✔' : '✘'} ${decision.padEnd(8)} ${p}\n`,
+        );
+      }
+      return;
+    }
+
+    // ── Explain mode ───────────────────────────────────────────────────
+
+    if (opts.explain) {
+      const { config, provenance, appliedGlobalPath, consentDecision } = loadConfigWithProvenance(
+        rootDir,
+        {
+          userConfig: ctx.program.opts().userConfig,
+        },
+      );
+      const globalPath = resolveUserConfigPath();
+      const consent = getUserConfigConsent(rootDir);
+
+      if (opts.json) {
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              config,
+              provenance,
+              appliedGlobalPath,
+              globalFilePath: globalPath,
+              consentDecision: consentDecision ?? consent ?? 'undecided',
+            },
+            null,
+            2,
+          )}\n`,
+        );
+        return;
+      }
+
+      // Human-readable explain output
+      process.stdout.write('=== Codegraph config provenance ===\n\n');
+
+      const consentStr = consentDecision ?? consent ?? 'undecided';
+      process.stdout.write(`Global config file : ${globalPath ?? '(none found)'}\n`);
+      process.stdout.write(`Applied this run   : ${appliedGlobalPath ? 'yes' : 'no'}\n`);
+      process.stdout.write(`Consent for repo   : ${consentStr}\n`);
+      process.stdout.write(
+        `  (change with \`codegraph config --enable-global\` or \`--disable-global\`)\n`,
+      );
+
+      if (!globalPath) {
+        process.stdout.write(
+          `\nDiscovery hint: create a global config at ~/.config/codegraph/config.json\n` +
+            `then run \`codegraph config --enable-global\` in repos where you want it applied.\n`,
+        );
+      } else if (!appliedGlobalPath) {
+        process.stdout.write(
+          `\nDiscovery hint: global config exists but is not applied to this repo.\n` +
+            `Run \`codegraph config --enable-global\` to enable it here.\n`,
+        );
+      }
+
+      process.stdout.write('\n--- Per-key provenance ---\n\n');
+      const provenanceEntries = Object.entries(provenance).sort(([a], [b]) => a.localeCompare(b));
+      for (const [key, source] of provenanceEntries) {
+        process.stdout.write(`  ${source.padEnd(8)} ${key}\n`);
+      }
+      return;
+    }
+
+    // ── Default: print effective config ────────────────────────────────
+
+    const globalPath = resolveUserConfigPath();
+    const consent = getUserConfigConsent(rootDir);
+
+    if (opts.json) {
+      const config = loadConfig(rootDir, { userConfig: ctx.program.opts().userConfig });
+      process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+    } else {
+      // Human-readable table: Key | Value | Source
+      const { config, provenance } = loadConfigWithProvenance(rootDir, {
+        userConfig: ctx.program.opts().userConfig,
+      });
+      process.stdout.write(
+        renderConfigTable(config as unknown as Record<string, unknown>, provenance),
+      );
+
+      if (globalPath && !consent) {
+        process.stderr.write(
+          `\nℹ Global config found at ${globalPath} — not applied to this repo.\n` +
+            `  Run \`codegraph config --enable-global\` to opt in, or\n` +
+            `  \`codegraph config --disable-global\` to dismiss this notice.\n`,
+        );
+      }
+    }
+  },
+};

package/src/cli/commands/triage.ts

@@ -31,7 +31,7 @@ async function runHotspots(opts: CommandOpts, ctx: CliContext): Promise<void> {
     offset: opts.offset ? parseInt(opts.offset as string, 10) : undefined,
     noTests: ctx.resolveNoTests(opts),
   });
-  if (!ctx.outputResult(data, 'hotspots', opts)) {
+  if (!ctx.outputResult(data, 'items', opts)) {
     console.log(formatHotspots(data));
   }
 }

package/src/cli/index.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Command } from 'commander';
+import { setUserConfigOverride } from '../infrastructure/config.js';
 import { setVerbose } from '../infrastructure/logger.js';
 import { checkForUpdates, printUpdateNotification } from '../infrastructure/update-check.js';
 import { ConfigError } from '../shared/errors.js';
@@ -25,9 +26,16 @@ program
   .version(pkg.version)
   .option('-v, --verbose', 'Enable verbose/debug output')
   .option('--engine <engine>', 'Parser engine: native, wasm, or auto (default: auto)', 'auto')
+  .option('--user-config [path]', 'Apply global user config for this run (optional custom path)')
+  .option('--no-user-config', 'Skip global user config for this run')
   .hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
     if (opts.verbose) setVerbose(true);
+    // Wire user-config flags into the config loader before any command runs.
+    // Commander sets opts.userConfig = true (bare flag), a string (path), or undefined.
+    // opts.userConfig is false when --no-user-config is passed (Commander negation).
+    const uc = opts.userConfig as string | boolean | undefined;
+    setUserConfigOverride(uc);
   })
   .hook('postAction', async (_thisCommand, actionCommand) => {
     const name = actionCommand.name();
@@ -67,6 +75,8 @@ const ctx: CliContext = {
 function registerCommand(parent: Command, def: CommandDefinition): Command {
   const cmd = parent.command(def.name).description(def.description);
 
+  if (def.alias) cmd.alias(def.alias);
+
   if (def.queryOpts) applyQueryOpts(cmd);
 
   for (const opt of def.options || []) {

package/src/cli/shared/options.ts

@@ -1,8 +1,18 @@
 import type { Command } from 'commander';
 import { loadConfig } from '../../infrastructure/config.js';
+import type { CodegraphConfig } from '../../types.js';
 import type { CommandOpts } from '../types.js';
 
-const config = loadConfig(process.cwd());
+// Deferred so global --user-config / --no-user-config flags are parsed
+// before config is first accessed (Commander parses flags before any command
+// action runs, but module-level code executes at import time).
+let _config: CodegraphConfig | undefined;
+const config: CodegraphConfig = new Proxy({} as CodegraphConfig, {
+  get(_t, prop: string) {
+    if (_config === undefined) _config = loadConfig(process.cwd());
+    return _config[prop as keyof CodegraphConfig];
+  },
+}) as CodegraphConfig;
 
 /**
  * Attach the common query options shared by most analysis commands.

package/src/cli/types.ts

@@ -25,6 +25,8 @@ export interface CliContext {
 export interface CommandDefinition {
   name: string;
   description: string;
+  /** Optional Commander.js alias (e.g. 'explain' for the 'audit' command). */
+  alias?: string;
   queryOpts?: boolean;
   options?: Array<[string, string, ...unknown[]]>;
   validate?(args: string[], opts: CommandOpts, ctx: CliContext): string | undefined;

package/src/db/migrations.ts

@@ -8,7 +8,7 @@ interface Migration {
   up: string;
 }
 
-// IMPORTANT: Migration DDL is mirrored in crates/codegraph-core/src/native_db.rs.
+// IMPORTANT: Migration DDL is mirrored in crates/codegraph-core/src/db/connection.rs.
 // Any changes here MUST be reflected there (and vice-versa).
 export const MIGRATIONS: Migration[] = [
   {

package/src/domain/graph/builder/call-resolver.ts

@@ -47,6 +47,22 @@ export function isModuleScopedLanguage(relPath: string): boolean {
 
 // ── Shared resolution functions ──────────────────────────────────────────
 
+/**
+ * Callable definition kinds — variable/constant bindings are NOT callable
+ * in the function-as-enclosing-scope sense (they are local declarations, not
+ * function bodies). Top-level variable bindings (e.g. Haskell `main = do …`)
+ * are handled separately as a fallback tier.
+ */
+const CALLABLE_KINDS = new Set(['function', 'method']);
+
+/**
+ * Variable-like binding kinds that may act as top-level callers when no
+ * enclosing function/method exists (e.g. Haskell top-level `main` is a
+ * `bind` node → kind `variable`).  Local variable declarations inside a
+ * function body must NOT win over the enclosing function.
+ */
+const TOP_LEVEL_BINDING_KINDS = new Set(['variable', 'constant']);
+
 export function findCaller(
   lookup: CallNodeLookup,
   call: { line: number },
@@ -59,26 +75,63 @@ export function findCaller(
   relPath: string,
   fileNodeRow: { id: number },
 ): { id: number; callerName: string | null } {
-  let caller: { id: number } | null = null;
-  let callerName: string | null = null;
-  let callerSpan = Infinity;
+  // Pass 1: find the narrowest enclosing function/method.
+  let fnCaller: { id: number } | null = null;
+  let fnCallerName: string | null = null;
+  let fnCallerSpan = Infinity;
+
+  // Pass 2: find the widest (outermost) enclosing variable/constant binding.
+  // Used as fallback when no function/method encloses the call site
+  // (e.g. Haskell `main = do …` is a `bind` node with kind `variable`).
+  // We pick the WIDEST span (outermost binding), not the narrowest, so that
+  // nested `let` bindings inside `main`'s do-block do not shadow `main`
+  // itself as the attributing caller.  The outermost enclosing variable is
+  // the "function-like" top-level binding.
+  let varCaller: { id: number } | null = null;
+  let varCallerName: string | null = null;
+  let varCallerSpan = -1; // looking for WIDEST span, so start at -1
+
   for (const def of definitions) {
     if (def.line <= call.line) {
-      const end = def.endLine || Infinity;
+      const end = def.endLine ?? Infinity;
       if (call.line <= end) {
-        const span = end - def.line;
-        if (span < callerSpan) {
-          const row = lookup.nodeId(def.name, def.kind, relPath, def.line);
-          if (row) {
-            caller = row;
-            callerName = def.name;
-            callerSpan = span;
+        const span = end === Infinity ? Infinity : end - def.line;
+        if (CALLABLE_KINDS.has(def.kind)) {
+          if (span < fnCallerSpan) {
+            const row = lookup.nodeId(def.name, def.kind, relPath, def.line);
+            if (row) {
+              fnCaller = row;
+              fnCallerName = def.name;
+              fnCallerSpan = span;
+            }
+          }
+        } else if (TOP_LEVEL_BINDING_KINDS.has(def.kind)) {
+          if (span > varCallerSpan) {
+            const row = lookup.nodeId(def.name, def.kind, relPath, def.line);
+            if (row) {
+              varCaller = row;
+              varCallerName = def.name;
+              varCallerSpan = span;
+            }
           }
         }
       }
     }
   }
-  return { ...(caller ?? fileNodeRow), callerName };
+
+  // Prefer function/method enclosing scope over variable binding.
+  // If a function/method encloses the call, use it — local variable
+  // declarations inside the function body must not shadow it.
+  // Only fall back to a variable/constant binding when the call is at
+  // top-level scope (no enclosing function/method found), which handles
+  // languages like Haskell where `main` is a top-level `bind` node.
+  if (fnCaller) {
+    return { ...fnCaller, callerName: fnCallerName };
+  }
+  if (varCaller) {
+    return { ...varCaller, callerName: varCallerName };
+  }
+  return { ...fileNodeRow, callerName: null };
 }
 
 export function resolveByMethodOrGlobal(
@@ -94,22 +147,25 @@ export function resolveByMethodOrGlobal(
     const effectiveReceiver = call.receiver.startsWith('this.')
       ? call.receiver.slice('this.'.length)
       : call.receiver;
-    // For this.prop receivers, also try the class-scoped key (ClassName.prop) seeded by
-    // handlePropWriteTypeMap — prevents false edges when multiple classes define the same
-    // property name (issue #1323).
-    let typeEntry =
-      typeMap.get(effectiveReceiver) ??
-      typeMap.get(call.receiver) ??
-      // Phase 8.3f: callee-scoped rest-param key (`callee::restName`) to avoid
-      // same-name rest-binding collision across functions in the same file (#1358).
-      (callerName ? typeMap.get(`${callerName}::${effectiveReceiver}`) : undefined);
-    if (!typeEntry && call.receiver.startsWith('this.') && callerName) {
+    // For this.prop receivers, prefer the class-scoped key (ClassName.prop) seeded by
+    // handlePropWriteTypeMap / handleFieldDefTypeMap — prevents false edges when multiple
+    // classes define the same property name (issues #1323, #1458).
+    // Class-scoped lookup runs first so bare fallback keys (confidence 0.6) don't shadow
+    // the correct per-class entry when callerName is available.
+    let typeEntry: unknown;
+    if (call.receiver.startsWith('this.') && callerName) {
       const dotIdx = callerName.lastIndexOf('.');
       if (dotIdx > -1) {
         const callerClass = callerName.slice(0, dotIdx);
         typeEntry = typeMap.get(`${callerClass}.${effectiveReceiver}`);
       }
     }
+    typeEntry ??=
+      typeMap.get(effectiveReceiver) ??
+      typeMap.get(call.receiver) ??
+      // Phase 8.3f: callee-scoped rest-param key (`callee::restName`) to avoid
+      // same-name rest-binding collision across functions in the same file (#1358).
+      (callerName ? typeMap.get(`${callerName}::${effectiveReceiver}`) : undefined);
     let typeName = typeEntry
       ? typeof typeEntry === 'string'
         ? typeEntry
@@ -299,13 +355,17 @@ export function resolveCallTargets(
  * Returns the edge tuple to insert, or null if nothing matched or the edge
  * was already seen.  Callers are responsible for the actual DB/array insert.
  *
- * Receiver resolution collects all same-file candidates first (no kind
- * filter), falls back to global candidates only when the same-file set is
- * entirely empty, then filters the chosen set by RECEIVER_KINDS.  This
- * matches the native Rust build path: if a file imports a name that happens
- * to be emitted as `kind='function'` in the importer, the same-file set is
- * non-empty and blocks the global fallback, so no receiver edge is emitted.
- * Keeping this behaviour identical to the Rust path maintains engine parity.
+ * Receiver resolution:
+ * 1. Look up same-file nodes for `effectiveReceiver` (unfiltered by kind).
+ * 2. If any same-file node exists AND `effectiveReceiver` is not in `importedNames`
+ *    (i.e. it is a locally-defined symbol, not an import artifact), apply
+ *    RECEIVER_KINDS and return the filtered set — no global fallback.
+ *    A local `function C(){}` means this file owns `C`; no cross-file class
+ *    should win over it (issue #1539).
+ * 3. If the same-file node IS an import artifact (e.g. destructured require),
+ *    or no same-file node exists at all, fall back to global candidates filtered
+ *    by RECEIVER_KINDS.  This preserves the pre-#1539 behaviour for cases where
+ *    an imported name appears as kind='function' in the importer file.
  */
 export function resolveReceiverEdge(
   lookup: CallNodeLookup,
@@ -314,6 +374,7 @@ export function resolveReceiverEdge(
   relPath: string,
   typeMap: Map<string, unknown>,
   seenCallEdges: Set<string>,
+  importedNames: ReadonlyMap<string, string>,
 ): { callerId: number; receiverId: number; confidence: number } | null {
   const typeEntry = typeMap.get(call.receiver);
   const typeName = typeEntry
@@ -326,18 +387,15 @@ export function resolveReceiverEdge(
       ? ((typeEntry as { confidence?: number }).confidence ?? null)
       : null;
   const effectiveReceiver = typeName || call.receiver;
-  // Filter-before: apply RECEIVER_KINDS to same-file candidates first, then
-  // fall back to global candidates (also filtered) only when same-file yields
-  // nothing.  This prevents an imported name emitted as kind='function' in the
-  // importing file from blocking the fallback to the actual class/struct/etc.
-  // node in the defining file.
-  const sameFileCandidates = lookup
-    .byNameAndFile(effectiveReceiver, relPath)
-    .filter((n) => RECEIVER_KINDS.has(n.kind ?? ''));
-  const candidates =
-    sameFileCandidates.length > 0
-      ? sameFileCandidates
-      : lookup.byName(effectiveReceiver).filter((n) => RECEIVER_KINDS.has(n.kind ?? ''));
+  // Block global fallback only when the same-file node is a local definition,
+  // not when it's an import artifact (e.g. `const { C } = require(…)` seeds a
+  // kind='function' node in the importer but the real class lives elsewhere).
+  const sameFileAll = lookup.byNameAndFile(effectiveReceiver, relPath);
+  const isLocalDefinition = sameFileAll.length > 0 && !importedNames?.has(effectiveReceiver);
+  const sameFileCandidates = sameFileAll.filter((n) => RECEIVER_KINDS.has(n.kind ?? ''));
+  const candidates = isLocalDefinition
+    ? sameFileCandidates
+    : lookup.byName(effectiveReceiver).filter((n) => RECEIVER_KINDS.has(n.kind ?? ''));
   if (candidates.length === 0) return null;
   const recvTarget = candidates[0]!;
   const recvKey = `recv|${caller.id}|${recvTarget.id}`;

package/src/domain/graph/builder/cha.ts

@@ -96,6 +96,14 @@ export function buildChaContext(fileSymbols: ReadonlyMap<string, ExtractorOutput
  * For `super`, resolution starts from the parent of the caller's class.
  * For `this`/`self`, resolution starts from the caller's own class and walks
  * up the inheritance chain (supporting inherited method lookup).
+ *
+ * When `callerFile` is provided, same-file method nodes are preferred: if the
+ * hierarchy walk finds a qualified method that exists in both the caller's own
+ * file AND in unrelated files (e.g. a class named `A` that appears in multiple
+ * fixture files), only the same-file nodes are returned.  This prevents
+ * cross-fixture false edges caused by accidental name collisions across
+ * unrelated files in the same project build.  When no same-file nodes exist,
+ * all found nodes are returned as before.
  */
 export function resolveThisDispatch(
   methodName: string,
@@ -103,6 +111,7 @@ export function resolveThisDispatch(
   receiver: 'this' | 'self' | 'super',
   chaCtx: ChaContext,
   lookup: CallNodeLookup,
+  callerFile?: string | null,
 ): ReadonlyArray<{ id: number; file: string }> {
   if (!callerName) return [];
   const dotIdx = callerName.indexOf('.');
@@ -119,7 +128,15 @@ export function resolveThisDispatch(
     visited.add(current);
     const qualified = `${current}.${methodName}`;
     const found = lookup.byName(qualified).filter((n) => n.kind === 'method');
-    if (found.length > 0) return found;
+    if (found.length > 0) {
+      // When the caller's file is known, prefer same-file nodes to avoid
+      // emitting cross-file edges to identically-named methods in unrelated
+      // files.  Only fall back to the full set when no same-file node exists.
+      if (callerFile && found.some((n) => n.file === callerFile)) {
+        return found.filter((n) => n.file === callerFile);
+      }
+      return found;
+    }
     current = chaCtx.parents.get(current);
   }
   return [];