cli-node-graph 1.0.1

package/dist/utils/path.d.ts

@@ -0,0 +1,9 @@
+/** Normalize a path to forward slashes. */
+export declare function toPosixPath(filePath: string): string;
+/** Get the folder path for a file. */
+export declare function folderOf(filePath: string): string;
+/** Resolve a path relative to a base directory. */
+export declare function resolveFrom(base: string, target: string): string;
+/** Get relative path from root. */
+export declare function relativeTo(root: string, filePath: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/utils/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":"AAEA,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,sCAAsC;AACtC,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,mCAAmC;AACnC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/utils/path.js

@@ -0,0 +1,18 @@
+import { dirname, normalize, relative, resolve, sep } from 'node:path';
+/** Normalize a path to forward slashes. */
+export function toPosixPath(filePath) {
+    return normalize(filePath).split(sep).join('/');
+}
+/** Get the folder path for a file. */
+export function folderOf(filePath) {
+    return toPosixPath(dirname(filePath));
+}
+/** Resolve a path relative to a base directory. */
+export function resolveFrom(base, target) {
+    return toPosixPath(resolve(base, target));
+}
+/** Get relative path from root. */
+export function relativeTo(root, filePath) {
+    return toPosixPath(relative(root, filePath));
+}
+//# sourceMappingURL=path.js.map

package/dist/utils/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEvE,2CAA2C;AAC3C,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,OAAO,SAAS,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,OAAO,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAAc;IACtD,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,QAAgB;IACvD,OAAO,WAAW,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,100 @@
+# Architecture
+
+## Overview
+
+cli-node-graph uses a layered architecture where each layer is independent and testable.
+
+```
+CLI
+  │
+  ▼
+Project Loader
+  │
+  ▼
+TypeScript Program (ProgramFactory)
+  │
+  ▼
+AST Walker (single traversal)
+  │
+  ▼
+Visitors (Import, Export, Class, Call, …)
+  │
+  ▼
+Resolvers (Symbol, Type, Module, Path)
+  │
+  ▼
+Graph Builder
+  │
+  ▼
+Graph Database
+  │
+  ├── Exporters (JSON, DOT, GraphML, …)
+  ├── Analyzers (Cycles, Impact, Dead Code, Layers)
+  └── Visualization (React Flow)
+```
+
+## Layers
+
+### Parser Layer
+
+- **ProgramFactory** — Reads `tsconfig.json`, creates `Program`, `TypeChecker`, and filtered source files
+- **ASTWalker** — Single-pass traversal dispatching to all visitors (avoids repeated AST walks)
+
+### Visitor Layer
+
+One visitor per concern:
+
+| Visitor | Responsibility |
+|---------|---------------|
+| ImportVisitor | Static and dynamic imports |
+| ExportVisitor | Exports and re-exports |
+| ClassVisitor | Classes, methods, properties, constructors |
+| InterfaceVisitor | Interface declarations |
+| EnumVisitor | Enum declarations |
+| FunctionVisitor | Functions, arrow functions, return types |
+| MethodVisitor | Method declarations |
+| VariableVisitor | Variable declarations |
+| CallVisitor | Call expressions resolved via TypeChecker |
+| DecoratorVisitor | Decorator usage |
+| TypeReferenceVisitor | Type references in signatures |
+| HeritageVisitor | extends / implements clauses |
+
+### Resolver Layer
+
+- **SymbolResolver** — `getSymbolAtLocation`, alias resolution, cached lookups
+- **TypeResolver** — `getTypeAtLocation`, call signatures, return types
+- **ModuleResolver** — Module specifier → file path resolution
+- **PathResolver** — Project-relative path normalization
+
+### Graph Layer
+
+- **Graph** — Indexed in-memory graph (by kind, file, adjacency)
+- **GraphBuilder** — Orchestrates the full pipeline
+- **GraphAlgorithms** — Topological sort, SCCs, shortest path, impact traversal
+
+### Analysis Layer
+
+- **CircularDependencyAnalyzer** — Finds all dependency cycles
+- **DeadCodeAnalyzer** — Unused exports, functions, orphan modules
+- **ImpactAnalyzer** — Downstream impact of changes
+- **DependencyAnalyzer** — Coupling metrics
+- **LayerViolationAnalyzer** — Architecture layer rule enforcement
+
+## Design Decisions
+
+1. **Single AST traversal** — All visitors run in one walk to support large codebases (100k+ nodes)
+2. **TypeChecker-first resolution** — No string matching; all symbol resolution goes through the TS API
+3. **Cached symbol lookups** — LRU cache prevents repeated TypeChecker calls
+4. **Indexed graph** — O(1) lookups by kind, file, and adjacency for fast queries
+5. **Independent exporters** — Each format is a standalone class implementing `GraphExporter`
+
+## Performance Considerations
+
+- Indexed adjacency lists for graph queries
+- Symbol lookup cache (10k entries default)
+- Filtered source files (no `.d.ts`, configurable excludes)
+- Graph filtering and cloning for subset analysis
+
+## Extensibility
+
+Add new node/edge kinds in `model/`, create a new visitor in `parser/visitors/`, register it in `GraphBuilder`. Add new exporters by implementing `GraphExporter`.

package/docs/CLI.md

@@ -0,0 +1,62 @@
+# CLI Reference
+
+## Commands
+
+### `cli-node-graph analyze [path]`
+
+Analyze a TypeScript project and build the dependency graph.
+
+```bash
+cli-node-graph analyze .
+cli-node-graph analyze ./apps/api --tsconfig tsconfig.app.json
+```
+
+### `cli-node-graph graph [path]`
+
+Show summary statistics of the cached or last-analyzed graph.
+
+### `cli-node-graph export [path] --format <format>`
+
+Export the graph to a file format.
+
+| Format | Description |
+|--------|-------------|
+| `json` | Full graph as JSON |
+| `dot` | Graphviz DOT |
+| `graphml` | GraphML XML |
+| `mermaid` | Mermaid diagram |
+| `cytoscape` | Cytoscape.js elements |
+| `reactflow` | React Flow nodes/edges |
+| `neo4j` | Neo4j CSV import |
+
+```bash
+cli-node-graph export . --format json -o graph.json
+cli-node-graph export . --format dot -o graph.dot
+cli-node-graph export . --format reactflow -o graph.json
+```
+
+### `cli-node-graph cycles [path]`
+
+Detect and list all circular dependencies.
+
+### `cli-node-graph impact <target> [path]`
+
+Analyze downstream impact of modifying a file or symbol.
+
+```bash
+cli-node-graph impact src/UserService.ts
+cli-node-graph impact UserController
+```
+
+### `cli-node-graph stats [path]`
+
+Show detailed graph statistics (node/edge counts by kind).
+
+## Cache
+
+Analysis results are cached in `.cli-node-graph/graph.json` in the project root.
+
+## Exit Codes
+
+- `0` — Success
+- `1` — Error (missing graph, unknown format, node not found)

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "cli-node-graph",
+  "version": "1.0.1",
+  "description": "TypeScript codebase knowledge graph analyzer (Nx-style)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE", "docs"],
+  "bin": {
+    "cli-node-graph": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli/index.ts",
+    "cli-node-graph": "tsx src/cli/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm test && pnpm build"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "typescript",
+    "dependency-graph",
+    "static-analysis",
+    "code-intelligence"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "fast-glob": "^3.3.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.26.1",
+    "eslint": "^9.22.0",
+    "prettier": "^3.5.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}