@kodus/kodus-graph 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodus/kodus-graph",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Code graph builder for Kodus code review — parses source code into structural graphs with nodes, edges, and analysis",
   "type": "module",
   "bin": {

package/src/analysis/diff.ts

@@ -1,5 +1,6 @@
 import type { IndexedGraph } from '../graph/loader';
 import type { GraphEdge, GraphNode } from '../graph/types';
+import { log } from '../shared/logger';
 
 export interface NodeChange {
   qualified_name: string;
@@ -45,6 +46,12 @@ export function computeStructuralDiff(
     if (changedSet.has(n.file_path)) newNodesMap.set(n.qualified_name, n);
   }
 
+  log.debug('diff: input', {
+    oldNodesInChanged: oldNodesInChanged.size,
+    newNodesInChanged: newNodesMap.size,
+    changedFiles,
+  });
+
   // Classify nodes
   const added: NodeChange[] = [];
   const removed: NodeChange[] = [];
@@ -79,12 +86,34 @@ export function computeStructuralDiff(
       if (n.content_hash && newN.content_hash) {
         // Definitive: hash comparison catches ALL content changes,
         // even same-line-count edits (e.g. `return 1` → `return 2`).
-        if (n.content_hash !== newN.content_hash) changes.push('body');
+        if (n.content_hash !== newN.content_hash) {
+          changes.push('body');
+          log.debug('diff: body change detected', {
+            node: qn,
+            oldHash: n.content_hash.substring(0, 8),
+            newHash: newN.content_hash.substring(0, 8),
+          });
+        } else {
+          log.debug('diff: hash match (displacement only)', {
+            node: qn,
+            oldLines: `${n.line_start}-${n.line_end}`,
+            newLines: `${newN.line_start}-${newN.line_end}`,
+          });
+        }
       } else if (n.line_start !== newN.line_start || n.line_end !== newN.line_end) {
         // Fallback (legacy data without content_hash): size heuristic.
         const oldSize = n.line_end - n.line_start;
         const newSize = newN.line_end - newN.line_start;
-        if (oldSize !== newSize) changes.push('line_range');
+        if (oldSize !== newSize) {
+          changes.push('line_range');
+          log.debug('diff: line_range fallback (no content_hash)', {
+            node: qn,
+            hasOldHash: !!n.content_hash,
+            hasNewHash: !!newN.content_hash,
+            oldSize,
+            newSize,
+          });
+        }
       }
       if ((n.params || '') !== (newN.params || '')) changes.push('params');
       if ((n.return_type || '') !== (newN.return_type || '')) changes.push('return_type');
@@ -121,6 +150,15 @@ export function computeStructuralDiff(
     riskByFile[file] = { dependents: count, risk };
   }
 
+  log.info('diff: result', {
+    added: added.length,
+    removed: removed.length,
+    modified: modified.length,
+    edgesAdded: addedEdges.length,
+    edgesRemoved: removedEdges.length,
+    modifiedDetails: modified.map((m) => `${m.qualified_name} [${m.changes.join(',')}]`),
+  });
+
   return {
     changed_files: changedFiles,
     summary: { added: added.length, removed: removed.length, modified: modified.length },

package/src/cli.ts

@@ -14,6 +14,9 @@ import { executeUpdate } from './commands/update';
 const program = new Command();
 
 import pkg from '../package.json';
+import { log } from './shared/logger';
+
+log.info(`kodus-graph v${pkg.version}`, { node: process.version, platform: process.platform });
 program.name('kodus-graph').description('Code graph builder for Kodus code review').version(pkg.version);
 
 program

package/src/commands/context.ts

@@ -22,6 +22,15 @@ interface ContextOptions {
 export async function executeContext(opts: ContextOptions): Promise<void> {
   const repoDir = resolve(opts.repoDir);
 
+  log.info('context: starting', {
+    files: opts.files,
+    repoDir,
+    graph: opts.graph ?? null,
+    format: opts.format,
+    minConfidence: opts.minConfidence,
+    maxDepth: opts.maxDepth,
+  });
+
   // Parse changed files using secure temp
   const tmp = createSecureTempFile('ctx');
   try {
@@ -33,6 +42,11 @@ export async function executeContext(opts: ContextOptions): Promise<void> {
     });
     const parseResult = JSON.parse(readFileSync(tmp.filePath, 'utf-8'));
 
+    log.info('context: parse done', {
+      nodes: parseResult.nodes?.length ?? 0,
+      edges: parseResult.edges?.length ?? 0,
+    });
+
     // Load and merge with main graph if provided
     let mergedGraph: GraphData;
     let oldGraph: GraphData | null = null;
@@ -53,6 +67,12 @@ export async function executeContext(opts: ContextOptions): Promise<void> {
       const changedSet = new Set(opts.files);
       const sameBranch = detectSameBranch(validated.data.nodes, parseResult.nodes, changedSet);
 
+      log.info('context: baseline graph loaded', {
+        graphNodes: validated.data.nodes.length,
+        graphEdges: validated.data.edges.length,
+        sameBranch,
+      });
+
       if (sameBranch) {
         // --graph was built from the same commit (e.g. kodus-ai's parse --all on PR branch).
         // Exclude changed files from oldGraph so diff detects their functions as "added"
@@ -88,6 +108,16 @@ export async function executeContext(opts: ContextOptions): Promise<void> {
       maxDepth: opts.maxDepth,
     });
 
+    log.info('context: analysis done', {
+      changedFunctions: output.analysis.changed_functions.length,
+      diff: output.analysis.structural_diff.summary,
+      blastRadius: output.analysis.blast_radius.total_functions,
+      risk: `${output.analysis.risk.level} (${output.analysis.risk.score})`,
+      testGaps: output.analysis.test_gaps.length,
+      affectedFlows: output.analysis.affected_flows.length,
+      duration_ms: output.analysis.metadata.duration_ms,
+    });
+
     if (opts.format === 'prompt') {
       writeFileSync(opts.out, formatPrompt(output));
     } else {
@@ -120,7 +150,10 @@ function detectSameBranch(
   }
 
   // No overlap means graph has no nodes for changed files — not same-branch scenario
-  if (graphHashes.size === 0) return false;
+  if (graphHashes.size === 0) {
+    log.debug('detectSameBranch: no graph hashes for changed files');
+    return false;
+  }
 
   const parseHashes = new Map<string, string>();
   for (const n of parseNodes) {
@@ -132,8 +165,18 @@ function detectSameBranch(
   // If any overlapping file has different hash → different branch
   for (const [file, hash] of graphHashes) {
     const parseHash = parseHashes.get(file);
-    if (parseHash && parseHash !== hash) return false;
+    if (parseHash && parseHash !== hash) {
+      log.debug('detectSameBranch: hash mismatch → different branch', {
+        file,
+        graphHash: hash.substring(0, 8),
+        parseHash: parseHash.substring(0, 8),
+      });
+      return false;
+    }
   }
 
+  log.debug('detectSameBranch: all hashes match → same branch', {
+    filesCompared: graphHashes.size,
+  });
   return true;
 }

package/src/graph/types.ts

@@ -247,6 +247,7 @@ export interface RawCallSite {
   callName: string; // function or method name being called
   line: number; // line number of the call
   diField?: string; // if DI pattern (this.field.method), the field name
+  resolveInClass?: string; // class to resolve in: current class for self.X(), parent for super().X()
 }
 
 export interface RawCallEdge {

package/src/parser/extractor.ts

@@ -32,6 +32,6 @@ export function extractCallsFromFile(root: SgRoot, filePath: string, lang: Lang
   } else if (lang === 'ruby') {
     extractCallsFromRuby(root, filePath, calls);
   } else {
-    extractCallsFromGeneric(root, filePath, calls);
+    extractCallsFromGeneric(root, filePath, lang as string, calls);
   }
 }

package/src/parser/extractors/generic.ts

@@ -1,7 +1,7 @@
 import type { SgNode, SgRoot } from '@ast-grep/napi';
 import type { RawCallSite, RawGraph } from '../../graph/types';
+import { type CallExtractionConfig, extractCalls } from '../../shared/extract-calls';
 import { computeContentHash } from '../../shared/file-hash';
-import { NOISE } from '../../shared/filters';
 import { log } from '../../shared/logger';
 import { LANG_KINDS } from '../languages';
 
@@ -69,22 +69,64 @@ export function extractGeneric(root: SgRoot, fp: string, lang: string, seen: Set
   }
 }
 
+/** Shared class-finder for languages using class/struct/impl AST kinds. */
+function findEnclosingClassGeneric(node: import('@ast-grep/napi').SgNode): import('@ast-grep/napi').SgNode | null {
+  return node.ancestors().find((a) => {
+    const k = String(a.kind());
+    return k.includes('class') || k.includes('struct') || k.includes('impl');
+  }) ?? null;
+}
+
+/** Per-language call extraction configs for self/super detection. */
+const GENERIC_CONFIGS: Record<string, CallExtractionConfig> = {
+  java: {
+    selfPrefixes: ['this.'],
+    superPrefixes: ['super.'],
+    findEnclosingClass: findEnclosingClassGeneric,
+    getParentClass: (classNode) => {
+      const sc = classNode.children().find((c) => c.kind() === 'superclass');
+      return sc?.children().find((c) => c.kind() === 'type_identifier')?.text();
+    },
+  },
+  csharp: {
+    selfPrefixes: ['this.'],
+    superPrefixes: ['base.'],
+    findEnclosingClass: findEnclosingClassGeneric,
+    getParentClass: (classNode) => {
+      const bl = classNode.children().find((c) => c.kind() === 'base_list');
+      return bl?.children().find((c) => c.kind() === 'identifier' || c.kind() === 'type_identifier')?.text();
+    },
+  },
+  rust: {
+    selfPrefixes: ['self.'],
+    superPrefixes: [],
+    findEnclosingClass: (node) =>
+      node.ancestors().find((a) => a.kind() === 'impl_item') ?? null,
+  },
+  go: {
+    selfPrefixes: [],
+    superPrefixes: [],
+    findEnclosingClass: findEnclosingClassGeneric,
+  },
+  php: {
+    selfPrefixes: [],
+    superPrefixes: [],
+    findEnclosingClass: findEnclosingClassGeneric,
+  },
+};
+
+/** Fallback config for unknown languages — no self/super detection. */
+const FALLBACK_CONFIG: CallExtractionConfig = {
+  selfPrefixes: [],
+  superPrefixes: [],
+  findEnclosingClass: findEnclosingClassGeneric,
+};
+
 /**
  * Extract raw call sites from a generic language AST.
- * Direct calls only.
+ * Uses per-language config for self/super detection.
  */
-export function extractCallsFromGeneric(root: SgRoot, fp: string, calls: RawCallSite[]): void {
-  const rootNode = root.root();
-
-  for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
-    const callee = m.getMatch('CALLEE')?.text();
-    if (!callee) continue;
-    const callName = callee.includes('.') ? callee.split('.').pop()! : callee;
-    if (NOISE.has(callName)) continue;
-    calls.push({
-      source: fp,
-      callName,
-      line: m.range().start.line,
-    });
-  }
+export function extractCallsFromGeneric(root: SgRoot, fp: string, lang: string, calls: RawCallSite[]): void {
+  const config = GENERIC_CONFIGS[lang] ?? FALLBACK_CONFIG;
+  extractCalls(root.root(), fp, config, calls);
 }

package/src/parser/extractors/python.ts

@@ -1,7 +1,7 @@
 import type { SgNode, SgRoot } from '@ast-grep/napi';
 import type { RawCallSite, RawGraph } from '../../graph/types';
+import { type CallExtractionConfig, extractCalls } from '../../shared/extract-calls';
 import { computeContentHash } from '../../shared/file-hash';
-import { NOISE } from '../../shared/filters';
 import { LANG_KINDS } from '../languages';
 
 export function extractPython(root: SgRoot, fp: string, seen: Set<string>, graph: RawGraph): void {
@@ -110,22 +110,24 @@ export function extractPython(root: SgRoot, fp: string, seen: Set<string>, graph
   }
 }
 
+/** Python-specific call extraction config for shared extractCalls(). */
+const PYTHON_CALL_CONFIG: CallExtractionConfig = {
+  selfPrefixes: ['self.'],
+  superPrefixes: ['super().'],
+  findEnclosingClass: (node) =>
+    node.ancestors().find((a: SgNode) => a.kind() === 'class_definition') ?? null,
+  getParentClass: (classNode) => {
+    const argList =
+      classNode.field('superclasses') ||
+      classNode.children().find((c: SgNode) => c.kind() === 'argument_list');
+    return argList?.children().find((c: SgNode) => c.kind() === 'identifier')?.text();
+  },
+};
+
 /**
  * Extract raw call sites from a Python AST.
- * Direct calls only — Python has no DI pattern.
+ * Detects self.X() and super().X() to preserve class resolution context.
  */
 export function extractCallsFromPython(root: SgRoot, fp: string, calls: RawCallSite[]): void {
-  const rootNode = root.root();
-
-  for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
-    const callee = m.getMatch('CALLEE')?.text();
-    if (!callee) continue;
-    const callName = callee.includes('.') ? callee.split('.').pop()! : callee;
-    if (NOISE.has(callName)) continue;
-    calls.push({
-      source: fp,
-      callName,
-      line: m.range().start.line,
-    });
-  }
+  extractCalls(root.root(), fp, PYTHON_CALL_CONFIG, calls);
 }

package/src/parser/extractors/ruby.ts

@@ -1,7 +1,7 @@
 import type { SgNode, SgRoot } from '@ast-grep/napi';
 import type { RawCallSite, RawGraph } from '../../graph/types';
+import { type CallExtractionConfig, extractCalls } from '../../shared/extract-calls';
 import { computeContentHash } from '../../shared/file-hash';
-import { NOISE } from '../../shared/filters';
 import { log } from '../../shared/logger';
 import { LANG_KINDS } from '../languages';
 
@@ -126,22 +126,22 @@ export function extractRuby(root: SgRoot, fp: string, seen: Set<string>, graph:
   }
 }
 
+/** Ruby-specific call extraction config for shared extractCalls(). */
+function createRubyCallConfig(): CallExtractionConfig {
+  const kinds = LANG_KINDS.ruby;
+  return {
+    selfPrefixes: ['self.'],
+    superPrefixes: ['super'],
+    findEnclosingClass: (node) =>
+      node.ancestors().find((a: SgNode) => a.kind() === kinds.class || a.kind() === kinds.module) ?? null,
+    getParentClass: (classNode) => classNode.field('superclass')?.text(),
+  };
+}
+
 /**
  * Extract raw call sites from a Ruby AST.
- * Direct calls only — Ruby has no DI pattern.
+ * Detects self.X() and super() to preserve class resolution context.
  */
 export function extractCallsFromRuby(root: SgRoot, fp: string, calls: RawCallSite[]): void {
-  const rootNode = root.root();
-
-  for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
-    const callee = m.getMatch('CALLEE')?.text();
-    if (!callee) continue;
-    const callName = callee.includes('.') ? callee.split('.').pop()! : callee;
-    if (NOISE.has(callName)) continue;
-    calls.push({
-      source: fp,
-      callName,
-      line: m.range().start.line,
-    });
-  }
+  extractCalls(root.root(), fp, createRubyCallConfig(), calls);
 }

package/src/parser/extractors/typescript.ts

@@ -1,6 +1,7 @@
 import type { SgNode, SgRoot } from '@ast-grep/napi';
 import { Lang } from '@ast-grep/napi';
 import type { RawCallSite, RawGraph } from '../../graph/types';
+import { type CallExtractionConfig, extractCalls } from '../../shared/extract-calls';
 import { computeContentHash } from '../../shared/file-hash';
 import { NOISE } from '../../shared/filters';
 import { LANG_KINDS } from '../languages';
@@ -302,6 +303,27 @@ export function extractTypeScript(
   }
 }
 
+/** TypeScript-specific call extraction config for shared extractCalls(). */
+const TS_CALL_CONFIG: CallExtractionConfig = {
+  selfPrefixes: ['this.'],
+  superPrefixes: ['super.'],
+  findEnclosingClass: (node) => {
+    const kinds = LANG_KINDS.typescript;
+    return node.ancestors().find(
+      (a: SgNode) => a.kind() === kinds.class || a.kind() === kinds.abstractClass,
+    ) ?? null;
+  },
+  getParentClass: (classNode) => {
+    const heritage = classNode.children().find((c: SgNode) => c.kind() === 'class_heritage');
+    const ext = heritage?.children().find((c: SgNode) => c.kind() === 'extends_clause');
+    return ext?.children().find(
+      (c: SgNode) => c.kind() === 'identifier' || c.kind() === 'type_identifier' || c.kind() === 'member_expression',
+    )?.text();
+  },
+  // Skip this.field.method — already handled by the DI pattern above
+  skipCallee: (callee) => callee.startsWith('this.') && callee.substring(5).includes('.'),
+};
+
 /**
  * Extract raw call sites from a TypeScript/JavaScript AST.
  * Finds DI calls (this.field.method) and direct calls ($CALLEE($$$ARGS)).
@@ -323,16 +345,6 @@ export function extractCallsFromTypeScript(root: SgRoot, fp: string, calls: RawC
     });
   }
 
-  // Direct calls: $CALLEE($$$ARGS)
-  for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
-    const callee = m.getMatch('CALLEE')?.text();
-    if (!callee || callee.startsWith('this.')) continue;
-    const callName = callee.includes('.') ? callee.split('.').pop()! : callee;
-    if (NOISE.has(callName)) continue;
-    calls.push({
-      source: fp,
-      callName,
-      line: m.range().start.line,
-    });
-  }
+  // Direct calls + self/super detection via shared function
+  extractCalls(rootNode, fp, TS_CALL_CONFIG, calls);
 }

package/src/resolver/call-resolver.ts

@@ -77,6 +77,22 @@ export function resolveAllCalls(
       }
     }
 
+    // Class-aware resolution for self.X() and super().X()
+    if (call.resolveInClass) {
+      const classResolved = resolveInClass(call.callName, fp, call.resolveInClass, symbolTable);
+      if (classResolved) {
+        callEdges.push({
+          source: fp,
+          target: classResolved.target,
+          callName: call.callName,
+          line: call.line,
+          confidence: classResolved.confidence,
+        });
+        stats[classResolved.strategy]++;
+        continue;
+      }
+    }
+
     // Name-based cascade fallback
     const resolved = resolveByName(call.callName, fp, symbolTable, importMap);
     if (resolved) {
@@ -94,6 +110,26 @@ export function resolveAllCalls(
   return { callEdges, stats };
 }
 
+// ── Class-aware resolution (self./super.) ──
+
+function resolveInClass(
+  callName: string,
+  currentFile: string,
+  className: string,
+  symbolTable: SymbolTable,
+): ResolveResult | null {
+  // Try same-file class method first (self.method() or super().method())
+  const inFile = symbolTable.lookupInFile(currentFile, callName, className);
+  if (inFile) return { target: inFile, confidence: 0.9, strategy: 'same' };
+
+  // Class might be in another file (imported parent class for super())
+  const candidates = symbolTable.lookupGlobal(callName);
+  const match = candidates.find((q) => q.includes(`::${className}.${callName}`));
+  if (match) return { target: match, confidence: 0.85, strategy: 'import' };
+
+  return null;
+}
+
 // ── DI resolution ──
 
 function resolveDICall(

package/src/resolver/symbol-table.ts

@@ -9,6 +9,7 @@
 export interface SymbolTable {
   add(file: string, name: string, qualified: string): void;
   lookupExact(file: string, name: string): string | null;
+  lookupInFile(file: string, name: string, className: string): string | null;
   isUnique(name: string): boolean;
   lookupGlobal(name: string): string[];
   readonly size: number;
@@ -16,20 +17,31 @@ export interface SymbolTable {
 }
 
 export function createSymbolTable(): SymbolTable {
-  const byFile = new Map<string, Map<string, string>>();
+  const byFile = new Map<string, Map<string, string[]>>();
   const byName = new Map<string, string[]>();
 
   return {
     add(file, name, qualified) {
       if (!byFile.has(file)) byFile.set(file, new Map());
-      byFile.get(file)!.set(name, qualified);
+      const fileMap = byFile.get(file)!;
+      if (!fileMap.has(name)) fileMap.set(name, []);
+      fileMap.get(name)!.push(qualified);
 
       if (!byName.has(name)) byName.set(name, []);
       byName.get(name)!.push(qualified);
     },
 
     lookupExact(file, name) {
-      return byFile.get(file)?.get(name) ?? null;
+      const candidates = byFile.get(file)?.get(name);
+      if (!candidates || candidates.length === 0) return null;
+      // Only return if unambiguous within this file
+      return candidates.length === 1 ? candidates[0] : null;
+    },
+
+    lookupInFile(file, name, className) {
+      const candidates = byFile.get(file)?.get(name);
+      if (!candidates || candidates.length === 0) return null;
+      return candidates.find((q) => q.includes(`::${className}.${name}`)) ?? null;
     },
 
     isUnique(name) {
@@ -42,7 +54,9 @@ export function createSymbolTable(): SymbolTable {
 
     get size() {
       let count = 0;
-      for (const m of byFile.values()) count += m.size;
+      for (const m of byFile.values()) {
+        for (const arr of m.values()) count += arr.length;
+      }
       return count;
     },
 

package/src/shared/extract-calls.ts

@@ -0,0 +1,75 @@
+import type { SgNode } from '@ast-grep/napi';
+import type { RawCallSite } from '../graph/types';
+import { NOISE } from './filters';
+
+/**
+ * Language-specific configuration for call extraction.
+ * Each language provides its self/super patterns and how to find class context in the AST.
+ */
+export interface CallExtractionConfig {
+  /** Prefixes indicating a self-reference (e.g., 'self.', 'this.') */
+  selfPrefixes: string[];
+  /** Prefixes indicating a super-reference (e.g., 'super().', 'super.', 'base.') */
+  superPrefixes: string[];
+  /** Find the enclosing class/module/impl node from a call site */
+  findEnclosingClass: (node: SgNode) => SgNode | null;
+  /** Extract the parent class name from a class node (for super resolution) */
+  getParentClass?: (classNode: SgNode) => string | undefined;
+  /** Skip this callee entirely (e.g., TS skips this.field.method — handled by DI) */
+  skipCallee?: (callee: string) => boolean;
+}
+
+/**
+ * Shared call extraction for all languages.
+ *
+ * Parses `$CALLEE($$$ARGS)` pattern, detects self/super references
+ * based on language config, and populates resolveInClass for
+ * class-aware resolution downstream.
+ */
+export function extractCalls(
+  rootNode: SgNode,
+  fp: string,
+  config: CallExtractionConfig,
+  calls: RawCallSite[],
+): void {
+  for (const m of rootNode.findAll('$CALLEE($$$ARGS)')) {
+    const callee = m.getMatch('CALLEE')?.text();
+    if (!callee) continue;
+    if (config.skipCallee?.(callee)) continue;
+
+    const callName = callee.includes('.') ? callee.split('.').pop()! : callee;
+    if (NOISE.has(callName)) continue;
+
+    let resolveInClass: string | undefined;
+
+    // Check self-reference: callee must be exactly `prefix + methodName` (no further chaining)
+    for (const prefix of config.selfPrefixes) {
+      if (!callee.startsWith(prefix)) continue;
+      const rest = callee.substring(prefix.length);
+      if (rest.includes('.')) break; // chained access (e.g., this.field.method) — not a self call
+      const classNode = config.findEnclosingClass(m);
+      resolveInClass = classNode?.field('name')?.text();
+      break;
+    }
+
+    // Check super-reference if no self match
+    if (!resolveInClass) {
+      for (const prefix of config.superPrefixes) {
+        const matches = callee === prefix || (callee.startsWith(prefix) && !callee.substring(prefix.length).includes('.'));
+        if (!matches) continue;
+        const classNode = config.findEnclosingClass(m);
+        if (classNode && config.getParentClass) {
+          resolveInClass = config.getParentClass(classNode);
+        }
+        break;
+      }
+    }
+
+    calls.push({
+      source: fp,
+      callName,
+      line: m.range().start.line,
+      ...(resolveInClass ? { resolveInClass } : {}),
+    });
+  }
+}

package/src/shared/logger.ts

@@ -1,5 +1,8 @@
 // src/shared/logger.ts
 export const log = {
+  info(msg: string, ctx?: Record<string, unknown>): void {
+    process.stderr.write(`[INFO] ${msg}${ctx ? ` ${JSON.stringify(ctx)}` : ''}\n`);
+  },
   debug(msg: string, ctx?: Record<string, unknown>): void {
     if (process.env.KODUS_GRAPH_DEBUG) {
       process.stderr.write(`[DEBUG] ${msg}${ctx ? ` ${JSON.stringify(ctx)}` : ''}\n`);