@getmikk/diagram-generator 1.2.0

package/package.json

@@ -0,0 +1,26 @@
+{
+    "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"
+    }
+}

package/src/generators/capsule-diagram.ts

@@ -0,0 +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, '_')
+    }
+}

package/src/generators/dependency-matrix.ts

@@ -0,0 +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, '_')
+    }
+}

package/src/generators/flow-diagram.ts

@@ -0,0 +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, '_')
+    }
+}

package/src/generators/health-diagram.ts

@@ -0,0 +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, '_')
+    }
+}

package/src/generators/impact-diagram.ts

@@ -0,0 +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, '_')
+    }
+}

package/src/generators/main-diagram.ts

@@ -0,0 +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, '_')
+    }
+}

package/src/generators/module-diagram.ts

@@ -0,0 +1,75 @@
+import * as path from 'node:path'
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * ModuleDiagramGenerator — generates a detailed Mermaid diagram for a
+ * single module, showing its internal files and function call graph.
+ * Outputs: .mikk/diagrams/modules/{moduleId}.mmd
+ */
+export class ModuleDiagramGenerator {
+    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 TD`)
+        lines.push(`    subgraph mod_${this.sanitizeId(moduleId)}["📦 Module: ${module.name}"]`)
+
+        const moduleFunctions = Object.values(this.lock.functions).filter(f => f.moduleId === moduleId)
+
+        // Group functions by file
+        const functionsByFile = new Map<string, typeof moduleFunctions>()
+        for (const fn of moduleFunctions) {
+            if (!functionsByFile.has(fn.file)) {
+                functionsByFile.set(fn.file, [])
+            }
+            functionsByFile.get(fn.file)!.push(fn)
+        }
+
+        // Add file subgraphs
+        for (const [filePath, fns] of functionsByFile) {
+            const fileName = path.basename(filePath)
+            lines.push(`        subgraph file_${this.sanitizeId(filePath)}["📄 ${fileName}"]`)
+            for (const fn of fns) {
+                const icon = fn.calledBy.length === 0 ? '⚡' : 'λ' // ⚡ for entry points (called by nothing internal)
+                lines.push(`            ${this.sanitizeId(fn.id)}["${icon} ${fn.name}"]`)
+            }
+            lines.push('        end')
+        }
+
+        lines.push('    end')
+        lines.push('')
+
+        // Add call edges
+        for (const fn of moduleFunctions) {
+            for (const callTarget of fn.calls) {
+                const targetFn = this.lock.functions[callTarget]
+                if (targetFn) {
+                    if (targetFn.moduleId === moduleId) {
+                        // Internal call
+                        lines.push(`    ${this.sanitizeId(fn.id)} --> ${this.sanitizeId(callTarget)}`)
+                    } else {
+                        // External call
+                        const targetMod = targetFn.moduleId
+                        lines.push(`    ${this.sanitizeId(fn.id)} -.->|"calls"| ext_${this.sanitizeId(callTarget)}["🔗 ${targetFn.name}<br/>(${targetMod})"]`)
+                    }
+                }
+            }
+        }
+
+        lines.push('')
+        lines.push('    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px')
+        lines.push('    classDef external fill:#ecf0f1,stroke:#bdc3c7,stroke-dasharray: 5 5')
+
+        return lines.join('\n')
+    }
+
+    private sanitizeId(id: string): string {
+        return id.replace(/[^a-zA-Z0-9_]/g, '_')
+    }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { DiagramOrchestrator } from './orchestrator.js'
+export { MainDiagramGenerator } from './generators/main-diagram.js'
+export { ModuleDiagramGenerator } from './generators/module-diagram.js'
+export { ImpactDiagramGenerator } from './generators/impact-diagram.js'
+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'

package/src/orchestrator.ts

@@ -0,0 +1,76 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs/promises'
+import type { MikkContract, MikkLock } from '@getmikk/core'
+import { MainDiagramGenerator } from './generators/main-diagram.js'
+import { ModuleDiagramGenerator } from './generators/module-diagram.js'
+import { ImpactDiagramGenerator } from './generators/impact-diagram.js'
+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'
+
+/**
+ * DiagramOrchestrator — generates all diagram types and writes them to
+ * the .mikk/diagrams/ directory structure.
+ */
+export class DiagramOrchestrator {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock,
+        private projectRoot: string
+    ) { }
+
+    /** Generate all diagrams */
+    async generateAll(): Promise<{ generated: string[] }> {
+        const generated: string[] = []
+
+        // Main diagram
+        const mainGen = new MainDiagramGenerator(this.contract, this.lock)
+        await this.writeDiagram('diagrams/main.mmd', mainGen.generate())
+        generated.push('diagrams/main.mmd')
+
+        // Health diagram
+        const healthGen = new HealthDiagramGenerator(this.contract, this.lock)
+        await this.writeDiagram('diagrams/health.mmd', healthGen.generate())
+        generated.push('diagrams/health.mmd')
+
+        // Flow diagram (entry points)
+        const flowGen = new FlowDiagramGenerator(this.lock)
+        await this.writeDiagram('diagrams/flows/entry-points.mmd', flowGen.generateEntryPoints())
+        generated.push('diagrams/flows/entry-points.mmd')
+
+        // Dependency matrix
+        const matrixGen = new DependencyMatrixGenerator(this.contract, this.lock)
+        await this.writeDiagram('diagrams/dependency-matrix.mmd', matrixGen.generate())
+        generated.push('diagrams/dependency-matrix.mmd')
+
+        // Per-module diagrams
+        for (const module of this.contract.declared.modules) {
+            const moduleGen = new ModuleDiagramGenerator(this.contract, this.lock)
+            await this.writeDiagram(`diagrams/modules/${module.id}.mmd`, moduleGen.generate(module.id))
+            generated.push(`diagrams/modules/${module.id}.mmd`)
+
+            const capsuleGen = new CapsuleDiagramGenerator(this.contract, this.lock)
+            await this.writeDiagram(`diagrams/capsules/${module.id}.mmd`, capsuleGen.generate(module.id))
+            generated.push(`diagrams/capsules/${module.id}.mmd`)
+        }
+
+        return { generated }
+    }
+
+    /** Generate impact diagram for specific changes */
+    async generateImpact(changedIds: string[], impactedIds: string[]): Promise<string> {
+        const impactGen = new ImpactDiagramGenerator(this.lock)
+        const diagram = impactGen.generate(changedIds, impactedIds)
+        const timestamp = Date.now()
+        const filename = `diagrams/impact/impact-${timestamp}.mmd`
+        await this.writeDiagram(filename, diagram)
+        return filename
+    }
+
+    private async writeDiagram(relativePath: string, content: string): Promise<void> {
+        const fullPath = path.join(this.projectRoot, '.mikk', relativePath)
+        await fs.mkdir(path.dirname(fullPath), { recursive: true })
+        await fs.writeFile(fullPath, content, 'utf-8')
+    }
+}

package/tests/smoke.test.ts

@@ -0,0 +1,5 @@
+import { expect, test } from "bun:test";
+
+test("smoke test - diagram-generator", () => {
+    expect(true).toBe(true);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "rootDir": "src"
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "tests"
+    ]
+}