depgraph-core 1.0.2 → 1.0.3

package/README.md

@@ -3,33 +3,30 @@
 [![npm version](https://img.shields.io/npm/v/depgraph-core.svg)](https://www.npmjs.com/package/depgraph-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**DepGraph Core** is a powerful static analysis tool designed to map code dependencies and simulate the ripple effect/impact of changes in JavaScript and TypeScript projects. By parsing imports, exports, functions, classes, and routing definitions, DepGraph constructs a comprehensive dependency graph, computes critical centrality metrics, and generates interactive impact simulations to prevent regression bugs in large codebases.
+**DepGraph Core** is a powerful static analysis CLI that maps code dependencies and simulates the ripple-effect impact of changes in JavaScript, TypeScript, Python, and Go projects. By parsing imports, exports, functions, and classes, DepGraph constructs a comprehensive dependency graph, computes centrality metrics, and generates impact simulations — helping you prevent regression bugs in large codebases.
 
 ---
 
 ## 🚀 Key Features
 
-*   🔍 **Automated Code Parsing**: Parses JavaScript, TypeScript, React components/hooks (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`), extracting functions, classes, interfaces, types, React constructs, and Express API routes.
-*   🕸️ **Dependency Graph Reconstruction**: Resolves local imports and links entities across files to construct an internal representation of your codebase topology.
-*   📈 **Metrics & Centrality Analysis**: Calculates in-degree, out-degree, and centrality scores for every entity to automatically identify **Critical Nodes** (nodes that, if modified, carry high regression risks).
-*   💥 **Impact Simulation Engine**: Runs a reverse Breadth-First Search (BFS) to model the cascading impact of changes to a specific function or component. Generates a risk score, details affected nodes, defines a targeted testing plan, and provides actionable engineering recommendations.
-*   🖥️ **Rich CLI Interface**: Colorized and structured console feedback designed for human readability, with a `--no-color` flag optimized for CI/CD pipelines.
-*   💾 **Detailed JSON Outputs**: Exports a comprehensive report containing metadata, files breakdown, graph structure, and simulation metrics.
+- 🔍 **Automated Code Parsing**: Supports JS, TS, React (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`), Python (`.py`), and Go (`.go`) — extracting functions, classes, interfaces, types, React hooks/components, and Express routes.
+- 🕸️ **Dependency Graph Reconstruction**: Resolves local imports and links entities across files to build a full topology map of your codebase.
+- 📈 **Metrics & Centrality Analysis**: Calculates in-degree, out-degree, and centrality scores for every entity to automatically identify **Critical Nodes**.
+- 💥 **Impact Simulation Engine**: Runs a reverse BFS to model the cascading impact of changing a specific function or class. Generates a risk score, lists affected nodes, and provides an actionable testing plan.
+- 🧬 **Git Diff Integration**: Automatically detects changed entities from your git history (uncommitted changes, a specific commit, or a branch comparison) and runs impact simulation on every changed function — no manual target needed.
+- 🖥️ **Rich CLI Interface**: Colorized, human-readable output with a `--no-color` flag for CI/CD pipelines.
+- 💾 **Detailed JSON Output**: Exports a comprehensive report containing graph structure, metrics, and simulation results.
 
 ---
 
 ## 📦 Installation
 
-### Global Installation
-Install `depgraph-core` globally via npm to run it anywhere:
-
+### Global (recommended)
 ```bash
 npm install -g depgraph-core
 ```
 
-### Run with `npx`
-Alternatively, execute it directly without local installation:
-
+### Via `npx` (no install required)
 ```bash
 npx depgraph-core <projectDir> [options]
 ```
@@ -46,73 +43,195 @@ depgraph <projectDir> [options]
 
 | Flag | Parameter | Description | Default |
 | :--- | :--- | :--- | :--- |
-| `--output` | `<file>` | Output path for the generated JSON report. | `./depgraph-output.json` |
-| `--impact` | `<name> <desc>` | Simulate changing a specific entity. Must supply its name and a reason/description. | `N/A` |
-| `--verbose` | — | Print per-file parsing and details. | `false` |
-| `--no-color` | — | Disable terminal ANSI color output (recommended for CI/CD logs). | `false` |
-| `--help`, `-h` | — | Display help message. | — |
+| `--output` | `<file>` | Output path for the generated JSON report | `./depgraph-output.json` |
+| `--impact` | `<name> <desc>` | Manually simulate changing a specific entity | — |
+| `--verbose` | — | Print per-file parsing details | `false` |
+| `--no-color` | — | Disable ANSI color output (for CI/CD) | `false` |
+| `--help`, `-h` | — | Show help message | — |
+
+### Git Flags
+
+| Flag | Parameter | Description |
+| :--- | :--- | :--- |
+| `--git-impact` | — | Auto-detect changed entities from git diff and run impact simulation |
+| `--commit` | `<sha>` | Analyze a specific commit (vs its parent) |
+| `--from` | `<branch>` | Compare from this branch (use with `--to`) |
+| `--to` | `<branch>` | Compare to this branch (use with `--from`) |
+
+---
+
+## 📖 Examples
 
-### Examples
+### Standard Usage
 
-#### 1. Generate a dependency report for a project
+#### Map a project
 ```bash
 depgraph ./src
 ```
 
-#### 2. Run with custom output path
+#### Custom output path
 ```bash
 depgraph ./src --output ./reports/graph-report.json
 ```
 
-#### 3. Simulate impact of modifying a critical component or helper
+#### Manually simulate a change
 ```bash
 depgraph ./src --impact "getUserById" "adding middleName field to returned object"
 ```
 
-#### 4. Run in CI Mode (silencing color output)
+#### CI mode
 ```bash
 depgraph ./src --no-color --output ./ci/depgraph.json
 ```
 
 ---
 
+### 🧬 Git Diff Integration
+
+`--git-impact` automatically reads your git diff, detects every function or class that changed, and runs an impact simulation for each one — no need to manually select a target entity.
+
+#### ⚙️ How It Works under the Hood
+
+1. **Git Diff Execution**: Runs the appropriate git command depending on the mode:
+   - **Uncommitted Changes**: `git diff HEAD` (detects staged & unstaged changes).
+   - **Last Commit (or Specific Commit)**: `git diff <commit>~1 <commit>` (compares the target commit against its parent).
+   - **Branch Comparison**: `git diff <from>...<to>` (finds the merge base and diffs to the target branch).
+2. **Context Parsing**: Scans git diff context lines (headers starting with `@@`) to extract target entities.
+3. **No Regex Duplication**: Reuses the regex patterns defined in the language parsers (`jsEntityPatterns`, `pyEntityPatterns`, `goEntityPatterns`) via the language registry.
+4. **Fallback Parsers**: Contains built-in fallback parser logic for popular OOP languages like Java (`.java`) and C# (`.cs`) to extract method signatures.
+5. **Change Description Generation**: Automatically analyzes added/removed lines in the change hunk to build descriptive labels (e.g. `getUserById: 3 line(s) changed to 2 new line(s)`).
+
+#### 📋 Git Commands Reference
+
+| Mode | CLI Command | Under-the-hood Command | Description |
+| :--- | :--- | :--- | :--- |
+| **Uncommitted Changes** | `depgraph ./src --git-impact` | `git diff HEAD` | Analyze your current workspace changes |
+| **Last Commit** | `depgraph ./src --git-impact --commit HEAD` | `git diff HEAD~1 HEAD` | Analyze the last commit |
+| **Specific Commit** | `depgraph ./src --git-impact --commit <sha>` | `git diff <sha>~1 <sha>` | Analyze any commit by its SHA |
+| **Branch Comparison** | `depgraph ./src --git-impact --from main --to feature/auth` | `git diff main...feature/auth` | Compare two branches |
+
+#### 🖥️ CLI Output Example
+
+Running `--git-impact` displays a colorized report of detected entities and runs an impact simulation for each one:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  DepGraph  v1.0.0
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔍 Scanning .
+
+📊 Graph Summary
+   Files  : 27
+   Nodes  : 76
+   Edges  : 252
+
+🔍 Reading git diff...
+
+Found 2 changed entity(s):
+   → slugify  (src/languages/javascript.ts)
+   → LanguageParser  (src/languages/registry.ts)
+
+Running impact simulation...
+
+──────────────────────────────────────────
+
+💥 Impact Simulation
+   Target      : slugify__javascript
+   Change      : slugify: 16 line(s) added
+   Risk Score  : 0
+   Risk Level  : LOW
+
+   ✓ No affected nodes found
+
+🧪 Testing Plan
+   → Test slugify directly after making changes
+
+💡 Recommendations
+   → Standard PR process is sufficient
+   → Unit tests for the changed node are enough
+
+──────────────────────────────────────────
+
+💥 Impact Simulation
+   Target      : LanguageParser__registry
+   Change      : LanguageParser: 6 line(s) added
+   Risk Score  : 100
+   Risk Level  : CRITICAL
+
+📋 Affected Nodes (3)
+
+   [CRITICAL] extractEntities
+   file    : src/languages/go.ts
+   reason  : extractEntities directly imports LanguageParser
+   action  : Update extractEntities to handle the new interface of LanguageParser
+   breaking: YES
+
+   [CRITICAL] extractImports
+   file    : src/languages/go.ts
+   reason  : extractImports directly imports LanguageParser
+   action  : Update extractImports to handle the new interface of LanguageParser
+   breaking: YES
+
+   [CRITICAL] extractExports
+   file    : src/languages/go.ts
+   reason  : extractExports directly imports LanguageParser
+   action  : Update extractExports to handle the new interface of LanguageParser
+   breaking: YES
+
+🧪 Testing Plan
+   → Test LanguageParser directly after making changes
+   → Regression test extractEntities — direct dependent
+   → Regression test extractImports — direct dependent
+   → Regression test extractExports — direct dependent
+   → Run full test suite — 3 nodes affected
+
+💡 Recommendations
+   → Full team review required before merging
+   → Consider a phased rollout
+   → Run full regression test suite
+   → 3 breaking change(s) must be updated before deploying
+
+✅ Output written to ./depgraph-output.json
+```
+
+**Supported languages for diff parsing:** JavaScript/TypeScript, Python, Go. Java and C# method signatures are handled via a built-in fallback.
+
+---
+
 ## 💥 Impact Simulation Mechanics
 
-When you simulate an impact using `--impact <name> <desc>`, the tool performs the following operations:
+When running `--impact` or `--git-impact`, the tool performs:
+
 1. **Target Identification**: Locates the node matching the provided name.
-2. **Reverse BFS Traversal**: Traverses backwards up the dependency graph up to a depth of 10 nodes to discover all direct and indirect dependents.
-3. **Risk Scoring**: Calculates a score from `0` to `100` based on:
-    * Number of critical-impact nodes (depth 1)
-    * Number of high-impact nodes (depth 2)
-    * Number of medium/low-impact nodes
-    * The target node's in-degree (how many other entities import it)
+2. **Reverse BFS Traversal**: Traverses backwards up the dependency graph (up to depth 10) to find all direct and indirect dependents.
+3. **Risk Scoring**: Calculates a score from `0–100` based on:
+   - Number of critical-impact nodes (depth 1)
+   - Number of high-impact nodes (depth 2)
+   - Number of medium/low-impact nodes
+   - The target node's in-degree
 4. **Risk Level Mapping**:
-    *   🔴 **CRITICAL** (Score $\ge$ 75): Requires comprehensive review, phased rollouts, and global regression testing.
-    *   🟡 **HIGH** (Score 50–74): Tech lead review recommended, feature flag encouraged.
-    *   🔵 **MEDIUM** (Score 25–49): Standard peer code review, targeted module testing.
-    *   🟢 **LOW** (Score < 25): Standard PR process is sufficient.
+   - 🔴 **CRITICAL** (≥ 75): Comprehensive review, phased rollout, full regression testing.
+   - 🟡 **HIGH** (50–74): Tech lead review, feature flag recommended.
+   - 🔵 **MEDIUM** (25–49): Standard peer review, targeted module testing.
+   - 🟢 **LOW** (< 25): Standard PR process is sufficient.
 
 ---
 
 ## 📁 Output JSON Schema
 
-The tool generates a JSON report containing the following structure:
-
 ```json
 {
   "meta": {
-    "version": "1.0.0",
-    "timestamp": "2026-07-16T02:45:52.311Z",
-    "totalFiles": 25,
-    "totalLines": 1968
+    "version": "1.0.2",
+    "timestamp": "2026-07-20T05:14:00.000Z",
+    "totalFiles": 26,
+    "totalLines": 2957
   },
   "summary": {
-    "totalNodes": 55,
-    "totalEdges": 191,
-    "entryPoints": [ "main__app" ],
-    "leafNodes": [ "formatDate__utils" ],
-    "isolatedNodes": [],
-    "criticalNodes": [ "dbClient__db" ]
+    "totalNodes": 70,
+    "totalEdges": 252,
+    "criticalNodes": ["simulateImpact__impact", "buildGraph__graph"]
   },
   "nodes": [
     {
@@ -125,30 +244,14 @@ The tool generates a JSON report containing the following structure:
       "complexity": "low",
       "inDegree": 3,
       "outDegree": 1,
-      "centralityScore": 7,
-      "connections": [ "dbClient__db", "getUserRoute__userController" ]
+      "centralityScore": 7
     }
   ],
   "edges": [
     {
       "from": "getUserRoute__userController",
       "to": "getUserById__userService",
-      "type": "imports",
-      "description": "getUserRoute imports getUserById from userService"
-    }
-  ],
-  "files": [
-    {
-      "filePath": "src/services/userService.ts",
-      "lang": "js",
-      "lines": 42,
-      "entities": [
-        { "name": "getUserById", "type": "function", "line": 15, "complexity": "low" }
-      ],
-      "imports": [
-        { "source": "../db", "names": ["dbClient"], "isLocal": true }
-      ],
-      "exports": [ "getUserById" ]
+      "type": "imports"
     }
   ],
   "impact": {
@@ -158,26 +261,15 @@ The tool generates a JSON report containing the following structure:
     "riskLevel": "HIGH",
     "affectedNodes": [
       {
-        "nodeId": "getUserRoute__userController",
         "name": "getUserRoute",
         "file": "src/controllers/userController.ts",
         "depth": 1,
         "impact": "critical",
-        "reason": "getUserRoute directly imports getUserById",
-        "changeRequired": "Update getUserRoute to handle the new interface of getUserById",
         "breakingChange": true
       }
     ],
-    "breakingChanges": [...],
-    "testingPlan": [
-      "Test getUserById directly after making changes",
-      "Regression test getUserRoute — direct dependent"
-    ],
-    "recommendations": [
-      "Tech lead review recommended",
-      "Feature flag this change",
-      "1 breaking change(s) must be updated before deploying"
-    ]
+    "testingPlan": ["Test getUserById directly", "Regression test getUserRoute"],
+    "recommendations": ["Tech lead review recommended", "Feature flag this change"]
   }
 }
 ```
@@ -186,41 +278,25 @@ The tool generates a JSON report containing the following structure:
 
 ## 💻 Development & Contribution
 
-If you are developing or contributing to `depgraph-core`, follow these steps:
-
-### Setup & Installation
-Clone the repository and install development dependencies:
+### Setup
 ```bash
+git clone https://github.com/arafat2020/depgraph.git
+cd depgraph
 npm install
 ```
 
 ### Commands
-*   **Compile TypeScript**:
-    ```bash
-    npm run build
-    ```
-*   **Create Production Bundle**:
-    Bundles the application into a standalone executable file `depgraph.js` via `esbuild`:
-    ```bash
-    npm run bundle
-    ```
-*   **Rebuild Code for Release**:
-    Cleans, recompiles, and bundles the source:
-    ```bash
-    npm run release
-    ```
-*   **Run Test Suite**:
-    Uses `vitest` for running tests:
-    ```bash
-    # Watch mode
-    npm run test
-    
-    # Run tests once (useful for CI)
-    npm run test:run
-    ```
+
+| Command | Description |
+| :--- | :--- |
+| `npm run build` | Compile TypeScript → `dist/` |
+| `npm run bundle` | Bundle `dist/main.js` → `depgraph.js` via esbuild |
+| `npm run release` | Build + bundle in one step |
+| `npm run test` | Run tests in watch mode (vitest) |
+| `npm run test:run` | Run tests once (for CI) |
 
 ---
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.