sdlc-agent-4-enterprise-server 1.0.0

package/src/engine/graph/call-graph-service.ts

@@ -0,0 +1,216 @@
+/**
+ * KSA-154: Call Graph Service - BFS traversal for callers/callees.
+ * Provides transitive call graph analysis with depth control.
+ */
+
+import { GraphRepository, CallerResult, CalleeResult } from '../database/graph-repository.js';
+import { SymbolResolver, ResolvedSymbol } from './symbol-resolver.js';
+
+export interface CallGraphItem {
+  symbol: string;
+  qualifiedName: string;
+  kind: string;
+  filePath: string;
+  definitionLine: number;
+  callSiteLine: number;
+  depthLevel: number;
+  parameters?: string | null;
+  isAsync?: boolean;
+}
+
+export interface CallGraphResponse {
+  symbol: string;
+  resolvedTo: Array<{ id: number; file: string; line: number; kind: string }>;
+  results: CallGraphItem[];
+  metadata: {
+    totalCount: number;
+    depthSearched: number;
+    truncated: boolean;
+    queryTimeMs: number;
+  };
+}
+
+export class CallGraphService {
+  private graphRepo: GraphRepository;
+  private symbolResolver: SymbolResolver;
+
+  constructor(graphRepo: GraphRepository, symbolResolver: SymbolResolver) {
+    this.graphRepo = graphRepo;
+    this.symbolResolver = symbolResolver;
+  }
+
+  /** Find all callers of a symbol with transitive depth. */
+  findCallers(
+    symbolName: string,
+    depth: number = 1,
+    limit: number = 20,
+    fileFilter?: string,
+    kindFilter: string | string[] = 'calls'
+  ): CallGraphResponse {
+    const startTime = Date.now();
+    const clampedDepth = Math.min(Math.max(depth, 1), 5);
+
+    const resolved = this.symbolResolver.resolve(symbolName);
+    if (resolved.length === 0) {
+      return this.symbolNotFoundResponse(symbolName);
+    }
+
+    // KSA-191: Support multiple kind filters (SF call types: flow-action, wire, apex-import)
+    const kinds = Array.isArray(kindFilter) ? kindFilter : [kindFilter];
+
+    const results: CallGraphItem[] = [];
+    const visited = new Set<number>();
+    const queue: Array<{ symbolName: string; depth: number }> = [];
+
+    for (const sym of resolved) {
+      queue.push({ symbolName: sym.name, depth: 0 });
+    }
+
+    while (queue.length > 0 && results.length < limit) {
+      const { symbolName: current, depth: currentDepth } = queue.shift()!;
+      if (currentDepth >= clampedDepth) continue;
+
+      // Query for each kind
+      for (const kind of kinds) {
+        const callers = this.graphRepo.findCallers(current, kind, limit - results.length);
+
+        for (const caller of callers) {
+          if (visited.has(caller.id)) continue;
+          visited.add(caller.id);
+
+          const item: CallGraphItem = {
+            symbol: caller.name,
+            qualifiedName: caller.parameters ? `${caller.parameters}.${caller.name}` : caller.name,
+            kind: caller.kind,
+            filePath: caller.file_path,
+            definitionLine: caller.def_line,
+            callSiteLine: caller.call_line,
+            depthLevel: currentDepth + 1,
+            parameters: caller.parameters,
+            isAsync: caller.is_async === 1,
+          };
+
+          if (fileFilter && !this.matchFilter(item.filePath, fileFilter)) continue;
+
+          results.push(item);
+
+          if (currentDepth + 1 < clampedDepth) {
+            queue.push({ symbolName: caller.name, depth: currentDepth + 1 });
+          }
+        }
+      }
+    }
+
+    return {
+      symbol: symbolName,
+      resolvedTo: resolved.map(s => ({ id: s.id, file: s.filePath, line: s.line, kind: s.kind })),
+      results,
+      metadata: {
+        totalCount: results.length,
+        depthSearched: clampedDepth,
+        truncated: results.length >= limit,
+        queryTimeMs: Date.now() - startTime,
+      },
+    };
+  }
+
+  /** Find all callees of a symbol with transitive depth. */
+  findCallees(
+    symbolName: string,
+    depth: number = 1,
+    limit: number = 20,
+    fileFilter?: string,
+    includeExternal: boolean = true,
+    kindFilter: string | string[] = 'calls'
+  ): CallGraphResponse {
+    const startTime = Date.now();
+    const clampedDepth = Math.min(Math.max(depth, 1), 5);
+
+    const resolved = this.symbolResolver.resolve(symbolName);
+    if (resolved.length === 0) {
+      return this.symbolNotFoundResponse(symbolName);
+    }
+
+    // KSA-191: Support multiple kind filters (SF: dml, soql, trigger-on)
+    const kinds = Array.isArray(kindFilter) ? kindFilter : [kindFilter];
+
+    const results: CallGraphItem[] = [];
+    const visited = new Set<string>();
+    const queue: Array<{ symbolId: number; depth: number }> = [];
+
+    for (const sym of resolved) {
+      queue.push({ symbolId: sym.id, depth: 0 });
+    }
+
+    while (queue.length > 0 && results.length < limit) {
+      const { symbolId, depth: currentDepth } = queue.shift()!;
+      if (currentDepth >= clampedDepth) continue;
+
+      for (const kind of kinds) {
+        const callees = this.graphRepo.findCallees(symbolId, kind, limit - results.length);
+
+        for (const callee of callees) {
+          const key = `${callee.name}:${callee.call_line}`;
+          if (visited.has(key)) continue;
+          visited.add(key);
+
+          if (!includeExternal && !callee.file_path) continue;
+
+          const item: CallGraphItem = {
+            symbol: callee.name,
+            qualifiedName: callee.name,
+            kind: callee.kind || 'unknown',
+            filePath: callee.file_path || '(external)',
+            definitionLine: callee.def_line || 0,
+            callSiteLine: callee.call_line,
+            depthLevel: currentDepth + 1,
+          };
+
+          if (fileFilter && item.filePath !== '(external)' && !this.matchFilter(item.filePath, fileFilter)) continue;
+
+          results.push(item);
+
+          if (callee.file_path && currentDepth + 1 < clampedDepth) {
+            const calleeResolved = this.symbolResolver.resolve(callee.name);
+            for (const cr of calleeResolved) {
+              if (cr.filePath === callee.file_path) {
+                queue.push({ symbolId: cr.id, depth: currentDepth + 1 });
+                break;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      symbol: symbolName,
+      resolvedTo: resolved.map(s => ({ id: s.id, file: s.filePath, line: s.line, kind: s.kind })),
+      results,
+      metadata: {
+        totalCount: results.length,
+        depthSearched: clampedDepth,
+        truncated: results.length >= limit,
+        queryTimeMs: Date.now() - startTime,
+      },
+    };
+  }
+
+  private symbolNotFoundResponse(symbolName: string): CallGraphResponse {
+    const suggestions = this.symbolResolver.suggest(symbolName);
+    return {
+      symbol: symbolName,
+      resolvedTo: [],
+      results: [],
+      metadata: { totalCount: 0, depthSearched: 0, truncated: false, queryTimeMs: 0 },
+    };
+  }
+
+  private matchFilter(filePath: string, filter: string): boolean {
+    if (filter.includes('*')) {
+      const regex = new RegExp('^' + filter.replace(/\*/g, '.*') + '$');
+      return regex.test(filePath);
+    }
+    return filePath.includes(filter);
+  }
+}

package/src/engine/graph/dependency-formatters.ts

@@ -0,0 +1,95 @@
+/**
+ * KSA-155: Dependency Formatters - tree/flat/graph output formats.
+ */
+
+import * as path from 'path';
+import { DependencyNode, DependencyResult } from './dependency-graph-service.js';
+
+export interface TreeNode {
+  file: string;
+  label: string;
+  depth: number;
+  importedSymbols: string[];
+  isExternal: boolean;
+  children: TreeNode[];
+}
+
+export function toTreeFormat(result: DependencyResult): object {
+  const { root, results } = result;
+  const byDepth = new Map<number, DependencyNode[]>();
+
+  for (const node of results) {
+    if (!byDepth.has(node.depth)) byDepth.set(node.depth, []);
+    byDepth.get(node.depth)!.push(node);
+  }
+
+  const tree: TreeNode = {
+    file: root,
+    label: path.basename(root),
+    depth: 0,
+    importedSymbols: [],
+    isExternal: false,
+    children: buildChildren(byDepth, 1),
+  };
+
+  return { root, tree, cycles: result.cycles, metadata: result.metadata };
+}
+
+function buildChildren(byDepth: Map<number, DependencyNode[]>, depth: number): TreeNode[] {
+  const nodes = byDepth.get(depth) || [];
+  return nodes.map(n => ({
+    file: n.file,
+    label: path.basename(n.file),
+    depth: n.depth,
+    importedSymbols: n.importedSymbols,
+    isExternal: n.isExternal,
+    children: buildChildren(byDepth, depth + 1),
+  }));
+}
+
+export function toFlatFormat(result: DependencyResult): object {
+  return {
+    root: result.root,
+    direction: result.direction,
+    dependencies: result.results.map(r => ({
+      file: r.file,
+      depth: r.depth,
+      importedSymbols: r.importedSymbols,
+      isExternal: r.isExternal,
+    })),
+    cycles: result.cycles,
+    metadata: result.metadata,
+  };
+}
+
+export function toGraphFormat(result: DependencyResult): object {
+  const { root, results } = result;
+  const nodes = [
+    { id: root, label: path.basename(root), depth: 0, isExternal: false },
+    ...results.map(r => ({
+      id: r.file,
+      label: path.basename(r.file),
+      depth: r.depth,
+      isExternal: r.isExternal,
+    })),
+  ];
+
+  const edges: Array<{ from: string; to: string; symbols: string[] }> = [];
+  // Build edges from results (each result is connected to root or parent at depth-1)
+  for (const r of results) {
+    if (r.depth === 1) {
+      edges.push({ from: root, to: r.file, symbols: r.importedSymbols });
+    }
+  }
+
+  return { nodes, edges, cycles: result.cycles, metadata: result.metadata };
+}
+
+export function formatDependencyResult(result: DependencyResult, format: string): object {
+  switch (format) {
+    case 'tree': return toTreeFormat(result);
+    case 'flat': return toFlatFormat(result);
+    case 'graph': return toGraphFormat(result);
+    default: return toTreeFormat(result);
+  }
+}

package/src/engine/graph/dependency-graph-service.ts

@@ -0,0 +1,236 @@
+/**
+ * KSA-155: Dependency Graph Service - BFS traversal on import relationships.
+ * Supports outgoing (what does this file import?) and incoming (who imports this file?) queries.
+ */
+
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import { FileResolver } from './file-resolver.js';
+
+export interface DependencyNode {
+  file: string;
+  depth: number;
+  importedSymbols: string[];
+  isExternal: boolean;
+}
+
+export interface DependencyResult {
+  root: string;
+  direction: string;
+  results: DependencyNode[];
+  cycles: string[][];
+  metadata: {
+    totalNodes: number;
+    maxDepthReached: number;
+    truncated: boolean;
+    queryTimeMs: number;
+    externalCount: number;
+  };
+}
+
+export class DependencyGraphService {
+  private db: Database.Database;
+  private fileResolver: FileResolver;
+
+  constructor(db: Database.Database, fileResolver: FileResolver) {
+    this.db = db;
+    this.fileResolver = fileResolver;
+  }
+
+  /** Query dependency graph with direction and depth control. */
+  query(
+    file: string,
+    direction: 'incoming' | 'outgoing' | 'both' = 'outgoing',
+    depth: number = 1,
+    includeExternal: boolean = false,
+    limit: number = 50,
+    kindFilter?: string | string[]
+  ): DependencyResult {
+    const startTime = Date.now();
+    const clampedDepth = Math.min(Math.max(depth, 1), 5);
+
+    const resolved = this.fileResolver.resolveFile(file);
+    if (!resolved) {
+      return this.fileNotFoundResponse(file);
+    }
+
+    // Determine which relationship kinds to traverse
+    const kinds = kindFilter
+      ? (Array.isArray(kindFilter) ? kindFilter : [kindFilter])
+      : undefined; // undefined = use default per direction
+
+    let results: DependencyNode[];
+    let cycles: string[][];
+
+    if (direction === 'both') {
+      const outgoing = this.bfsTraversal(resolved, 'outgoing', clampedDepth, includeExternal, limit, kinds);
+      const incoming = this.bfsTraversal(resolved, 'incoming', clampedDepth, includeExternal, limit, kinds);
+      results = this.mergeResults(outgoing.results, incoming.results);
+      cycles = [...outgoing.cycles, ...incoming.cycles];
+    } else {
+      const traversal = this.bfsTraversal(resolved, direction, clampedDepth, includeExternal, limit, kinds);
+      results = traversal.results;
+      cycles = traversal.cycles;
+    }
+
+    return {
+      root: resolved,
+      direction,
+      results,
+      cycles,
+      metadata: {
+        totalNodes: results.length,
+        maxDepthReached: Math.min(clampedDepth, Math.max(...results.map(r => r.depth), 0)),
+        truncated: results.length >= limit,
+        queryTimeMs: Date.now() - startTime,
+        externalCount: results.filter(r => r.isExternal).length,
+      },
+    };
+  }
+
+  private bfsTraversal(
+    root: string,
+    direction: 'incoming' | 'outgoing',
+    maxDepth: number,
+    includeExternal: boolean,
+    limit: number,
+    kinds?: string[]
+  ): { results: DependencyNode[]; cycles: string[][] } {
+    const visited = new Set<string>([root]);
+    const results: DependencyNode[] = [];
+    const cycles: string[][] = [];
+    const queue: Array<{ file: string; depth: number; path: string[] }> = [
+      { file: root, depth: 0, path: [root] },
+    ];
+
+    while (queue.length > 0 && results.length < limit) {
+      const { file: current, depth: currentDepth, path: currentPath } = queue.shift()!;
+      if (currentDepth >= maxDepth) continue;
+
+      const deps = direction === 'outgoing'
+        ? this.getOutgoingDeps(current, kinds)
+        : this.getIncomingDeps(current, kinds);
+
+      for (const dep of deps) {
+        const isExternal = this.fileResolver.isExternal(dep.target);
+
+        if (isExternal && !includeExternal) continue;
+
+        const resolvedTarget = isExternal
+          ? dep.target
+          : this.fileResolver.resolveImportTarget(current, dep.target);
+
+        if (!resolvedTarget) continue;
+
+        // Cycle detection
+        if (currentPath.includes(resolvedTarget)) {
+          cycles.push([...currentPath, resolvedTarget]);
+          continue;
+        }
+
+        if (!visited.has(resolvedTarget)) {
+          visited.add(resolvedTarget);
+          results.push({
+            file: resolvedTarget,
+            depth: currentDepth + 1,
+            importedSymbols: dep.symbols,
+            isExternal,
+          });
+
+          if (!isExternal && currentDepth + 1 < maxDepth) {
+            queue.push({
+              file: resolvedTarget,
+              depth: currentDepth + 1,
+              path: [...currentPath, resolvedTarget],
+            });
+          }
+        }
+      }
+    }
+
+    return { results, cycles };
+  }
+
+  private getOutgoingDeps(filePath: string, kinds?: string[]): Array<{ target: string; symbols: string[] }> {
+    // KSA-191: Support querying multiple relationship kinds (default: imports + SF kinds)
+    const queryKinds = kinds ?? ['imports', 'trigger-on', 'soql', 'dml', 'wire', 'flow-action', 'flow-object', 'apex-import', 'calls', 'inherits', 'implements'];
+    const placeholders = queryKinds.map(() => '?').join(',');
+    const rows = this.db.prepare(`
+      SELECT target_symbol, metadata, kind
+      FROM relationships
+      WHERE file_path = ? AND kind IN (${placeholders})
+      ORDER BY line
+    `).all(filePath, ...queryKinds) as { target_symbol: string; metadata: string | null; kind: string }[];
+
+    // Group by module/target
+    const grouped = new Map<string, string[]>();
+    for (const row of rows) {
+      const module = this.extractModule(row.target_symbol);
+      if (!grouped.has(module)) grouped.set(module, []);
+      const symbol = this.extractSymbolName(row.target_symbol);
+      if (symbol) grouped.get(module)!.push(symbol);
+    }
+
+    return Array.from(grouped.entries()).map(([target, symbols]) => ({ target, symbols }));
+  }
+
+  private getIncomingDeps(filePath: string, kinds?: string[]): Array<{ target: string; symbols: string[] }> {
+    const basename = path.basename(filePath, path.extname(filePath));
+    // KSA-191: Support multiple relationship kinds for incoming deps
+    const queryKinds = kinds ?? ['imports', 'trigger-on', 'soql', 'dml', 'wire', 'flow-action', 'flow-object', 'apex-import', 'calls', 'inherits', 'implements'];
+    const placeholders = queryKinds.map(() => '?').join(',');
+    const rows = this.db.prepare(`
+      SELECT DISTINCT file_path, target_symbol
+      FROM relationships
+      WHERE kind IN (${placeholders})
+        AND (target_symbol LIKE ? OR target_symbol LIKE ? OR target_symbol LIKE ?)
+    `).all(...queryKinds, `%/${basename}`, `%${basename}%`, filePath) as { file_path: string; target_symbol: string }[];
+
+    const grouped = new Map<string, string[]>();
+    for (const row of rows) {
+      if (row.file_path === filePath) continue; // Skip self
+      if (!grouped.has(row.file_path)) grouped.set(row.file_path, []);
+      grouped.get(row.file_path)!.push(this.extractSymbolName(row.target_symbol) || '*');
+    }
+
+    return Array.from(grouped.entries()).map(([target, symbols]) => ({ target, symbols }));
+  }
+
+  private extractModule(targetSymbol: string): string {
+    // target_symbol format: "module/path.symbol" or "module/path"
+    const lastDot = targetSymbol.lastIndexOf('.');
+    if (lastDot > 0 && !targetSymbol.includes('/')) return targetSymbol;
+    if (lastDot > 0) return targetSymbol.substring(0, lastDot);
+    return targetSymbol;
+  }
+
+  private extractSymbolName(targetSymbol: string): string {
+    const lastDot = targetSymbol.lastIndexOf('.');
+    if (lastDot > 0 && lastDot < targetSymbol.length - 1) {
+      return targetSymbol.substring(lastDot + 1);
+    }
+    return path.basename(targetSymbol);
+  }
+
+  private mergeResults(outgoing: DependencyNode[], incoming: DependencyNode[]): DependencyNode[] {
+    const seen = new Set<string>();
+    const merged: DependencyNode[] = [];
+    for (const node of [...outgoing, ...incoming]) {
+      if (!seen.has(node.file)) {
+        seen.add(node.file);
+        merged.push(node);
+      }
+    }
+    return merged;
+  }
+
+  private fileNotFoundResponse(file: string): DependencyResult {
+    return {
+      root: file,
+      direction: 'outgoing',
+      results: [],
+      cycles: [],
+      metadata: { totalNodes: 0, maxDepthReached: 0, truncated: false, queryTimeMs: 0, externalCount: 0 },
+    };
+  }
+}

package/src/engine/graph/file-resolver.ts

@@ -0,0 +1,102 @@
+/**
+ * KSA-155: File Resolver - resolves import paths to indexed file paths.
+ * Handles relative imports, bare specifiers, and extension resolution.
+ */
+
+import * as path from 'path';
+import Database from 'better-sqlite3';
+
+export class FileResolver {
+  private indexedFiles: Set<string>;
+  private workspaceRoot: string;
+
+  private static readonly EXTENSIONS = ['.ts', '.js', '.tsx', '.jsx', '.kt', '.py', '/index.ts', '/index.js'];
+  private static readonly STDLIB_MODULES = new Set([
+    // Node.js
+    'fs', 'path', 'http', 'https', 'url', 'crypto', 'os', 'util', 'stream', 'events',
+    'child_process', 'cluster', 'net', 'dns', 'tls', 'readline', 'zlib', 'buffer',
+    'assert', 'querystring', 'string_decoder', 'timers', 'vm', 'worker_threads',
+    // Python
+    'sys', 'json', 're', 'math', 'datetime', 'collections', 'itertools',
+    'functools', 'typing', 'pathlib', 'abc', 'dataclasses', 'enum', 'logging',
+    'unittest', 'io', 'subprocess', 'threading', 'multiprocessing',
+  ]);
+
+  constructor(db: Database.Database, workspaceRoot: string) {
+    this.workspaceRoot = workspaceRoot;
+    this.indexedFiles = this.loadIndexedFiles(db);
+  }
+
+  private loadIndexedFiles(db: Database.Database): Set<string> {
+    const rows = db.prepare('SELECT relative_path FROM files').all() as { relative_path: string }[];
+    return new Set(rows.map(r => r.relative_path));
+  }
+
+  /** Resolve an input file path to a canonical indexed path. */
+  resolveFile(input: string): string | null {
+    // Exact match on relative path
+    if (this.indexedFiles.has(input)) return input;
+
+    // Try normalizing separators
+    const normalized = input.replace(/\\/g, '/');
+    if (this.indexedFiles.has(normalized)) return normalized;
+
+    // Try stripping workspace root prefix
+    if (input.startsWith(this.workspaceRoot)) {
+      const relative = input.substring(this.workspaceRoot.length).replace(/^[/\\]/, '').replace(/\\/g, '/');
+      if (this.indexedFiles.has(relative)) return relative;
+    }
+
+    // Try with extensions
+    const withExt = this.findWithExtensions(normalized);
+    if (withExt) return withExt;
+
+    // Fuzzy: find by basename
+    const basename = path.basename(input);
+    const matches = [...this.indexedFiles].filter(f => f.endsWith(basename) || f.endsWith('/' + basename));
+    if (matches.length === 1) return matches[0];
+
+    return null;
+  }
+
+  /** Resolve an import target relative to a source file. */
+  resolveImportTarget(sourceFile: string, target: string): string | null {
+    if (target.startsWith('.')) {
+      const dir = path.dirname(sourceFile).replace(/\\/g, '/');
+      const resolved = path.posix.resolve('/' + dir, target).substring(1);
+      return this.findWithExtensions(resolved);
+    }
+
+    // Try as workspace-relative path
+    return this.findWithExtensions(target);
+  }
+
+  /** Check if a target is an external (non-project) dependency. */
+  isExternal(target: string): boolean {
+    const base = target.split('/')[0].split('.')[0];
+    if (FileResolver.STDLIB_MODULES.has(base)) return true;
+
+    // Bare specifier that doesn't start with . or /
+    if (!target.startsWith('.') && !target.startsWith('/')) {
+      const resolved = this.resolveImportTarget('', target);
+      return resolved === null;
+    }
+    return false;
+  }
+
+  /** Refresh the indexed files set (call after re-indexing). */
+  refresh(db: Database.Database): void {
+    this.indexedFiles = this.loadIndexedFiles(db);
+  }
+
+  private findWithExtensions(basePath: string): string | null {
+    // Try exact first
+    if (this.indexedFiles.has(basePath)) return basePath;
+
+    for (const ext of FileResolver.EXTENSIONS) {
+      const candidate = basePath + ext;
+      if (this.indexedFiles.has(candidate)) return candidate;
+    }
+    return null;
+  }
+}