@getmikk/diagram-generator 1.2.0 → 1.3.1

package/README.md

@@ -0,0 +1,245 @@
+# @getmikk/diagram-generator
+
+> Mermaid.js diagram generation — produces architecture, flow, health, impact, capsule, and dependency matrix visualizations from your codebase's lock file.
+
+[![npm](https://img.shields.io/npm/v/@getmikk/diagram-generator)](https://www.npmjs.com/package/@getmikk/diagram-generator)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
+
+`@getmikk/diagram-generator` turns the `mikk.json` contract and `mikk.lock.json` lock file into rich [Mermaid.js](https://mermaid.js.org/) diagrams. Every diagram is generated entirely from AST-derived data — no manual drawing required. Supports 7 diagram types covering everything from high-level architecture to per-function call flows.
+
+---
+
+## Installation
+
+```bash
+npm install @getmikk/diagram-generator
+# or
+bun add @getmikk/diagram-generator
+```
+
+**Peer dependency:** `@getmikk/core`
+
+---
+
+## Quick Start
+
+```typescript
+import { DiagramOrchestrator } from '@getmikk/diagram-generator'
+import { ContractReader, LockReader } from '@getmikk/core'
+
+const contract = await new ContractReader().read('./mikk.json')
+const lock = await new LockReader().read('./mikk.lock.json')
+
+const orchestrator = new DiagramOrchestrator(contract, lock, process.cwd())
+const result = await orchestrator.generateAll()
+
+console.log(result.generated) // List of generated .mmd file paths
+// Files written to .mikk/diagrams/
+```
+
+---
+
+## Diagram Types
+
+### 1. Main Architecture Diagram
+
+High-level `graph TD` showing all modules with file/function counts and inter-module edges.
+
+```typescript
+import { MainDiagramGenerator } from '@getmikk/diagram-generator'
+
+const gen = new MainDiagramGenerator(contract, lock)
+const mermaid = gen.generate()
+```
+
+**Output example:**
+
+```mermaid
+graph TD
+  auth["auth<br/>📁 5 files · 📦 12 functions"]
+  payments["payments<br/>📁 3 files · 📦 8 functions"]
+  auth --> payments
+```
+
+---
+
+### 2. Module Detail Diagram
+
+Zoomed-in per-module diagram showing file subgraphs, internal call edges, and external dependencies.
+
+```typescript
+import { ModuleDiagramGenerator } from '@getmikk/diagram-generator'
+
+const gen = new ModuleDiagramGenerator(contract, lock)
+const mermaid = gen.generate('auth') // module ID
+```
+
+Shows:
+- Subgraphs for each file in the module
+- Function nodes within each file
+- Internal call edges between functions
+- External call links to other modules
+
+---
+
+### 3. Impact Diagram
+
+Visualizes the blast radius of changes — what's directly changed (red) vs. transitively impacted (orange).
+
+```typescript
+import { ImpactDiagramGenerator } from '@getmikk/diagram-generator'
+
+const gen = new ImpactDiagramGenerator(lock)
+const mermaid = gen.generate(
+  ['auth/login.ts::validateToken'],   // changed node IDs
+  ['payments/checkout.ts::processPayment'] // impacted node IDs
+)
+```
+
+**Output:** `graph LR` with color-coded nodes:
+- 🔴 **Red** — directly changed
+- 🟠 **Orange** — transitively impacted
+- Edges show the propagation chain
+
+---
+
+### 4. Health Dashboard
+
+Module health overview with cohesion percentage, coupling count, function count, and color-coded status.
+
+```typescript
+import { HealthDiagramGenerator } from '@getmikk/diagram-generator'
+
+const gen = new HealthDiagramGenerator(contract, lock)
+const mermaid = gen.generate()
+```
+
+**Metrics per module:**
+
+| Metric | Description |
+|--------|-------------|
+| Cohesion % | Ratio of internal calls to total calls (higher = better) |
+| Coupling | Count of cross-module dependencies (lower = better) |
+| Functions | Total function count |
+| Health | 🟢 Green (>70% cohesion) · 🟡 Yellow (40-70%) · 🔴 Red (<40%) |
+
+---
+
+### 5. Flow Diagram (Sequence)
+
+Traces a function's call chain as a Mermaid sequence diagram.
+
+```typescript
+import { FlowDiagramGenerator } from '@getmikk/diagram-generator'
+
+const gen = new FlowDiagramGenerator(lock)
+
+// Trace from a specific function
+const sequence = gen.generate('auth/login.ts::handleLogin', /* maxDepth */ 5)
+
+// Show all entry-point functions grouped by module
+const entryPoints = gen.generateEntryPoints()
+```
+
+The sequence diagram follows the call graph depth-first, showing which function calls which, across module boundaries.
+
+---
+
+### 6. Capsule Diagram
+
+Shows a module's public API surface — the "capsule" boundary:
+
+```typescript
+import { CapsuleDiagramGenerator } from '@getmikk/diagram-generator'
+
+const gen = new CapsuleDiagramGenerator(contract, lock)
+const mermaid = gen.generate('auth') // module ID
+```
+
+**Visualizes:**
+- **Public functions** — exported and listed in the module's `publicApi`
+- **Internal functions** — everything else
+- **External consumers** — other modules that call into this module's public API
+
+---
+
+### 7. Dependency Matrix
+
+N×N cross-module dependency analysis:
+
+```typescript
+import { DependencyMatrixGenerator } from '@getmikk/diagram-generator'
+
+const gen = new DependencyMatrixGenerator(contract, lock)
+
+// Mermaid graph with weighted edges
+const graph = gen.generate()
+
+// Markdown table (N×N matrix)
+const table = gen.generateTable()
+```
+
+**Markdown table example:**
+
+| | auth | payments | users |
+|---|---|---|---|
+| **auth** | — | 5 | 2 |
+| **payments** | 1 | — | 3 |
+| **users** | 0 | 0 | — |
+
+Numbers represent cross-module function call counts.
+
+---
+
+## DiagramOrchestrator
+
+The orchestrator generates all diagrams at once and writes them to `.mikk/diagrams/`:
+
+```typescript
+import { DiagramOrchestrator } from '@getmikk/diagram-generator'
+
+const orchestrator = new DiagramOrchestrator(contract, lock, projectRoot)
+
+// Generate everything
+const result = await orchestrator.generateAll()
+// Writes:
+//   .mikk/diagrams/main.mmd
+//   .mikk/diagrams/health.mmd
+//   .mikk/diagrams/matrix.mmd
+//   .mikk/diagrams/flow-entrypoints.mmd
+//   .mikk/diagrams/module-{id}.mmd  (one per module)
+//   .mikk/diagrams/capsule-{id}.mmd (one per module)
+
+// Generate impact diagram for specific changes
+const impactMmd = await orchestrator.generateImpact(changedIds, impactedIds)
+// Writes: .mikk/diagrams/impact.mmd
+```
+
+**Output files:** All diagrams are `.mmd` files that can be rendered with:
+- [Mermaid Live Editor](https://mermaid.live/)
+- GitHub Markdown (native Mermaid support)
+- VS Code Mermaid extensions
+- `mmdc` CLI (mermaid-cli)
+
+---
+
+## Types
+
+```typescript
+import {
+  DiagramOrchestrator,
+  MainDiagramGenerator,
+  ModuleDiagramGenerator,
+  ImpactDiagramGenerator,
+  HealthDiagramGenerator,
+  FlowDiagramGenerator,
+  CapsuleDiagramGenerator,
+  DependencyMatrixGenerator,
+} from '@getmikk/diagram-generator'
+```
+
+---
+
+## License
+
+[Apache-2.0](../../LICENSE)

package/package.json

@@ -1,26 +1,30 @@
-{
-    "name": "@getmikk/diagram-generator",
-    "version": "1.2.0",
-    "type": "module",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "import": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        }
-    },
-    "scripts": {
-        "build": "tsc",
-        "test": "bun test",
-        "publish": "npm publish --access public",
-        "dev": "tsc --watch"
-    },
-    "dependencies": {
-        "@getmikk/core": "workspace:*"
-    },
-    "devDependencies": {
-        "typescript": "^5.7.0",
-        "@types/node": "^22.0.0"
-    }
-}
+{
+    "name": "@getmikk/diagram-generator",
+    "version": "1.3.1",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Ansh-dhanani/mikk"
+    },
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "bun test",
+        "dev": "tsc --watch"
+    },
+    "dependencies": {
+        "@getmikk/core": "^1.3.1"
+    },
+    "devDependencies": {
+        "typescript": "^5.7.0",
+        "@types/node": "^22.0.0"
+    }
+}

package/src/generators/capsule-diagram.ts

@@ -1,79 +1,79 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
-
-/**
- * CapsuleDiagramGenerator — generates capsule diagrams that show
- * the public API surface of a module (what it exports to the world).
- * Outputs: .mikk/diagrams/capsules/{moduleId}.mmd
- */
-export class CapsuleDiagramGenerator {
-    constructor(
-        private contract: MikkContract,
-        private lock: MikkLock
-    ) { }
-
-    generate(moduleId: string): string {
-        const module = this.contract.declared.modules.find(m => m.id === moduleId)
-        if (!module) return `%% Module "${moduleId}" not found`
-
-        const lines: string[] = []
-        lines.push('graph LR')
-        lines.push('')
-
-        // Module capsule (subgraph)
-        lines.push(`    subgraph ${this.sanitizeId(moduleId)}["📦 ${module.name}"]`)
-        lines.push(`        direction TB`)
-
-        // Find exported functions (those called by functions in other modules)
-        const moduleFunctions = Object.values(this.lock.functions).filter(f => f.moduleId === moduleId)
-        const exportedFns = moduleFunctions.filter(fn =>
-            fn.calledBy.some(callerId => {
-                const caller = this.lock.functions[callerId]
-                return caller && caller.moduleId !== moduleId
-            })
-        )
-
-        // Internal functions
-        const internalFns = moduleFunctions.filter(fn => !exportedFns.includes(fn))
-
-        if (exportedFns.length > 0) {
-            lines.push(`        subgraph public["🔓 Public API"]`)
-            for (const fn of exportedFns) {
-                lines.push(`            ${this.sanitizeId(fn.id)}["${fn.name}"]`)
-            }
-            lines.push('        end')
-        }
-
-        if (internalFns.length > 0 && internalFns.length <= 10) {
-            lines.push(`        subgraph internal["🔒 Internal"]`)
-            for (const fn of internalFns) {
-                lines.push(`            ${this.sanitizeId(fn.id)}["${fn.name}"]`)
-            }
-            lines.push('        end')
-        } else if (internalFns.length > 10) {
-            lines.push(`        internal["🔒 ${internalFns.length} internal functions"]`)
-        }
-
-        lines.push('    end')
-        lines.push('')
-
-        // Show external consumers
-        for (const fn of exportedFns) {
-            for (const callerId of fn.calledBy) {
-                const caller = this.lock.functions[callerId]
-                if (caller && caller.moduleId !== moduleId) {
-                    lines.push(`    ext_${this.sanitizeId(callerId)}["${caller.name}<br/>(${caller.moduleId})"] --> ${this.sanitizeId(fn.id)}`)
-                }
-            }
-        }
-
-        lines.push('')
-        lines.push('    classDef publicApi fill:#27ae60,stroke:#2c3e50,color:#fff')
-        lines.push('    classDef internalApi fill:#7f8c8d,stroke:#2c3e50,color:#fff')
-
-        return lines.join('\n')
-    }
-
-    private sanitizeId(id: string): string {
-        return id.replace(/[^a-zA-Z0-9_]/g, '_')
-    }
-}
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * CapsuleDiagramGenerator — generates capsule diagrams that show
+ * the public API surface of a module (what it exports to the world).
+ * Outputs: .mikk/diagrams/capsules/{moduleId}.mmd
+ */
+export class CapsuleDiagramGenerator {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock
+    ) { }
+
+    generate(moduleId: string): string {
+        const module = this.contract.declared.modules.find(m => m.id === moduleId)
+        if (!module) return `%% Module "${moduleId}" not found`
+
+        const lines: string[] = []
+        lines.push('graph LR')
+        lines.push('')
+
+        // Module capsule (subgraph)
+        lines.push(`    subgraph ${this.sanitizeId(moduleId)}["📦 ${module.name}"]`)
+        lines.push(`        direction TB`)
+
+        // Find exported functions (those called by functions in other modules)
+        const moduleFunctions = Object.values(this.lock.functions).filter(f => f.moduleId === moduleId)
+        const exportedFns = moduleFunctions.filter(fn =>
+            fn.calledBy.some(callerId => {
+                const caller = this.lock.functions[callerId]
+                return caller && caller.moduleId !== moduleId
+            })
+        )
+
+        // Internal functions
+        const internalFns = moduleFunctions.filter(fn => !exportedFns.includes(fn))
+
+        if (exportedFns.length > 0) {
+            lines.push(`        subgraph public["🔓 Public API"]`)
+            for (const fn of exportedFns) {
+                lines.push(`            ${this.sanitizeId(fn.id)}["${fn.name}"]`)
+            }
+            lines.push('        end')
+        }
+
+        if (internalFns.length > 0 && internalFns.length <= 10) {
+            lines.push(`        subgraph internal["🔒 Internal"]`)
+            for (const fn of internalFns) {
+                lines.push(`            ${this.sanitizeId(fn.id)}["${fn.name}"]`)
+            }
+            lines.push('        end')
+        } else if (internalFns.length > 10) {
+            lines.push(`        internal["🔒 ${internalFns.length} internal functions"]`)
+        }
+
+        lines.push('    end')
+        lines.push('')
+
+        // Show external consumers
+        for (const fn of exportedFns) {
+            for (const callerId of fn.calledBy) {
+                const caller = this.lock.functions[callerId]
+                if (caller && caller.moduleId !== moduleId) {
+                    lines.push(`    ext_${this.sanitizeId(callerId)}["${caller.name}<br/>(${caller.moduleId})"] --> ${this.sanitizeId(fn.id)}`)
+                }
+            }
+        }
+
+        lines.push('')
+        lines.push('    classDef publicApi fill:#27ae60,stroke:#2c3e50,color:#fff')
+        lines.push('    classDef internalApi fill:#7f8c8d,stroke:#2c3e50,color:#fff')
+
+        return lines.join('\n')
+    }
+
+    private sanitizeId(id: string): string {
+        return id.replace(/[^a-zA-Z0-9_]/g, '_')
+    }
+}

package/src/generators/dependency-matrix.ts

@@ -1,97 +1,97 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
-
-/**
- * DependencyMatrixGenerator — generates an N×N dependency matrix
- * showing how many cross-module calls exist between each pair of modules.
- * Useful for spotting hidden coupling between modules.
- *
- * Output: a Mermaid block diagram with a matrix-like layout or
- * a structured text table that can be rendered in documentation.
- */
-export class DependencyMatrixGenerator {
-    constructor(
-        private contract: MikkContract,
-        private lock: MikkLock
-    ) { }
-
-    /**
-     * Generate a Mermaid diagram showing the dependency matrix.
-     * Uses a graph with weighted edges between all module pairs.
-     */
-    generate(): string {
-        const modules = this.contract.declared.modules
-        const matrix = this.computeMatrix()
-        const lines: string[] = []
-
-        lines.push('graph LR')
-        lines.push('')
-
-        // Module nodes
-        for (const mod of modules) {
-            const fnCount = Object.values(this.lock.functions)
-                .filter(f => f.moduleId === mod.id).length
-            lines.push(`    ${this.sanitizeId(mod.id)}["${mod.name}<br/>${fnCount} fn"]`)
-        }
-        lines.push('')
-
-        // Weighted edges
-        for (const [key, count] of matrix) {
-            const [fromId, toId] = key.split('|')
-            if (count > 0) {
-                const thickness = count > 10 ? '==>' : count > 3 ? '-->' : '-.->'
-                lines.push(`    ${this.sanitizeId(fromId)} ${thickness}|${count}| ${this.sanitizeId(toId)}`)
-            }
-        }
-
-        lines.push('')
-        lines.push('    classDef default fill:#ecf0f1,stroke:#34495e,color:#2c3e50')
-
-        return lines.join('\n')
-    }
-
-    /**
-     * Generate a markdown table showing the N×N dependency matrix.
-     * Useful for claude.md or documentation.
-     */
-    generateTable(): string {
-        const modules = this.contract.declared.modules
-        const matrix = this.computeMatrix()
-        const lines: string[] = []
-
-        // Header
-        lines.push('| From \\ To | ' + modules.map(m => m.name).join(' | ') + ' |')
-        lines.push('| --- | ' + modules.map(() => '---').join(' | ') + ' |')
-
-        // Rows
-        for (const fromMod of modules) {
-            const cells = modules.map(toMod => {
-                if (fromMod.id === toMod.id) return '-'
-                const count = matrix.get(`${fromMod.id}|${toMod.id}`) || 0
-                return count > 0 ? String(count) : '0'
-            })
-            lines.push(`| **${fromMod.name}** | ${cells.join(' | ')} |`)
-        }
-
-        return lines.join('\n')
-    }
-
-    private computeMatrix(): Map<string, number> {
-        const counts = new Map<string, number>()
-
-        for (const fn of Object.values(this.lock.functions)) {
-            for (const callTarget of fn.calls) {
-                const targetFn = this.lock.functions[callTarget]
-                if (targetFn && fn.moduleId !== targetFn.moduleId) {
-                    const key = `${fn.moduleId}|${targetFn.moduleId}`
-                    counts.set(key, (counts.get(key) || 0) + 1)
-                }
-            }
-        }
-
-        return counts
-    }
-
-    private sanitizeId(id: string): string {
-        return id.replace(/[^a-zA-Z0-9_]/g, '_')
-    }
-}
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * DependencyMatrixGenerator — generates an N×N dependency matrix
+ * showing how many cross-module calls exist between each pair of modules.
+ * Useful for spotting hidden coupling between modules.
+ *
+ * Output: a Mermaid block diagram with a matrix-like layout or
+ * a structured text table that can be rendered in documentation.
+ */
+export class DependencyMatrixGenerator {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock
+    ) { }
+
+    /**
+     * Generate a Mermaid diagram showing the dependency matrix.
+     * Uses a graph with weighted edges between all module pairs.
+     */
+    generate(): string {
+        const modules = this.contract.declared.modules
+        const matrix = this.computeMatrix()
+        const lines: string[] = []
+
+        lines.push('graph LR')
+        lines.push('')
+
+        // Module nodes
+        for (const mod of modules) {
+            const fnCount = Object.values(this.lock.functions)
+                .filter(f => f.moduleId === mod.id).length
+            lines.push(`    ${this.sanitizeId(mod.id)}["${mod.name}<br/>${fnCount} fn"]`)
+        }
+        lines.push('')
+
+        // Weighted edges
+        for (const [key, count] of matrix) {
+            const [fromId, toId] = key.split('|')
+            if (count > 0) {
+                const thickness = count > 10 ? '==>' : count > 3 ? '-->' : '-.->'
+                lines.push(`    ${this.sanitizeId(fromId)} ${thickness}|${count}| ${this.sanitizeId(toId)}`)
+            }
+        }
+
+        lines.push('')
+        lines.push('    classDef default fill:#ecf0f1,stroke:#34495e,color:#2c3e50')
+
+        return lines.join('\n')
+    }
+
+    /**
+     * Generate a markdown table showing the N×N dependency matrix.
+     * Useful for claude.md or documentation.
+     */
+    generateTable(): string {
+        const modules = this.contract.declared.modules
+        const matrix = this.computeMatrix()
+        const lines: string[] = []
+
+        // Header
+        lines.push('| From \\ To | ' + modules.map(m => m.name).join(' | ') + ' |')
+        lines.push('| --- | ' + modules.map(() => '---').join(' | ') + ' |')
+
+        // Rows
+        for (const fromMod of modules) {
+            const cells = modules.map(toMod => {
+                if (fromMod.id === toMod.id) return '-'
+                const count = matrix.get(`${fromMod.id}|${toMod.id}`) || 0
+                return count > 0 ? String(count) : '0'
+            })
+            lines.push(`| **${fromMod.name}** | ${cells.join(' | ')} |`)
+        }
+
+        return lines.join('\n')
+    }
+
+    private computeMatrix(): Map<string, number> {
+        const counts = new Map<string, number>()
+
+        for (const fn of Object.values(this.lock.functions)) {
+            for (const callTarget of fn.calls) {
+                const targetFn = this.lock.functions[callTarget]
+                if (targetFn && fn.moduleId !== targetFn.moduleId) {
+                    const key = `${fn.moduleId}|${targetFn.moduleId}`
+                    counts.set(key, (counts.get(key) || 0) + 1)
+                }
+            }
+        }
+
+        return counts
+    }
+
+    private sanitizeId(id: string): string {
+        return id.replace(/[^a-zA-Z0-9_]/g, '_')
+    }
+}