@shvmgyl15/tsgraph 0.1.0

package/src/boundaries/index.test.ts

@@ -0,0 +1,335 @@
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import {
+  makeGraph,
+  makeImportEdge,
+  makeFileNode,
+  makePackageNode,
+} from "../graph/types.js";
+import {
+  loadBoundariesConfig,
+  checkBoundaries,
+} from "./index.js";
+import type { BoundariesConfig, LayerConfig } from "./index.js";
+
+function createTempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "tsgraph-boundaries-"));
+}
+
+function makeConfig(layers: LayerConfig[]): BoundariesConfig {
+  return { layers };
+}
+
+const uiLayer: LayerConfig = {
+  name: "ui",
+  path: "src/components",
+  dependsOn: ["shared"],
+};
+
+const sharedLayer: LayerConfig = {
+  name: "shared",
+  path: "src/shared",
+  dependsOn: ["lib"],
+};
+
+const libLayer: LayerConfig = {
+  name: "lib",
+  path: "src/lib",
+  dependsOn: [],
+};
+
+const defaultConfig = makeConfig([uiLayer, sharedLayer, libLayer]);
+
+describe("loadBoundariesConfig", () => {
+  it("reads and parses valid config", () => {
+    const dir = createTempDir();
+    const configDir = path.join(dir, ".tsgraph");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(configDir, "boundaries.json"),
+      JSON.stringify(defaultConfig),
+      "utf-8",
+    );
+    const loaded = loadBoundariesConfig(dir);
+    expect(loaded).not.toBeNull();
+    expect(loaded!.layers).toHaveLength(3);
+    expect(loaded!.layers[0].name).toBe("ui");
+    expect(loaded!.layers[0].dependsOn).toEqual(["shared"]);
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("returns null when file does not exist", () => {
+    const dir = createTempDir();
+    const loaded = loadBoundariesConfig(dir);
+    expect(loaded).toBeNull();
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("returns null for invalid JSON", () => {
+    const dir = createTempDir();
+    const configDir = path.join(dir, ".tsgraph");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(configDir, "boundaries.json"),
+      "not json",
+      "utf-8",
+    );
+    const loaded = loadBoundariesConfig(dir);
+    expect(loaded).toBeNull();
+    fs.rmSync(dir, { recursive: true });
+  });
+
+  it("returns null for invalid schema", () => {
+    const dir = createTempDir();
+    const configDir = path.join(dir, ".tsgraph");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(configDir, "boundaries.json"),
+      JSON.stringify({ layers: [{ name: "ui" }] }),
+      "utf-8",
+    );
+    const loaded = loadBoundariesConfig(dir);
+    expect(loaded).toBeNull();
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
+describe("checkBoundaries", () => {
+  it("allows legal import within same layer", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Button.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/components/Panel.tsx", packageName: "app" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Button.tsx",
+          fromPackage: "app",
+          importPath: "./Panel",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("allows legal import to a depended-on layer", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/shared/helper.ts", packageName: "shared" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../shared/helper",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("flags violation for import to a non-depended layer", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/lib/util.ts", packageName: "lib" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../lib/util",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(1);
+    expect(result.allowed).toBe(0);
+    expect(result.violations[0].fromLayer).toBe("ui");
+    expect(result.violations[0].toLayer).toBe("lib");
+    expect(result.violations[0].fromFile).toBe("src/components/Page.tsx");
+    expect(result.violations[0].toFile).toBe("src/lib/util.ts");
+    expect(result.violations[0].toPackage).toBe("lib");
+    expect(result.violations[0].rule).toBe("ui → lib not allowed");
+  });
+
+  it("allows legal import through transitive dependency chain", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/shared/util.ts", packageName: "shared" }),
+        makeFileNode({ path: "src/lib/helper.ts", packageName: "lib" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/shared/util.ts",
+          fromPackage: "shared",
+          importPath: "../lib/helper",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("treats bare module imports as allowed (unresolved)", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "react",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("treats imports to files outside known layers as allowed", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/generated/api.ts", packageName: "api" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../generated/api",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("treats files outside any layer as allowed", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/generated/api.ts", packageName: "api" }),
+        makeFileNode({ path: "src/lib/util.ts", packageName: "lib" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/generated/api.ts",
+          fromPackage: "api",
+          importPath: "../lib/util",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("handles mixed allowed and violating imports", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/shared/helper.ts", packageName: "shared" }),
+        makeFileNode({ path: "src/lib/util.ts", packageName: "lib" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../shared/helper",
+        }),
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../lib/util",
+        }),
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "react",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(1);
+    expect(result.allowed).toBe(2);
+    expect(result.violations[0].toLayer).toBe("lib");
+  });
+
+  it("resolves imports with .tsx extension", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/shared/helper.tsx", packageName: "shared" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../shared/helper",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("resolves imports with index.ts pattern", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/shared/index.ts", packageName: "shared" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../shared",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(0);
+    expect(result.allowed).toBe(1);
+  });
+
+  it("populates toPackage from graph file nodes", () => {
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/components/Page.tsx", packageName: "app" }),
+        makeFileNode({ path: "src/lib/util.ts", packageName: "lib-pkg" }),
+      ],
+      imports: [
+        makeImportEdge({
+          fromFile: "src/components/Page.tsx",
+          fromPackage: "app",
+          importPath: "../lib/util",
+        }),
+      ],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.violations).toHaveLength(1);
+    expect(result.violations[0].toPackage).toBe("lib-pkg");
+  });
+
+  it("returns config in result", () => {
+    const graph = makeGraph({
+      files: [],
+      imports: [],
+    });
+    const result = checkBoundaries(graph, defaultConfig);
+    expect(result.config).toBe(defaultConfig);
+    expect(result.config.layers).toHaveLength(3);
+  });
+});

package/src/boundaries/index.ts

@@ -0,0 +1,137 @@
+import type { Graph } from "../graph/types.js";
+import path from "node:path";
+import fs from "node:fs";
+import { z } from "zod/v4";
+
+export interface LayerConfig {
+  name: string;
+  path: string;
+  dependsOn: string[];
+}
+
+export interface BoundariesConfig {
+  layers: LayerConfig[];
+}
+
+export interface BoundaryViolation {
+  fromFile: string;
+  fromLayer: string;
+  toFile: string;
+  toLayer: string;
+  toPackage: string;
+  rule: string;
+}
+
+export interface BoundaryResult {
+  violations: BoundaryViolation[];
+  allowed: number;
+  config: BoundariesConfig;
+}
+
+const layerConfigSchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  dependsOn: z.array(z.string()),
+});
+
+const boundariesConfigSchema = z.object({
+  layers: z.array(layerConfigSchema),
+});
+
+export function loadBoundariesConfig(rootDir: string): BoundariesConfig | null {
+  const configPath = path.join(rootDir, ".tsgraph", "boundaries.json");
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const result = boundariesConfigSchema.safeParse(parsed);
+    if (!result.success) return null;
+    return result.data;
+  } catch {
+    return null;
+  }
+}
+
+const EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+const INDEX_PATTERNS = ["/index", ""];
+
+function findLayerByPath(filePath: string, config: BoundariesConfig): LayerConfig | undefined {
+  return config.layers.find((layer) => filePath.startsWith(layer.path));
+}
+
+function resolveTargetPath(fromFile: string, importPath: string): string | undefined {
+  if (importPath.startsWith(".")) {
+    const dir = path.posix.dirname(fromFile);
+    return path.posix.normalize(path.posix.join(dir, importPath));
+  }
+  if (importPath.startsWith("/")) {
+    return path.posix.normalize(importPath);
+  }
+  return undefined;
+}
+
+function matchFile(resolved: string, files: { path: string }[]): string | undefined {
+  for (const file of files) {
+    if (file.path === resolved) return file.path;
+    for (const ext of EXTENSIONS) {
+      if (file.path === resolved + ext) return file.path;
+    }
+    for (const ext of EXTENSIONS) {
+      for (const idx of INDEX_PATTERNS) {
+        if (file.path === resolved + idx + ext) return file.path;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function checkBoundaries(graph: Graph, config: BoundariesConfig): BoundaryResult {
+  const violations: BoundaryViolation[] = [];
+  let allowed = 0;
+
+  for (const imp of graph.imports) {
+    const fromLayer = findLayerByPath(imp.fromFile, config);
+    if (!fromLayer) {
+      allowed++;
+      continue;
+    }
+
+    const resolved = resolveTargetPath(imp.fromFile, imp.importPath);
+    if (!resolved) {
+      allowed++;
+      continue;
+    }
+
+    const matchedFile = matchFile(resolved, graph.files);
+    if (!matchedFile) {
+      allowed++;
+      continue;
+    }
+
+    const toLayer = findLayerByPath(matchedFile, config);
+    if (!toLayer) {
+      allowed++;
+      continue;
+    }
+
+    if (fromLayer.name === toLayer.name) {
+      allowed++;
+      continue;
+    }
+
+    if (!fromLayer.dependsOn.includes(toLayer.name)) {
+      const targetFile = graph.files.find((f) => f.path === matchedFile);
+      violations.push({
+        fromFile: imp.fromFile,
+        fromLayer: fromLayer.name,
+        toFile: matchedFile,
+        toLayer: toLayer.name,
+        toPackage: targetFile?.packageName ?? toLayer.name,
+        rule: `${fromLayer.name} → ${toLayer.name} not allowed`,
+      });
+    } else {
+      allowed++;
+    }
+  }
+
+  return { violations, allowed, config };
+}

package/src/changes/index.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from "vitest";
+import {
+  makeGraph,
+  makeFileNode,
+  makeSymbolNode,
+  makeImportEdge,
+} from "../graph/types.js";
+import { getChanges, getStale } from "./index.js";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { execSync } from "node:child_process";
+
+function createGitRepo(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tsgraph-changes-"));
+  execSync("git init", { cwd: dir, stdio: "pipe" });
+  execSync('git config user.email "test@test.com"', { cwd: dir, stdio: "pipe" });
+  execSync('git config user.name "Test"', { cwd: dir, stdio: "pipe" });
+  return dir;
+}
+
+function writeFile(root: string, relPath: string, content: string) {
+  const fullPath = path.join(root, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, "utf-8");
+}
+
+describe("getChanges", () => {
+  it("returns empty result if not a git repo", () => {
+    const graph = makeGraph({ files: [], symbols: [], imports: [] });
+    const result = getChanges(graph, "/tmp/nonexistent");
+    expect(result.totalFiles).toBe(0);
+    expect(result.totalSymbols).toBe(0);
+  });
+
+  it("finds changed files with symbols from a git diff", () => {
+    const dir = createGitRepo();
+    writeFile(dir, "src/index.ts", 'export const x = 1;\n');
+    execSync("git add . && git commit -m 'initial'", { cwd: dir, stdio: "pipe" });
+    writeFile(dir, "src/lib/util.ts", 'export const util = 2;\n');
+    execSync("git add . && git commit -m 'add util'", { cwd: dir, stdio: "pipe" });
+
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/index.ts", packageName: "app" }),
+        makeFileNode({ path: "src/lib/util.ts", packageName: "app" }),
+      ],
+      symbols: [
+        makeSymbolNode({
+          name: "x",
+          kind: "const",
+          file: "src/index.ts",
+          packageName: "app",
+          line: 1,
+          endLine: 1,
+          isExported: true,
+        }),
+        makeSymbolNode({
+          name: "util",
+          kind: "const",
+          file: "src/lib/util.ts",
+          packageName: "app",
+          line: 1,
+          endLine: 1,
+          isExported: true,
+        }),
+      ],
+      imports: [],
+    });
+
+    const result = getChanges(graph, dir, "HEAD~1");
+    expect(result.totalFiles).toBeGreaterThanOrEqual(1);
+    expect(result.totalSymbols).toBeGreaterThanOrEqual(1);
+    const utilFile = result.files.find((f) => f.path === "src/lib/util.ts");
+    expect(utilFile).toBeTruthy();
+    fs.rmSync(dir, { recursive: true });
+  });
+});
+
+describe("getStale", () => {
+  it("returns empty result if not a git repo", () => {
+    const graph = makeGraph({ files: [], symbols: [], imports: [] });
+    const result = getStale(graph, "/tmp/nonexistent");
+    expect(result.totalFiles).toBe(0);
+  });
+
+  it("returns files without recent commits", () => {
+    const dir = createGitRepo();
+    writeFile(dir, "src/old.ts", 'export const old = 1;\n');
+    execSync("git add . && git commit -m 'initial'", { cwd: dir, stdio: "pipe" });
+
+    const graph = makeGraph({
+      files: [
+        makeFileNode({ path: "src/old.ts", packageName: "app" }),
+      ],
+      symbols: [
+        makeSymbolNode({
+          name: "old",
+          kind: "const",
+          file: "src/old.ts",
+          packageName: "app",
+          line: 1,
+          endLine: 1,
+          isExported: true,
+        }),
+      ],
+      imports: [],
+    });
+
+    const result = getStale(graph, dir, 0);
+    expect(result.totalFiles).toBe(0);
+    fs.rmSync(dir, { recursive: true });
+  });
+});

package/src/changes/index.ts

@@ -0,0 +1,95 @@
+import type { Graph, SymbolNode, FileNode } from "../graph/types.js";
+import {
+  getDiffFiles,
+  getStaleFiles,
+  isGitRepo,
+} from "../git/index.js";
+import type { ChangedFile } from "../git/index.js";
+
+export interface ChangedSymbolInfo {
+  symbol: SymbolNode;
+  file: string;
+  status: ChangedFile["status"];
+}
+
+export interface ChangeResult {
+  files: {
+    path: string;
+    status: ChangedFile["status"];
+    symbolCount: number;
+  }[];
+  symbols: ChangedSymbolInfo[];
+  totalFiles: number;
+  totalSymbols: number;
+}
+
+export interface StaleResult {
+  files: {
+    path: string;
+    symbolCount: number;
+    symbolNames: string[];
+  }[];
+  totalFiles: number;
+}
+
+function symbolsInFile(graph: Graph, filePath: string): SymbolNode[] {
+  return graph.symbols.filter((s) => s.file === filePath);
+}
+
+export function getChanges(
+  graph: Graph,
+  rootDir: string,
+  base: string = "main",
+): ChangeResult {
+  if (!isGitRepo(rootDir)) {
+    return { files: [], symbols: [], totalFiles: 0, totalSymbols: 0 };
+  }
+
+  const changed = getDiffFiles(rootDir, base);
+  const files: ChangeResult["files"] = [];
+  const symbols: ChangedSymbolInfo[] = [];
+
+  for (const c of changed) {
+    const graphFile = graph.files.find((f) => f.path === c.path);
+    if (!graphFile) {
+      files.push({ path: c.path, status: c.status, symbolCount: 0 });
+      continue;
+    }
+    const fileSymbols = symbolsInFile(graph, c.path);
+    files.push({
+      path: c.path,
+      status: c.status,
+      symbolCount: fileSymbols.length,
+    });
+    for (const sym of fileSymbols) {
+      symbols.push({ symbol: sym, file: c.path, status: c.status });
+    }
+  }
+
+  return { files, symbols, totalFiles: files.length, totalSymbols: symbols.length };
+}
+
+export function getStale(
+  graph: Graph,
+  rootDir: string,
+  days: number = 90,
+): StaleResult {
+  if (!isGitRepo(rootDir)) {
+    return { files: [], totalFiles: 0 };
+  }
+
+  const stalePaths = getStaleFiles(rootDir, days);
+  const files: StaleResult["files"] = [];
+
+  for (const p of stalePaths) {
+    const syms = symbolsInFile(graph, p);
+    if (syms.length === 0) continue;
+    files.push({
+      path: p,
+      symbolCount: syms.length,
+      symbolNames: syms.map((s) => s.name),
+    });
+  }
+
+  return { files, totalFiles: files.length };
+}