depgraph-core 1.5.2 → 1.8.0

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

package/docs/stage-parser.md

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