@getmikk/diagram-generator 1.7.1 → 1.8.1

package/README.md

@@ -1,249 +1,74 @@
-# @getmikk/diagram-generator
+# @getmikk/diagram-generator
 
-> Auto-generated Mermaid.js architecture diagrams from your actual codebase — no manual drawing, always accurate.
+> 7 Mermaid architecture diagrams generated from your 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 `mikk.json` and `mikk.lock.json` into rich [Mermaid.js](https://mermaid.js.org/) diagrams. Every diagram is derived entirely from compiler-grade AST data — function call edges, module assignments, Merkle health scores, import relationships. 7 diagram types: from high-level architecture overviews to per-function call flow sequences to N×N dependency matrices.
+Generates Mermaid `.mmd` files from `mikk.lock.json` and `mikk.json`. All metrics are derived from the actual call graph — no manual input.
 
-Because diagrams come from the lock file, they're always accurate. Run `mikk analyze` and your diagrams reflect the current codebase.
-
-> Part of [Mikk](../../README.md) — the codebase nervous system for AI-assisted development.
+> Part of [Mikk](../../README.md) — live architectural context for your AI agent.
 
 ---
 
-## Installation
+## Usage
+
+Generated automatically by `mikk init` and `mikk analyze`. Or regenerate manually:
 
 ```bash
-npm install @getmikk/diagram-generator
-# or
-bun add @getmikk/diagram-generator
+mikk visualize all          # all 7 diagrams
+mikk visualize module <id>  # one module diagram
 ```
 
-**Peer dependency:** `@getmikk/core`
-
----
-
-## Quick Start
+Programmatically:
 
 ```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
+const orchestrator = new DiagramOrchestrator(contract, lock, projectRoot)
+const { generated } = await orchestrator.generateAll()
+// generated: string[] — paths of written .mmd files
 ```
 
-**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
+## Diagrams
 
-N×N cross-module dependency analysis:
+All files are written to `.mikk/diagrams/`.
 
-```typescript
-import { DependencyMatrixGenerator } from '@getmikk/diagram-generator'
+### `main.mmd`
+Full architecture overview. All modules as nodes, inter-module dependencies as directed edges. Entry points marked distinctly.
 
-const gen = new DependencyMatrixGenerator(contract, lock)
+### `health.mmd`
+Module health dashboard. For each module, shows:
+- **Cohesion** — ratio of internal calls to total calls (higher = more self-contained)
+- **Coupling** — count of external function calls + cross-module file imports (lower = more independent)
+- **Function count**
+- **Health indicator** — 🟢 healthy (> 70%), 🟡 warning (40–70%), 🔴 critical (< 40%)
 
-// Mermaid graph with weighted edges
-const graph = gen.generate()
+Metrics are computed directly from the call graph in the lock file — not estimated.
 
-// Markdown table (N×N matrix)
-const table = gen.generateTable()
-```
+### `matrix.mmd`
+Dependency matrix. Grid of which modules depend on which. Identifies tight coupling and potential circular dependencies at a glance.
 
-**Markdown table example:**
+### `flow-entrypoints.mmd`
+Entry point call flow. Traces how calls propagate from declared entry functions into the rest of the codebase.
 
-| | auth | payments | users |
-|---|---|---|---|
-| **auth** | — | 5 | 2 |
-| **payments** | 1 | — | 3 |
-| **users** | 0 | 0 | — |
+### `impact-<file>.mmd`
+Blast radius visualization for a specific file change. Generated by `mikk context impact <file>`. Shows the change origin and all impacted nodes.
 
-Numbers represent cross-module function call counts.
+### `modules/<id>.mmd`
+Per-module internal call graph. All functions in the module as nodes, internal function calls as edges. Exported functions marked distinctly.
 
----
-
-## 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)
+### `capsules/<id>.mmd`
+Per-module public API capsule. Shows only the exported surface — function names, params, return types — without internal implementation detail.
 
 ---
 
-## Types
-
-```typescript
-import {
-  DiagramOrchestrator,
-  MainDiagramGenerator,
-  ModuleDiagramGenerator,
-  ImpactDiagramGenerator,
-  HealthDiagramGenerator,
-  FlowDiagramGenerator,
-  CapsuleDiagramGenerator,
-  DependencyMatrixGenerator,
-} from '@getmikk/diagram-generator'
-```
-
----
+## Viewing Diagrams
 
-## License
+Any Mermaid-compatible renderer works. Recommended:
 
-[Apache-2.0](../../LICENSE)
+- **VS Code**: install the "Mermaid Preview" extension, then open any `.mmd` file
+- **GitHub**: Mermaid renders natively in `.md` files — embed with ` ```mermaid ` fences
+- **Mermaid Live**: paste at https://mermaid.live

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/diagram-generator",
-    "version": "1.7.1",
+    "version": "1.8.1",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -21,7 +21,7 @@
         "dev": "tsc --watch"
     },
     "dependencies": {
-        "@getmikk/core": "^1.7.1"
+        "@getmikk/core": "^1.8.3"
     },
     "devDependencies": {
         "typescript": "^5.7.0",

package/src/generators/commands-diagram.ts

@@ -0,0 +1,100 @@
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * Generates a Mermaid mindmap of all mikk CLI commands grouped by category.
+ * Does not depend on contract or lock data — it is a static reference diagram.
+ */
+export class CommandsDiagramGenerator {
+    // contract/lock kept for interface consistency with other generators
+    constructor(
+        private _contract?: MikkContract,
+        private _lock?: MikkLock,
+    ) {}
+
+    generate(): string {
+        return `mindmap
+  root((mikk))
+    Setup
+      mikk init
+        Scan project
+        Build dependency graph
+        Generate all artifacts
+      mikk analyze
+        Re-analyze after changes
+        Update lock file
+      mikk watch
+        Live file watcher daemon
+        Incremental updates
+        100ms debounce
+      mikk diff
+        Files changed since last analysis
+      mikk remove
+        Uninstall mikk
+        Delete all artifacts
+    Health
+      mikk stats
+        Per-module metrics
+        Function counts
+        Dead code %
+      mikk doctor
+        7-point diagnostic check
+        Config validation
+        Lock freshness
+      mikk dead-code
+        Unused functions
+        Filter by module
+    Architecture
+      mikk ci
+        Exit non-zero on violations
+        CI pipeline gate
+      mikk ci --strict
+        Also enforce dead code threshold
+      mikk ci --format json
+        Machine-readable output
+      mikk contract validate
+        Constraint violations
+        Drift detection
+      mikk contract show-boundaries
+        Cross-module dependencies
+    Context
+      mikk context query
+        Architecture question
+        Graph-traced response
+      mikk context impact
+        Blast radius of a file change
+        Classified by severity
+      mikk context for
+        Token-budgeted task context
+    Refactoring
+      mikk intent
+        Pre-flight a refactor
+        Detect conflicts before coding
+      mikk rename
+        Coordinated multi-file rename
+        Find all call sites
+    MCP Server
+      mikk mcp
+        Start MCP server
+        22 tools available
+      mikk mcp install
+        Install into Claude Desktop
+        Install into Cursor
+    Visualization
+      mikk visualize all
+        Regenerate all diagrams
+        7 diagram types
+      mikk visualize module
+        Per-module call graph
+        Public API capsule
+      mikk visualize commands
+        This diagram
+    Decisions
+      mikk adr list
+        All architectural decisions
+      mikk adr add
+        New ADR
+      mikk adr get
+        Details for a specific ADR
+`
+    }
+}

package/src/generators/dependency-matrix.ts

@@ -93,7 +93,9 @@ export class DependencyMatrixGenerator {
         // Count file-level cross-module imports
         for (const file of Object.values(this.lock.files)) {
             if (!file.imports) continue
-            for (const importedPath of file.imports) {
+            for (const imp of file.imports) {
+                const importedPath = imp.resolvedPath
+                if (!importedPath) continue
                 const importedFile = this.lock.files[importedPath]
                 if (importedFile && file.moduleId !== importedFile.moduleId) {
                     const key = `${file.moduleId}|${importedFile.moduleId}`

package/src/generators/health-diagram.ts

@@ -45,7 +45,9 @@ export class HealthDiagramGenerator {
         }
         for (const file of Object.values(this.lock.files)) {
             if (!file.imports) continue
-            for (const importedPath of file.imports) {
+            for (const imp of file.imports) {
+                const importedPath = imp.resolvedPath
+                if (!importedPath) continue
                 const importedFile = this.lock.files[importedPath]
                 if (importedFile && file.moduleId !== importedFile.moduleId) {
                     const key = `${file.moduleId}|${importedFile.moduleId}`
@@ -88,7 +90,9 @@ export class HealthDiagramGenerator {
         }
         for (const file of moduleFiles) {
             if (!file.imports) continue
-            for (const importedPath of file.imports) {
+            for (const imp of file.imports) {
+                const importedPath = imp.resolvedPath
+                if (!importedPath) continue
                 const importedFile = this.lock.files[importedPath]
                 if (importedFile) {
                     if (importedFile.moduleId === moduleId) internalCalls++

package/src/generators/main-diagram.ts

@@ -61,7 +61,9 @@ export class MainDiagramGenerator {
         // File-level cross-module imports
         for (const file of Object.values(this.lock.files)) {
             if (!file.imports) continue
-            for (const importedPath of file.imports) {
+            for (const imp of file.imports) {
+                const importedPath = imp.resolvedPath
+                if (!importedPath) continue
                 const importedFile = this.lock.files[importedPath]
                 if (importedFile && file.moduleId !== importedFile.moduleId) {
                     const edgeKey = `${file.moduleId}→${importedFile.moduleId}`
@@ -103,7 +105,7 @@ export class MainDiagramGenerator {
         const ranked = allFiles
             .map(f => ({
                 ...f,
-                connections: (f.imports?.length || 0) + (Object.values(this.lock.files).filter(other => other.imports?.includes(f.path)).length),
+                connections: (f.imports?.length || 0) + (Object.values(this.lock.files).filter(other => other.imports?.some(i => i.resolvedPath === f.path)).length),
             }))
             .sort((a, b) => b.connections - a.connections)
 
@@ -146,8 +148,8 @@ export class MainDiagramGenerator {
         for (const file of filesToShow) {
             if (!file.imports) continue
             for (const imp of file.imports) {
-                if (shownPaths.has(imp)) {
-                    lines.push(`    ${this.sanitizeId(file.path)} --> ${this.sanitizeId(imp)}`)
+                if (imp.resolvedPath && shownPaths.has(imp.resolvedPath)) {
+                    lines.push(`    ${this.sanitizeId(file.path)} --> ${this.sanitizeId(imp.resolvedPath)}`)
                 }
             }
         }

package/src/index.ts

@@ -6,3 +6,4 @@ export { HealthDiagramGenerator } from './generators/health-diagram.js'
 export { FlowDiagramGenerator } from './generators/flow-diagram.js'
 export { CapsuleDiagramGenerator } from './generators/capsule-diagram.js'
 export { DependencyMatrixGenerator } from './generators/dependency-matrix.js'
+export { CommandsDiagramGenerator } from './generators/commands-diagram.js'

package/src/orchestrator.ts

@@ -8,6 +8,7 @@ import { HealthDiagramGenerator } from './generators/health-diagram.js'
 import { FlowDiagramGenerator } from './generators/flow-diagram.js'
 import { CapsuleDiagramGenerator } from './generators/capsule-diagram.js'
 import { DependencyMatrixGenerator } from './generators/dependency-matrix.js'
+import { CommandsDiagramGenerator } from './generators/commands-diagram.js'
 
 /**
  * DiagramOrchestrator — generates all diagram types and writes them to

package/tests/diagram.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'bun:test'
+import { MainDiagramGenerator } from '../src/generators/main-diagram.js'
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+describe('MainDiagramGenerator', () => {
+    it('generates a file-level view for 0 modules', () => {
+        const contract: MikkContract = {
+            project: { name: 'test', language: 'typescript', framework: null },
+            declared: {
+                modules: [],
+                constraints: [],
+                decisions: []
+            },
+            overwrite: { mode: 'never', requireConfirmation: false }
+        }
+        const lock: MikkLock = {
+            version: '1',
+            lastUpdated: new Date().toISOString(),
+            files: {},
+            functions: {},
+            classes: {},
+            modules: {}
+        }
+        
+        const gen = new MainDiagramGenerator(contract, lock)
+        const diagram = gen.generate()
+        expect(diagram).toContain('graph TD')
+    })
+    
+    it('generates a multi-module view for 2+ modules', () => {
+        const contract: MikkContract = {
+            project: { name: 'test', language: 'typescript', framework: null },
+            declared: {
+                modules: [
+                    { id: 'auth', name: 'Auth', functions: [] },
+                    { id: 'db', name: 'Database', functions: [] }
+                ],
+                constraints: [],
+                decisions: []
+            },
+            overwrite: { mode: 'never', requireConfirmation: false }
+        }
+        const lock: MikkLock = {
+            version: '1',
+            lastUpdated: new Date().toISOString(),
+            files: {},
+            functions: {},
+            classes: {},
+            modules: {}
+        }
+        
+        const gen = new MainDiagramGenerator(contract, lock)
+        const diagram = gen.generate()
+        expect(diagram).toContain('auth["📦 Auth')
+        expect(diagram).toContain('db["📦 Database')
+    })
+})