@shvmgyl15/tsgraph 0.1.0 → 0.2.0

package/AGENTS.md

@@ -1,64 +0,0 @@
-# tsgraph — Project DNA
-
-## Vision
-A fast, local-only CLI tool that indexes Next.js / React / TypeScript codebases using AST
-parsing into a queryable graph.json for AI coding agents. Equivalent to gograph but for TS.
-Output is Markdown + JSON. No network calls, no telemetry, no SaaS backend.
-
-## Design Philosophy (Go → TS Adaptation)
-tsgraph is inspired by gograph (Go) but adapted for TypeScript/React/Next.js — NOT a blind copy.
-Key language-driven differences:
-- **Export model**: TS `export` keyword maps to `isExported`; class methods are always considered exported (default `public`)
-- **No goroutines/channels** — replaced by async/promise/setTimeout concurrency
-- **No struct tags** — TS has no native equivalent
-- **Router detection** is Next.js App Router / Pages Router, not Gin/mux
-- **React components** tracked via `isClientComponent` / `isServerComponent`
-- **Interface satisfaction** is structural in TS — `ImplementsEdge` may be dropped if unused
-- Go-specific concepts (structs with fields+tests, `MutationEdge`, `StructField.tags`) are present but may be removed if they don't earn their keep for TS
-
-## Tech Stack
-- Runtime: Node.js + tsx (dev) / tsc (build)
-- AST: ts-morph (wraps TypeScript compiler API)
-- CLI: commander
-- MCP: @modelcontextprotocol/sdk
-- Testing: vitest
-- Linting: none (tsc strict mode is sufficient)
-
-## Agent Rules
-
-### Task Management
-- READ TODOS.md at session start to know what's done and what's next
-- UPDATE TODOS.md when you start/finish a task (`[.]` in-progress, `[x]` done)
-- Work in phase order unless a task has no blockers
-
-### Orchestration
-- This is a single-orchestrator project. When a task has multiple independent
-  sub-tasks, delegate via the `task` tool (`subagent_type: general`) rather
-  than doing them sequentially.
-- For each delegated sub-task, specify:
-  1. Exact files the sub-agent may modify
-  2. Which phase from TODOS.md it belongs to
-  3. What to return (never let sub-agents commit or merge)
-- After all sub-tasks complete, run `npm run build && npm test` and fix
-  any issues directly. Do NOT re-delegate broken builds.
-
-### Quality
-- Run `npm run build` (tsc) AND `npm test` (vitest) after every task completion
-- Fix all type errors and test failures before marking `[x]`
-- If build is already broken when you start, note it in TODOS.md and fix it first
-
-### Research
-- Use webfetch when unsure about an API — check ts-morph docs, Next.js docs,
-  or reference gograph's Go source at https://github.com/ozgurcd/gograph
-- DO NOT guess API signatures
-
-### Code Style
-- No comments in source files unless logic is non-obvious
-- Named exports only (no default exports)
-- Strict TypeScript everywhere, avoid `any`
-- Follow patterns from adjacent files in the codebase
-- No emojis in source code or commit messages
-
-### Communication
-- Be concise. Use TODOS.md for status, respond with only what's needed.
-- If stuck, explain the blocker clearly rather than overthinking.

package/TODOS.md

@@ -1,61 +0,0 @@
-# tsgraph — Implementation Plan
-
-## Phase 1: Project Scaffold
-- [x] Update opencode.json with AGENTS.md reference
-- [x] Create AGENTS.md with project DNA
-- [x] Create TODOS.md (this file)
-- [x] Initialize package.json with dependencies
-- [x] Configure tsconfig.json (strict, ESNext)
-- [x] Setup vitest config
-- [x] Create src directory structure
-
-## Phase 2: Core Data Model
-- [x] Define graph types (Graph, PackageNode, FileNode, SymbolNode, etc.)
-- [x] Add JSON serialization / deserialization
-- [x] Write unit tests for graph types
-
-## Phase 3: Scanner + Parser Core
-- [x] Implement file scanner (walk tree, gitignore support, file classification)
-- [x] Implement symbol extractor (ts-morph: functions, classes, interfaces, types, enums, vars)
-- [x] Implement call expression extractor
-- [x] Implement import edge + dependency (package.json) extractor
-- [x] Wire up `build` command end-to-end
-- [x] Write parser/scanner unit tests
-
-## Phase 4: Query Commands
-- [x] callers / callees
-- [x] node / source / query
-- [x] context (bundle — node + source + callers + callees + tests)
-- [x] imports / public / focus
-- [x] Write query command tests
-
-## Phase 5: Next.js / React Extractors
-- [x] App Router tree detection (page/layout/loading/error/route files)
-- [x] Pages Router detection
-- [x] 'use client' / 'use server' + hooks analysis
-- [x] Route extraction from API / route handlers
-- [x] Write extractor tests
-
-## Phase 6: Analysis Commands
-- [x] complexity (cyclomatic)
-- [x] hotspot / coupling / deps
-- [x] Write analysis tests
-
-## Phase 7: Graph Traversal
-- [x] impact (BFS downstream blast radius)
-- [x] path (BFS shortest path between symbols)
-- [x] orphans (dead code detection)
-- [x] trace / errorflow (reverse BFS from string literal)
-- [x] Write traversal tests
-
-## Phase 8: MCP Server
-- [x] MCP stdio server wrapping all query tools
-- [x] Tool definition for each search/query command
-- [x] MCP integration test
-
-## Phase 9: Advanced Features
-- [x] boundaries (architecture enforcement via .tsgraph/boundaries.json)
-- [x] changes / stale (git-aware incremental analysis)
-- [x] plan / review (change planning reports)
-- [x] add-opencode-plugin (auto-configure opencode MCP + agent)
-- [x] Enhanced GRAPH_REPORT.md (hotspots, boundaries, coupling, stale)

package/opencode.json

@@ -1,24 +0,0 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "model": "opencode-go/deepseek-v4-flash",
-  "default_agent": "plan",
-  "instructions": [
-    "AGENTS.md"
-  ],
-  "permission": {
-    "read": {
-      "*": "allow",
-      "*.env": "allow",
-      "*.env.*": "allow"
-    },
-    "external_directory": {
-      "/tmp/**": "allow"
-    },
-    "grep": "allow",
-    "glob": "allow",
-    "lsp": "allow",
-    "skill": "allow",
-    "webfetch": "allow",
-    "websearch": "allow"
-  }
-}

package/src/analysis/analysis.test.ts

@@ -1,405 +0,0 @@
-import { describe, it, expect } from "vitest";
-import path from "node:path";
-import fs from "node:fs";
-import os from "node:os";
-import {
-  makeGraph,
-  makeSymbolNode,
-  makeCallEdge,
-  makeImportEdge,
-  makePackageNode,
-  makeFileNode,
-} from "../graph/types.js";
-import { cyclomaticComplexity, analyzeComplexity } from "./complexity.js";
-import { findHotspots } from "./hotspot.js";
-import { analyzeCoupling, dependencyTree } from "./coupling.js";
-
-function createTempDir(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), "tsgraph-test-"));
-}
-
-describe("cyclomaticComplexity", () => {
-  it("returns 1 for a function with no branches", () => {
-    const code = `function greet() { return "hello"; }`;
-    expect(cyclomaticComplexity(code)).toBe(1);
-  });
-
-  it("counts if statements", () => {
-    const code = `function f() {
-      if (a) return 1;
-      if (b) return 2;
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(3);
-  });
-
-  it("counts if-else as single branch point", () => {
-    const code = `function f() {
-      if (a) { return 1; }
-      else { return 2; }
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(2);
-  });
-
-  it("counts else-if as additional branch", () => {
-    const code = `function f() {
-      if (a) { return 1; }
-      else if (b) { return 2; }
-      else { return 3; }
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(3);
-  });
-
-  it("counts for loops", () => {
-    const code = `function f() {
-      for (let i = 0; i < 10; i++) {}
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(2);
-  });
-
-  it("counts while loops", () => {
-    const code = `function f() {
-      while (true) { break; }
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(2);
-  });
-
-  it("counts case labels", () => {
-    const code = `function f(x: number) {
-      switch (x) {
-        case 1: return "a";
-        case 2: return "b";
-        case 3: return "c";
-      }
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(4);
-  });
-
-  it("counts catch clauses", () => {
-    const code = `function f() {
-      try { doStuff(); }
-      catch (e) { handle(); }
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(2);
-  });
-
-  it("counts ternary operators", () => {
-    const code = `function f() {
-      return a ? b : c;
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(2);
-  });
-
-  it("counts logical && and ||", () => {
-    const code = `function f() {
-      if (a && b || c) return 1;
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(4);
-  });
-
-  it("avoids counting string literals", () => {
-    const code = `function f() {
-      const s = "if (true) { for(;;) {} }";
-      return s;
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(1);
-  });
-
-  it("ignores comments", () => {
-    const code = `function f() {
-      // if (true) { return 1; }
-      /* for(;;) {} */
-      return 0;
-    }`;
-    expect(cyclomaticComplexity(code)).toBe(1);
-  });
-});
-
-describe("analyzeComplexity", () => {
-  it("returns complexity for all functions in a project", () => {
-    const dir = createTempDir();
-    const filePath = path.join(dir, "src/lib.ts");
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(
-      filePath,
-      [
-        "export function simple() { return 1; }",
-        "export function complex() {",
-        "  if (a) { for(;;) {} }",
-        "  return 0;",
-        "}",
-      ].join("\n"),
-      "utf-8",
-    );
-
-    const graph = makeGraph({
-      root: dir,
-      files: [makeFileNode({ path: "src/lib.ts", lines: 5 })],
-      symbols: [
-        makeSymbolNode({
-          id: "simple",
-          name: "simple",
-          kind: "function",
-          file: "src/lib.ts",
-          line: 1,
-          endLine: 1,
-          packageName: "app",
-          isExported: true,
-        }),
-        makeSymbolNode({
-          id: "complex",
-          name: "complex",
-          kind: "function",
-          file: "src/lib.ts",
-          line: 2,
-          endLine: 5,
-          packageName: "app",
-          isExported: true,
-        }),
-      ],
-    });
-
-    const results = analyzeComplexity(graph);
-    expect(results).toHaveLength(2);
-    const simple = results.find((r) => r.symbol.name === "simple");
-    const complex = results.find((r) => r.symbol.name === "complex");
-    expect(simple!.complexity).toBe(1);
-    expect(complex!.complexity).toBeGreaterThanOrEqual(2);
-
-    fs.rmSync(dir, { recursive: true });
-  });
-
-  it("filters by file when specified", () => {
-    const dir = createTempDir();
-    const filePath = path.join(dir, "src/a.ts");
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, "export function foo() {}", "utf-8");
-
-    const graph = makeGraph({
-      root: dir,
-      symbols: [
-        makeSymbolNode({
-          id: "foo",
-          name: "foo",
-          kind: "function",
-          file: "src/a.ts",
-          line: 1,
-          endLine: 1,
-        }),
-        makeSymbolNode({
-          id: "bar",
-          name: "bar",
-          kind: "function",
-          file: "src/b.ts",
-          line: 1,
-          endLine: 1,
-        }),
-      ],
-    });
-
-    const results = analyzeComplexity(graph, "a.ts");
-    expect(results).toHaveLength(1);
-    expect(results[0].symbol.name).toBe("foo");
-
-    fs.rmSync(dir, { recursive: true });
-  });
-});
-
-describe("findHotspots", () => {
-  it("returns top hotspots sorted by score", () => {
-    const dir = createTempDir();
-    const filePath = path.join(dir, "src/hot.ts");
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(
-      filePath,
-      [
-        "export function a() {",
-        "  if (x) { for(;;) {} }",
-        "  if (y) { while(z) {} }",
-        "  return 0;",
-        "}",
-        "export function b() { return 1; }",
-      ].join("\n"),
-      "utf-8",
-    );
-
-    const graph = makeGraph({
-      root: dir,
-      files: [makeFileNode({ path: "src/hot.ts", lines: 6 })],
-      symbols: [
-        makeSymbolNode({
-          id: "a",
-          name: "a",
-          kind: "function",
-          file: "src/hot.ts",
-          line: 1,
-          endLine: 5,
-          packageName: "app",
-        }),
-        makeSymbolNode({
-          id: "b",
-          name: "b",
-          kind: "function",
-          file: "src/hot.ts",
-          line: 6,
-          endLine: 6,
-          packageName: "app",
-        }),
-      ],
-    });
-
-    const hotspots = findHotspots(graph, 5);
-    expect(hotspots.length).toBeGreaterThanOrEqual(1);
-    expect(hotspots[0].file).toBe("src/hot.ts");
-
-    fs.rmSync(dir, { recursive: true });
-  });
-});
-
-describe("analyzeCoupling", () => {
-  it("finds packages importing from other modules", () => {
-    const graph = makeGraph({
-      files: [
-        makeFileNode({ path: "src/orders.ts", packageName: "orders" }),
-        makeFileNode({ path: "src/payment.ts", packageName: "payment" }),
-        makeFileNode({ path: "src/notify.ts", packageName: "notify" }),
-      ],
-      imports: [
-        makeImportEdge({
-          fromFile: "src/orders.ts",
-          fromPackage: "orders",
-          importPath: "payment",
-          alias: "payment",
-          isDefault: true,
-        }),
-        makeImportEdge({
-          fromFile: "src/orders.ts",
-          fromPackage: "orders",
-          importPath: "notify",
-          alias: "notify",
-          isDefault: true,
-        }),
-        makeImportEdge({
-          fromFile: "src/orders.ts",
-          fromPackage: "orders",
-          importPath: "payment",
-          alias: "processPayment",
-          isDefault: false,
-        }),
-      ],
-    });
-
-    const results = analyzeCoupling(graph);
-    expect(results).toHaveLength(2);
-    const paymentCoupling = results.find((r) => r.coupledTo === "payment");
-    expect(paymentCoupling).toBeTruthy();
-    expect(paymentCoupling!.importCount).toBe(2);
-    expect(paymentCoupling!.packageName).toBe("orders");
-  });
-});
-
-describe("dependencyTree", () => {
-  it("builds a tree from call edges", () => {
-    const graph = makeGraph({
-      symbols: [
-        makeSymbolNode({
-          id: "src/main.ts::serve",
-          name: "serve",
-          kind: "function",
-          file: "src/main.ts",
-          line: 1,
-          endLine: 5,
-          packageName: "app",
-        }),
-        makeSymbolNode({
-          id: "src/main.ts::greet",
-          name: "greet",
-          kind: "function",
-          file: "src/main.ts",
-          line: 6,
-          endLine: 8,
-          packageName: "app",
-        }),
-        makeSymbolNode({
-          id: "src/main.ts::log",
-          name: "log",
-          kind: "function",
-          file: "src/main.ts",
-          line: 9,
-          endLine: 11,
-          packageName: "app",
-        }),
-      ],
-      calls: [
-        makeCallEdge({
-          callerSymbolId: "src/main.ts::serve",
-          callerName: "serve",
-          calleeRaw: "greet",
-          file: "src/main.ts",
-          line: 3,
-        }),
-        makeCallEdge({
-          callerSymbolId: "src/main.ts::serve",
-          callerName: "serve",
-          calleeRaw: "log",
-          file: "src/main.ts",
-          line: 4,
-        }),
-      ],
-    });
-
-    const tree = dependencyTree(graph, "serve");
-    expect(tree).toBeTruthy();
-    expect(tree!.name).toBe("serve");
-    expect(tree!.children).toHaveLength(2);
-    const childNames = tree!.children.map((c) => c.name).sort();
-    expect(childNames).toEqual(["greet", "log"]);
-  });
-
-  it("returns undefined for unknown symbol", () => {
-    const graph = makeGraph();
-    const tree = dependencyTree(graph, "noop");
-    expect(tree).toBeUndefined();
-  });
-
-  it("respects max depth", () => {
-    const graph = makeGraph({
-      symbols: [
-        makeSymbolNode({
-          id: "a",
-          name: "a",
-          kind: "function",
-          file: "a.ts",
-          line: 1,
-          endLine: 1,
-          packageName: "app",
-        }),
-        makeSymbolNode({
-          id: "b",
-          name: "b",
-          kind: "function",
-          file: "b.ts",
-          line: 1,
-          endLine: 1,
-          packageName: "app",
-        }),
-        makeSymbolNode({
-          id: "c",
-          name: "c",
-          kind: "function",
-          file: "c.ts",
-          line: 1,
-          endLine: 1,
-          packageName: "app",
-        }),
-      ],
-      calls: [
-        makeCallEdge({ callerSymbolId: "a", callerName: "a", calleeRaw: "b", file: "a.ts", line: 1 }),
-        makeCallEdge({ callerSymbolId: "b", callerName: "b", calleeRaw: "c", file: "b.ts", line: 1 }),
-      ],
-    });
-
-    const tree = dependencyTree(graph, "a", 1);
-    expect(tree!.children).toHaveLength(1);
-    expect(tree!.children[0].children).toHaveLength(0);
-  });
-});

package/src/analysis/complexity.ts

@@ -1,107 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import type { Graph, SymbolNode } from "../graph/types.js";
-
-interface DecisionPattern {
-  regex: RegExp;
-  label: string;
-}
-
-const DECISION_PATTERNS: DecisionPattern[] = [
-  { regex: /\bif\s*\(/g, label: "if" },
-  { regex: /\belse\s+if\s*\(/g, label: "elseif" },
-  { regex: /\bfor\s*\(/g, label: "for" },
-  { regex: /\bwhile\s*\(/g, label: "while" },
-  { regex: /\bdo\s*\{/g, label: "do" },
-  { regex: /\bcatch\s*\(/g, label: "catch" },
-  { regex: /\bcase\s+/g, label: "case" },
-  { regex: /\|\|/g, label: "or" },
-  { regex: /&&/g, label: "and" },
-];
-
-function stripComments(code: string): string {
-  return code
-    .replace(/\/\/.*$/gm, "")
-    .replace(/\/\*[\s\S]*?\*\//g, "");
-}
-
-function stripStrings(code: string): string {
-  const inString = (s: string) => {
-    let result = "";
-    let i = 0;
-    while (i < s.length) {
-      if (s[i] === '"' || s[i] === "'" || s[i] === "`") {
-        const quote = s[i];
-        i++;
-        while (i < s.length && s[i] !== quote) {
-          if (s[i] === "\\") i++;
-          i++;
-        }
-      } else {
-        result += s[i];
-      }
-      i++;
-    }
-    return result;
-  };
-  return inString(code);
-}
-
-export function cyclomaticComplexity(sourceCode: string): number {
-  const cleaned = stripStrings(stripComments(sourceCode));
-  let decisions = 0;
-
-  for (const dp of DECISION_PATTERNS) {
-    const matches = cleaned.match(dp.regex);
-    if (matches) decisions += matches.length;
-  }
-
-  const elseIfCount = (cleaned.match(/\belse\s+if\s*\(/g) || []).length;
-  decisions -= elseIfCount;
-
-  const ternaryMatches = cleaned.match(/\?/g);
-  if (ternaryMatches) {
-    for (const m of ternaryMatches) {
-      const idx = cleaned.indexOf(m);
-      const before = cleaned[idx - 1];
-      if (before !== "?" && before !== "!" && before !== "=") {
-        decisions++;
-      }
-    }
-  }
-
-  return Math.max(1, 1 + decisions);
-}
-
-export interface ComplexityResult {
-  symbol: SymbolNode;
-  complexity: number;
-}
-
-export function analyzeComplexity(
-  graph: Graph,
-  fileFilter?: string,
-): ComplexityResult[] {
-  const results: ComplexityResult[] = [];
-  const root = graph.root;
-
-  for (const sym of graph.symbols) {
-    if (fileFilter && !sym.file.includes(fileFilter)) continue;
-    if (sym.kind !== "function" && sym.kind !== "method") continue;
-
-    const filePath = path.join(root, sym.file);
-    try {
-      const content = fs.readFileSync(filePath, "utf-8");
-      const lines = content.split("\n");
-      const start = Math.max(0, sym.line - 1);
-      const end = Math.min(lines.length, sym.endLine);
-      const snippet = lines.slice(start, end).join("\n");
-      const complexity = cyclomaticComplexity(snippet);
-      results.push({ symbol: sym, complexity });
-    } catch {
-      continue;
-    }
-  }
-
-  return results;
-}