depgraph-core 1.5.1 → 1.8.0

package/docs/stage-collector.md

@@ -1,109 +0,0 @@
-# Stage 1 — Collector
-
-> **File**: `src/stages/collector.ts`  
-> **Exports**: `collectFiles(dir: string): string[]`
-
----
-
-## What It Does
-
-The collector is the very first thing that runs. Its job is simple: **walk a directory tree and return a flat list of file paths** that the rest of the pipeline should process.
-
-It does **not** read file contents — it only looks at names, extensions, and file sizes.
-
----
-
-## How It Works
-
-### 1. Recursive directory walk
-
-`collectFiles` calls an internal `walk()` helper which:
-
-1. Reads the entries of the current directory with `fs.readdirSync`.
-2. For each entry:
-   - If it's a **directory**, check it against `IGNORE_DIRS`. If not ignored, recurse into it.
-   - If it's a **file**, check its extension against `SUPPORTED_EXTS` and its size against `MAX_FILE_SIZE`.
-
-```ts
-if (stat.isDirectory()) {
-  if (!IGNORE_DIRS.has(entry)) walk(fullPath);
-  continue;
-}
-
-const ext = path.extname(entry);
-if (SUPPORTED_EXTS.has(ext) && stat.size < MAX_FILE_SIZE) {
-  results.push(fullPath);
-}
-```
-
-### 2. Ignored directories
-
-Defined in `src/constants.ts`:
-
-```ts
-export const IGNORE_DIRS = new Set([
-  'node_modules', '.git', 'dist', 'build',
-  '.next', '__pycache__', 'vendor', 'venv',
-  'target', 'out', 'coverage', '.cache'
-]);
-```
-
-These are skipped entirely — the walker never descends into them.
-
-### 3. Supported extensions
-
-Also from constants:
-
-```ts
-export const SUPPORTED_EXTS = new Set([
-  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
-  '.py', '.go', '.java', '.cs', '.rb',
-  '.php', '.swift', '.kt', '.vue', '.svelte'
-]);
-```
-
-> **Note**: Collecting a file with `.java` doesn't mean it will be *parsed* successfully. The collector just gathers eligible paths. If no language parser is registered for that extension, the parser stage silently drops it.
-
-### 4. Size guard
-
-```ts
-export const MAX_FILE_SIZE = 300_000; // 300 KB
-```
-
-Files over 300 KB are skipped. This prevents the scanner from choking on minified bundles, lock files accidentally using a supported extension, or generated code.
-
----
-
-## Error Handling
-
-The collector is fault-tolerant at the entry level:
-- If a directory can't be read (permissions, broken symlink), it logs a warning and continues.
-- If `fs.statSync` fails on an entry, it skips that entry and continues.
-
-It **never throws** — it always returns whatever it managed to collect.
-
----
-
-## Output
-
-A flat `string[]` of absolute file paths, for example:
-
-```
-[
-  "/project/src/main.ts",
-  "/project/src/utils/auth.ts",
-  "/project/src/routes/users.ts"
-]
-```
-
----
-
-## Configuration Quick Reference
-
-| Constant | Default | Description |
-|---|---|---|
-| `IGNORE_DIRS` | See above | Directory names to skip entirely |
-| `SUPPORTED_EXTS` | See above | File extensions that are eligible |
-| `MAX_FILE_SIZE` | `300_000` (300 KB) | Maximum file size in bytes |
-
-All constants live in [`src/constants.ts`](../src/constants.ts).

package/docs/stage-graph.md

@@ -1,157 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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

@@ -1,113 +0,0 @@
-# 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

@@ -1,144 +0,0 @@
-# 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