@shvmgyl15/tsgraph 0.1.0

package/src/mcp/server.ts

@@ -0,0 +1,217 @@
+import fs from "node:fs";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod/v4";
+import type { Graph } from "../graph/types.js";
+import { deserialize } from "../graph/types.js";
+import { findCallers, findCallees, findNode, querySymbols, findImports, findPublic, context } from "../search/index.js";
+import { impact, findPath, findOrphans, trace } from "../traversal/index.js";
+import { analyzeComplexity, findHotspots, analyzeCoupling } from "../analysis/index.js";
+
+function loadGraph(rootDir: string): Graph {
+  const graphPath = path.join(rootDir, ".tsgraph", "graph.json");
+  const raw = fs.readFileSync(graphPath, "utf-8");
+  return deserialize(raw);
+}
+
+function text(text: string) {
+  return { content: [{ type: "text" as const, text }] };
+}
+
+function error(msg: string) {
+  return { content: [{ type: "text" as const, text: msg }], isError: true as const };
+}
+
+function withGraph<T>(rootDir: string, fn: (graph: Graph) => T): T {
+  try {
+    const graph = loadGraph(rootDir);
+    return fn(graph);
+  } catch (err) {
+    throw new Error(`Failed to load graph: ${(err as Error).message}`);
+  }
+}
+
+export async function startMcpServer(rootDir: string): Promise<void> {
+  const server = new McpServer({
+    name: "tsgraph",
+    version: "0.1.0",
+  });
+
+  server.resource(
+    "graph.json",
+    `file://${path.join(rootDir, ".tsgraph", "graph.json")}`,
+    { mimeType: "application/json" },
+    async (uri) => ({
+      contents: [{
+        uri: uri.href,
+        mimeType: "application/json",
+        text: fs.readFileSync(new URL(uri.href), "utf-8"),
+      }],
+    }),
+  );
+
+  server.registerTool("callers", {
+    description: "Find which functions call a given symbol",
+    inputSchema: z.object({ symbol: z.string() }),
+  }, async ({ symbol }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findCallers(g, symbol)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("callees", {
+    description: "Find which functions a given symbol calls",
+    inputSchema: z.object({ symbol: z.string() }),
+  }, async ({ symbol }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findCallees(g, symbol)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("node", {
+    description: "Get detailed information about a symbol",
+    inputSchema: z.object({ symbol: z.string() }),
+  }, async ({ symbol }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findNode(g, symbol)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("query", {
+    description: "Search for symbols matching a pattern",
+    inputSchema: z.object({ pattern: z.string() }),
+  }, async ({ pattern }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => querySymbols(g, pattern)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("context", {
+    description: "Bundle node, source, callers, and callees for a symbol",
+    inputSchema: z.object({ symbol: z.string() }),
+  }, async ({ symbol }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => context(g, symbol)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("imports", {
+    description: "Find all files importing a specific package path",
+    inputSchema: z.object({ path: z.string() }),
+  }, async ({ path: importPath }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findImports(g, importPath)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("public", {
+    description: "List exported symbols, optionally scoped to a package",
+    inputSchema: z.object({ package: z.string().optional() }),
+  }, async ({ package: pkg }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findPublic(g, pkg)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("impact", {
+    description: "Show downstream blast radius (callers recursively)",
+    inputSchema: z.object({ symbol: z.string(), depth: z.number().optional() }),
+  }, async ({ symbol, depth }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => impact(g, symbol, depth)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("path", {
+    description: "Find shortest call path between two symbols",
+    inputSchema: z.object({ from: z.string(), to: z.string(), depth: z.number().optional() }),
+  }, async ({ from, to, depth }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findPath(g, from, to, depth)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("orphans", {
+    description: "Find dead code — symbols with no callers or tests",
+    inputSchema: z.object({}),
+  }, async () => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findOrphans(g)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("trace", {
+    description: "Find a string literal across symbols and trace callers upstream",
+    inputSchema: z.object({ string: z.string(), depth: z.number().optional() }),
+  }, async ({ string: searchStr, depth }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => trace(g, searchStr, depth)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("complexity", {
+    description: "Show cyclomatic complexity for functions and methods",
+    inputSchema: z.object({ file: z.string().optional(), sort: z.boolean().optional(), min: z.number().optional() }),
+  }, async ({ file, sort, min }) => {
+    try {
+      const graph = loadGraph(rootDir);
+      let results = analyzeComplexity(graph, file);
+      if (min) results = results.filter((r) => r.complexity >= min);
+      if (sort) results.sort((a, b) => b.complexity - a.complexity);
+      return text(JSON.stringify(results, null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("hotspot", {
+    description: "Rank files by complexity × size (hotness score)",
+    inputSchema: z.object({ top: z.number().optional() }),
+  }, async ({ top }) => {
+    try {
+      return text(JSON.stringify(withGraph(rootDir, (g) => findHotspots(g, top)), null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  server.registerTool("coupling", {
+    description: "Show package coupling based on import edges",
+    inputSchema: z.object({ package: z.string().optional() }),
+  }, async ({ package: pkg }) => {
+    try {
+      const graph = loadGraph(rootDir);
+      let results = analyzeCoupling(graph);
+      if (pkg) results = results.filter((r) => r.packageName === pkg);
+      return text(JSON.stringify(results, null, 2));
+    } catch (err) {
+      return error((err as Error).message);
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/nextjs/index.ts

@@ -0,0 +1,23 @@
+import type { Graph } from "../graph/types.js";
+import type { ScannedFile } from "../scanner/index.js";
+import { extractAppRouter } from "./router.js";
+import { extractPagesRouter } from "./pages.js";
+import { classifyReactComponents } from "./react.js";
+import { extractAPIRoutes } from "./routes.js";
+
+export { extractAppRouter } from "./router.js";
+export { extractPagesRouter } from "./pages.js";
+export { classifyReactComponents } from "./react.js";
+export { extractAPIRoutes } from "./routes.js";
+
+export function extractNextJs(
+  graph: Graph,
+  rootDir: string,
+  scanned: ScannedFile[],
+): Graph {
+  let g = extractAppRouter(graph, scanned);
+  g = extractPagesRouter(g, scanned);
+  g = classifyReactComponents(g, rootDir);
+  g = extractAPIRoutes(g, scanned, rootDir);
+  return g;
+}

package/src/nextjs/nextjs.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { scanFiles } from "../scanner/index.js";
+import { parseProject } from "../parser/index.js";
+import { extractAppRouter } from "./router.js";
+import { extractPagesRouter } from "./pages.js";
+import { classifyReactComponents } from "./react.js";
+import { extractAPIRoutes } from "./routes.js";
+import { makeGraph, makeFileNode } from "../graph/types.js";
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "tsgraph-test-"));
+}
+
+function writeFile(dir: string, relativePath: string, content: string) {
+  const fullPath = path.join(dir, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, "utf-8");
+}
+
+describe("extractAppRouter", () => {
+  it("builds tree with page, layout, loading", () => {
+    const dir = createTempDir();
+    writeFile(dir, "app/page.tsx", "export default function Home() {}");
+    writeFile(dir, "app/layout.tsx", "export default function RootLayout() {}");
+    writeFile(dir, "app/loading.tsx", "export default function Loading() {}");
+
+    const { files } = scanFiles(dir);
+    const graph = makeGraph({ root: dir, files: files.map((f) => makeFileNode({ path: f.relativePath })) });
+    const result = extractAppRouter(graph, files);
+
+    expect(result.appRouter).toBeTruthy();
+    expect(result.appRouter!.path).toBe("/");
+    expect(result.appRouter!.files.page).toMatch(/app\/page\.tsx$/);
+    expect(result.appRouter!.files.layout).toMatch(/app\/layout\.tsx$/);
+    expect(result.appRouter!.files.loading).toMatch(/app\/loading\.tsx$/);
+    expect(result.appRouter!.files.error).toBeUndefined();
+
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("detects nested route segments", () => {
+    const dir = createTempDir();
+    writeFile(dir, "app/layout.tsx", "export default function Root() {}");
+    writeFile(dir, "app/dashboard/page.tsx", "export default function Dashboard() {}");
+    writeFile(dir, "app/dashboard/layout.tsx", "export default function DashLayout() {}");
+    writeFile(dir, "app/dashboard/settings/page.tsx", "export default function Settings() {}");
+
+    const { files } = scanFiles(dir);
+    const graph = makeGraph({ root: dir, files: files.map((f) => makeFileNode({ path: f.relativePath })) });
+    const result = extractAppRouter(graph, files);
+
+    expect(result.appRouter).toBeTruthy();
+    expect(result.appRouter!.children).toHaveLength(1);
+    expect(result.appRouter!.children[0].path).toBe("/dashboard");
+    expect(result.appRouter!.children[0].files.page).toMatch(/dashboard\/page\.tsx$/);
+    expect(result.appRouter!.children[0].children).toHaveLength(1);
+    expect(result.appRouter!.children[0].children[0].path).toBe("/dashboard/settings");
+
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("returns undefined when no app directory", () => {
+    const dir = createTempDir();
+    writeFile(dir, "src/index.ts", "const x = 1;");
+    const { files } = scanFiles(dir);
+    const graph = makeGraph({ root: dir });
+    const result = extractAppRouter(graph, files);
+    expect(result.appRouter).toBeUndefined();
+
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
+describe("extractPagesRouter", () => {
+  it("detects index and nested pages", () => {
+    const dir = createTempDir();
+    writeFile(dir, "pages/index.tsx", "export default function Home() {}");
+    writeFile(dir, "pages/about.tsx", "export default function About() {}");
+    writeFile(dir, "pages/blog/[slug].tsx", "export default function Post() {}");
+
+    const { files } = scanFiles(dir);
+    const graph = makeGraph({ root: dir });
+    const result = extractPagesRouter(graph, files);
+
+    expect(result.routes).toHaveLength(3);
+    const paths = result.routes.map((r) => r.path).sort();
+    expect(paths).toEqual(["/", "/about", "/blog/:slug"]);
+    expect(result.routes[0].method).toBe("GET");
+
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("ignores non-page files", () => {
+    const dir = createTempDir();
+    writeFile(dir, "pages/api/users.ts", "export default function handler() {}");
+    writeFile(dir, "pages/_app.tsx", "export default function App() {}");
+    writeFile(dir, "pages/_document.tsx", "");
+
+    const { files } = scanFiles(dir);
+    const graph = makeGraph({ root: dir });
+    const result = extractPagesRouter(graph, files);
+
+    const paths = result.routes.map((r) => r.path);
+    expect(paths).toContain("/api/users");
+
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
+describe("classifyReactComponents", () => {
+  it("sets isClientComponent from 'use client' directive", () => {
+    const dir = createTempDir();
+    writeFile(dir, "component.tsx", `"use client";
+export function Button() { return null; }`);
+
+    const { files } = scanFiles(dir);
+    const graph = parseProject(dir, files);
+    const button = graph.symbols.find((s) => s.name === "Button");
+    expect(button).toBeTruthy();
+    expect(button!.isClientComponent).toBe(true);
+
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("sets isServerComponent from 'use server' directive", () => {
+    const dir = createTempDir();
+    writeFile(dir, "action.ts", `"use server";
+export async function submit() { return null; }`);
+
+    const { files } = scanFiles(dir);
+    const graph = parseProject(dir, files);
+    const submit = graph.symbols.find((s) => s.name === "submit");
+    expect(submit).toBeTruthy();
+    expect(submit!.isServerComponent).toBe(true);
+
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("detects hooks in tsx functions", () => {
+    const dir = createTempDir();
+    writeFile(dir, "counter.tsx", `
+import { useState } from "react";
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return null;
+}`);
+
+    const { files } = scanFiles(dir);
+    const graph = parseProject(dir, files);
+    const counter = graph.symbols.find((s) => s.name === "Counter");
+    expect(counter).toBeTruthy();
+    expect(counter!.isClientComponent).toBe(true);
+
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
+describe("extractAPIRoutes", () => {
+  it("extracts HTTP methods from route.ts", () => {
+    const dir = createTempDir();
+    writeFile(dir, "app/api/users/route.ts", `
+export async function GET() { return Response.json({}); }
+export async function POST(req: Request) { return Response.json({}); }
+`);
+
+    const { files } = scanFiles(dir);
+    const graph = makeGraph({ root: dir });
+    const result = extractAPIRoutes(graph, files, dir);
+
+    const routes = result.routes.sort((a, b) => a.method.localeCompare(b.method));
+    expect(routes).toHaveLength(2);
+    expect(routes[0].method).toBe("GET");
+    expect(routes[0].path).toBe("/api/users");
+    expect(routes[1].method).toBe("POST");
+    expect(routes[1].path).toBe("/api/users");
+
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("handles dynamic route params", () => {
+    const dir = createTempDir();
+    writeFile(dir, "app/api/items/[id]/route.ts", `
+export async function GET(req: Request, { params }: { params: { id: string } }) {
+  return Response.json({});
+}
+`);
+
+    const { files } = scanFiles(dir);
+    const graph = makeGraph({ root: dir });
+    const result = extractAPIRoutes(graph, files, dir);
+
+    expect(result.routes).toHaveLength(1);
+    expect(result.routes[0].path).toBe("/api/items/:id");
+
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
+describe("end-to-end: parseProject with Next.js", () => {
+  it("produces appRouter and routes from a Next.js project", () => {
+    const dir = createTempDir();
+    writeFile(dir, "package.json", JSON.stringify({ name: "my-app", dependencies: { "next": "^14" } }));
+    writeFile(dir, "app/layout.tsx", "export default function Root({ children }: { children: React.ReactNode }) { return null; }");
+    writeFile(dir, "app/page.tsx", `"use client";
+import { useState } from "react";
+export default function Home() {
+  const [count, setCount] = useState(0);
+  return null;
+}`);
+    writeFile(dir, "app/api/hello/route.ts", "export async function GET() { return Response.json({}); }");
+    writeFile(dir, "pages/about.tsx", "export default function About() { return null; }");
+
+    const { files } = scanFiles(dir);
+    const graph = parseProject(dir, files);
+
+    expect(graph.appRouter).toBeTruthy();
+    expect(graph.appRouter!.files.layout).toBeTruthy();
+    expect(graph.appRouter!.files.page).toBeTruthy();
+
+    const home = graph.symbols.find((s) => s.name === "Home");
+    expect(home).toBeTruthy();
+    expect(home!.isClientComponent).toBe(true);
+
+    const routePaths = graph.routes.map((r) => r.path);
+    expect(routePaths).toContain("/api/hello");
+    expect(routePaths).toContain("/about");
+
+    fs.rmSync(dir, { recursive: true });
+  });
+});

package/src/nextjs/pages.ts

@@ -0,0 +1,43 @@
+import path from "node:path";
+import type { Graph, HTTPRoute } from "../graph/types.js";
+import type { ScannedFile } from "../scanner/index.js";
+
+function pagePathToRoute(relativePath: string): string | undefined {
+  let p = relativePath
+    .replace(/^pages[/\\]/, "")
+    .replace(/\.[jt]sx?$/, "")
+    .replace(/index$/, "")
+    .replace(/\[\.\.\.(.+?)\]/, "*$1")
+    .replace(/\[(.+?)\]/g, ":$1");
+
+  if (!p.startsWith("/")) p = "/" + p;
+  return p === "/" ? "/" : p.replace(/\/$/, "");
+}
+
+export function extractPagesRouter(
+  graph: Graph,
+  scanned: ScannedFile[],
+): Graph {
+  const newRoutes: HTTPRoute[] = [...graph.routes];
+
+  for (const sf of scanned) {
+    const rel = sf.relativePath;
+    if (!rel.startsWith("pages/") && !rel.startsWith("pages\\")) continue;
+    const ext = path.extname(rel);
+    if (ext !== ".ts" && ext !== ".tsx" && ext !== ".js" && ext !== ".jsx") continue;
+
+    const route = pagePathToRoute(rel);
+    if (!route) continue;
+
+    const isApi = route.startsWith("/api");
+    newRoutes.push({
+      method: "GET",
+      path: route,
+      handler: isApi ? `pages${route}` : rel,
+      file: rel,
+      line: 1,
+    });
+  }
+
+  return { ...graph, routes: newRoutes };
+}

package/src/nextjs/react.ts

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Graph, SymbolNode } from "../graph/types.js";
+
+const REACT_HOOKS = new Set([
+  "useState", "useEffect", "useContext", "useReducer", "useCallback",
+  "useMemo", "useRef", "useImperativeHandle", "useLayoutEffect",
+  "useDebugValue", "useTransition", "useDeferredValue", "useId",
+  "useSyncExternalStore", "useInsertionEffect", "useActionState",
+  "useOptimistic",
+]);
+
+function getDirectives(filePath: string): {
+  isClient: boolean;
+  isServer: boolean;
+} {
+  try {
+    const fd = fs.openSync(filePath, "r");
+    const buffer = Buffer.alloc(512);
+    const bytesRead = fs.readSync(fd, buffer, 0, 512, 0);
+    fs.closeSync(fd);
+    const head = buffer.toString("utf-8", 0, bytesRead);
+    const lines = head.split("\n").slice(0, 5);
+    const trimmed = lines.map((l) => l.trim().replace(/;$/, ""));
+    return {
+      isClient: trimmed.some((l) => l === `"use client"` || l === `'use client'`),
+      isServer: trimmed.some((l) => l === `"use server"` || l === `'use server'`),
+    };
+  } catch {
+    return { isClient: false, isServer: false };
+  }
+}
+
+function checkHookUsage(
+  filePath: string,
+  symbols: SymbolNode[],
+): SymbolNode[] {
+  const updated: SymbolNode[] = [];
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    for (const sym of symbols) {
+      const lines = content.split("\n");
+      const snippet = lines.slice(sym.line - 1, sym.endLine).join("\n");
+      const usesHooks = [...REACT_HOOKS].some((hook) => {
+        const idx = snippet.indexOf(hook);
+        if (idx === -1) return false;
+        const before = snippet[idx - 1];
+        if (before && (before === "." || /[a-zA-Z0-9]/.test(before))) return false;
+        return true;
+      });
+      if (usesHooks) {
+        updated.push({ ...sym, isClientComponent: true });
+      } else {
+        updated.push(sym);
+      }
+    }
+  } catch {
+    return symbols;
+  }
+  return updated;
+}
+
+export function classifyReactComponents(
+  graph: Graph,
+  rootDir: string,
+): Graph {
+  const symByFile = new Map<string, SymbolNode[]>();
+  for (const sym of graph.symbols) {
+    const list = symByFile.get(sym.file) ?? [];
+    list.push(sym);
+    symByFile.set(sym.file, list);
+  }
+
+  const updatedSymbols: SymbolNode[] = [];
+
+  for (const [fileRel, symbols] of symByFile) {
+    const filePath = path.join(rootDir, fileRel);
+    const { isClient, isServer } = getDirectives(filePath);
+
+    if (isClient || isServer) {
+      updatedSymbols.push(
+        ...symbols.map((s) => ({
+          ...s,
+          isClientComponent: isClient || s.isClientComponent,
+          isServerComponent: isServer || s.isServerComponent,
+        })),
+      );
+      continue;
+    }
+
+    if (fileRel.endsWith(".tsx")) {
+      const checked = checkHookUsage(filePath, symbols);
+      updatedSymbols.push(...checked);
+    } else {
+      updatedSymbols.push(...symbols);
+    }
+  }
+
+  return { ...graph, symbols: updatedSymbols };
+}