archgraph 0.1.0

package/packages/core/src/analyze-project.js

@@ -0,0 +1,1238 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const METHOD_NAMES = new Set(['get', 'post', 'put', 'patch', 'delete']);
+const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'coverage', '.turbo', '.next']);
+
+function slug(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+}
+
+function normalizeSlashes(value) {
+  return value.replaceAll('\\', '/');
+}
+
+function joinPath(base, leaf) {
+  const baseNorm = base === '/' ? '' : base;
+  const leafNorm = leaf.startsWith('/') ? leaf : `/${leaf}`;
+  const raw = `${baseNorm}${leafNorm}`.replace(/\/+/g, '/');
+  if (raw.length > 1 && raw.endsWith('/')) {
+    return raw.slice(0, -1);
+  }
+  return raw;
+}
+
+function inferPurpose(label) {
+  const text = label.toLowerCase();
+  if (text.includes('search') || text.includes('discover') || text.includes('influencer') || text.includes('keyword')) {
+    return 'discovery';
+  }
+  if (text.includes('analysis') || text.includes('fit') || text.includes('score') || text.includes('deep')) {
+    return 'analysis';
+  }
+  if (text.includes('dm') || text.includes('email') || text.includes('outreach') || text.includes('send')) {
+    return 'outreach';
+  }
+  if (text.includes('auto') || text.includes('schedule') || text.includes('cron')) {
+    return 'automation';
+  }
+  if (text.includes('chat') || text.includes('stream') || text.includes('session')) {
+    return 'chat';
+  }
+  return null;
+}
+
+class GraphStore {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.nodes = [];
+    this.edges = [];
+    this.groups = [];
+    this.nodeKeyToId = new Map();
+    this.edgeKeySet = new Set();
+    this.groupKeySet = new Set();
+    this.idCount = 0;
+  }
+
+  #nextId(prefix) {
+    this.idCount += 1;
+    return `${prefix}:${String(this.idCount).padStart(6, '0')}`;
+  }
+
+  addNode({ kind, label, file, symbol, external = false, tags = [], meta = {}, keyHint }) {
+    const key = keyHint ?? `${kind}|${file ?? ''}|${symbol ?? ''}|${label}`;
+    const existing = this.nodeKeyToId.get(key);
+    if (existing) {
+      return existing;
+    }
+
+    const id = this.#nextId(slug(kind) || 'node');
+    this.nodeKeyToId.set(key, id);
+    this.nodes.push({
+      id,
+      kind,
+      label,
+      file,
+      symbol,
+      external,
+      tags,
+      meta,
+    });
+    return id;
+  }
+
+  addEdge({ kind, from, to, label = '', meta = {} }) {
+    if (!from || !to) return null;
+    const key = `${kind}|${from}|${to}|${label}`;
+    if (this.edgeKeySet.has(key)) return key;
+    this.edgeKeySet.add(key);
+    this.edges.push({ id: this.#nextId('edge'), kind, from, to, label: label || undefined, meta });
+    return key;
+  }
+
+  addGroup({ id, kind, name, memberNodeIds }) {
+    const key = `${kind}|${name}`;
+    if (this.groupKeySet.has(key)) return;
+    this.groupKeySet.add(key);
+    this.groups.push({ id, kind, name, memberNodeIds: [...new Set(memberNodeIds)] });
+  }
+
+  toBundle() {
+    const byKind = {};
+    const byFile = {};
+
+    for (const node of this.nodes) {
+      if (!byKind[node.kind]) byKind[node.kind] = [];
+      byKind[node.kind].push(node.id);
+
+      if (node.file) {
+        const f = normalizeSlashes(node.file);
+        if (!byFile[f]) byFile[f] = [];
+        byFile[f].push(node.id);
+      }
+    }
+
+    const strings = [...new Set(this.nodes.map((n) => n.label).concat(this.edges.map((e) => e.kind)))];
+
+    return {
+      schemaVersion: '1.1.0',
+      createdAt: new Date().toISOString(),
+      project: {
+        rootPath: this.projectPath,
+        name: basename(this.projectPath),
+      },
+      strings,
+      nodes: this.nodes,
+      edges: this.edges,
+      groups: this.groups,
+      indexes: {
+        byKind,
+        byFile,
+      },
+    };
+  }
+}
+
+async function walkFiles(root) {
+  const out = [];
+
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(join(dir, entry.name));
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = extname(entry.name);
+      if (!EXTENSIONS.has(ext)) continue;
+      out.push(join(dir, entry.name));
+    }
+  }
+
+  await walk(root);
+  out.sort();
+  return out;
+}
+
+function normalizeImportPath(specifier) {
+  return specifier.replace(/\.(js|mjs|cjs)$/, '');
+}
+
+function resolveModulePath(filePath, specifier, knownFiles) {
+  if (!specifier.startsWith('.')) return null;
+  const fromDir = dirname(filePath);
+  const base = resolve(fromDir, normalizeImportPath(specifier));
+
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}.js`,
+    `${base}.jsx`,
+    join(base, 'index.ts'),
+    join(base, 'index.tsx'),
+    join(base, 'index.js'),
+    join(base, 'index.jsx'),
+  ];
+
+  for (const candidate of candidates) {
+    if (knownFiles.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+async function loadTypeScript() {
+  const candidates = [
+    'typescript',
+    '/Users/sangsoolee/GitHub/scout-manager-backend/node_modules/typescript/lib/typescript.js',
+    '/Users/sangsoolee/GitHub/scout-manager/node_modules/typescript/lib/typescript.js',
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      if (candidate.startsWith('/')) {
+        const mod = await import(pathToFileURL(candidate).href);
+        return mod.default ?? mod;
+      }
+      const mod = await import(candidate);
+      return mod.default ?? mod;
+    } catch {
+      // continue
+    }
+  }
+
+  return null;
+}
+
+function createSourceFile(ts, filePath, text) {
+  if (!ts) return null;
+  const kind = filePath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  return ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, kind);
+}
+
+function getLiteralText(ts, node) {
+  if (!node || !ts) return null;
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  return null;
+}
+
+function getIdentifierName(ts, node) {
+  if (!node || !ts) return null;
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+    return node.name.text;
+  }
+  return null;
+}
+
+function getSourceText(sourceFile, node) {
+  if (!sourceFile || !node) return '';
+  return sourceFile.text.slice(node.getStart(sourceFile), node.end);
+}
+
+function buildLoc(ts, sourceFile, node) {
+  if (!ts || !sourceFile || !node) return null;
+  const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  const end = sourceFile.getLineAndCharacterOfPosition(node.end);
+  return {
+    startLine: start.line + 1,
+    startCol: start.character + 1,
+    endLine: end.line + 1,
+    endCol: end.character + 1,
+  };
+}
+
+function buildSignature(ts, sourceFile, node, name, kind = 'function') {
+  if (!ts || !sourceFile || !node || !name) return null;
+  const params = (node.parameters ?? [])
+    .map((param) => {
+      if (param.name && typeof param.name.getText === 'function') {
+        return param.name.getText(sourceFile);
+      }
+      return 'arg';
+    })
+    .join(', ');
+  return kind === 'method' ? `${name}(${params})` : `function ${name}(${params})`;
+}
+
+function parseImports(ts, sourceFile, filePath, knownFiles) {
+  const imports = new Map();
+  if (!ts || !sourceFile) return imports;
+
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isImportDeclaration(stmt) || !stmt.moduleSpecifier) continue;
+    const specifier = getLiteralText(ts, stmt.moduleSpecifier);
+    if (!specifier) continue;
+
+    const resolvedFile = resolveModulePath(filePath, specifier, knownFiles);
+    const external = !specifier.startsWith('.');
+
+    const clause = stmt.importClause;
+    if (!clause) continue;
+
+    if (clause.name) {
+      imports.set(clause.name.text, {
+        local: clause.name.text,
+        imported: 'default',
+        source: specifier,
+        resolvedFile,
+        external,
+      });
+    }
+
+    if (clause.namedBindings) {
+      if (ts.isNamespaceImport(clause.namedBindings)) {
+        const local = clause.namedBindings.name.text;
+        imports.set(local, {
+          local,
+          imported: '*',
+          source: specifier,
+          resolvedFile,
+          external,
+        });
+      } else if (ts.isNamedImports(clause.namedBindings)) {
+        for (const element of clause.namedBindings.elements) {
+          const local = element.name.text;
+          const imported = element.propertyName?.text ?? element.name.text;
+          imports.set(local, {
+            local,
+            imported,
+            source: specifier,
+            resolvedFile,
+            external,
+          });
+        }
+      }
+    }
+  }
+
+  return imports;
+}
+
+function parseFileSymbols(ts, sourceFile) {
+  const functionRecords = [];
+  const callRecords = [];
+  const functionRanges = [];
+  const routeMethodCalls = [];
+  const routeUseCalls = [];
+  const appObjects = new Set();
+  const routerObjects = new Set();
+
+  if (!ts || !sourceFile) {
+    return {
+      functionRecords,
+      callRecords,
+      functionRanges,
+      routeMethodCalls,
+      routeUseCalls,
+      appObjects,
+      routerObjects,
+    };
+  }
+
+  function expressionToText(node) {
+    if (!node) return '';
+    return getSourceText(sourceFile, node).replace(/\s+/g, ' ').trim().slice(0, 180);
+  }
+
+  function addFunction(name, node, kind = 'function') {
+    if (!name) return null;
+    const record = {
+      name,
+      kind,
+      start: node.pos,
+      end: node.end,
+      loc: buildLoc(ts, sourceFile, node),
+      signature: buildSignature(ts, sourceFile, node, name, kind),
+    };
+    functionRecords.push(record);
+    functionRanges.push(record);
+    return record;
+  }
+
+  function addCallRecord(from, callee, condition) {
+    if (!from || !callee) return;
+    callRecords.push({
+      from,
+      callee,
+      condition: condition
+        ? {
+            ...condition,
+            label: condition.label?.slice(0, 160),
+          }
+        : null,
+    });
+  }
+
+  function scanRouteHandlerReferences(node, knownNames) {
+    const found = new Map();
+
+    function visit(n) {
+      function maybeAdd(name, locNode = n, allowUnknown = false) {
+        if (!name || found.has(name)) return;
+        if (allowUnknown) {
+          if (!(knownNames.has(name) || /^[a-z][A-Za-z0-9_]*$/.test(name))) return;
+        } else if (!knownNames.has(name)) {
+          return;
+        }
+        found.set(name, {
+          name,
+          loc: buildLoc(ts, sourceFile, locNode),
+        });
+      }
+
+      if (ts.isIdentifier(n)) {
+        maybeAdd(n.text, n);
+      }
+      if (ts.isCallExpression(n)) {
+        const name = getIdentifierName(ts, n.expression);
+        maybeAdd(name, n.expression, true);
+      }
+      ts.forEachChild(n, visit);
+    }
+
+    visit(node);
+    return [...found.values()];
+  }
+
+  function visit(node, currentFunctionName = null, condition = null) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+      const localName = node.name.text;
+      const init = node.initializer;
+
+      if (init && ts.isCallExpression(init)) {
+        const exprName = getIdentifierName(ts, init.expression);
+        if (exprName === 'Router') routerObjects.add(localName);
+        if (exprName === 'express') appObjects.add(localName);
+      }
+
+      if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+        addFunction(localName, init, 'function');
+        visit(init, localName, condition);
+        return;
+      }
+    }
+
+    if (ts.isFunctionDeclaration(node) && node.name) {
+      addFunction(node.name.text, node, 'function');
+      if (node.body) {
+        visit(node.body, node.name.text, condition);
+      }
+      return;
+    }
+
+    if (ts.isMethodDeclaration(node) && node.name) {
+      const methodName = getIdentifierName(ts, node.name);
+      if (methodName) {
+        addFunction(methodName, node, 'method');
+        if (node.body) {
+          visit(node.body, methodName, condition);
+        }
+        return;
+      }
+    }
+
+    if (ts.isIfStatement(node)) {
+      const label = `if ${expressionToText(node.expression)}`;
+      const loc = buildLoc(ts, sourceFile, node.expression);
+      visit(node.expression, currentFunctionName, condition);
+      visit(node.thenStatement, currentFunctionName, { type: 'true', label, loc });
+      if (node.elseStatement) {
+        visit(node.elseStatement, currentFunctionName, { type: 'false', label, loc });
+      }
+      return;
+    }
+
+    if (ts.isSwitchStatement(node)) {
+      const label = `switch ${expressionToText(node.expression)}`;
+      visit(node.expression, currentFunctionName, condition);
+      for (const clause of node.caseBlock.clauses) {
+        const caseLabel = ts.isCaseClause(clause) ? expressionToText(clause.expression) : 'default';
+        const caseLoc = buildLoc(ts, sourceFile, ts.isCaseClause(clause) ? clause.expression : node.expression);
+        for (const stmt of clause.statements) {
+          visit(stmt, currentFunctionName, { type: 'case', label, caseLabel, loc: caseLoc });
+        }
+      }
+      return;
+    }
+
+    if (ts.isConditionalExpression(node)) {
+      const label = `ternary ${expressionToText(node.condition)}`;
+      const loc = buildLoc(ts, sourceFile, node.condition);
+      visit(node.condition, currentFunctionName, condition);
+      visit(node.whenTrue, currentFunctionName, { type: 'true', label, loc });
+      visit(node.whenFalse, currentFunctionName, { type: 'false', label, loc });
+      return;
+    }
+
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      const objectExpr = node.expression.expression;
+      const objectName = getIdentifierName(ts, objectExpr);
+      const methodName = getIdentifierName(ts, node.expression.name);
+
+      if (METHOD_NAMES.has(methodName)) {
+        const [pathArg, ...restArgs] = node.arguments;
+        const path = getLiteralText(ts, pathArg);
+        if (objectName && path) {
+          const knownNames = new Set(functionRecords.map((r) => r.name));
+          const handlerRefs = new Map();
+
+          function addHandlerRef(name, loc) {
+            if (!name || handlerRefs.has(name)) return;
+            handlerRefs.set(name, { name, loc });
+          }
+
+          for (const arg of restArgs) {
+            if (ts.isIdentifier(arg)) {
+              addHandlerRef(arg.text, buildLoc(ts, sourceFile, arg));
+            }
+            for (const ref of scanRouteHandlerReferences(arg, knownNames)) {
+              addHandlerRef(ref.name, ref.loc);
+            }
+          }
+
+          routeMethodCalls.push({
+            objectName,
+            method: methodName.toUpperCase(),
+            path,
+            handlers: [...handlerRefs.keys()],
+            handlerRefs: [...handlerRefs.values()],
+            loc: buildLoc(ts, sourceFile, node),
+          });
+        }
+      }
+
+      if (methodName === 'use') {
+        const [pathArg, targetArg] = node.arguments;
+        const path = getLiteralText(ts, pathArg);
+        if (objectName && path && targetArg) {
+          const target = getIdentifierName(ts, targetArg);
+          if (target) {
+            routeUseCalls.push({
+              objectName,
+              path,
+              targetIdentifier: target,
+              loc: buildLoc(ts, sourceFile, node),
+            });
+          }
+        }
+      }
+
+      if (currentFunctionName) {
+        const callee = getIdentifierName(ts, node.expression);
+        if (callee) {
+          addCallRecord(currentFunctionName, callee, condition);
+        }
+      }
+    }
+
+    if (ts.isCallExpression(node) && currentFunctionName && ts.isIdentifier(node.expression)) {
+      addCallRecord(currentFunctionName, node.expression.text, condition);
+    }
+
+    ts.forEachChild(node, (child) => visit(child, currentFunctionName, condition));
+  }
+
+  visit(sourceFile);
+
+  return {
+    functionRecords,
+    callRecords,
+    functionRanges,
+    routeMethodCalls,
+    routeUseCalls,
+    appObjects,
+    routerObjects,
+  };
+}
+
+function parseMcpTools(fileText) {
+  const toolNames = new Set();
+  const toolArrays = [...fileText.matchAll(/(?:const|export\s+const)\s+([A-Z0-9_]*TOOLS)\s*=\s*\[([\s\S]*?)\]/g)];
+  for (const match of toolArrays) {
+    const body = match[2] ?? '';
+    for (const entry of body.matchAll(/['"`]([^'"`]+)['"`]/g)) {
+      toolNames.add(entry[1]);
+    }
+  }
+
+  const callToolMatches = [...fileText.matchAll(/\.callTool(?:<[^>]+>)?\(\s*['"`]([^'"`]+)['"`]/g)];
+  for (const match of callToolMatches) {
+    toolNames.add(match[1]);
+  }
+
+  return {
+    tools: [...toolNames],
+    callMatches: callToolMatches.map((m) => ({ tool: m[1], index: m.index ?? 0 })),
+  };
+}
+
+function parseLangGraph(fileText) {
+  const nodes = new Set();
+  const edges = [];
+
+  for (const match of fileText.matchAll(/\.addNode\(\s*['"`]([^'"`]+)['"`]/g)) {
+    nodes.add(match[1]);
+  }
+
+  for (const match of fileText.matchAll(/\.addEdge\(\s*([^,]+?)\s*,\s*([^)]+?)\)/g)) {
+    const rawFrom = match[1].trim();
+    const rawTo = match[2].trim();
+
+    const from = rawFrom.replace(/^['"`]|['"`]$/g, '');
+    const to = rawTo.replace(/^['"`]|['"`]$/g, '');
+
+    if (from && from !== 'START' && from !== 'END') nodes.add(from);
+    if (to && to !== 'START' && to !== 'END') nodes.add(to);
+    if (from && to && from !== 'START' && to !== 'END') {
+      edges.push({ from, to });
+    }
+  }
+
+  for (const match of fileText.matchAll(/\.addConditionalEdges\(\s*['"`]([^'"`]+)['"`][\s\S]*?\{([\s\S]*?)\}\s*\)/g)) {
+    const from = match[1];
+    const body = match[2] ?? '';
+    nodes.add(from);
+
+    for (const m of body.matchAll(/([A-Za-z0-9_]+)\s*:\s*['"`]([^'"`]+)['"`]/g)) {
+      const to = m[2];
+      if (to === '__end__' || to === 'END') continue;
+      nodes.add(to);
+      edges.push({ from, to });
+    }
+  }
+
+  return {
+    nodes: [...nodes],
+    edges,
+  };
+}
+
+function buildAdjacency(edges) {
+  const map = new Map();
+  for (const edge of edges) {
+    if (!map.has(edge.from)) map.set(edge.from, []);
+    map.get(edge.from).push(edge.to);
+  }
+  return map;
+}
+
+function collectReachable(start, adjacency, maxDepth = 4) {
+  const seen = new Set();
+  const queue = [{ id: start, depth: 0 }];
+  while (queue.length) {
+    const { id, depth } = queue.shift();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (depth >= maxDepth) continue;
+    const next = adjacency.get(id) ?? [];
+    for (const n of next) {
+      if (!seen.has(n)) queue.push({ id: n, depth: depth + 1 });
+    }
+  }
+  return seen;
+}
+
+export async function analyzeProject(options) {
+  const projectPath = resolve(options.projectPath);
+  const ts = await loadTypeScript();
+  const files = await walkFiles(projectPath);
+  const knownFiles = new Set(files);
+
+  const graph = new GraphStore(projectPath);
+
+  const importMapByFile = new Map();
+  const fileInfoByFile = new Map();
+  const fileNodeByFile = new Map();
+  const moduleNodeByFile = new Map();
+
+  const functionNodeByFileAndName = new Map();
+  const functionNodeByName = new Map();
+  const functionCallsById = new Map();
+  const functionMetaById = new Map();
+
+  const routeMethods = [];
+  const routeUses = [];
+  const appObjectsByFile = new Map();
+  const routerObjectsByFile = new Map();
+
+  const langgraphNodeIds = new Map();
+  const mcpToolNodeIds = new Map();
+
+  for (const filePath of files) {
+    const fileText = await readFile(filePath, 'utf8');
+    const sourceFile = createSourceFile(ts, filePath, fileText);
+
+    const relFile = normalizeSlashes(relative(projectPath, filePath));
+    const fileNode = graph.addNode({
+      kind: 'file',
+      label: relFile,
+      file: relFile,
+      symbol: relFile,
+      keyHint: `file|${relFile}`,
+    });
+
+    const moduleNode = graph.addNode({
+      kind: 'module',
+      label: relFile,
+      file: relFile,
+      symbol: relFile,
+      keyHint: `module|${relFile}`,
+    });
+
+    fileNodeByFile.set(filePath, fileNode);
+    moduleNodeByFile.set(filePath, moduleNode);
+
+    const imports = parseImports(ts, sourceFile, filePath, knownFiles);
+    importMapByFile.set(filePath, imports);
+
+    const parsed = parseFileSymbols(ts, sourceFile);
+    fileInfoByFile.set(filePath, {
+      ...parsed,
+      text: fileText,
+      relFile,
+    });
+
+    appObjectsByFile.set(filePath, parsed.appObjects);
+    routerObjectsByFile.set(filePath, parsed.routerObjects);
+
+    const byName = new Map();
+    functionNodeByFileAndName.set(filePath, byName);
+
+    for (const fn of parsed.functionRecords) {
+      const kind = fn.kind === 'method' ? 'method' : 'function';
+      const nodeId = graph.addNode({
+        kind,
+        label: fn.name,
+        file: relFile,
+        symbol: fn.name,
+        meta: {
+          loc: fn.loc ?? undefined,
+          signature: fn.signature ?? undefined,
+        },
+        keyHint: `${kind}|${relFile}|${fn.name}`,
+      });
+      byName.set(fn.name, nodeId);
+      if (!functionNodeByName.has(fn.name)) functionNodeByName.set(fn.name, new Set());
+      functionNodeByName.get(fn.name).add(nodeId);
+      functionMetaById.set(nodeId, {
+        name: fn.name,
+        file: filePath,
+        loc: fn.loc ?? null,
+        signature: fn.signature ?? null,
+        kind,
+      });
+      graph.addEdge({ kind: 'imports', from: moduleNode, to: nodeId, label: 'declares' });
+    }
+
+    for (const call of parsed.callRecords) {
+      const fromNode = byName.get(call.from);
+      if (!fromNode) continue;
+      if (!functionCallsById.has(fromNode)) functionCallsById.set(fromNode, []);
+      functionCallsById.get(fromNode).push(call);
+    }
+
+    for (const route of parsed.routeMethodCalls) {
+      routeMethods.push({ ...route, filePath });
+    }
+
+    for (const useCall of parsed.routeUseCalls) {
+      routeUses.push({ ...useCall, filePath });
+    }
+
+    const langgraph = parseLangGraph(fileText);
+    for (const name of langgraph.nodes) {
+      const nodeId = graph.addNode({
+        kind: 'langgraph_node',
+        label: name,
+        file: relFile,
+        symbol: name,
+        keyHint: `langgraph_node|${relFile}|${name}`,
+      });
+      langgraphNodeIds.set(`${relFile}:${name}`, nodeId);
+    }
+    for (const edge of langgraph.edges) {
+      const from = graph.addNode({
+        kind: 'langgraph_node',
+        label: edge.from,
+        file: relFile,
+        symbol: edge.from,
+        keyHint: `langgraph_node|${relFile}|${edge.from}`,
+      });
+      const to = graph.addNode({
+        kind: 'langgraph_node',
+        label: edge.to,
+        file: relFile,
+        symbol: edge.to,
+        keyHint: `langgraph_node|${relFile}|${edge.to}`,
+      });
+      graph.addEdge({ kind: 'langgraph_edge', from, to, label: `${edge.from}->${edge.to}` });
+    }
+
+    const mcp = parseMcpTools(fileText);
+    for (const tool of mcp.tools) {
+      const nodeId = graph.addNode({
+        kind: 'mcp_tool',
+        label: tool,
+        file: relFile,
+        symbol: tool,
+        keyHint: `mcp_tool|${tool}`,
+      });
+      mcpToolNodeIds.set(tool, nodeId);
+    }
+
+    for (const callMatch of mcp.callMatches) {
+      const fnInRange = parsed.functionRanges.find((range) => callMatch.index >= range.start && callMatch.index <= range.end);
+      const fromId = fnInRange ? byName.get(fnInRange.name) : moduleNode;
+      const toId = mcpToolNodeIds.get(callMatch.tool);
+      if (fromId && toId) {
+        graph.addEdge({ kind: 'uses_mcp_tool', from: fromId, to: toId });
+      }
+    }
+  }
+
+  function resolveFunctionNode(filePath, name) {
+    function pickKnownByName() {
+      const candidates = functionNodeByName.get(name);
+      if (!candidates || !candidates.size) return null;
+      if (candidates.size === 1) return [...candidates][0];
+
+      const ranked = [...candidates].sort((a, b) => {
+        const aFile = functionMetaById.get(a)?.file ?? '';
+        const bFile = functionMetaById.get(b)?.file ?? '';
+        const aAgents = aFile.includes('/packages/agents/') ? 0 : 1;
+        const bAgents = bFile.includes('/packages/agents/') ? 0 : 1;
+        if (aAgents !== bAgents) return aAgents - bAgents;
+        return aFile.localeCompare(bFile);
+      });
+      return ranked[0] ?? null;
+    }
+
+    const byName = functionNodeByFileAndName.get(filePath);
+    if (byName?.has(name)) return byName.get(name);
+
+    const imports = importMapByFile.get(filePath);
+    const imported = imports?.get(name);
+    if (imported?.resolvedFile) {
+      const importedMap = functionNodeByFileAndName.get(imported.resolvedFile);
+      if (imported.imported === 'default') {
+        // default export handler not resolved symbolically; fallback to same local name
+        if (importedMap?.has(name)) return importedMap.get(name);
+      }
+      if (importedMap?.has(imported.imported)) return importedMap.get(imported.imported);
+      if (importedMap?.has(name)) return importedMap.get(name);
+    }
+
+    if (imported?.external && imported.source === '@repo/agents') {
+      const known = pickKnownByName();
+      if (known) return known;
+
+      const externalFn = graph.addNode({
+        kind: 'function',
+        label: name,
+        file: imported.source,
+        symbol: name,
+        external: true,
+        keyHint: `function|${imported.source}|${name}`,
+      });
+
+      const agentNode = graph.addNode({
+        kind: 'agent',
+        label: name,
+        file: imported.source,
+        symbol: name,
+        external: true,
+        keyHint: `agent|${imported.source}|${name}`,
+      });
+      graph.addEdge({ kind: 'invokes_agent', from: externalFn, to: agentNode });
+      return externalFn;
+    }
+
+    const known = pickKnownByName();
+    if (known) return known;
+
+    return null;
+  }
+
+  const conditionNodeByFunctionKey = new Map();
+
+  function ensureConditionNode(fromId, fromMeta, condition) {
+    const key = `${fromId}|${condition.type}|${condition.label}|${condition.caseLabel ?? ''}`;
+    if (conditionNodeByFunctionKey.has(key)) return conditionNodeByFunctionKey.get(key);
+
+    const relFile = fromMeta?.file ? normalizeSlashes(relative(projectPath, fromMeta.file)) : undefined;
+    const conditionNodeId = graph.addNode({
+      kind: 'condition',
+      label: condition.caseLabel ? `${condition.label} :: ${condition.caseLabel}` : condition.label,
+      file: relFile,
+      symbol: condition.label,
+      meta: {
+        loc: condition.loc ?? undefined,
+        branchType: condition.type,
+        caseLabel: condition.caseLabel ?? undefined,
+      },
+      keyHint: `condition|${fromId}|${condition.type}|${condition.label}|${condition.caseLabel ?? ''}`,
+    });
+    conditionNodeByFunctionKey.set(key, conditionNodeId);
+    graph.addEdge({ kind: 'evaluates_condition', from: fromId, to: conditionNodeId, label: condition.label });
+    return conditionNodeId;
+  }
+
+  // Resolve call graph edges (direct)
+  for (const [fromId, callEntries] of functionCallsById.entries()) {
+    const fromMeta = functionMetaById.get(fromId);
+    if (!fromMeta) continue;
+    for (const callEntry of callEntries) {
+      const calleeName = callEntry.callee;
+      const toId = resolveFunctionNode(fromMeta.file, calleeName);
+      if (!toId) continue;
+      graph.addEdge({ kind: 'calls', from: fromId, to: toId, label: calleeName });
+
+      if (callEntry.condition?.label) {
+        const conditionNodeId = ensureConditionNode(fromId, fromMeta, callEntry.condition);
+        const conditionalKind =
+          callEntry.condition.type === 'case'
+            ? 'condition_case'
+            : callEntry.condition.type === 'false'
+              ? 'condition_false'
+              : 'condition_true';
+        graph.addEdge({
+          kind: conditionalKind,
+          from: conditionNodeId,
+          to: toId,
+          label: callEntry.condition.caseLabel ?? calleeName,
+        });
+      }
+
+      const imports = importMapByFile.get(fromMeta.file);
+      if (imports?.get(calleeName)?.external && imports.get(calleeName).source === '@repo/agents') {
+        const agentNode = graph.addNode({
+          kind: 'agent',
+          label: calleeName,
+          file: '@repo/agents',
+          symbol: calleeName,
+          external: true,
+          keyHint: `agent|@repo/agents|${calleeName}`,
+        });
+        graph.addEdge({ kind: 'invokes_agent', from: fromId, to: agentNode });
+      }
+    }
+  }
+
+  // Resolve import relations between modules
+  for (const [filePath, imports] of importMapByFile.entries()) {
+    const fromModule = moduleNodeByFile.get(filePath);
+    for (const imported of imports.values()) {
+      if (!fromModule) continue;
+      if (imported.resolvedFile) {
+        const toModule = moduleNodeByFile.get(imported.resolvedFile);
+        if (toModule) {
+          graph.addEdge({ kind: 'imports', from: fromModule, to: toModule, label: imported.source });
+        }
+      }
+    }
+  }
+
+  const methodByFileObject = new Map();
+  const useByFileObject = new Map();
+
+  for (const method of routeMethods) {
+    const key = `${method.filePath}|${method.objectName}`;
+    if (!methodByFileObject.has(key)) methodByFileObject.set(key, []);
+    methodByFileObject.get(key).push(method);
+  }
+
+  for (const useCall of routeUses) {
+    const key = `${useCall.filePath}|${useCall.objectName}`;
+    if (!useByFileObject.has(key)) useByFileObject.set(key, []);
+    useByFileObject.get(key).push(useCall);
+  }
+
+  const endpointNodes = [];
+  const routeHandlerNodeByKey = new Map();
+  const routeHandlerToFunction = new Map();
+
+  function ensureRouteHandlerNode(name, filePath, meta = null) {
+    const relFile = normalizeSlashes(relative(projectPath, filePath));
+    const key = `${relFile}|${name}`;
+    if (routeHandlerNodeByKey.has(key)) return routeHandlerNodeByKey.get(key);
+    const nodeId = graph.addNode({
+      kind: 'route_handler',
+      label: name,
+      file: relFile,
+      symbol: name,
+      meta: {
+        loc: meta?.loc ?? undefined,
+        signature: `function ${name}(...)`,
+      },
+      keyHint: `route_handler|${relFile}|${name}`,
+    });
+    routeHandlerNodeByKey.set(key, nodeId);
+
+    const functionId = resolveFunctionNode(filePath, name);
+    if (functionId) {
+      routeHandlerToFunction.set(nodeId, functionId);
+    }
+    return nodeId;
+  }
+
+  function resolveImportedRouterFile(filePath, targetIdentifier) {
+    const imports = importMapByFile.get(filePath);
+    const imp = imports?.get(targetIdentifier);
+    if (imp?.resolvedFile) return imp.resolvedFile;
+
+    // Heuristic for dynamically imported `routes` module pattern:
+    // const routes = routesModule.default; app.use('/api', routes);
+    if (targetIdentifier === 'routes') {
+      const directory = dirname(filePath);
+      const candidates = [
+        join(directory, 'routes', 'index.ts'),
+        join(directory, 'routes', 'index.tsx'),
+        join(directory, 'routes', 'index.js'),
+        join(directory, 'routes', 'index.jsx'),
+      ];
+      for (const candidate of candidates) {
+        if (knownFiles.has(candidate)) return candidate;
+      }
+    }
+    return null;
+  }
+
+  function pickPrimaryRouterObject(filePath) {
+    const routerSet = routerObjectsByFile.get(filePath);
+    if (routerSet && routerSet.size) return [...routerSet][0];
+
+    for (const method of routeMethods) {
+      if (method.filePath === filePath) return method.objectName;
+    }
+    return 'router';
+  }
+
+  function expandMountedRoutes(filePath, objectName, prefix, seen = new Set()) {
+    const contextKey = `${filePath}|${objectName}|${prefix}`;
+    if (seen.has(contextKey)) return;
+    seen.add(contextKey);
+
+    const methodKey = `${filePath}|${objectName}`;
+    const methods = methodByFileObject.get(methodKey) ?? [];
+    for (const method of methods) {
+      const fullPath = joinPath(prefix, method.path);
+      const endpointLabel = `${method.method} ${fullPath}`;
+      const relFile = normalizeSlashes(relative(projectPath, filePath));
+
+      const endpointId = graph.addNode({
+        kind: 'endpoint',
+        label: endpointLabel,
+        file: relFile,
+        symbol: endpointLabel,
+        meta: {
+          loc: method.loc ?? undefined,
+          signature: endpointLabel,
+        },
+        keyHint: `endpoint|${endpointLabel}`,
+      });
+      endpointNodes.push(endpointId);
+      graph.addEdge({ kind: 'declares_endpoint', from: fileNodeByFile.get(filePath), to: endpointId });
+
+      const handlerRefs = method.handlerRefs?.length
+        ? method.handlerRefs
+        : method.handlers.map((name) => ({ name, loc: method.loc ?? null }));
+      for (const handlerRef of handlerRefs) {
+        const handler = handlerRef.name;
+        const routeHandlerId = ensureRouteHandlerNode(handler, filePath, handlerRef);
+        if (routeHandlerId) {
+          graph.addEdge({ kind: 'handles', from: endpointId, to: routeHandlerId, label: handler });
+        }
+
+        const functionId = resolveFunctionNode(filePath, handler);
+        if (functionId) {
+          graph.addEdge({ kind: 'handles', from: endpointId, to: functionId, label: handler });
+
+          const imports = importMapByFile.get(filePath);
+          if (imports?.get(handler)?.source === '@repo/agents') {
+            const agentNode = graph.addNode({
+              kind: 'agent',
+              label: handler,
+              file: '@repo/agents',
+              symbol: handler,
+              external: true,
+              keyHint: `agent|@repo/agents|${handler}`,
+            });
+            graph.addEdge({ kind: 'invokes_agent', from: functionId, to: agentNode });
+          }
+        }
+      }
+    }
+
+    const uses = useByFileObject.get(methodKey) ?? [];
+    for (const useCall of uses) {
+      const nextPrefix = joinPath(prefix, useCall.path);
+      const targetFile = resolveImportedRouterFile(filePath, useCall.targetIdentifier);
+      if (!targetFile) continue;
+      const targetObject = pickPrimaryRouterObject(targetFile);
+      expandMountedRoutes(targetFile, targetObject, nextPrefix, seen);
+    }
+  }
+
+  for (const [filePath, appObjects] of appObjectsByFile.entries()) {
+    for (const appObject of appObjects) {
+      expandMountedRoutes(filePath, appObject, '');
+    }
+  }
+
+  // Fallback for router-only projects
+  if (!endpointNodes.length) {
+    for (const [filePath, routerObjects] of routerObjectsByFile.entries()) {
+      for (const routerObject of routerObjects) {
+        expandMountedRoutes(filePath, routerObject, '');
+      }
+    }
+  }
+
+  // Transitive call edges
+  const directCallEdges = graph.edges.filter((edge) => edge.kind === 'calls');
+  const adjacency = buildAdjacency(directCallEdges);
+
+  for (const [fromId] of functionCallsById.entries()) {
+    const seen = collectReachable(fromId, adjacency, 5);
+    for (const toId of seen) {
+      if (toId === fromId) continue;
+      graph.addEdge({ kind: 'calls', from: fromId, to: toId, label: 'transitive' });
+    }
+  }
+
+  // Route handler call expansion
+  for (const [routeHandlerId, functionId] of routeHandlerToFunction.entries()) {
+    graph.addEdge({ kind: 'calls', from: routeHandlerId, to: functionId, label: 'handler_impl' });
+    const reachable = collectReachable(functionId, adjacency, 5);
+    for (const targetId of reachable) {
+      if (targetId === functionId) continue;
+      graph.addEdge({ kind: 'calls', from: routeHandlerId, to: targetId, label: 'transitive' });
+    }
+  }
+
+  // Phase 2 frontend adapter
+  if (options.includeFrontend) {
+    const frontendRoot = options.frontendPath ? resolve(options.frontendPath) : null;
+    if (frontendRoot) {
+      const frontendRouteFile = join(frontendRoot, 'app', 'routes.ts');
+      try {
+        const text = await readFile(frontendRouteFile, 'utf8');
+        const rel = normalizeSlashes(relative(projectPath, frontendRouteFile));
+        const moduleNode = graph.addNode({
+          kind: 'module',
+          label: rel,
+          file: rel,
+          symbol: rel,
+          keyHint: `module|${rel}`,
+        });
+
+        for (const match of text.matchAll(/route\(\s*['"`]([^'"`]+)['"`],\s*['"`]([^'"`]+)['"`]/g)) {
+          const path = `/${match[1].replace(/^\//, '')}`;
+          const targetFile = match[2];
+          const uiRoute = graph.addNode({
+            kind: 'ui_route',
+            label: path,
+            file: rel,
+            symbol: path,
+            keyHint: `ui_route|${path}`,
+          });
+          const component = graph.addNode({
+            kind: 'ui_component',
+            label: targetFile,
+            file: rel,
+            symbol: targetFile,
+            keyHint: `ui_component|${targetFile}`,
+          });
+          graph.addEdge({ kind: 'imports', from: moduleNode, to: uiRoute });
+          graph.addEdge({ kind: 'imports', from: uiRoute, to: component, label: 'renders' });
+        }
+      } catch {
+        // ignore frontend adapter failures in backend-first mode
+      }
+    }
+  }
+
+  // Grouping
+  const graphAdj = buildAdjacency(graph.edges);
+
+  const endpointNodeList = graph.nodes.filter((n) => n.kind === 'endpoint');
+  for (const endpoint of endpointNodeList) {
+    const members = [...collectReachable(endpoint.id, graphAdj, 3)];
+    const groupId = graph.addNode({
+      kind: 'group',
+      label: endpoint.label,
+      symbol: endpoint.label,
+      keyHint: `group|endpoint|${endpoint.label}`,
+    });
+    graph.addGroup({
+      id: groupId,
+      kind: 'endpoint',
+      name: endpoint.label,
+      memberNodeIds: members,
+    });
+    for (const memberId of members) {
+      graph.addEdge({ kind: 'belongs_to_group', from: memberId, to: groupId, label: 'endpoint' });
+    }
+  }
+
+  const agentNodes = graph.nodes.filter((n) => n.kind === 'agent');
+  for (const agent of agentNodes) {
+    const members = [...collectReachable(agent.id, graphAdj, 2)];
+    const groupId = graph.addNode({
+      kind: 'group',
+      label: agent.label,
+      symbol: agent.label,
+      keyHint: `group|agent|${agent.label}`,
+    });
+    graph.addGroup({
+      id: groupId,
+      kind: 'agent',
+      name: agent.label,
+      memberNodeIds: members,
+    });
+    for (const memberId of members) {
+      graph.addEdge({ kind: 'belongs_to_group', from: memberId, to: groupId, label: 'agent' });
+    }
+  }
+
+  const purposeBuckets = new Map();
+  for (const node of graph.nodes) {
+    if (node.kind === 'group') continue;
+    const purpose = inferPurpose(node.label);
+    if (!purpose) continue;
+    if (!purposeBuckets.has(purpose)) purposeBuckets.set(purpose, new Set());
+    purposeBuckets.get(purpose).add(node.id);
+  }
+
+  for (const [purpose, nodeSet] of purposeBuckets.entries()) {
+    const members = [...nodeSet];
+    const groupId = graph.addNode({
+      kind: 'group',
+      label: purpose,
+      symbol: purpose,
+      keyHint: `group|purpose|${purpose}`,
+    });
+    graph.addGroup({
+      id: groupId,
+      kind: 'purpose',
+      name: purpose,
+      memberNodeIds: members,
+    });
+    for (const memberId of members) {
+      graph.addEdge({ kind: 'belongs_to_group', from: memberId, to: groupId, label: 'purpose' });
+    }
+  }
+
+  return graph.toBundle();
+}