@getmikk/diagram-generator 1.3.1 → 1.5.0

package/package.json

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

package/src/generators/capsule-diagram.ts

@@ -16,6 +16,7 @@ export class CapsuleDiagramGenerator {
         if (!module) return `%% Module "${moduleId}" not found`
 
         const lines: string[] = []
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
         lines.push('graph LR')
         lines.push('')
 
@@ -67,8 +68,22 @@ export class CapsuleDiagramGenerator {
         }
 
         lines.push('')
-        lines.push('    classDef publicApi fill:#27ae60,stroke:#2c3e50,color:#fff')
-        lines.push('    classDef internalApi fill:#7f8c8d,stroke:#2c3e50,color:#fff')
+        lines.push('    classDef publicApi fill:#22c55e,stroke:#4ade80,color:#f0fdf4')
+        lines.push('    classDef internalApi fill:#64748b,stroke:#94a3b8,color:#f1f5f9')
+
+        // Apply classes to nodes
+        for (const fn of exportedFns) {
+            lines.push(`    class ${this.sanitizeId(fn.id)} publicApi`)
+        }
+        for (const fn of internalFns) {
+            if (internalFns.length <= 10) {
+                lines.push(`    class ${this.sanitizeId(fn.id)} internalApi`)
+            }
+        }
+        // Apply to the summary node if used
+        if (internalFns.length > 10) {
+            lines.push('    class internal internalApi')
+        }
 
         return lines.join('\n')
     }

package/src/generators/dependency-matrix.ts

@@ -23,6 +23,7 @@ export class DependencyMatrixGenerator {
         const matrix = this.computeMatrix()
         const lines: string[] = []
 
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
         lines.push('graph LR')
         lines.push('')
 
@@ -44,7 +45,7 @@ export class DependencyMatrixGenerator {
         }
 
         lines.push('')
-        lines.push('    classDef default fill:#ecf0f1,stroke:#34495e,color:#2c3e50')
+        lines.push('    classDef default fill:#334155,stroke:#64748b,color:#e2e8f0')
 
         return lines.join('\n')
     }
@@ -78,6 +79,7 @@ export class DependencyMatrixGenerator {
     private computeMatrix(): Map<string, number> {
         const counts = new Map<string, number>()
 
+        // Count function-level cross-module calls
         for (const fn of Object.values(this.lock.functions)) {
             for (const callTarget of fn.calls) {
                 const targetFn = this.lock.functions[callTarget]
@@ -88,6 +90,18 @@ 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) {
+                const importedFile = this.lock.files[importedPath]
+                if (importedFile && file.moduleId !== importedFile.moduleId) {
+                    const key = `${file.moduleId}|${importedFile.moduleId}`
+                    counts.set(key, (counts.get(key) || 0) + 1)
+                }
+            }
+        }
+
         return counts
     }
 

package/src/generators/flow-diagram.ts

@@ -13,6 +13,7 @@ export class FlowDiagramGenerator {
     /** Generate a sequence diagram starting from a function */
     generate(startFunctionId: string, maxDepth: number = 5): string {
         const lines: string[] = []
+        lines.push('%%{init: {"theme": "dark"}}%%')
         lines.push('sequenceDiagram')
         lines.push('')
 
@@ -29,6 +30,7 @@ export class FlowDiagramGenerator {
     /** Generate a flow diagram showing all entry points grouped by module */
     generateEntryPoints(): string {
         const lines: string[] = []
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
         lines.push('graph TD')
         lines.push('')
 
@@ -67,7 +69,7 @@ export class FlowDiagramGenerator {
         }
 
         lines.push('')
-        lines.push('    classDef default fill:#f9f9f9,stroke:#333')
+        lines.push('    classDef default fill:#334155,stroke:#64748b,color:#e2e8f0')
 
         return lines.join('\n')
     }

package/src/generators/health-diagram.ts

@@ -13,6 +13,7 @@ export class HealthDiagramGenerator {
 
     generate(): string {
         const lines: string[] = []
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
         lines.push('graph TD')
         lines.push('')
 
@@ -28,7 +29,7 @@ export class HealthDiagramGenerator {
             classAssignments.push(`    class ${sid} ${healthClass}`)
         }
 
-        // Add inter-module dependency edges for context
+        // Add inter-module dependency edges for context (function calls + file imports)
         const moduleEdges = new Set<string>()
         for (const fn of Object.values(this.lock.functions)) {
             for (const callTarget of fn.calls) {
@@ -42,11 +43,24 @@ export class HealthDiagramGenerator {
                 }
             }
         }
+        for (const file of Object.values(this.lock.files)) {
+            if (!file.imports) continue
+            for (const importedPath of file.imports) {
+                const importedFile = this.lock.files[importedPath]
+                if (importedFile && file.moduleId !== importedFile.moduleId) {
+                    const key = `${file.moduleId}|${importedFile.moduleId}`
+                    if (!moduleEdges.has(key)) {
+                        moduleEdges.add(key)
+                        lines.push(`    ${this.sanitizeId(file.moduleId)} -.-> ${this.sanitizeId(importedFile.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('    classDef healthy fill:#22c55e,stroke:#4ade80,color:#f0fdf4')
+        lines.push('    classDef warning fill:#f59e0b,stroke:#fbbf24,color:#1e293b')
+        lines.push('    classDef critical fill:#ef4444,stroke:#f87171,color:#fef2f2')
         lines.push('')
         for (const assignment of classAssignments) {
             lines.push(assignment)
@@ -57,9 +71,10 @@ export class HealthDiagramGenerator {
 
     private computeMetrics(moduleId: string) {
         const moduleFunctions = Object.values(this.lock.functions).filter(f => f.moduleId === moduleId)
+        const moduleFiles = Object.values(this.lock.files).filter(f => f.moduleId === moduleId)
         const functionCount = moduleFunctions.length
 
-        // Coupling: count of external calls
+        // Coupling: count of external calls + external file imports
         let externalCalls = 0
         let internalCalls = 0
         for (const fn of moduleFunctions) {
@@ -71,6 +86,16 @@ export class HealthDiagramGenerator {
                 }
             }
         }
+        for (const file of moduleFiles) {
+            if (!file.imports) continue
+            for (const importedPath of file.imports) {
+                const importedFile = this.lock.files[importedPath]
+                if (importedFile) {
+                    if (importedFile.moduleId === moduleId) internalCalls++
+                    else externalCalls++
+                }
+            }
+        }
 
         // Cohesion: ratio of internal to total calls
         const totalCalls = internalCalls + externalCalls

package/src/generators/impact-diagram.ts

@@ -12,6 +12,7 @@ export class ImpactDiagramGenerator {
 
     generate(changedNodeIds: string[], impactedNodeIds: string[]): string {
         const lines: string[] = []
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
         lines.push('graph LR')
         lines.push('')
 
@@ -46,8 +47,8 @@ export class ImpactDiagramGenerator {
         }
 
         lines.push('')
-        lines.push('    classDef changed fill:#e74c3c,stroke:#c0392b,color:#fff')
-        lines.push('    classDef impacted fill:#e67e22,stroke:#d35400,color:#fff')
+        lines.push('    classDef changed fill:#ef4444,stroke:#f87171,color:#fef2f2')
+        lines.push('    classDef impacted fill:#f59e0b,stroke:#fbbf24,color:#1e293b')
 
         for (const id of changedNodeIds) {
             lines.push(`    class ${this.sanitizeId(id)} changed`)

package/src/generators/main-diagram.ts

@@ -1,8 +1,10 @@
+import * as path from 'node:path'
 import type { MikkContract, MikkLock } from '@getmikk/core'
 
 /**
  * MainDiagramGenerator — generates the top-level Mermaid diagram
  * showing all modules and their interconnections.
+ * For single-module projects, shows a file-level view instead.
  * Outputs: .mikk/diagrams/main.mmd
  */
 export class MainDiagramGenerator {
@@ -12,7 +14,20 @@ export class MainDiagramGenerator {
     ) { }
 
     generate(): string {
+        const modules = this.contract.declared.modules
+
+        // Single module or no modules — show a file-level view instead of one useless node
+        if (modules.length <= 1) {
+            return this.generateFileLevelView()
+        }
+
+        return this.generateModuleLevelView()
+    }
+
+    /** Standard multi-module view — modules as nodes, inter-module calls as edges */
+    private generateModuleLevelView(): string {
         const lines: string[] = []
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
         lines.push('graph TD')
         lines.push('')
 
@@ -26,9 +41,10 @@ export class MainDiagramGenerator {
 
         lines.push('')
 
-        // Add inter-module edges based on cross-module function calls
+        // Add inter-module edges based on cross-module function calls AND file imports
         const moduleEdges = new Map<string, Set<string>>()
 
+        // Function-level cross-module calls
         for (const fn of Object.values(this.lock.functions)) {
             for (const callTarget of fn.calls) {
                 const targetFn = this.lock.functions[callTarget]
@@ -42,6 +58,23 @@ 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) {
+                const importedFile = this.lock.files[importedPath]
+                if (importedFile && file.moduleId !== importedFile.moduleId) {
+                    const edgeKey = `${file.moduleId}→${importedFile.moduleId}`
+                    if (!moduleEdges.has(edgeKey)) {
+                        moduleEdges.set(edgeKey, new Set())
+                    }
+                    const fromName = file.path.split('/').pop() || file.path
+                    const toName = importedFile.path.split('/').pop() || importedFile.path
+                    moduleEdges.get(edgeKey)!.add(`${fromName}→${toName}`)
+                }
+            }
+        }
+
         for (const [edge, calls] of moduleEdges) {
             const [from, to] = edge.split('→')
             lines.push(`    ${this.sanitizeId(from)} -->|${calls.size} calls| ${this.sanitizeId(to)}`)
@@ -49,7 +82,7 @@ export class MainDiagramGenerator {
 
         // Style
         lines.push('')
-        lines.push('    classDef module fill:#4a90d9,stroke:#2c3e50,color:#fff,stroke-width:2px')
+        lines.push('    classDef module fill:#3b82f6,stroke:#60a5fa,color:#f8fafc,stroke-width:2px')
         for (const module of this.contract.declared.modules) {
             lines.push(`    class ${this.sanitizeId(module.id)} module`)
         }
@@ -57,6 +90,75 @@ export class MainDiagramGenerator {
         return lines.join('\n')
     }
 
+    /**
+     * File-level view — for single-module or no-module projects.
+     * Shows the top files grouped by directory, with import edges between them.
+     * Caps at 25 files to keep the diagram readable.
+     */
+    private generateFileLevelView(): string {
+        const MAX_FILES = 25
+        const allFiles = Object.values(this.lock.files)
+
+        // Sort by number of connections (imports + importedBy) — most connected first
+        const ranked = allFiles
+            .map(f => ({
+                ...f,
+                connections: (f.imports?.length || 0) + (Object.values(this.lock.files).filter(other => other.imports?.includes(f.path)).length),
+            }))
+            .sort((a, b) => b.connections - a.connections)
+
+        const filesToShow = ranked.slice(0, MAX_FILES)
+        const shownPaths = new Set(filesToShow.map(f => f.path))
+        const collapsedCount = allFiles.length - filesToShow.length
+
+        const lines: string[] = []
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
+        lines.push('graph TD')
+        lines.push('')
+
+        // Group files by top-level directory
+        const byDir = new Map<string, typeof filesToShow>()
+        for (const file of filesToShow) {
+            const parts = file.path.split('/')
+            const dir = parts.length > 1 ? parts.slice(0, -1).join('/') : '.'
+            if (!byDir.has(dir)) byDir.set(dir, [])
+            byDir.get(dir)!.push(file)
+        }
+
+        for (const [dir, files] of byDir) {
+            const dirLabel = dir === '.' ? 'root' : dir
+            lines.push(`    subgraph dir_${this.sanitizeId(dir)}["📂 ${dirLabel}"]`)
+            for (const file of files) {
+                const fileName = path.basename(file.path)
+                const fnCount = Object.values(this.lock.functions).filter(f => f.file === file.path).length
+                lines.push(`        ${this.sanitizeId(file.path)}["📄 ${fileName}${fnCount > 0 ? `<br/>${fnCount} fn` : ''}"]`)
+            }
+            lines.push('    end')
+        }
+
+        if (collapsedCount > 0) {
+            lines.push(`    collapsed["📁 +${collapsedCount} more files"]`)
+        }
+
+        lines.push('')
+
+        // Add import edges between shown files
+        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)}`)
+                }
+            }
+        }
+
+        // Style
+        lines.push('')
+        lines.push('    classDef default fill:#334155,stroke:#64748b,color:#e2e8f0,stroke-width:1px')
+
+        return lines.join('\n')
+    }
+
     private sanitizeId(id: string): string {
         return id.replace(/[^a-zA-Z0-9_]/g, '_')
     }

package/src/generators/module-diagram.ts

@@ -1,9 +1,16 @@
 import * as path from 'node:path'
 import type { MikkContract, MikkLock } from '@getmikk/core'
 
+/** Maximum functions to show in a single module diagram before collapsing */
+const MAX_FUNCTIONS_PER_DIAGRAM = 40
+
+/** Maximum files to show as subgraphs before collapsing smallest ones */
+const MAX_FILES_PER_DIAGRAM = 15
+
 /**
  * ModuleDiagramGenerator — generates a detailed Mermaid diagram for a
  * single module, showing its internal files and function call graph.
+ * For large modules, collapses internal-only functions to keep diagrams readable.
  * Outputs: .mikk/diagrams/modules/{moduleId}.mmd
  */
 export class ModuleDiagramGenerator {
@@ -16,23 +23,97 @@ export class ModuleDiagramGenerator {
         const module = this.contract.declared.modules.find(m => m.id === moduleId)
         if (!module) return `%% Module "${moduleId}" not found`
 
+        const moduleFunctions = Object.values(this.lock.functions).filter(f => f.moduleId === moduleId)
+
+        // If the module is very large, only show "important" functions:
+        // - Exported functions (called by other modules)
+        // - Entry points (called by nothing internal)
+        // - Functions that call or are called by other modules
+        // - Top-N most-connected functions
+        let visibleFunctions = moduleFunctions
+        let collapsedCount = 0
+
+        if (moduleFunctions.length > MAX_FUNCTIONS_PER_DIAGRAM) {
+            const importantFns = new Set<string>()
+
+            for (const fn of moduleFunctions) {
+                // Entry points — nothing internal calls them
+                const isEntryPoint = fn.calledBy.length === 0
+                // Cross-module caller or callee
+                const hasCrossModuleCalls = fn.calls.some(id => {
+                    const target = this.lock.functions[id]
+                    return target && target.moduleId !== moduleId
+                })
+                const isCalledCrossModule = fn.calledBy.some(id => {
+                    const caller = this.lock.functions[id]
+                    return caller && caller.moduleId !== moduleId
+                })
+                // Exported
+                const isExported = fn.isExported
+
+                if (isEntryPoint || hasCrossModuleCalls || isCalledCrossModule || isExported) {
+                    importantFns.add(fn.id)
+                }
+            }
+
+            // If still too many, pick the most connected ones
+            if (importantFns.size > MAX_FUNCTIONS_PER_DIAGRAM) {
+                const sorted = [...importantFns]
+                    .map(id => ({ id, connections: (this.lock.functions[id]?.calls.length || 0) + (this.lock.functions[id]?.calledBy.length || 0) }))
+                    .sort((a, b) => b.connections - a.connections)
+                    .slice(0, MAX_FUNCTIONS_PER_DIAGRAM)
+                    .map(x => x.id)
+                importantFns.clear()
+                for (const id of sorted) importantFns.add(id)
+            }
+
+            // If too few important functions, add the most connected ones
+            if (importantFns.size < Math.min(10, moduleFunctions.length)) {
+                const sorted = moduleFunctions
+                    .filter(fn => !importantFns.has(fn.id))
+                    .sort((a, b) => (b.calls.length + b.calledBy.length) - (a.calls.length + a.calledBy.length))
+                for (const fn of sorted) {
+                    if (importantFns.size >= MAX_FUNCTIONS_PER_DIAGRAM) break
+                    importantFns.add(fn.id)
+                }
+            }
+
+            visibleFunctions = moduleFunctions.filter(fn => importantFns.has(fn.id))
+            collapsedCount = moduleFunctions.length - visibleFunctions.length
+        }
+
         const lines: string[] = []
+        lines.push('%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e293b", "primaryTextColor": "#e2e8f0", "lineColor": "#64748b", "secondaryColor": "#334155", "tertiaryColor": "#475569", "background": "#0f172a", "mainBkg": "#1e293b", "nodeBorder": "#475569"}}}%%')
         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)
+        lines.push(`    subgraph mod_${this.sanitizeId(moduleId)}["📦 Module: ${module.name}${collapsedCount > 0 ? ` (${collapsedCount} internal functions collapsed)` : ''}"]`)
 
         // Group functions by file
-        const functionsByFile = new Map<string, typeof moduleFunctions>()
-        for (const fn of moduleFunctions) {
+        const functionsByFile = new Map<string, typeof visibleFunctions>()
+        for (const fn of visibleFunctions) {
             if (!functionsByFile.has(fn.file)) {
                 functionsByFile.set(fn.file, [])
             }
             functionsByFile.get(fn.file)!.push(fn)
         }
 
+        // If too many files, collapse the smallest ones into a summary node
+        let filesToRender = [...functionsByFile.entries()]
+        let collapsedFiles = 0
+        if (filesToRender.length > MAX_FILES_PER_DIAGRAM) {
+            // Sort by function count, keep the largest files
+            filesToRender.sort((a, b) => b[1].length - a[1].length)
+            const kept = filesToRender.slice(0, MAX_FILES_PER_DIAGRAM)
+            const dropped = filesToRender.slice(MAX_FILES_PER_DIAGRAM)
+            collapsedFiles = dropped.length
+            const droppedFnCount = dropped.reduce((sum, [, fns]) => sum + fns.length, 0)
+            filesToRender = kept
+
+            // Add a summary node for collapsed files
+            lines.push(`        collapsed_files["📁 +${collapsedFiles} more files (${droppedFnCount} functions)"]`)
+        }
+
         // Add file subgraphs
-        for (const [filePath, fns] of functionsByFile) {
+        for (const [filePath, fns] of filesToRender) {
             const fileName = path.basename(filePath)
             lines.push(`        subgraph file_${this.sanitizeId(filePath)}["📄 ${fileName}"]`)
             for (const fn of fns) {
@@ -45,15 +126,16 @@ export class ModuleDiagramGenerator {
         lines.push('    end')
         lines.push('')
 
-        // Add call edges
-        for (const fn of moduleFunctions) {
+        // Add call edges (only for visible functions)
+        const visibleIds = new Set(visibleFunctions.map(fn => fn.id))
+        for (const fn of visibleFunctions) {
             for (const callTarget of fn.calls) {
                 const targetFn = this.lock.functions[callTarget]
                 if (targetFn) {
-                    if (targetFn.moduleId === moduleId) {
-                        // Internal call
+                    if (targetFn.moduleId === moduleId && visibleIds.has(callTarget)) {
+                        // Internal call (both visible)
                         lines.push(`    ${this.sanitizeId(fn.id)} --> ${this.sanitizeId(callTarget)}`)
-                    } else {
+                    } else if (targetFn.moduleId !== moduleId) {
                         // External call
                         const targetMod = targetFn.moduleId
                         lines.push(`    ${this.sanitizeId(fn.id)} -.->|"calls"| ext_${this.sanitizeId(callTarget)}["🔗 ${targetFn.name}<br/>(${targetMod})"]`)
@@ -63,8 +145,8 @@ export class ModuleDiagramGenerator {
         }
 
         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')
+        lines.push('    classDef default fill:#334155,stroke:#64748b,color:#e2e8f0,stroke-width:1px')
+        lines.push('    classDef external fill:#1e293b,stroke:#475569,color:#94a3b8,stroke-dasharray: 5 5')
 
         return lines.join('\n')
     }