@getmikk/diagram-generator 1.2.0 → 1.3.0

package/src/generators/flow-diagram.ts

@@ -1,108 +1,108 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
-
-/**
- * FlowDiagramGenerator — generates sequence diagrams for specific
- * function call flows (e.g., "show me the HTTP request → response flow").
- * Outputs: .mikk/diagrams/flows/{flowName}.mmd
- */
-export class FlowDiagramGenerator {
-    constructor(
-        private lock: MikkLock
-    ) { }
-
-    /** Generate a sequence diagram starting from a function */
-    generate(startFunctionId: string, maxDepth: number = 5): string {
-        const lines: string[] = []
-        lines.push('sequenceDiagram')
-        lines.push('')
-
-        const visited = new Set<string>()
-        this.traceFlow(startFunctionId, lines, visited, 0, maxDepth)
-
-        if (lines.length <= 2) {
-            lines.push(`    Note over ${this.sanitizeId(startFunctionId)}: No outgoing calls found`)
-        }
-
-        return lines.join('\n')
-    }
-
-    /** Generate a flow diagram showing all entry points grouped by module */
-    generateEntryPoints(): string {
-        const lines: string[] = []
-        lines.push('graph TD')
-        lines.push('')
-
-        // Find functions with no callers (entry points)
-        const allFunctions = Object.values(this.lock.functions)
-        const entryPoints = allFunctions.filter(fn => fn.calledBy.length === 0)
-
-        // Group entry points by module
-        const entryByModule = new Map<string, typeof entryPoints>()
-        for (const fn of entryPoints) {
-            if (!entryByModule.has(fn.moduleId)) {
-                entryByModule.set(fn.moduleId, [])
-            }
-            entryByModule.get(fn.moduleId)!.push(fn)
-        }
-
-        for (const [modId, fns] of entryByModule) {
-            lines.push(`    subgraph mod_${this.sanitizeId(modId)}["📦 ${modId}"]`)
-            for (const fn of fns) {
-                lines.push(`        ${this.sanitizeId(fn.id)}["🚀 ${fn.name}<br/>(Entry)"]`)
-            }
-            lines.push('    end')
-        }
-
-        lines.push('')
-
-        // Show first-level calls from entry points
-        for (const fn of entryPoints) {
-            const outEdges = fn.calls
-            for (const targetId of outEdges) {
-                const targetFn = this.lock.functions[targetId]
-                if (targetFn) {
-                    lines.push(`    ${this.sanitizeId(fn.id)} --> ${this.sanitizeId(targetId)}["${targetFn.name}"]`)
-                }
-            }
-        }
-
-        lines.push('')
-        lines.push('    classDef default fill:#f9f9f9,stroke:#333')
-
-        return lines.join('\n')
-    }
-
-    private traceFlow(
-        fnId: string,
-        lines: string[],
-        visited: Set<string>,
-        depth: number,
-        maxDepth: number
-    ): void {
-        if (depth >= maxDepth || visited.has(fnId)) return
-        visited.add(fnId)
-
-        const fn = this.lock.functions[fnId]
-        if (!fn) return
-
-        const participant = this.getParticipantName(fn.moduleId, fn.name)
-
-        for (const callTarget of fn.calls) {
-            const targetFn = this.lock.functions[callTarget]
-            if (!targetFn) continue
-
-            const targetParticipant = this.getParticipantName(targetFn.moduleId, targetFn.name)
-            lines.push(`    ${participant}->>+${targetParticipant}: ${fn.name}() → ${targetFn.name}()`)
-            this.traceFlow(callTarget, lines, visited, depth + 1, maxDepth)
-            lines.push(`    ${targetParticipant}-->>-${participant}: return`)
-        }
-    }
-
-    private getParticipantName(moduleId: string, fnName: string): string {
-        return this.sanitizeId(`${moduleId}_${fnName}`)
-    }
-
-    private sanitizeId(id: string): string {
-        return id.replace(/[^a-zA-Z0-9_]/g, '_')
-    }
-}
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * FlowDiagramGenerator — generates sequence diagrams for specific
+ * function call flows (e.g., "show me the HTTP request → response flow").
+ * Outputs: .mikk/diagrams/flows/{flowName}.mmd
+ */
+export class FlowDiagramGenerator {
+    constructor(
+        private lock: MikkLock
+    ) { }
+
+    /** Generate a sequence diagram starting from a function */
+    generate(startFunctionId: string, maxDepth: number = 5): string {
+        const lines: string[] = []
+        lines.push('sequenceDiagram')
+        lines.push('')
+
+        const visited = new Set<string>()
+        this.traceFlow(startFunctionId, lines, visited, 0, maxDepth)
+
+        if (lines.length <= 2) {
+            lines.push(`    Note over ${this.sanitizeId(startFunctionId)}: No outgoing calls found`)
+        }
+
+        return lines.join('\n')
+    }
+
+    /** Generate a flow diagram showing all entry points grouped by module */
+    generateEntryPoints(): string {
+        const lines: string[] = []
+        lines.push('graph TD')
+        lines.push('')
+
+        // Find functions with no callers (entry points)
+        const allFunctions = Object.values(this.lock.functions)
+        const entryPoints = allFunctions.filter(fn => fn.calledBy.length === 0)
+
+        // Group entry points by module
+        const entryByModule = new Map<string, typeof entryPoints>()
+        for (const fn of entryPoints) {
+            if (!entryByModule.has(fn.moduleId)) {
+                entryByModule.set(fn.moduleId, [])
+            }
+            entryByModule.get(fn.moduleId)!.push(fn)
+        }
+
+        for (const [modId, fns] of entryByModule) {
+            lines.push(`    subgraph mod_${this.sanitizeId(modId)}["📦 ${modId}"]`)
+            for (const fn of fns) {
+                lines.push(`        ${this.sanitizeId(fn.id)}["🚀 ${fn.name}<br/>(Entry)"]`)
+            }
+            lines.push('    end')
+        }
+
+        lines.push('')
+
+        // Show first-level calls from entry points
+        for (const fn of entryPoints) {
+            const outEdges = fn.calls
+            for (const targetId of outEdges) {
+                const targetFn = this.lock.functions[targetId]
+                if (targetFn) {
+                    lines.push(`    ${this.sanitizeId(fn.id)} --> ${this.sanitizeId(targetId)}["${targetFn.name}"]`)
+                }
+            }
+        }
+
+        lines.push('')
+        lines.push('    classDef default fill:#f9f9f9,stroke:#333')
+
+        return lines.join('\n')
+    }
+
+    private traceFlow(
+        fnId: string,
+        lines: string[],
+        visited: Set<string>,
+        depth: number,
+        maxDepth: number
+    ): void {
+        if (depth >= maxDepth || visited.has(fnId)) return
+        visited.add(fnId)
+
+        const fn = this.lock.functions[fnId]
+        if (!fn) return
+
+        const participant = this.getParticipantName(fn.moduleId, fn.name)
+
+        for (const callTarget of fn.calls) {
+            const targetFn = this.lock.functions[callTarget]
+            if (!targetFn) continue
+
+            const targetParticipant = this.getParticipantName(targetFn.moduleId, targetFn.name)
+            lines.push(`    ${participant}->>+${targetParticipant}: ${fn.name}() → ${targetFn.name}()`)
+            this.traceFlow(callTarget, lines, visited, depth + 1, maxDepth)
+            lines.push(`    ${targetParticipant}-->>-${participant}: return`)
+        }
+    }
+
+    private getParticipantName(moduleId: string, fnName: string): string {
+        return this.sanitizeId(`${moduleId}_${fnName}`)
+    }
+
+    private sanitizeId(id: string): string {
+        return id.replace(/[^a-zA-Z0-9_]/g, '_')
+    }
+}

package/src/generators/health-diagram.ts

@@ -1,88 +1,88 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
-
-/**
- * HealthDiagramGenerator — generates a module health dashboard showing
- * coupling, cohesion, and complexity metrics.
- * Outputs: .mikk/diagrams/health.mmd
- */
-export class HealthDiagramGenerator {
-    constructor(
-        private contract: MikkContract,
-        private lock: MikkLock
-    ) { }
-
-    generate(): string {
-        const lines: string[] = []
-        lines.push('graph TD')
-        lines.push('')
-
-        const classAssignments: string[] = []
-
-        for (const module of this.contract.declared.modules) {
-            const metrics = this.computeMetrics(module.id)
-            const healthIcon = metrics.health > 0.7 ? '🟢' : metrics.health > 0.4 ? '🟡' : '🔴'
-            const healthClass = metrics.health > 0.7 ? 'healthy' : metrics.health > 0.4 ? 'warning' : 'critical'
-            const sid = this.sanitizeId(module.id)
-
-            lines.push(`    ${sid}["${healthIcon} ${module.name}<br/>Cohesion: ${(metrics.cohesion * 100).toFixed(0)}%<br/>Coupling: ${metrics.coupling}<br/>Functions: ${metrics.functionCount}"]`)
-            classAssignments.push(`    class ${sid} ${healthClass}`)
-        }
-
-        // Add inter-module dependency edges for context
-        const moduleEdges = new Set<string>()
-        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}`
-                    if (!moduleEdges.has(key)) {
-                        moduleEdges.add(key)
-                        lines.push(`    ${this.sanitizeId(fn.moduleId)} -.-> ${this.sanitizeId(targetFn.moduleId)}`)
-                    }
-                }
-            }
-        }
-
-        lines.push('')
-        lines.push('    classDef healthy fill:#27ae60,stroke:#2c3e50,color:#fff')
-        lines.push('    classDef warning fill:#f39c12,stroke:#2c3e50,color:#fff')
-        lines.push('    classDef critical fill:#e74c3c,stroke:#2c3e50,color:#fff')
-        lines.push('')
-        for (const assignment of classAssignments) {
-            lines.push(assignment)
-        }
-
-        return lines.join('\n')
-    }
-
-    private computeMetrics(moduleId: string) {
-        const moduleFunctions = Object.values(this.lock.functions).filter(f => f.moduleId === moduleId)
-        const functionCount = moduleFunctions.length
-
-        // Coupling: count of external calls
-        let externalCalls = 0
-        let internalCalls = 0
-        for (const fn of moduleFunctions) {
-            for (const call of fn.calls) {
-                const target = this.lock.functions[call]
-                if (target) {
-                    if (target.moduleId === moduleId) internalCalls++
-                    else externalCalls++
-                }
-            }
-        }
-
-        // Cohesion: ratio of internal to total calls
-        const totalCalls = internalCalls + externalCalls
-        const cohesion = totalCalls === 0 ? 0.5 : internalCalls / totalCalls
-
-        // Health: weighted score
-        const health = cohesion * 0.6 + (functionCount > 0 ? Math.min(1, 10 / functionCount) * 0.4 : 0.4)
-
-        return { cohesion, coupling: externalCalls, functionCount, health }
-    }
-
-    private sanitizeId(id: string): string {
-        return id.replace(/[^a-zA-Z0-9_]/g, '_')
-    }
-}
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * HealthDiagramGenerator — generates a module health dashboard showing
+ * coupling, cohesion, and complexity metrics.
+ * Outputs: .mikk/diagrams/health.mmd
+ */
+export class HealthDiagramGenerator {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock
+    ) { }
+
+    generate(): string {
+        const lines: string[] = []
+        lines.push('graph TD')
+        lines.push('')
+
+        const classAssignments: string[] = []
+
+        for (const module of this.contract.declared.modules) {
+            const metrics = this.computeMetrics(module.id)
+            const healthIcon = metrics.health > 0.7 ? '🟢' : metrics.health > 0.4 ? '🟡' : '🔴'
+            const healthClass = metrics.health > 0.7 ? 'healthy' : metrics.health > 0.4 ? 'warning' : 'critical'
+            const sid = this.sanitizeId(module.id)
+
+            lines.push(`    ${sid}["${healthIcon} ${module.name}<br/>Cohesion: ${(metrics.cohesion * 100).toFixed(0)}%<br/>Coupling: ${metrics.coupling}<br/>Functions: ${metrics.functionCount}"]`)
+            classAssignments.push(`    class ${sid} ${healthClass}`)
+        }
+
+        // Add inter-module dependency edges for context
+        const moduleEdges = new Set<string>()
+        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}`
+                    if (!moduleEdges.has(key)) {
+                        moduleEdges.add(key)
+                        lines.push(`    ${this.sanitizeId(fn.moduleId)} -.-> ${this.sanitizeId(targetFn.moduleId)}`)
+                    }
+                }
+            }
+        }
+
+        lines.push('')
+        lines.push('    classDef healthy fill:#27ae60,stroke:#2c3e50,color:#fff')
+        lines.push('    classDef warning fill:#f39c12,stroke:#2c3e50,color:#fff')
+        lines.push('    classDef critical fill:#e74c3c,stroke:#2c3e50,color:#fff')
+        lines.push('')
+        for (const assignment of classAssignments) {
+            lines.push(assignment)
+        }
+
+        return lines.join('\n')
+    }
+
+    private computeMetrics(moduleId: string) {
+        const moduleFunctions = Object.values(this.lock.functions).filter(f => f.moduleId === moduleId)
+        const functionCount = moduleFunctions.length
+
+        // Coupling: count of external calls
+        let externalCalls = 0
+        let internalCalls = 0
+        for (const fn of moduleFunctions) {
+            for (const call of fn.calls) {
+                const target = this.lock.functions[call]
+                if (target) {
+                    if (target.moduleId === moduleId) internalCalls++
+                    else externalCalls++
+                }
+            }
+        }
+
+        // Cohesion: ratio of internal to total calls
+        const totalCalls = internalCalls + externalCalls
+        const cohesion = totalCalls === 0 ? 0.5 : internalCalls / totalCalls
+
+        // Health: weighted score
+        const health = cohesion * 0.6 + (functionCount > 0 ? Math.min(1, 10 / functionCount) * 0.4 : 0.4)
+
+        return { cohesion, coupling: externalCalls, functionCount, health }
+    }
+
+    private sanitizeId(id: string): string {
+        return id.replace(/[^a-zA-Z0-9_]/g, '_')
+    }
+}

package/src/generators/impact-diagram.ts

@@ -1,65 +1,65 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
-
-/**
- * ImpactDiagramGenerator — generates a Mermaid diagram showing the
- * impact of changes in specific files/functions.
- * Outputs: .mikk/diagrams/impact/{filename}.mmd
- */
-export class ImpactDiagramGenerator {
-    constructor(
-        private lock: MikkLock
-    ) { }
-
-    generate(changedNodeIds: string[], impactedNodeIds: string[]): string {
-        const lines: string[] = []
-        lines.push('graph LR')
-        lines.push('')
-
-        // Changed nodes (red)
-        for (const id of changedNodeIds) {
-            const fn = this.lock.functions[id]
-            if (fn) {
-                lines.push(`    ${this.sanitizeId(id)}["🔴 ${fn.name}<br/>${fn.file}"]`)
-            }
-        }
-
-        // Impacted nodes (orange)
-        for (const id of impactedNodeIds) {
-            const fn = this.lock.functions[id]
-            if (fn) {
-                lines.push(`    ${this.sanitizeId(id)}["🟠 ${fn.name}<br/>${fn.file}"]`)
-            }
-        }
-
-        lines.push('')
-
-        // Draw edges showing the impact chain
-        const allIds = new Set([...changedNodeIds, ...impactedNodeIds])
-        for (const id of allIds) {
-            const fn = this.lock.functions[id]
-            if (!fn) continue
-            for (const callerId of fn.calledBy) {
-                if (allIds.has(callerId)) {
-                    lines.push(`    ${this.sanitizeId(callerId)} --> ${this.sanitizeId(id)}`)
-                }
-            }
-        }
-
-        lines.push('')
-        lines.push('    classDef changed fill:#e74c3c,stroke:#c0392b,color:#fff')
-        lines.push('    classDef impacted fill:#e67e22,stroke:#d35400,color:#fff')
-
-        for (const id of changedNodeIds) {
-            lines.push(`    class ${this.sanitizeId(id)} changed`)
-        }
-        for (const id of impactedNodeIds) {
-            lines.push(`    class ${this.sanitizeId(id)} impacted`)
-        }
-
-        return lines.join('\n')
-    }
-
-    private sanitizeId(id: string): string {
-        return id.replace(/[^a-zA-Z0-9_]/g, '_')
-    }
-}
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * ImpactDiagramGenerator — generates a Mermaid diagram showing the
+ * impact of changes in specific files/functions.
+ * Outputs: .mikk/diagrams/impact/{filename}.mmd
+ */
+export class ImpactDiagramGenerator {
+    constructor(
+        private lock: MikkLock
+    ) { }
+
+    generate(changedNodeIds: string[], impactedNodeIds: string[]): string {
+        const lines: string[] = []
+        lines.push('graph LR')
+        lines.push('')
+
+        // Changed nodes (red)
+        for (const id of changedNodeIds) {
+            const fn = this.lock.functions[id]
+            if (fn) {
+                lines.push(`    ${this.sanitizeId(id)}["🔴 ${fn.name}<br/>${fn.file}"]`)
+            }
+        }
+
+        // Impacted nodes (orange)
+        for (const id of impactedNodeIds) {
+            const fn = this.lock.functions[id]
+            if (fn) {
+                lines.push(`    ${this.sanitizeId(id)}["🟠 ${fn.name}<br/>${fn.file}"]`)
+            }
+        }
+
+        lines.push('')
+
+        // Draw edges showing the impact chain
+        const allIds = new Set([...changedNodeIds, ...impactedNodeIds])
+        for (const id of allIds) {
+            const fn = this.lock.functions[id]
+            if (!fn) continue
+            for (const callerId of fn.calledBy) {
+                if (allIds.has(callerId)) {
+                    lines.push(`    ${this.sanitizeId(callerId)} --> ${this.sanitizeId(id)}`)
+                }
+            }
+        }
+
+        lines.push('')
+        lines.push('    classDef changed fill:#e74c3c,stroke:#c0392b,color:#fff')
+        lines.push('    classDef impacted fill:#e67e22,stroke:#d35400,color:#fff')
+
+        for (const id of changedNodeIds) {
+            lines.push(`    class ${this.sanitizeId(id)} changed`)
+        }
+        for (const id of impactedNodeIds) {
+            lines.push(`    class ${this.sanitizeId(id)} impacted`)
+        }
+
+        return lines.join('\n')
+    }
+
+    private sanitizeId(id: string): string {
+        return id.replace(/[^a-zA-Z0-9_]/g, '_')
+    }
+}

package/src/generators/main-diagram.ts

@@ -1,63 +1,63 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
-
-/**
- * MainDiagramGenerator — generates the top-level Mermaid diagram
- * showing all modules and their interconnections.
- * Outputs: .mikk/diagrams/main.mmd
- */
-export class MainDiagramGenerator {
-    constructor(
-        private contract: MikkContract,
-        private lock: MikkLock
-    ) { }
-
-    generate(): string {
-        const lines: string[] = []
-        lines.push('graph TD')
-        lines.push('')
-
-        // Add module nodes
-        for (const module of this.contract.declared.modules) {
-            const lockModule = this.lock.modules[module.id]
-            const fileCount = lockModule?.files.length || 0
-            const fnCount = Object.values(this.lock.functions).filter(f => f.moduleId === module.id).length
-            lines.push(`    ${this.sanitizeId(module.id)}["📦 ${module.name}<br/>${fileCount} files, ${fnCount} functions"]`)
-        }
-
-        lines.push('')
-
-        // Add inter-module edges based on cross-module function calls
-        const moduleEdges = new Map<string, Set<string>>()
-
-        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 edgeKey = `${fn.moduleId}→${targetFn.moduleId}`
-                    if (!moduleEdges.has(edgeKey)) {
-                        moduleEdges.set(edgeKey, new Set())
-                    }
-                    moduleEdges.get(edgeKey)!.add(`${fn.name}→${targetFn.name}`)
-                }
-            }
-        }
-
-        for (const [edge, calls] of moduleEdges) {
-            const [from, to] = edge.split('→')
-            lines.push(`    ${this.sanitizeId(from)} -->|${calls.size} calls| ${this.sanitizeId(to)}`)
-        }
-
-        // Style
-        lines.push('')
-        lines.push('    classDef module fill:#4a90d9,stroke:#2c3e50,color:#fff,stroke-width:2px')
-        for (const module of this.contract.declared.modules) {
-            lines.push(`    class ${this.sanitizeId(module.id)} module`)
-        }
-
-        return lines.join('\n')
-    }
-
-    private sanitizeId(id: string): string {
-        return id.replace(/[^a-zA-Z0-9_]/g, '_')
-    }
-}
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * MainDiagramGenerator — generates the top-level Mermaid diagram
+ * showing all modules and their interconnections.
+ * Outputs: .mikk/diagrams/main.mmd
+ */
+export class MainDiagramGenerator {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock
+    ) { }
+
+    generate(): string {
+        const lines: string[] = []
+        lines.push('graph TD')
+        lines.push('')
+
+        // Add module nodes
+        for (const module of this.contract.declared.modules) {
+            const lockModule = this.lock.modules[module.id]
+            const fileCount = lockModule?.files.length || 0
+            const fnCount = Object.values(this.lock.functions).filter(f => f.moduleId === module.id).length
+            lines.push(`    ${this.sanitizeId(module.id)}["📦 ${module.name}<br/>${fileCount} files, ${fnCount} functions"]`)
+        }
+
+        lines.push('')
+
+        // Add inter-module edges based on cross-module function calls
+        const moduleEdges = new Map<string, Set<string>>()
+
+        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 edgeKey = `${fn.moduleId}→${targetFn.moduleId}`
+                    if (!moduleEdges.has(edgeKey)) {
+                        moduleEdges.set(edgeKey, new Set())
+                    }
+                    moduleEdges.get(edgeKey)!.add(`${fn.name}→${targetFn.name}`)
+                }
+            }
+        }
+
+        for (const [edge, calls] of moduleEdges) {
+            const [from, to] = edge.split('→')
+            lines.push(`    ${this.sanitizeId(from)} -->|${calls.size} calls| ${this.sanitizeId(to)}`)
+        }
+
+        // Style
+        lines.push('')
+        lines.push('    classDef module fill:#4a90d9,stroke:#2c3e50,color:#fff,stroke-width:2px')
+        for (const module of this.contract.declared.modules) {
+            lines.push(`    class ${this.sanitizeId(module.id)} module`)
+        }
+
+        return lines.join('\n')
+    }
+
+    private sanitizeId(id: string): string {
+        return id.replace(/[^a-zA-Z0-9_]/g, '_')
+    }
+}