@ebowwa/dependency-graph 1.0.0

package/src/builder.ts

@@ -0,0 +1,366 @@
+/**
+ * @ebowwa/dependency-graph - Graph Builder
+ *
+ * Builds dependency graphs from package.json and import analysis
+ */
+
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import type {
+  DependencyGraph,
+  DependencyNode,
+  DependencyEdge,
+  BuildOptions,
+} from "./types.js";
+
+interface PackageInfo {
+  name: string;
+  path: string;
+  version: string;
+}
+
+export class DependencyGraphBuilder {
+  private monorepoRoot: string;
+  private graph: DependencyGraph;
+  private packageCache: Map<string, { path: string; pkg: Record<string, unknown> }> = new Map();
+
+  constructor(monorepoRoot: string) {
+    this.monorepoRoot = monorepoRoot;
+    this.graph = {
+      nodes: new Map(),
+      edges: [],
+      reverseEdges: new Map(),
+    };
+  }
+
+  /**
+   * Build the complete dependency graph
+   */
+  async build(options: BuildOptions = {}): Promise<DependencyGraph> {
+    const {
+      includeDevDependencies = false,
+      analyzeImports = true,
+      excludePatterns = [],
+    } = options;
+
+    // Discover all packages in the monorepo
+    const packages = await this.discoverPackages();
+
+    // Add nodes for all packages
+    for (const pkg of packages) {
+      this.addNode(pkg.name, pkg.path, "workspace", pkg.version);
+    }
+
+    // Analyze dependencies for each package
+    for (const pkg of packages) {
+      await this.analyzePackageDependencies(
+        pkg,
+        includeDevDependencies,
+        excludePatterns
+      );
+
+      if (analyzeImports) {
+        await this.analyzeImports(pkg);
+      }
+    }
+
+    // Build reverse edges for impact analysis
+    this.buildReverseEdges();
+
+    return this.graph;
+  }
+
+  /**
+   * Discover all package.json files in the monorepo
+   */
+  private async discoverPackages(): Promise<PackageInfo[]> {
+    const packages: PackageInfo[] = [];
+    const seen = new Set<string>();
+
+    // Search in common locations
+    const searchPaths = [
+      this.monorepoRoot,
+      join(this.monorepoRoot, "packages"),
+      join(this.monorepoRoot, "packages/src"),
+      join(this.monorepoRoot, "apps"),
+      join(this.monorepoRoot, "MCP/packages"),
+    ];
+
+    for (const searchPath of searchPaths) {
+      if (!existsSync(searchPath)) continue;
+      await this.searchDirectory(searchPath, packages, seen, 0, 4);
+    }
+
+    return packages;
+  }
+
+  /**
+   * Recursively search for package.json files
+   */
+  private async searchDirectory(
+    dir: string,
+    packages: PackageInfo[],
+    seen: Set<string>,
+    depth: number,
+    maxDepth: number
+  ): Promise<void> {
+    if (depth > maxDepth) return;
+
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        // Skip node_modules and hidden dirs
+        if (entry.name === "node_modules" || entry.name.startsWith("."))
+          continue;
+        if (entry.name === "dist" || entry.name === "build") continue;
+
+        const fullPath = join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+          await this.searchDirectory(
+            fullPath,
+            packages,
+            seen,
+            depth + 1,
+            maxDepth
+          );
+        } else if (entry.name === "package.json") {
+          const packageDir = dirname(fullPath);
+          const relativePath = relative(this.monorepoRoot, packageDir);
+
+          if (seen.has(relativePath)) continue;
+          seen.add(relativePath);
+
+          try {
+            const pkg = JSON.parse(readFileSync(fullPath, "utf-8"));
+            if (pkg.name && !pkg.private) {
+              packages.push({
+                name: pkg.name,
+                path: relativePath,
+                version: pkg.version || "0.0.0",
+              });
+              this.packageCache.set(pkg.name, { path: relativePath, pkg });
+            }
+          } catch {
+            // Invalid package.json, skip
+          }
+        }
+      }
+    } catch {
+      // Directory not accessible, skip
+    }
+  }
+
+  /**
+   * Analyze package.json dependencies
+   */
+  private async analyzePackageDependencies(
+    pkg: PackageInfo,
+    includeDev: boolean,
+    excludePatterns: string[]
+  ): Promise<void> {
+    const pkgPath = join(this.monorepoRoot, pkg.path, "package.json");
+    if (!existsSync(pkgPath)) return;
+
+    const packageJson = JSON.parse(readFileSync(pkgPath, "utf-8"));
+
+    const depTypes = ["dependencies"];
+    if (includeDev)
+      depTypes.push("devDependencies", "peerDependencies", "optionalDependencies");
+
+    for (const depType of depTypes) {
+      const deps = packageJson[depType];
+      if (!deps) continue;
+
+      for (const [depName, depVersion] of Object.entries(
+        deps as Record<string, string>
+      )) {
+        // Check if this matches any exclude pattern
+        if (excludePatterns.some((pattern) => depName.match(pattern))) continue;
+
+        const isWorkspace =
+          depVersion === "workspace:*" ||
+          depVersion === "workspace:^" ||
+          depVersion === "workspace:~";
+
+        if (isWorkspace) {
+          // This is a workspace dependency
+          const targetPkg = this.packageCache.get(depName);
+          if (targetPkg) {
+            this.addEdge(pkg.name, depName, "workspace");
+          }
+        } else if (this.packageCache.has(depName)) {
+          // It's a local package but not using workspace: protocol
+          this.addEdge(pkg.name, depName, "workspace");
+        } else {
+          // External dependency
+          this.addNode(depName, "", "external", depVersion as string);
+          this.addEdge(pkg.name, depName, "external");
+        }
+      }
+    }
+  }
+
+  /**
+   * Analyze TypeScript/JavaScript imports
+   */
+  private async analyzeImports(pkg: PackageInfo): Promise<void> {
+    const pkgDir = join(this.monorepoRoot, pkg.path);
+
+    // Common source directories
+    const sourceDirs = ["src", "lib", ""];
+
+    for (const sourceDir of sourceDirs) {
+      const searchPath = sourceDir ? join(pkgDir, sourceDir) : pkgDir;
+      if (!existsSync(searchPath)) continue;
+      await this.analyzeImportsInDirectory(pkg.name, searchPath);
+    }
+  }
+
+  /**
+   * Recursively analyze imports in a directory
+   */
+  private async analyzeImportsInDirectory(
+    packageName: string,
+    dir: string
+  ): Promise<void> {
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+        if (entry.name === "dist" || entry.name === "build") continue;
+
+        const fullPath = join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+          await this.analyzeImportsInDirectory(packageName, fullPath);
+        } else if (
+          entry.name.endsWith(".ts") ||
+          entry.name.endsWith(".tsx") ||
+          entry.name.endsWith(".js") ||
+          entry.name.endsWith(".jsx") ||
+          entry.name.endsWith(".mjs")
+        ) {
+          await this.analyzeImportsInFile(packageName, fullPath);
+        }
+      }
+    } catch {
+      // Directory not accessible
+    }
+  }
+
+  /**
+   * Analyze imports in a single file
+   */
+  private async analyzeImportsInFile(
+    packageName: string,
+    filePath: string
+  ): Promise<void> {
+    try {
+      const content = readFileSync(filePath, "utf-8");
+
+      // Match various import patterns
+      const importPatterns = [
+        // ES imports: import ... from '...' | import ... from "..."
+        /import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s*,?\s*)*\s+from\s+['"]([^'"]+)['"]/g,
+        // Dynamic imports: import('...')
+        /import\(['"]([^'"]+)['"]\)/g,
+        // require(): require('...') | require("...")
+        /require\(['"]([^'"]+)['"]\)/g,
+        // Export from: export ... from '...'
+        /export\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+)\s+from\s+)?['"]([^'"]+)['"]/g,
+      ];
+
+      for (const pattern of importPatterns) {
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+          const importPath = match[1];
+
+          // Skip relative imports
+          if (importPath.startsWith(".") || importPath.startsWith("/")) continue;
+
+          // Check if this is a known workspace package
+          for (const [pkgName, pkgData] of this.packageCache) {
+            if (
+              importPath === pkgName ||
+              importPath.startsWith(pkgName + "/")
+            ) {
+              this.addEdge(packageName, pkgName, "import", importPath);
+              break;
+            }
+          }
+        }
+      }
+    } catch {
+      // File not readable
+    }
+  }
+
+  /**
+   * Add a node to the graph
+   */
+  private addNode(
+    name: string,
+    path: string,
+    type: "package" | "workspace" | "external",
+    version?: string
+  ): void {
+    if (!this.graph.nodes.has(name)) {
+      this.graph.nodes.set(name, { name, path, type, version });
+      this.graph.reverseEdges.set(name, new Set());
+    }
+  }
+
+  /**
+   * Add an edge to the graph
+   */
+  private addEdge(
+    from: string,
+    to: string,
+    type: "workspace" | "external" | "import",
+    importPath?: string
+  ): void {
+    // Skip self-references
+    if (from === to) return;
+
+    // Check if edge already exists
+    const existing = this.graph.edges.find((e) => e.from === from && e.to === to);
+    if (existing) return;
+
+    this.graph.edges.push({ from, to, type, importPath });
+
+    // Update reverse edges
+    if (!this.graph.reverseEdges.has(to)) {
+      this.graph.reverseEdges.set(to, new Set());
+    }
+    this.graph.reverseEdges.get(to)!.add(from);
+  }
+
+  /**
+   * Build reverse edges for impact analysis
+   */
+  private buildReverseEdges(): void {
+    for (const [to, dependents] of this.graph.reverseEdges) {
+      // Ensure node exists
+      if (!this.graph.nodes.has(to)) {
+        this.graph.nodes.set(to, { name: to, path: "", type: "external" });
+      }
+    }
+  }
+
+  /**
+   * Get the built graph
+   */
+  getGraph(): DependencyGraph {
+    return this.graph;
+  }
+
+  /**
+   * Get the monorepo root
+   */
+  getMonorepoRoot(): string {
+    return this.monorepoRoot;
+  }
+}

package/src/formatters.ts

@@ -0,0 +1,191 @@
+/**
+ * @ebowwa/dependency-graph - Output Formatters
+ *
+ * Format dependency graphs for various output formats
+ */
+
+import type { DependencyGraph, OutputFormat } from "./types.js";
+
+/**
+ * Format the graph for output
+ */
+export function formatGraph(graph: DependencyGraph, format: OutputFormat): string {
+  switch (format) {
+    case "mermaid":
+      return formatAsMermaid(graph);
+    case "dot":
+      return formatAsDot(graph);
+    case "tree":
+      return formatAsTree(graph);
+    case "json":
+    default:
+      return formatAsJson(graph);
+  }
+}
+
+/**
+ * Format as JSON
+ */
+export function formatAsJson(graph: DependencyGraph): string {
+  return JSON.stringify(
+    {
+      nodes: Array.from(graph.nodes.values()),
+      edges: graph.edges,
+    },
+    null,
+    2
+  );
+}
+
+/**
+ * Format as Mermaid diagram
+ */
+export function formatAsMermaid(graph: DependencyGraph): string {
+  const lines = ["graph TD"];
+
+  // Add nodes
+  for (const [name, node] of graph.nodes) {
+    const label = node.type === "workspace" ? `📦 ${name}` : `📚 ${name}`;
+    lines.push(`  ${sanitizeId(name)}["${label}"]`);
+  }
+
+  // Add edges
+  for (const edge of graph.edges) {
+    const from = sanitizeId(edge.from);
+    const to = sanitizeId(edge.to);
+    const label =
+      edge.type === "workspace"
+        ? "workspace"
+        : edge.type === "import"
+          ? "imports"
+          : "external";
+    lines.push(`  ${from} -->|${label}| ${to}`);
+  }
+
+  // Add styles
+  lines.push("  classDef workspace fill:#e1f5fe");
+  lines.push("  classDef external fill:#f5f5f5");
+  lines.push("  classDef import fill:#fff3e0");
+
+  for (const [name, node] of graph.nodes) {
+    const id = sanitizeId(name);
+    if (node.type === "workspace") {
+      lines.push(`  class ${id} workspace`);
+    } else if (node.type === "external") {
+      lines.push(`  class ${id} external`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format as Graphviz DOT
+ */
+export function formatAsDot(graph: DependencyGraph): string {
+  const lines = ["digraph dependencies {"];
+  lines.push("  rankdir=LR;");
+  lines.push("  node [shape=box];");
+
+  // Add nodes
+  for (const [name, node] of graph.nodes) {
+    const color = node.type === "workspace" ? "lightblue" : "lightgray";
+    lines.push(`  "${name}" [fillcolor=${color}, style=filled];`);
+  }
+
+  // Add edges
+  for (const edge of graph.edges) {
+    const style = edge.type === "workspace" ? "solid" : "dashed";
+    lines.push(
+      `  "${edge.from}" -> "${edge.to}" [style=${style}, label="${edge.type}"];`
+    );
+  }
+
+  lines.push("}");
+  return lines.join("\n");
+}
+
+/**
+ * Format as ASCII tree
+ */
+export function formatAsTree(graph: DependencyGraph): string {
+  const lines: string[] = [];
+  const seen = new Set<string>();
+
+  // Find root nodes (no incoming edges from other workspace packages)
+  const workspaceNodes = Array.from(graph.nodes.values()).filter(
+    (n) => n.type === "workspace"
+  );
+  const incomingEdges = new Map<string, number>();
+
+  for (const node of workspaceNodes) {
+    incomingEdges.set(node.name, 0);
+  }
+
+  for (const edge of graph.edges) {
+    if (graph.nodes.get(edge.to)?.type === "workspace") {
+      incomingEdges.set(edge.to, (incomingEdges.get(edge.to) || 0) + 1);
+    }
+  }
+
+  // Start from roots
+  for (const [name, node] of graph.nodes) {
+    if (node.type === "workspace" && (incomingEdges.get(name) || 0) === 0) {
+      lines.push(`📦 ${name}`);
+      printTree(graph, name, "", seen, lines);
+    }
+  }
+
+  // Add any disconnected nodes
+  for (const [name, node] of graph.nodes) {
+    if (!seen.has(name) && node.type === "workspace") {
+      lines.push(`📦 ${name} (disconnected)`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function printTree(
+  graph: DependencyGraph,
+  nodeName: string,
+  prefix: string,
+  seen: Set<string>,
+  lines: string[]
+): void {
+  seen.add(nodeName);
+
+  // Find outgoing edges to other workspace packages
+  const outgoing = graph.edges.filter(
+    (e) =>
+      e.from === nodeName && graph.nodes.get(e.to)?.type === "workspace"
+  );
+
+  for (let i = 0; i < outgoing.length; i++) {
+    const edge = outgoing[i];
+    const isLast = i === outgoing.length - 1;
+    const connector = isLast ? "└──" : "├──";
+    const childPrefix = prefix + (isLast ? "    " : "│   ");
+
+    lines.push(`${prefix}${connector} 📦 ${edge.to} [${edge.type}]`);
+    if (!seen.has(edge.to)) {
+      printTree(graph, edge.to, childPrefix, seen, lines);
+    }
+  }
+
+  // Show external dependencies count
+  const externals = graph.edges.filter(
+    (e) =>
+      e.from === nodeName && graph.nodes.get(e.to)?.type === "external"
+  );
+  if (externals.length > 0) {
+    lines.push(`${prefix}└── 📚 ${externals.length} external dependencies`);
+  }
+}
+
+/**
+ * Sanitize ID for Mermaid/DOT formats
+ */
+function sanitizeId(name: string): string {
+  return name.replace(/[^a-zA-Z0-9]/g, "_");
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @ebowwa/dependency-graph
+ *
+ * Core dependency graph analysis and visualization for monorepos
+ *
+ * @example
+ * ```typescript
+ * import { DependencyGraphBuilder, formatGraph, analyzeImpact, findCircularDependencies } from '@ebowwa/dependency-graph';
+ *
+ * const builder = new DependencyGraphBuilder('/path/to/monorepo');
+ * const graph = await builder.build({ analyzeImports: true });
+ *
+ * // Format as Mermaid diagram
+ * const mermaid = formatGraph(graph, 'mermaid');
+ *
+ * // Find circular dependencies
+ * const cycles = findCircularDependencies(graph);
+ *
+ * // Analyze impact of changing a package
+ * const impact = analyzeImpact(graph, '@ebowwa/terminal');
+ * ```
+ */
+
+// Types
+export type {
+  DependencyNode,
+  DependencyEdge,
+  DependencyGraph,
+  ImportInfo,
+  BuildOptions,
+  ImpactResult,
+  OutputFormat,
+  PackageInfo,
+} from "./types.js";
+
+// Builder
+export { DependencyGraphBuilder } from "./builder.js";
+
+// Analysis
+export {
+  findCircularDependencies,
+  analyzeImpact,
+  findUnusedPackages,
+  getPackageInfo,
+  getWorkspacePackages,
+  getExternalDependencies,
+} from "./analysis.js";
+
+// Formatters
+export {
+  formatGraph,
+  formatAsJson,
+  formatAsMermaid,
+  formatAsDot,
+  formatAsTree,
+} from "./formatters.js";

package/src/types.ts

@@ -0,0 +1,58 @@
+/**
+ * @ebowwa/dependency-graph - Core Types
+ *
+ * Type definitions for dependency graph analysis
+ */
+
+export interface DependencyNode {
+  name: string;
+  path: string;
+  type: "package" | "workspace" | "external";
+  version?: string;
+}
+
+export interface DependencyEdge {
+  from: string;
+  to: string;
+  type: "workspace" | "external" | "import";
+  importPath?: string;
+}
+
+export interface DependencyGraph {
+  nodes: Map<string, DependencyNode>;
+  edges: DependencyEdge[];
+  reverseEdges: Map<string, Set<string>>;
+}
+
+export interface ImportInfo {
+  from: string;
+  imports: string[];
+  file: string;
+}
+
+export interface BuildOptions {
+  includeDevDependencies?: boolean;
+  analyzeImports?: boolean;
+  excludePatterns?: string[];
+}
+
+export interface ImpactResult {
+  direct: string[];
+  transitive: string[];
+  all: string[];
+}
+
+export type OutputFormat = "json" | "mermaid" | "dot" | "tree";
+
+export interface PackageInfo {
+  name: string;
+  type: "package" | "workspace" | "external";
+  path: string;
+  version?: string;
+  dependencies: Array<{
+    name: string;
+    type: "workspace" | "external" | "import";
+    version?: string;
+  }>;
+  dependents: string[];
+}