@shvmgyl15/tsgraph 0.1.0

package/src/traversal/traversal.test.ts

@@ -0,0 +1,266 @@
+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,
+  makeTestEdge,
+  makeFileNode,
+} from "../graph/types.js";
+import { impact, findPath, findOrphans, trace } from "./traversal.js";
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "tsgraph-test-"));
+}
+
+describe("impact", () => {
+  it("finds direct callers", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "b", name: "b", kind: "function", file: "b.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "c", name: "c", kind: "function", file: "c.ts", line: 1, endLine: 1 }),
+      ],
+      calls: [
+        makeCallEdge({ callerSymbolId: "b", callerName: "b", calleeRaw: "a", file: "b.ts", line: 1 }),
+        makeCallEdge({ callerSymbolId: "c", callerName: "c", calleeRaw: "a", file: "c.ts", line: 1 }),
+      ],
+    });
+
+    const results = impact(graph, "a");
+    expect(results).toHaveLength(2);
+    const names = results.map((r) => r.symbol.name).sort();
+    expect(names).toEqual(["b", "c"]);
+    expect(results.every((r) => r.depth === 1)).toBe(true);
+  });
+
+  it("traverses multiple levels", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "b", name: "b", kind: "function", file: "b.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "c", name: "c", kind: "function", file: "c.ts", line: 1, endLine: 1 }),
+      ],
+      calls: [
+        makeCallEdge({ callerSymbolId: "b", callerName: "b", calleeRaw: "a", file: "b.ts", line: 1 }),
+        makeCallEdge({ callerSymbolId: "c", callerName: "c", calleeRaw: "b", file: "c.ts", line: 1 }),
+      ],
+    });
+
+    const results = impact(graph, "a");
+    expect(results).toHaveLength(2);
+    const b = results.find((r) => r.symbol.name === "b");
+    const c = results.find((r) => r.symbol.name === "c");
+    expect(b).toBeTruthy();
+    expect(c).toBeTruthy();
+    expect(b!.depth).toBe(1);
+    expect(c!.depth).toBe(2);
+  });
+
+  it("respects max depth", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "b", name: "b", kind: "function", file: "b.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "c", name: "c", kind: "function", file: "c.ts", line: 1, endLine: 1 }),
+      ],
+      calls: [
+        makeCallEdge({ callerSymbolId: "b", callerName: "b", calleeRaw: "a", file: "b.ts", line: 1 }),
+        makeCallEdge({ callerSymbolId: "c", callerName: "c", calleeRaw: "b", file: "c.ts", line: 1 }),
+      ],
+    });
+
+    const results = impact(graph, "a", 1);
+    expect(results).toHaveLength(1);
+    expect(results[0].symbol.name).toBe("b");
+  });
+
+  it("returns empty for symbol with no callers", () => {
+    const graph = makeGraph({
+      symbols: [makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 })],
+    });
+    const results = impact(graph, "a");
+    expect(results).toHaveLength(0);
+  });
+
+  it("returns empty for unknown symbol", () => {
+    const graph = makeGraph();
+    const results = impact(graph, "noop");
+    expect(results).toHaveLength(0);
+  });
+});
+
+describe("findPath", () => {
+  it("finds a direct path between two symbols", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "b", name: "b", kind: "function", file: "b.ts", line: 1, endLine: 1 }),
+      ],
+      calls: [makeCallEdge({ callerSymbolId: "a", callerName: "a", calleeRaw: "b", file: "a.ts", line: 1 })],
+    });
+
+    const p = findPath(graph, "a", "b");
+    expect(p).toBeTruthy();
+    expect(p!.map((n) => n.name)).toEqual(["a", "b"]);
+  });
+
+  it("finds a multi-hop path", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "b", name: "b", kind: "function", file: "b.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "c", name: "c", kind: "function", file: "c.ts", line: 1, endLine: 1 }),
+      ],
+      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 p = findPath(graph, "a", "c");
+    expect(p).toBeTruthy();
+    expect(p!.map((n) => n.name)).toEqual(["a", "b", "c"]);
+  });
+
+  it("returns self-path when from === to", () => {
+    const graph = makeGraph({
+      symbols: [makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 })],
+    });
+    const p = findPath(graph, "a", "a");
+    expect(p).toBeTruthy();
+    expect(p!.map((n) => n.name)).toEqual(["a"]);
+  });
+
+  it("returns undefined when no path exists", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "a", name: "a", kind: "function", file: "a.ts", line: 1, endLine: 1 }),
+        makeSymbolNode({ id: "b", name: "b", kind: "function", file: "b.ts", line: 1, endLine: 1 }),
+      ],
+    });
+    const p = findPath(graph, "a", "b");
+    expect(p).toBeUndefined();
+  });
+
+  it("returns undefined for unknown symbols", () => {
+    const graph = makeGraph();
+    expect(findPath(graph, "a", "b")).toBeUndefined();
+    expect(findPath(graph, "a", "a")).toBeUndefined();
+  });
+});
+
+describe("findOrphans", () => {
+  it("skips unexported symbols that are called", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "a", name: "a", kind: "function", isExported: false }),
+        makeSymbolNode({ id: "b", name: "b", kind: "function", isExported: true }),
+      ],
+      calls: [makeCallEdge({ callerSymbolId: "b", callerName: "b", calleeRaw: "a", file: "b.ts", line: 1 })],
+    });
+
+    const orphans = findOrphans(graph);
+    const deadNames = orphans.map((o) => o.symbol.name);
+    expect(deadNames).not.toContain("a"); // "a" is called by "b"
+  });
+
+  it("flags unexported symbols with no callers", () => {
+    const graph = makeGraph({
+      symbols: [
+        makeSymbolNode({ id: "dead", name: "dead", kind: "function", isExported: false }),
+        makeSymbolNode({ id: "alive", name: "alive", kind: "function", isExported: false }),
+      ],
+      calls: [makeCallEdge({ callerSymbolId: "alive", callerName: "alive", calleeRaw: "nonexistent", file: "x.ts", line: 1 })],
+    });
+
+    const orphans = findOrphans(graph);
+    expect(orphans.some((o) => o.symbol.name === "dead")).toBe(true);
+  });
+
+  it("flags exported symbols with no callers or tests", () => {
+    const graph = makeGraph({
+      symbols: [makeSymbolNode({ id: "unused", name: "unused", kind: "function", isExported: true })],
+    });
+
+    const orphans = findOrphans(graph);
+    expect(orphans).toHaveLength(1);
+    expect(orphans[0].symbol.name).toBe("unused");
+  });
+
+  it("excludes symbols referenced in tests", () => {
+    const graph = makeGraph({
+      symbols: [makeSymbolNode({ id: "tested", name: "tested", kind: "function", isExported: false })],
+      testEdges: [makeTestEdge({ testFunc: "test.ts", target: "tested", file: "test.ts", line: 1 })],
+    });
+
+    const orphans = findOrphans(graph);
+    expect(orphans).toHaveLength(0);
+  });
+});
+
+describe("trace", () => {
+  it("finds string matches in symbol bodies and their callers", () => {
+    const dir = createTempDir();
+    const filePath = path.join(dir, "src/lib.ts");
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(
+      filePath,
+      [
+        'function doStuff() {',
+        '  throw new Error("boom");',
+        '}',
+        'function caller() {',
+        '  doStuff();',
+        '}',
+      ].join("\n"),
+      "utf-8",
+    );
+
+    const graph = makeGraph({
+      root: dir,
+      symbols: [
+        makeSymbolNode({ id: "doStuff", name: "doStuff", kind: "function", file: "src/lib.ts", line: 1, endLine: 3 }),
+        makeSymbolNode({ id: "caller", name: "caller", kind: "function", file: "src/lib.ts", line: 4, endLine: 6 }),
+      ],
+      calls: [
+        makeCallEdge({ callerSymbolId: "caller", callerName: "caller", calleeRaw: "doStuff", file: "src/lib.ts", line: 5 }),
+      ],
+    });
+
+    const results = trace(graph, "boom");
+    expect(results).toHaveLength(1);
+    expect(results[0].match.symbol.name).toBe("doStuff");
+    expect(results[0].match.contextLine).toContain("boom");
+    expect(results[0].callers).toHaveLength(1);
+    expect(results[0].callers[0].symbol.name).toBe("caller");
+
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("returns empty for no match", () => {
+    const graph = makeGraph({
+      symbols: [makeSymbolNode({ id: "foo", name: "foo", kind: "function", file: "x.ts", line: 1, endLine: 1 })],
+    });
+    const results = trace(graph, "nonexistent");
+    expect(results).toHaveLength(0);
+  });
+
+  it("is case-insensitive", () => {
+    const dir = createTempDir();
+    const filePath = path.join(dir, "x.ts");
+    fs.writeFileSync(filePath, 'function foo() { return "HELLO"; }', "utf-8");
+
+    const graph = makeGraph({
+      root: dir,
+      symbols: [makeSymbolNode({ id: "foo", name: "foo", kind: "function", file: "x.ts", line: 1, endLine: 1 })],
+    });
+
+    const results = trace(graph, "hello");
+    expect(results).toHaveLength(1);
+
+    fs.rmSync(dir, { recursive: true });
+  });
+});

package/src/traversal/traversal.ts

@@ -0,0 +1,185 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { Graph, SymbolNode } from "../graph/types.js";
+
+export interface ImpactNode {
+  symbol: SymbolNode;
+  depth: number;
+  callChain: string[];
+}
+
+export function impact(
+  graph: Graph,
+  symbolName: string,
+  maxDepth: number = 5,
+): ImpactNode[] {
+  const start = graph.symbols.find((s) => s.name === symbolName);
+  if (!start) return [];
+
+  const results: ImpactNode[] = [];
+  const visited = new Set<string>();
+  const queue: { sym: SymbolNode; depth: number; chain: string[] }[] = [
+    { sym: start, depth: 0, chain: [start.name] },
+  ];
+  visited.add(start.id);
+
+  while (queue.length > 0) {
+    const { sym, depth, chain } = queue.shift()!;
+    if (depth > 0) {
+      results.push({ symbol: sym, depth, callChain: chain });
+    }
+    if (depth >= maxDepth) continue;
+
+    const callers = graph.calls.filter((c) => c.calleeRaw === sym.name);
+    for (const edge of callers) {
+      const caller = graph.symbols.find((s) => s.id === edge.callerSymbolId);
+      if (!caller || visited.has(caller.id)) continue;
+      visited.add(caller.id);
+      queue.push({
+        sym: caller,
+        depth: depth + 1,
+        chain: [...chain, caller.name],
+      });
+    }
+  }
+
+  return results;
+}
+
+export interface PathNode {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+}
+
+export function findPath(
+  graph: Graph,
+  fromName: string,
+  toName: string,
+  maxDepth: number = 10,
+): PathNode[] | undefined {
+  const from = graph.symbols.find((s) => s.name === fromName);
+  const to = graph.symbols.find((s) => s.name === toName);
+  if (!from || !to) return undefined;
+  if (from.id === to.id) return [{ name: from.name, kind: from.kind, file: from.file, line: from.line }];
+
+  const visited = new Set<string>();
+  const parent = new Map<string, { prev: string; edge: { name: string; kind: string; file: string; line: number } }>();
+  const queue: string[] = [from.id];
+  visited.add(from.id);
+
+  while (queue.length > 0) {
+    const currentId = queue.shift()!;
+    const current = graph.symbols.find((s) => s.id === currentId);
+    if (!current) continue;
+
+    const calleeEdges = graph.calls.filter((c) => c.callerSymbolId === currentId);
+    for (const edge of calleeEdges) {
+      const callee = graph.symbols.find(
+        (s) => s.name === edge.calleeRaw,
+      );
+      if (!callee || visited.has(callee.id)) continue;
+      visited.add(callee.id);
+      parent.set(callee.id, {
+        prev: currentId,
+        edge: { name: callee.name, kind: callee.kind, file: callee.file, line: callee.line },
+      });
+      if (callee.id === to.id) {
+        const pathNodes: PathNode[] = [];
+        let step: string | undefined = to.id;
+        while (step) {
+          const sym = graph.symbols.find((s) => s.id === step)!;
+          pathNodes.unshift({ name: sym.name, kind: sym.kind, file: sym.file, line: sym.line });
+          const p = parent.get(step);
+          step = p?.prev;
+        }
+        return pathNodes;
+      }
+      queue.push(callee.id);
+    }
+  }
+
+  return undefined;
+}
+
+export interface OrphanResult {
+  symbol: SymbolNode;
+  reason: string;
+}
+
+export function findOrphans(graph: Graph): OrphanResult[] {
+  const calledNames = new Set(graph.calls.map((c) => c.calleeRaw));
+  const testTargets = new Set(graph.testEdges.map((t) => t.target));
+
+  const results: OrphanResult[] = [];
+
+  for (const sym of graph.symbols) {
+    if (sym.isExported) {
+      const incomingCallers = graph.calls.filter((c) => c.calleeRaw === sym.name);
+      if (incomingCallers.length === 0 && !testTargets.has(sym.name)) {
+        results.push({ symbol: sym, reason: "exported but no callers or tests" });
+      }
+    } else {
+      if (!calledNames.has(sym.name) && !testTargets.has(sym.name)) {
+        results.push({ symbol: sym, reason: "unexported, no callers or tests" });
+      }
+    }
+  }
+
+  return results;
+}
+
+export interface TraceMatch {
+  symbol: SymbolNode;
+  file: string;
+  line: number;
+  contextLine: string;
+}
+
+export interface TraceResult {
+  match: TraceMatch;
+  callers: ImpactNode[];
+}
+
+export function trace(
+  graph: Graph,
+  searchString: string,
+  maxDepth: number = 5,
+): TraceResult[] {
+  const lowerSearch = searchString.toLowerCase();
+  const results: TraceResult[] = [];
+
+  for (const sym of graph.symbols) {
+    if (sym.kind !== "function" && sym.kind !== "method") continue;
+
+    const filePath = path.join(graph.root, sym.file);
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const lines = content.split("\n");
+    const start = Math.max(0, sym.line - 1);
+    const end = Math.min(lines.length, sym.endLine);
+
+    for (let i = start; i < end; i++) {
+      if (lines[i].toLowerCase().includes(lowerSearch)) {
+        const impactNodes = impact(graph, sym.name, maxDepth);
+        results.push({
+          match: {
+            symbol: sym,
+            file: sym.file,
+            line: i + 1,
+            contextLine: lines[i].trim(),
+          },
+          callers: impactNodes,
+        });
+      }
+    }
+  }
+
+  return results;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ESNext"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+});