@ashkand/code-graph-mcp 0.2.2

package/src/indexer.js

@@ -0,0 +1,434 @@
+// Indexer: walks the repo, parses files, builds the Graph, persists manifest
+// for incremental re-index (spec R1, R2).
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { Graph } from "./graph.js";
+import { parseJsTs, parsePython, normalizeEndpoint } from "./parsers.js";
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".venv", "venv",
+  "__pycache__", ".codegraph", "coverage", ".turbo", ".cache", "out",
+]);
+const JS_EXT = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
+const PY_EXT = new Set([".py"]);
+const MAX_FILE_BYTES = 1_500_000;
+
+export function walkFiles(root) {
+  const files = [];
+  (function walk(dir) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith(".") && e.name !== ".env.example") {
+        if (e.isDirectory()) continue;
+      }
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(full);
+      } else if (e.isFile()) {
+        files.push(full);
+      }
+    }
+  })(root);
+  return files;
+}
+
+function hashFile(full) {
+  return crypto.createHash("sha1").update(fs.readFileSync(full)).digest("hex");
+}
+
+function detectPackages(root, allFiles) {
+  const pkgs = [];
+  for (const f of allFiles) {
+    const base = path.basename(f);
+    if (!["package.json", "pyproject.toml", "requirements.txt"].includes(base)) continue;
+    const dir = path.dirname(f);
+    const rel = path.relative(root, dir) || ".";
+    let name = path.basename(dir === root ? root : dir);
+    let deps = [];
+    let kind = base === "package.json" ? "node" : "python";
+    try {
+      if (base === "package.json") {
+        const pj = JSON.parse(fs.readFileSync(f, "utf8"));
+        name = pj.name ?? name;
+        deps = Object.keys({ ...pj.dependencies }).slice(0, 20);
+        if (pj.workspaces) kind = "node-workspace-root";
+      } else if (base === "pyproject.toml") {
+        const src = fs.readFileSync(f, "utf8");
+        name = src.match(/^name\s*=\s*["']([^"']+)["']/m)?.[1] ?? name;
+        deps = [...src.matchAll(/^\s*["']?([A-Za-z][\w.-]+)["']?\s*(?:[><=~^].*)?,?\s*$/gm)]
+          .map((m) => m[1]).filter((d) => !["dependencies", "project", "name", "version", "python"].includes(d)).slice(0, 20);
+      } else {
+        deps = fs.readFileSync(f, "utf8").split("\n")
+          .map((l) => l.trim().split(/[><=~;[\s]/)[0]).filter(Boolean).filter((l) => !l.startsWith("#")).slice(0, 20);
+      }
+    } catch { /* unparseable manifest: keep defaults */ }
+    // avoid duplicate package per dir (pyproject + requirements)
+    if (!pkgs.some((p) => p.dir === rel)) pkgs.push({ dir: rel, name, kind, deps });
+    else pkgs.find((p) => p.dir === rel).deps.push(...deps);
+  }
+  return pkgs;
+}
+
+function pkgFor(pkgs, rel) {
+  let best = null;
+  for (const p of pkgs) {
+    if (p.dir === "." || rel === p.dir || rel.startsWith(p.dir + "/")) {
+      if (!best || p.dir.length > best.dir.length) best = p;
+    }
+  }
+  return best;
+}
+
+// Resolve a relative import spec against the importing file. Returns rel path or null.
+function resolveImport(root, fromRel, spec) {
+  if (!spec.startsWith(".")) return null; // package import
+  const baseDir = path.dirname(fromRel);
+  const target = path.normalize(path.join(baseDir, spec));
+  const candidates = [
+    target,
+    ...[".ts", ".tsx", ".js", ".jsx", ".mjs", ".py"].map((e) => target + e),
+    ...["index.ts", "index.tsx", "index.js", "index.jsx"].map((i) => path.join(target, i)),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(root, c)) && fs.statSync(path.join(root, c)).isFile()) {
+      return c.split(path.sep).join("/");
+    }
+  }
+  return null;
+}
+
+// ---------- per-file parsing into graph fragments ----------
+function indexFile(graph, root, rel, pkgs, warnings) {
+  const full = path.join(root, rel);
+  const ext = path.extname(rel).toLowerCase();
+  if (!JS_EXT.has(ext) && !PY_EXT.has(ext)) return;
+  let src, bytes = 0;
+  try {
+    const st = fs.statSync(full);
+    if (st.size > MAX_FILE_BYTES) { warnings.push(`${rel}: too large, skipped`); return; }
+    bytes = st.size;
+    src = fs.readFileSync(full, "utf8");
+  } catch (e) { warnings.push(`${rel}: unreadable (${e.code ?? e.message})`); return; }
+
+  const fileId = `file:${rel}`;
+  graph.addNode({ id: fileId, type: "file", name: path.basename(rel), file: rel, extra: { bytes } });
+  const pkg = pkgFor(pkgs, rel);
+  if (pkg) graph.addEdge(`package:${pkg.dir}`, fileId, "contains");
+
+  try {
+    if (JS_EXT.has(ext)) indexJsFile(graph, root, rel, fileId, src);
+    else indexPyFile(graph, rel, fileId, src);
+  } catch (e) {
+    warnings.push(`${rel}: parse error (${e.message})`);
+  }
+}
+
+function indexJsFile(graph, root, rel, fileId, src) {
+  const parsed = parseJsTs(rel, src);
+
+  for (const spec of parsed.imports) {
+    const target = resolveImport(root, rel, spec);
+    if (target) {
+      const tid = `file:${target}`;
+      if (!graph.nodes.has(tid)) graph.addNode({ id: tid, type: "file", name: path.basename(target), file: target });
+      graph.addEdge(fileId, tid, "imports");
+    }
+  }
+
+  for (const comp of parsed.components) {
+    const cid = `component:${rel}#${comp}`;
+    graph.addNode({ id: cid, type: "component", name: comp, file: rel });
+    graph.addEdge(fileId, cid, "contains");
+  }
+  // rendered children + hooks: resolved to nodes in the link phase (names may live in other files)
+  graph._pendingRenders ??= [];
+  for (const comp of parsed.components) {
+    for (const child of parsed.rendered ?? []) {
+      if (child !== comp) graph._pendingRenders.push({ from: `component:${rel}#${comp}`, name: child, type: "renders" });
+    }
+    for (const hook of parsed.hooks ?? []) {
+      graph._pendingRenders.push({ from: `component:${rel}#${comp}`, name: hook, type: "uses" });
+    }
+  }
+
+  for (const r of parsed.routes) {
+    const rid = `route:${r.path}`;
+    graph.addNode({ id: rid, type: "route", name: r.path, file: rel, extra: { component: r.component } });
+    if (r.component) graph._pendingRenders.push({ from: rid, name: r.component, type: "renders" });
+  }
+
+  parsed.calls.forEach((c, i) => {
+    const eid = `endpoint-call:${rel}#${i}:${c.method} ${c.normPath}`;
+    graph.addNode({ id: eid, type: "endpoint-call", name: `${c.method} ${c.normPath}`, file: rel, extra: { method: c.method, raw: c.raw, normPath: c.normPath } });
+    graph.addEdge(fileId, eid, "contains");
+    // attribute the call to components in the same file (best-effort)
+    for (const comp of parsed.components) graph.addEdge(`component:${rel}#${comp}`, eid, "calls");
+  });
+
+  for (const ar of parsed.apiRoutes) {
+    addApiRoute(graph, rel, fileId, ar, ""); // express mounts resolved in link phase
+  }
+  if (parsed.mounts?.length) {
+    graph._mounts ??= [];
+    for (const m of parsed.mounts) graph._mounts.push({ file: rel, ...m });
+  }
+}
+
+function indexPyFile(graph, rel, fileId, src) {
+  const parsed = parsePython(rel, src);
+  graph._pyIncludes ??= [];
+  graph._pyImports ??= {};
+  graph._pyImports[rel] = parsed.pyImports;
+  for (const inc of parsed.includes) graph._pyIncludes.push({ file: rel, ...inc });
+  for (const ar of parsed.apiRoutes) {
+    const localPrefix = parsed.routerPrefixes[ar.routerVar] ?? "";
+    addApiRoute(graph, rel, fileId, ar, localPrefix);
+  }
+}
+
+function addApiRoute(graph, rel, fileId, ar, prefix) {
+  const fullPath = joinPaths(prefix, ar.path);
+  const norm = normalizeEndpoint(fullPath);
+  const rid = `api-route:${ar.method} ${norm}@${rel}`;
+  graph.addNode({
+    id: rid, type: "api-route", name: `${ar.method} ${fullPath}`, file: rel,
+    extra: { method: ar.method, path: fullPath, normPath: norm, framework: ar.framework, routerVar: ar.routerVar ?? null, rawPath: ar.path },
+  });
+  graph.addEdge(fileId, rid, "contains");
+  if (ar.handler) {
+    const hid = `handler:${rel}#${ar.handler}`;
+    if (!graph.nodes.has(hid)) graph.addNode({ id: hid, type: "handler", name: ar.handler, file: rel });
+    graph.addEdge(rid, hid, "handled-by");
+  }
+}
+
+export function joinPaths(a, b) {
+  const joined = `${a ?? ""}/${b ?? ""}`.replace(/\/{2,}/g, "/");
+  return joined === "" ? "/" : joined;
+}
+
+// ---------- link phase: cross-file resolution ----------
+function linkGraph(graph, pkgs) {
+  // pending name-based edges (renders/uses)
+  for (const p of graph._pendingRenders ?? []) {
+    const targets = graph.findByName(p.name).filter((n) => n.type === "component" || p.type === "uses");
+    for (const t of targets.slice(0, 3)) graph.addEdge(p.from, t.id, p.type);
+  }
+  delete graph._pendingRenders;
+
+  // FastAPI include_router prefixes: re-prefix api-routes of the included router.
+  // The included name is often an alias (from .auth import router as auth_router),
+  // so resolve via the including file's imports to the defining file.
+  for (const inc of graph._pyIncludes ?? []) {
+    if (!inc.prefix) continue;
+    const imports = graph._pyImports?.[inc.file] ?? [];
+    const imp = imports.find((i) => i.alias === inc.router);
+    let targetFile = null;
+    let targetVar = inc.router;
+    if (imp) {
+      targetVar = imp.name; // original variable name in the defining module
+      targetFile = resolvePyModule(graph, inc.file, imp.module);
+    }
+    for (const n of [...graph.nodes.values()]) {
+      if (n.type !== "api-route" || n.extra?.framework !== "fastapi" || n.extra._mounted) continue;
+      const varMatch = n.extra.routerVar === targetVar || n.extra.routerVar === inc.router;
+      const fileMatch = !targetFile || n.file === targetFile;
+      if (varMatch && fileMatch) applyPrefix(graph, n, inc.prefix);
+    }
+  }
+  delete graph._pyIncludes;
+  delete graph._pyImports;
+
+  // Express mounts: app.use('/api', usersRouter) — prefix routes defined on `router` in imported files
+  for (const m of graph._mounts ?? []) {
+    const mountFile = graph.nodes.get(`file:${m.file}`);
+    if (!mountFile) continue;
+    const imported = graph.neighbors(mountFile.id, "out", ["imports"]).map((e) => e.node.file);
+    for (const n of [...graph.nodes.values()]) {
+      if (n.type !== "api-route" || n.extra?.framework !== "express" || n.extra._mounted) continue;
+      if (imported.includes(n.file)) applyPrefix(graph, n, m.prefix);
+    }
+  }
+  delete graph._mounts;
+
+  // hits-endpoint: endpoint-call -> api-route by method + normalized path (with :param wildcards)
+  const apiRoutes = [...graph.nodes.values()].filter((n) => n.type === "api-route");
+  for (const call of [...graph.nodes.values()].filter((n) => n.type === "endpoint-call")) {
+    for (const ar of apiRoutes) {
+      if (ar.extra.method !== call.extra.method) continue;
+      if (pathsMatch(call.extra.normPath, ar.extra.normPath)) {
+        graph.addEdge(call.id, ar.id, "hits-endpoint");
+      }
+    }
+  }
+}
+
+// Resolve a python module spec (".auth", "app.users") relative to the importing
+// file into a repo-relative .py path present in the graph.
+function resolvePyModule(graph, fromRel, moduleSpec) {
+  const fromDir = fromRel.split("/").slice(0, -1).join("/");
+  const candidates = [];
+  if (moduleSpec.startsWith(".")) {
+    const ups = moduleSpec.match(/^\.+/)[0].length - 1;
+    const rest = moduleSpec.replace(/^\.+/, "").split(".").filter(Boolean);
+    let base = fromDir.split("/");
+    base = base.slice(0, base.length - ups);
+    candidates.push([...base, ...rest].join("/") + ".py");
+    candidates.push([...base, ...rest, "__init__"].join("/") + ".py");
+  } else {
+    const rest = moduleSpec.split(".");
+    candidates.push(rest.join("/") + ".py");
+    candidates.push([fromDir.split("/")[0], ...rest].join("/") + ".py");
+    // suffix match fallback: any indexed file ending in the module path
+    const suffix = "/" + rest.join("/") + ".py";
+    for (const f of graph.byFile.keys()) if (f.endsWith(suffix)) candidates.push(f);
+  }
+  for (const c of candidates) if (graph.byFile.has(c) || graph.nodes.has(`file:${c}`)) return c;
+  return null;
+}
+
+function applyPrefix(graph, node, prefix) {
+  const newPath = joinPaths(prefix, node.extra.rawPathWithLocal ?? node.extra.path);
+  const oldNorm = node.extra.normPath;
+  node.extra.path = newPath;
+  node.extra.normPath = normalizeEndpoint(newPath);
+  node.extra._mounted = true;
+  node.name = `${node.extra.method} ${newPath}`;
+  graph.byEndpointPath.get(oldNorm)?.delete(node.id);
+  if (!graph.byEndpointPath.has(node.extra.normPath)) graph.byEndpointPath.set(node.extra.normPath, new Set());
+  graph.byEndpointPath.get(node.extra.normPath).add(node.id);
+}
+
+// segment-wise match where :param matches any single segment on either side
+export function pathsMatch(a, b) {
+  const sa = a.split("/").filter(Boolean);
+  const sb = b.split("/").filter(Boolean);
+  if (sa.length !== sb.length) return false;
+  for (let i = 0; i < sa.length; i++) {
+    if (sa[i] === sb[i]) continue;
+    if (sa[i] === ":param" || sb[i] === ":param") continue;
+    return false;
+  }
+  return true;
+}
+
+// ---------- top-level API ----------
+export function fullIndex(root) {
+  const t0 = Date.now();
+  const graph = new Graph(root);
+  const warnings = [];
+  const allFiles = walkFiles(root);
+  const pkgs = detectPackages(root, allFiles);
+  for (const p of pkgs) {
+    graph.addNode({ id: `package:${p.dir}`, type: "package", name: p.name, file: p.dir, extra: { kind: p.kind, deps: p.deps } });
+  }
+  const manifest = {};
+  const rels = allFiles.map((f) => path.relative(root, f).split(path.sep).join("/"));
+  for (const rel of rels) {
+    const ext = path.extname(rel).toLowerCase();
+    if (!JS_EXT.has(ext) && !PY_EXT.has(ext)) continue;
+    manifest[rel] = hashFile(path.join(root, rel));
+    indexFile(graph, root, rel, pkgs, warnings);
+  }
+  linkGraph(graph, pkgs);
+  graph.save();
+  saveManifest(root, manifest);
+  return { graph, warnings, ms: Date.now() - t0, changed: Object.keys(manifest).length, added: Object.keys(manifest).length, removed: 0, mode: "full" };
+}
+
+export function incrementalIndex(root, graph) {
+  const t0 = Date.now();
+  const prev = loadManifest(root);
+  if (!prev || !graph) return fullIndex(root);
+  const warnings = [];
+  const allFiles = walkFiles(root);
+  const pkgs = detectPackages(root, allFiles);
+  const rels = new Set(
+    allFiles.map((f) => path.relative(root, f).split(path.sep).join("/"))
+      .filter((rel) => JS_EXT.has(path.extname(rel).toLowerCase()) || PY_EXT.has(path.extname(rel).toLowerCase()))
+  );
+  const next = {};
+  let changed = 0, added = 0, removed = 0;
+  for (const rel of rels) {
+    next[rel] = hashFile(path.join(root, rel));
+    if (!(rel in prev)) added++;
+    else if (prev[rel] !== next[rel]) changed++;
+  }
+  for (const rel of Object.keys(prev)) if (!rels.has(rel)) removed++;
+
+  if (changed + added + removed === 0) {
+    return { graph, warnings, ms: Date.now() - t0, changed, added, removed, mode: "incremental-noop" };
+  }
+  // Simplest correct incremental strategy: reparse only changed/added files,
+  // remove deleted ones, then redo the (cheap, in-memory) link phase.
+  for (const rel of Object.keys(prev)) {
+    if (!rels.has(rel) || prev[rel] !== next[rel]) graph.removeFile(rel);
+  }
+  // link-phase edges are name-based; drop and rebuild them to avoid stale links
+  graph.edges = graph.edges.filter((e) => !["renders", "uses", "hits-endpoint"].includes(e.type));
+  graph.rebuildAdjacency();
+  for (const rel of rels) {
+    if (!(rel in prev) || prev[rel] !== next[rel]) indexFile(graph, root, rel, pkgs, warnings);
+  }
+  // re-run pending link resolution against full node set
+  // (renders/uses edges from unchanged files were dropped; regenerate them by
+  //  re-parsing is overkill — instead we re-link from stored component render info.
+  //  To keep this correct without storing render lists, reparse unchanged JS files' link data only.)
+  relinkUnchanged(graph, root, rels, prev, next, pkgs, warnings);
+  linkGraph(graph, pkgs);
+  graph.save();
+  saveManifest(root, next);
+  return { graph, warnings, ms: Date.now() - t0, changed, added, removed, mode: "incremental" };
+}
+
+// Rebuild name-based pending links for unchanged files (cheap parse of already-hot files).
+function relinkUnchanged(graph, root, rels, prev, next, pkgs, warnings) {
+  for (const rel of rels) {
+    if (rel in prev && prev[rel] === next[rel]) {
+      const ext = path.extname(rel).toLowerCase();
+      if (PY_EXT.has(ext)) {
+        try {
+          const src = fs.readFileSync(path.join(root, rel), "utf8");
+          const parsed = parsePython(rel, src);
+          graph._pyIncludes ??= [];
+          graph._pyImports ??= {};
+          graph._pyImports[rel] = parsed.pyImports;
+          for (const inc of parsed.includes) graph._pyIncludes.push({ file: rel, ...inc });
+        } catch (e) { warnings.push(`${rel}: relink error (${e.message})`); }
+        continue;
+      }
+      if (!JS_EXT.has(ext)) continue;
+      try {
+        const src = fs.readFileSync(path.join(root, rel), "utf8");
+        const parsed = parseJsTs(rel, src);
+        if (parsed.mounts?.length) {
+          graph._mounts ??= [];
+          for (const m of parsed.mounts) graph._mounts.push({ file: rel, ...m });
+        }
+        graph._pendingRenders ??= [];
+        for (const comp of parsed.components) {
+          for (const child of parsed.rendered ?? []) {
+            if (child !== comp) graph._pendingRenders.push({ from: `component:${rel}#${comp}`, name: child, type: "renders" });
+          }
+          for (const hook of parsed.hooks ?? []) {
+            graph._pendingRenders.push({ from: `component:${rel}#${comp}`, name: hook, type: "uses" });
+          }
+        }
+        for (const r of parsed.routes) {
+          if (r.component) graph._pendingRenders.push({ from: `route:${r.path}`, name: r.component, type: "renders" });
+        }
+      } catch (e) { warnings.push(`${rel}: relink error (${e.message})`); }
+    }
+  }
+}
+
+function saveManifest(root, manifest) {
+  fs.mkdirSync(Graph.storageDir(root), { recursive: true });
+  fs.writeFileSync(Graph.manifestPath(root), JSON.stringify(manifest));
+}
+function loadManifest(root) {
+  try { return JSON.parse(fs.readFileSync(Graph.manifestPath(root), "utf8")); } catch { return null; }
+}

package/src/install.js

@@ -0,0 +1,73 @@
+// `code-graph-mcp install <target>` — one-command client setup (spec R7).
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_SRC = path.join(__dirname, "..", "skills", "code-graph");
+
+const SERVER_ENTRY = {
+  command: "npx",
+  args: ["-y", "@ashkand/code-graph-mcp", "--repo", "."],
+};
+
+function mergeMcpJson(file, entryArgs) {
+  let config = { mcpServers: {} };
+  if (fs.existsSync(file)) {
+    try { config = JSON.parse(fs.readFileSync(file, "utf8")); }
+    catch { throw new Error(`${file} exists but is not valid JSON — fix it or remove it, then re-run install`); }
+  }
+  config.mcpServers ??= {};
+  const already = JSON.stringify(config.mcpServers["code-graph"]) === JSON.stringify(entryArgs);
+  config.mcpServers["code-graph"] = entryArgs; // idempotent overwrite of our own entry only
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
+  return already ? "unchanged" : "written";
+}
+
+function copySkill(destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.cpSync(SKILL_SRC, destDir, { recursive: true });
+}
+
+export function install(target, repo) {
+  const lines = [];
+  switch (target) {
+    case "claude-code": {
+      const mcpFile = path.join(repo, ".mcp.json");
+      const state = mergeMcpJson(mcpFile, SERVER_ENTRY);
+      lines.push(`${state}: ${mcpFile} (mcpServers.code-graph)`);
+      const skillDest = path.join(repo, ".claude", "skills", "code-graph");
+      copySkill(skillDest);
+      lines.push(`copied skill -> ${skillDest}`);
+      lines.push(`done. Restart Claude Code in ${repo} and ask: "where does <SomePage> land in the backend?"`);
+      break;
+    }
+    case "cursor": {
+      const mcpFile = path.join(repo, ".cursor", "mcp.json");
+      const state = mergeMcpJson(mcpFile, { ...SERVER_ENTRY, args: ["-y", "@ashkand/code-graph-mcp", "--repo", "${workspaceFolder}"] });
+      lines.push(`${state}: ${mcpFile} (mcpServers.code-graph)`);
+      lines.push("done. Reload Cursor; the code-graph tools appear under MCP.");
+      break;
+    }
+    default: {
+      lines.push(target ? `unknown target "${target}" — manual setup:` : "manual setup per client:");
+      lines.push("");
+      lines.push("Claude Code:    code-graph-mcp install claude-code --repo <path>");
+      lines.push("Cursor:         code-graph-mcp install cursor --repo <path>");
+      lines.push("");
+      lines.push("Claude Desktop (claude_desktop_config.json):");
+      lines.push('  "code-graph": { "command": "npx", "args": ["-y", "@ashkand/code-graph-mcp", "--repo", "/abs/path/to/repo"] }');
+      lines.push("");
+      lines.push("Codex CLI (~/.codex/config.toml):");
+      lines.push("  [mcp_servers.code-graph]");
+      lines.push('  command = "npx"');
+      lines.push('  args = ["-y", "@ashkand/code-graph-mcp", "--repo", "/abs/path/to/repo"]');
+      lines.push("");
+      lines.push("Claude.ai / Claude Desktop custom connector (remote):");
+      lines.push("  host with: npx -y @ashkand/code-graph-mcp --repo <path> --http --port 3333 --auth-token <secret>");
+      lines.push("  then add https://your-domain/mcp/<secret> in Settings > Connectors (see README).");
+    }
+  }
+  return lines.join("\n");
+}

package/src/parsers.js

@@ -0,0 +1,158 @@
+// Lightweight regex/heuristic parsers. Deliberately not a full AST:
+// fast, zero native deps, and "good enough" for structural graphs.
+// Every parser returns { components, routes, calls, imports, apiRoutes } fragments.
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
+
+// ---------- shared: endpoint path normalization (spec E3) ----------
+// `${API}/users/${id}` -> /users/:param ; /users/{user_id} -> /users/:param ; /users/:id -> /users/:param
+export function normalizeEndpoint(raw) {
+  let p = raw.trim();
+  p = p.replace(/\$\{[^}]*\}/g, ":param");     // template literals
+  p = p.replace(/\{[^}]*\}/g, ":param");       // FastAPI-style {id}
+  p = p.replace(/:[A-Za-z_][\w]*/g, ":param"); // express-style :id
+  // strip scheme+host and leading base-var placeholders
+  p = p.replace(/^https?:\/\/[^/]+/i, "");
+  p = p.replace(/^:param(?=\/)/, "");          // `${API_BASE}/users` -> /users
+  if (!p.startsWith("/")) p = "/" + p;
+  p = p.replace(/\/{2,}/g, "/");
+  if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+  p = p.split("?")[0];
+  return p.toLowerCase();
+}
+
+// ---------- JS/TS frontend ----------
+export function parseJsTs(rel, src) {
+  const out = { components: [], routes: [], calls: [], imports: [], apiRoutes: [] };
+
+  // imports: import X from './y'; import { a, b } from "../z"; require('./w')
+  const importRe = /import\s+(?:[\w${},*\s]+?\s+from\s+)?["']([^"']+)["']|require\(\s*["']([^"']+)["']\s*\)/g;
+  for (const m of src.matchAll(importRe)) {
+    const spec = m[1] ?? m[2];
+    if (spec) out.imports.push(spec);
+  }
+
+  // components: exported PascalCase function/arrow/class
+  const compRes = [
+    /export\s+default\s+function\s+([A-Z]\w*)/g,
+    /export\s+(?:default\s+)?class\s+([A-Z]\w*)/g,
+    /export\s+function\s+([A-Z]\w*)/g,
+    /export\s+(?:default\s+)?const\s+([A-Z]\w*)\s*(?::[^=]+)?=\s*(?:React\.)?(?:memo\(|forwardRef\()?\s*(?:async\s*)?(?:function|\()/g,
+    /(?:^|\n)\s*(?:const|function)\s+([A-Z]\w*)\s*(?:=\s*)?\((?:[^)]*)\)\s*(?:=>)?\s*\{[\s\S]{0,400}?return\s*\(?\s*</g,
+  ];
+  const seen = new Set();
+  for (const re of compRes) {
+    for (const m of src.matchAll(re)) {
+      if (!seen.has(m[1])) { seen.add(m[1]); out.components.push(m[1]); }
+    }
+  }
+
+  // hooks used (custom useXxx) — recorded as "uses" targets
+  out.hooks = [...new Set([...src.matchAll(/\buse[A-Z]\w*/g)].map((m) => m[0]))]
+    .filter((h) => !["useState", "useEffect", "useMemo", "useCallback", "useRef", "useContext", "useReducer", "useLayoutEffect", "useId", "useTransition"].includes(h));
+
+  // JSX children rendered: <PascalCase
+  out.rendered = [...new Set([...src.matchAll(/<([A-Z]\w*)[\s/>]/g)].map((m) => m[1]))]
+    .filter((c) => !["Fragment", "React", "Suspense", "StrictMode"].includes(c));
+
+  // React Router: <Route path="/x" element={<Comp/>}> (attrs in either order)
+  const routeTagRe = /<Route\b[^>]*>/g;
+  for (const m of src.matchAll(routeTagRe)) {
+    const tag = m[0];
+    const p = tag.match(/path\s*=\s*["']([^"']+)["']/);
+    const el = tag.match(/element\s*=\s*\{\s*<([A-Z]\w*)/) ?? tag.match(/component\s*=\s*\{\s*([A-Z]\w*)/);
+    if (p) out.routes.push({ path: p[1], component: el?.[1] ?? null });
+  }
+  // createBrowserRouter([{ path: '/x', element: <Comp/> }, ...])
+  const objRouteRe = /path\s*:\s*["']([^"']+)["'][\s\S]{0,200}?(?:element\s*:\s*<([A-Z]\w*)|Component\s*:\s*([A-Z]\w*))/g;
+  for (const m of src.matchAll(objRouteRe)) {
+    out.routes.push({ path: m[1], component: m[2] ?? m[3] ?? null });
+  }
+
+  // HTTP calls
+  // fetch('...', { method: 'POST' })  /  fetch(`...`)
+  const fetchRe = /fetch\s*\(\s*(["'`])([\s\S]*?)\1\s*(?:,\s*\{([\s\S]{0,300}?)\})?/g;
+  for (const m of src.matchAll(fetchRe)) {
+    const url = m[2];
+    if (!looksLikeUrlPath(url)) continue;
+    const method = m[3]?.match(/method\s*:\s*["'`](\w+)["'`]/i)?.[1]?.toUpperCase() ?? "GET";
+    out.calls.push({ method, raw: url, normPath: normalizeEndpoint(url) });
+  }
+  // axios.get('...') / api.post(`...`) / client.delete('...')
+  const clientRe = new RegExp(String.raw`\b(\w+)\.(${HTTP_METHODS.join("|")})\s*\(\s*(["'\`])([\s\S]*?)\3`, "g");
+  for (const m of src.matchAll(clientRe)) {
+    const [, obj, method, , url] = m;
+    if (obj === "router" || obj === "app" || obj === "server") continue; // express server-side, handled below
+    if (!looksLikeUrlPath(url)) continue;
+    out.calls.push({ method: method.toUpperCase(), raw: url, normPath: normalizeEndpoint(url), client: obj });
+  }
+  // axios({ url: '...', method: 'post' })
+  const axiosCfgRe = /axios\s*\(\s*\{([\s\S]{0,400}?)\}\s*\)/g;
+  for (const m of src.matchAll(axiosCfgRe)) {
+    const url = m[1].match(/url\s*:\s*["'`]([^"'`]+)["'`]/)?.[1];
+    if (!url || !looksLikeUrlPath(url)) continue;
+    const method = m[1].match(/method\s*:\s*["'`](\w+)["'`]/)?.[1]?.toUpperCase() ?? "GET";
+    out.calls.push({ method, raw: url, normPath: normalizeEndpoint(url) });
+  }
+
+  // Express backend routes in JS: app.get('/x', handler) / router.post('/y', fn)
+  const expressRe = new RegExp(String.raw`\b(app|router|server)\.(${HTTP_METHODS.join("|")})\s*\(\s*(["'\`])([^"'\`]+)\3\s*,\s*([\w.]+|async|\()`, "g");
+  for (const m of src.matchAll(expressRe)) {
+    const [, , method, , p, handlerTok] = m;
+    const handler = /^[\w.]+$/.test(handlerTok) && !["async"].includes(handlerTok) ? handlerTok : null;
+    out.apiRoutes.push({ method: method.toUpperCase(), path: p, handler, framework: "express" });
+  }
+  // app.use('/prefix', someRouter)
+  out.mounts = [];
+  const useRe = /\b(?:app|server)\.use\s*\(\s*["'`]([^"'`]+)["'`]\s*,\s*(\w+)/g;
+  for (const m of src.matchAll(useRe)) out.mounts.push({ prefix: m[1], router: m[2] });
+
+  return out;
+}
+
+function looksLikeUrlPath(s) {
+  return /^(https?:\/\/|\/|`?\$\{)/.test(s) || s.startsWith("${") || /^[\w-]+\/[\w-]/.test(s) === false && s.includes("/");
+}
+
+// ---------- Python backend (FastAPI / Flask) ----------
+export function parsePython(rel, src) {
+  const out = { apiRoutes: [], routerPrefixes: {}, includes: [], pyImports: [] };
+
+  // from .auth import router as auth_router  /  from app.users import router
+  const fromImportRe = /from\s+([\w.]+)\s+import\s+([\w,\s]+?)(?:\n|$)/g;
+  for (const m of src.matchAll(fromImportRe)) {
+    for (const part of m[2].split(",")) {
+      const seg = part.trim().match(/^(\w+)(?:\s+as\s+(\w+))?$/);
+      if (seg) out.pyImports.push({ module: m[1], name: seg[1], alias: seg[2] ?? seg[1] });
+    }
+  }
+
+  // router = APIRouter(prefix="/auth")
+  const apiRouterRe = /(\w+)\s*=\s*APIRouter\s*\(([^)]*)\)/g;
+  for (const m of src.matchAll(apiRouterRe)) {
+    const prefix = m[2].match(/prefix\s*=\s*["']([^"']+)["']/)?.[1] ?? "";
+    out.routerPrefixes[m[1]] = prefix;
+  }
+  // app.include_router(auth_router, prefix="/api")
+  const includeRe = /\.include_router\s*\(\s*([\w.]+)([^)]*)\)/g;
+  for (const m of src.matchAll(includeRe)) {
+    const prefix = m[2].match(/prefix\s*=\s*["']([^"']+)["']/)?.[1] ?? "";
+    out.includes.push({ router: m[1].split(".").pop(), prefix });
+  }
+  // @app.get("/path") / @router.post("/path")  followed by def name(
+  const decoRe = new RegExp(String.raw`@(\w+)\.(${HTTP_METHODS.join("|")})\s*\(\s*["']([^"']+)["'][^)]*\)\s*(?:@[\w.()\s"',=]+\s*)*(?:async\s+)?def\s+(\w+)`, "g");
+  for (const m of src.matchAll(decoRe)) {
+    const [, obj, method, p, fn] = m;
+    out.apiRoutes.push({ method: method.toUpperCase(), path: p, handler: fn, routerVar: obj, framework: "fastapi" });
+  }
+  // Flask: @app.route("/path", methods=["POST"]) def fn
+  const flaskRe = /@(\w+)\.route\s*\(\s*["']([^"']+)["']([^)]*)\)\s*(?:async\s+)?def\s+(\w+)/g;
+  for (const m of src.matchAll(flaskRe)) {
+    const methods = m[3].match(/methods\s*=\s*\[([^\]]+)\]/)?.[1]
+      ?.split(",").map((s) => s.replace(/["'\s]/g, "").toUpperCase()) ?? ["GET"];
+    for (const method of methods) {
+      out.apiRoutes.push({ method, path: m[2], handler: m[4], routerVar: m[1], framework: "flask" });
+    }
+  }
+  return out;
+}