depgraph-core 1.0.2 → 1.5.0

package/docs/stage-graph.md

@@ -0,0 +1,157 @@
+# Stage 3 — Graph Builder
+
+> **File**: `src/stages/graph.ts`  
+> **Exports**: `buildGraph(parsedFiles: ParsedFile[]): DepGraph`
+
+---
+
+## What It Does
+
+The graph builder takes the flat list of `ParsedFile` objects and turns it into a **directed dependency graph**: a collection of **nodes** (entities) connected by **edges** (import relationships).
+
+After this stage, you know exactly which entity depends on which other entity, across the entire codebase.
+
+---
+
+## The Three-Step Build Process
+
+### Step 1 — Create a node for every entity
+
+Every `RawEntity` found in every file becomes a `DepNode` in the graph:
+
+```ts
+for (const file of parsedFiles) {
+  const fileBase = path.basename(file.filePath, path.extname(file.filePath));
+
+  for (const entity of file.entities) {
+    const id = makeId(entity.name, fileBase); // e.g. "getUserById__userService"
+
+    if (nodes.has(id)) continue; // skip duplicates
+
+    nodes.set(id, {
+      id,
+      name: entity.name,
+      type: entity.type,
+      file: file.filePath,
+      line: entity.line,
+      lang: file.lang,
+      complexity: entity.complexity,
+      inDegree: 0,
+      outDegree: 0,
+      centralityScore: 0,
+      connections: [],
+    });
+  }
+}
+```
+
+**Node IDs** are composite strings: `entityName__fileBasename`.  
+For example, the function `getUserById` in `src/services/userService.ts` gets ID `getUserById__userService`.
+
+This scheme prevents collisions when two files have a function with the same name.
+
+### Step 2 — Build a file path lookup map
+
+```ts
+const fileMap = new Map<string, ParsedFile>();
+for (const file of parsedFiles) {
+  fileMap.set(file.filePath, file);
+}
+```
+
+This allows O(1) lookup from a resolved file path → its `ParsedFile` data.
+
+### Step 3 — Connect nodes through imports
+
+This is where the real graph-building happens. For every file:
+
+1. Iterate over its `imports`.
+2. Skip **external** imports (packages like `express`, `lodash`) — only local imports matter.
+3. **Resolve** the import path to an actual file on disk (see path resolution below).
+4. For each imported name, find the matching entity in the target file.
+5. Create an edge from **every entity in the importing file** to the **matching target entity**.
+
+```ts
+edges.push({
+  from: fromId,
+  to: toId,
+  type: 'imports',
+  description: `${fromEntity.name} imports ${importedName} from ${path.basename(resolvedPath)}`,
+});
+```
+
+Duplicate edges are guarded against before insertion.
+
+---
+
+## Path Resolution
+
+Import paths like `"./userService"` don't include an extension. The `resolvePath` helper tries these candidates in priority order:
+
+```
+./userService
+./userService.ts
+./userService.tsx
+./userService.js
+./userService.jsx
+./userService/index.ts
+./userService/index.js
+```
+
+It finds the first candidate that matches a known file in `parsedFiles` and returns that path. If nothing matches, the import is silently skipped.
+
+---
+
+## Output Shape — `DepGraph`
+
+```ts
+interface DepGraph {
+  nodes: Map<string, DepNode>;
+  edges: DepEdge[];
+}
+```
+
+At this point, all `inDegree`, `outDegree`, and `centralityScore` fields on each node are still `0`. The **Metrics stage** fills these in (see [stage-metrics.md](./stage-metrics.md)).
+
+---
+
+## Edge Direction Convention
+
+```
+FROM → TO
+ (importer)  (imported)
+```
+
+If `routes/users.ts` imports `getUserById` from `services/userService.ts`, the edge is:
+
+```
+GET /api/users__users  →  getUserById__userService
+```
+
+This forward-direction convention means: **following edges = following dependencies**.  
+For impact analysis (who depends on me?), edges are traversed **in reverse** (see [stage-impact.md](./stage-impact.md)).
+
+---
+
+## The `makeId` Helper
+
+```ts
+function makeId(name: string, fileBase: string): string {
+  const cleanName = name.replace(/[^a-zA-Z0-9]/g, '_');
+  const cleanBase = fileBase.replace(/[^a-zA-Z0-9]/g, '_');
+  return `${cleanName}__${cleanBase}`;
+}
+```
+
+Non-alphanumeric characters (e.g. spaces, slashes in route paths like `GET /api/users`) are replaced with underscores. This keeps IDs safe for use as JSON keys and stable across runs.
+
+---
+
+## Common Gotchas
+
+| Situation | Behaviour |
+|---|---|
+| Two files export the same function name | First one wins; second is skipped (duplicate `id` guard) |
+| Import resolves to a file with no entities | The import is dropped — nothing to link to |
+| Circular imports (A imports B, B imports A) | Both edges are created; no infinite loop — the graph is built in a single linear pass |
+| External package imports | Skipped via the `isLocal` flag on `RawImport` |

package/docs/stage-impact.md

@@ -0,0 +1,154 @@
+# Stage 5 — Impact Simulator
+
+> **File**: `src/stages/impact.ts`  
+> **Exports**: `simulateImpact(graph, targetName, changeDescription): ImpactReport`  
+> **Triggered by**: `--impact <name> <description>` CLI flag
+
+---
+
+## What It Does
+
+The impact simulator answers the question: **"If I change this entity, what else breaks?"**
+
+It performs a **reverse Breadth-First Search (BFS)** starting from the target node, walking *against* the edge direction to find every node that (directly or transitively) depends on the target. It then scores each affected node by impact severity and produces a risk report with testing recommendations.
+
+---
+
+## The Four-Step Algorithm
+
+### Step 1 — Find the target node
+
+```ts
+const targetNode = [...graph.nodes.values()]
+  .find(n => n.name === targetName);
+```
+
+Searches by `name` (not `id`). If the target is not found, an empty report is returned immediately.
+
+### Step 2 — Reverse BFS
+
+A standard BFS, but instead of following edges *forward* (A→B means A depends on B), we follow edges *backward* (find all edges where `edge.to === nodeId`):
+
+```ts
+function getDirectDependents(graph, nodeId) {
+  return graph.edges
+    .filter(e => e.to === nodeId)
+    .map(e => e.from);
+}
+```
+
+The BFS seeds the queue with **direct dependents** (depth 1) and expands outward, level by level, until:
+- A node has already been visited (`visited` Set), or
+- The depth exceeds `MAX_BFS_DEPTH` (default: `10`)
+
+```
+target node
+   ▲
+   │  (direct dependents — depth 1)
+[A, B, C]
+   ▲
+   │  (dependents of A, B, C — depth 2)
+[D, E, F, G]
+   ▲  ...and so on up to depth 10
+```
+
+### Step 3 — Score each affected node
+
+Impact level is determined by **BFS depth**:
+
+| Depth | Impact Level | Breaking Change? |
+|---|---|---|
+| 1 | `critical` | ✅ Yes |
+| 2 | `high` | ✅ Yes |
+| 3–4 | `medium` | ❌ No |
+| 5–10 | `low` | ❌ No |
+
+Nodes at depth ≤ 2 are flagged as `breakingChange: true` because they directly consume the target's interface.
+
+### Step 4 — Compute the risk score
+
+```ts
+const score = C * 30 + H * 15 + M * 7 + L * 2 + inDegree * 3;
+return Math.min(100, score);
+```
+
+Where `C`, `H`, `M`, `L` are the counts of critical/high/medium/low affected nodes, and `inDegree` is the target node's own in-degree.
+
+The score is capped at 100.
+
+**Risk level thresholds:**
+
+| Score | Risk Level |
+|---|---|
+| ≥ 75 | `CRITICAL` |
+| ≥ 50 | `HIGH` |
+| ≥ 25 | `MEDIUM` |
+| < 25  | `LOW` |
+
+---
+
+## Output Shape — `ImpactReport`
+
+```ts
+interface ImpactReport {
+  targetNode: string;           // the ID of the changed node
+  changeDescription: string;   // from CLI --impact flag
+  riskScore: number;            // 0–100
+  riskLevel: string;            // LOW / MEDIUM / HIGH / CRITICAL
+  affectedNodes: AffectedNode[];
+  breakingChanges: AffectedNode[]; // subset of affectedNodes where breakingChange=true
+  testingPlan: string[];
+  recommendations: string[];
+}
+```
+
+### `AffectedNode`
+
+```ts
+interface AffectedNode {
+  nodeId:        string;
+  name:          string;
+  file:          string;
+  depth:         number;     // BFS distance from target
+  impact:        string;     // critical / high / medium / low
+  reason:        string;     // human-readable why
+  changeRequired: string;    // what action is needed
+  breakingChange: boolean;
+}
+```
+
+---
+
+## Recommendations Logic
+
+Recommendations are generated automatically based on the risk score:
+
+| Risk Score | Recommendations |
+|---|---|
+| ≥ 75 | Full team review, phased rollout, full regression suite |
+| ≥ 50 | Tech lead review, feature flag the change |
+| ≥ 25 | Code review, test all affected modules |
+| < 25 | Standard PR process sufficient |
+
+If any breaking changes exist, an additional note is always appended.
+
+---
+
+## Usage Example
+
+```bash
+node depgraph.js ./src --impact "getUserById" "removing userId parameter"
+```
+
+This runs the full pipeline and then simulates changing `getUserById`, returning a detailed report of everything that would be affected.
+
+---
+
+## Edge Cases
+
+| Situation | Behaviour |
+|---|---|
+| Target not found | Returns an empty report with `riskScore: 0` and an explanatory testing plan entry |
+| Target has no dependents | Returns an empty `affectedNodes` array and `LOW` risk |
+| Circular dependencies | The `visited` Set prevents infinite loops |
+| Extremely deep dependency chains | `MAX_BFS_DEPTH = 10` hard-caps traversal |

package/docs/stage-metrics.md

@@ -0,0 +1,113 @@
+# Stage 4 — Metrics
+
+> **File**: `src/stages/metrics.ts`  
+> **Exports**: `computeMetrics`, `getEntryPoints`, `getLeafNodes`, `getIsolatedNodes`, `getCriticalNodes`
+
+---
+
+## What It Does
+
+The metrics stage takes the raw graph from the builder and **enriches each node** with three numeric properties: `inDegree`, `outDegree`, and `centralityScore`. It also provides four helper functions for categorising nodes.
+
+This stage **mutates** the nodes inside the graph in place and returns the same `DepGraph` object.
+
+---
+
+## `computeMetrics(graph: DepGraph): DepGraph`
+
+### Step 1 — Count in-degree and out-degree
+
+The function iterates over every edge and increments counters on the two endpoint nodes:
+
+```ts
+for (const edge of graph.edges) {
+  const fromNode = graph.nodes.get(edge.from);
+  const toNode   = graph.nodes.get(edge.to);
+
+  if (fromNode) fromNode.outDegree += 1;  // this node imports something
+  if (toNode)   toNode.inDegree   += 1;   // this node is imported by something
+}
+```
+
+| Property | Meaning |
+|---|---|
+| `inDegree` | Number of other nodes that import **this** node |
+| `outDegree` | Number of nodes **this** node imports |
+
+### Step 2 — Compute centrality score
+
+```ts
+node.centralityScore = node.inDegree * 2 + node.outDegree;
+```
+
+The formula weights **inDegree** more heavily (×2) because being imported by many things is riskier than importing many things. A node with a high inDegree is a "load-bearing" piece of code — changing it breaks many consumers.
+
+---
+
+## Node Categorisation Helpers
+
+These four helper functions are used by both the **Output** stage and the **main** entry point to produce the summary section of the report.
+
+### `getEntryPoints(graph)`
+
+```ts
+n.inDegree === 0 && n.outDegree > 0
+```
+
+**Nothing imports this node, but it imports others.**  
+These are application roots: `main.ts`, route files, top-level scripts. They start the dependency chain.
+
+### `getLeafNodes(graph)`
+
+```ts
+n.outDegree === 0 && n.inDegree > 0
+```
+
+**This node imports nothing, but others import it.**  
+These are pure utilities and helpers: `hashPassword`, `formatDate`, shared constants. They're at the bottom of the dependency chain.
+
+### `getIsolatedNodes(graph)`
+
+```ts
+n.inDegree === 0 && n.outDegree === 0
+```
+
+**This node has no connections at all.**  
+These are dead code candidates — entities defined but never imported or used by any other tracked entity in the project.
+
+### `getCriticalNodes(graph)`
+
+```ts
+n.centralityScore > 20
+```
+
+**Nodes with a centrality score above 20.**  
+These are architectural hotspots. Modifying them carries high risk of unintended side-effects across the codebase. The impact simulator (see [stage-impact.md](./stage-impact.md)) was designed specifically for these.
+
+---
+
+## Understanding the Score Threshold
+
+The threshold of `20` for critical nodes translates roughly to:
+- A node imported by 10 other nodes (`10 * 2 = 20`), or
+- A node imported by 7 nodes and importing 6 others (`7*2 + 6 = 20`)
+
+Adjust `getCriticalNodes` if your project has a different risk tolerance.
+
+---
+
+## Example — Annotated Node After This Stage
+
+```json
+{
+  "id": "getUserById__userService",
+  "name": "getUserById",
+  "type": "function",
+  "inDegree": 8,
+  "outDegree": 2,
+  "centralityScore": 18,
+  "connections": ["usersRouter__routes", "adminRouter__routes", "..."]
+}
+```
+
+This node is imported by 8 other nodes and imports 2. Its centrality score is 18 — just under the critical threshold.

package/docs/stage-output.md

@@ -0,0 +1,144 @@
+# Stage 6 — Output
+
+> **File**: `src/stages/output.ts`  
+> **Exports**: `writeOutput(graph, parsed, outputPath, impact?): void`
+
+---
+
+## What It Does
+
+The output stage is the final step in the pipeline. It takes the fully-enriched graph, the parsed file list, and the optional impact report, **serialises everything into a structured JSON document**, and writes it to disk.
+
+---
+
+## The Four-Step Write Process
+
+### Step 1 — Compute the summary
+
+```ts
+const summary = {
+  totalNodes:    graph.nodes.size,
+  totalEdges:    graph.edges.length,
+  entryPoints:   getEntryPoints(graph),
+  leafNodes:     getLeafNodes(graph),
+  isolatedNodes: getIsolatedNodes(graph),
+  criticalNodes: getCriticalNodes(graph),
+};
+```
+
+This calls the four categorisation helpers from the metrics stage (see [stage-metrics.md](./stage-metrics.md)) to produce the summary section.
+
+### Step 2 — Assemble the full output object
+
+```ts
+const output: OutputJSON = {
+  meta: {
+    version:    '1.0.0',
+    timestamp:  new Date().toISOString(),
+    totalFiles: parsed.length,
+    totalLines: totalLines,
+  },
+  summary,
+  nodes:  [...graph.nodes.values()],   // Map → Array
+  edges:  graph.edges,
+  files:  parsed,
+  impact,                              // undefined if --impact was not used
+};
+```
+
+The `nodes` Map is converted to an Array here so it serialises correctly as JSON.
+
+### Step 3 — Write to disk
+
+```ts
+fs.writeFileSync(
+  outputPath,
+  JSON.stringify(output, null, 2),  // pretty-printed, 2-space indent
+  'utf-8'
+);
+```
+
+If the output directory does not exist, it is created recursively:
+
+```ts
+const dir = path.dirname(outputPath);
+if (!fs.existsSync(dir)) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+```
+
+### Step 4 — Print confirmation
+
+After a successful write, a summary is printed to stdout:
+
+```
+✅ Output written to ./depgraph-output.json
+   12 files
+   87 nodes
+   143 edges
+   3240 total lines of code
+```
+
+If an impact report was included:
+
+```
+💥 Impact Report included
+   Target     : getUserById__userService
+   Risk Level : HIGH
+   Risk Score : 62
+   Affected   : 9 nodes
+```
+
+---
+
+## Output File Schema — `OutputJSON`
+
+```ts
+interface OutputJSON {
+  meta: {
+    version:    string;   // tool version, e.g. "1.0.0"
+    timestamp:  string;   // ISO 8601 datetime
+    totalFiles: number;
+    totalLines: number;
+  };
+  summary: {
+    totalNodes:    number;
+    totalEdges:    number;
+    entryPoints:   string[];  // node IDs
+    leafNodes:     string[];  // node IDs
+    isolatedNodes: string[];  // node IDs (dead code candidates)
+    criticalNodes: string[];  // node IDs (centrality > 20)
+  };
+  nodes:  DepNode[];
+  edges:  DepEdge[];
+  files:  ParsedFile[];
+  impact?: ImpactReport;    // only present if --impact was used
+}
+```
+
+See [data-types.md](./data-types.md) for the full definitions of each nested type.
+
+---
+
+## Default Output Path
+
+```
+./depgraph-output.json
+```
+
+Override with `--output <path>`:
+
+```bash
+node depgraph.js ./src --output ./reports/my-graph.json
+```
+
+---
+
+## Using the Output File
+
+The JSON output is designed to be consumed by:
+
+- **Visualisation tools** — feed `nodes` and `edges` into a graph renderer (e.g. D3, Cytoscape, Sigma.js)
+- **CI checks** — inspect `summary.criticalNodes` or `impact.riskLevel` in a script
+- **IDE plugins** — parse `files` to annotate code with entity metadata
+- **AI tools** — pass the graph as context for code review or refactoring suggestions

package/docs/stage-parser.md

@@ -0,0 +1,144 @@
+# Stage 2 — Parser
+
+> **File**: `src/stages/parser.ts`  
+> **Exports**: `parseFile(filePath: string): ParsedFile | null`, `parseFiles(filePaths: string[]): ParsedFile[]`
+
+---
+
+## What It Does
+
+The parser takes each file path from the collector and:
+
+1. Reads the raw source code from disk.
+2. Looks up the correct **language parser** from the registry based on the file extension.
+3. Strips single-line `//` comments from the code before analysis.
+4. Calls the language parser to extract **entities**, **imports**, and **exports**.
+5. Returns a structured `ParsedFile` object.
+
+---
+
+## The `parseFile` Function — Step by Step
+
+### Step 1: Read the file
+
+```ts
+const code = fs.readFileSync(filePath, 'utf-8');
+```
+
+If the file can't be read, it logs a warning and returns `null`.
+
+### Step 2: Resolve the language parser
+
+```ts
+const ext = path.extname(filePath).toLowerCase();
+const parser = getLanguageParser(ext);
+if (!parser) return null;
+```
+
+`getLanguageParser` queries the language registry (see [language-registry.md](./language-registry.md)). If no parser is registered for the extension, the file is silently skipped.
+
+### Step 3: Strip single-line comments
+
+```ts
+const cleanCode = code
+  .split('\n')
+  .map(line => {
+    const commentIndex = line.indexOf('//');
+    if (commentIndex === -1) return line;
+    // make sure // is not inside a string
+    const before = line.slice(0, commentIndex);
+    const inString = (before.match(/"/g) || []).length % 2 !== 0
+                  || (before.match(/'/g) || []).length % 2 !== 0;
+    return inString ? line : line.slice(0, commentIndex);
+  })
+  .join('\n');
+```
+
+This is done before passing code to any parser to prevent `//` inside comments from confusing regex patterns. The string-detection guard prevents false positives on lines like:
+
+```ts
+const url = "https://example.com"; // this would break without the guard
+```
+
+> **Limitation**: The guard only checks for unbalanced `"` or `'` quotes on the *same line*. Multi-line strings or template literals are not fully handled.
+
+### Step 4: Extract data via the language parser
+
+```ts
+const lines    = code.split('\n').length;       // count from original code
+const entities = parser.extractEntities(cleanCode, filePath);
+const imports  = parser.extractImports(cleanCode);
+const exports  = parser.extractExports(cleanCode);
+```
+
+Note that line counting uses the **original** code (before stripping) to get accurate line numbers. Extraction uses the **clean** code.
+
+### Step 5: Return the result
+
+```ts
+return { filePath, lang: parser.lang, lines, entities, imports, exports };
+```
+
+---
+
+## The `parseFiles` Function
+
+A simple iterator over `parseFile`. Files that return `null` are silently dropped:
+
+```ts
+for (const filePath of filePaths) {
+  const parsed = parseFile(filePath);
+  if (parsed) results.push(parsed);
+}
+```
+
+---
+
+## Output Shape — `ParsedFile`
+
+```ts
+interface ParsedFile {
+  filePath: string;   // e.g. "/project/src/auth.ts"
+  lang: string;       // e.g. "js" — from the parser's lang field
+  lines: number;      // total line count
+  entities: RawEntity[];
+  imports:  RawImport[];
+  exports:  string[];
+}
+```
+
+See [data-types.md](./data-types.md) for the full definitions of `RawEntity` and `RawImport`.
+
+---
+
+## What "entities" means
+
+An entity is any named code construct the parser can recognise:
+
+- Functions, async functions, arrow functions
+- Classes, interfaces, types (TypeScript)
+- React components and hooks
+- Express/Fastify API route declarations
+- Python classes and `def` functions
+
+Every entity has a `name`, `type`, `line`, and `complexity` rating.
+
+---
+
+## Complexity Estimation
+
+Each language parser estimates complexity by counting branching keywords in the entity's body:
+
+| Branch count | Rating |
+|---|---|
+| 0–3 | `"low"` |
+| 4–8 | `"medium"` |
+| 9+  | `"high"` |
+
+Thresholds are set in `COMPLEXITY_THRESHOLDS` in [`src/constants.ts`](../src/constants.ts).
+
+---
+
+## Adding Support for a New Language
+
+You don't touch the parser stage at all. Instead, register a new language parser — see [language-registry.md](./language-registry.md).