@getmikk/core 1.3.2 → 1.5.0

package/src/graph/cluster-detector.ts

@@ -1,6 +1,73 @@
 import * as path from 'node:path'
 import type { DependencyGraph, ModuleCluster, GraphNode } from './types.js'
 
+// ─── Domain keyword maps for semantic naming ────────────────────────
+// Each entry maps a human-readable domain label to keywords found in
+// function names and file basenames.  The first match wins.
+const DOMAIN_KEYWORDS: [string, string[]][] = [
+    // Core backends
+    ['Authentication', ['auth', 'login', 'logout', 'signin', 'signup', 'session', 'jwt', 'token', 'credential', 'password', 'oauth', 'sso']],
+    ['Encryption', ['encrypt', 'decrypt', 'cipher', 'aes', 'argon', 'derive', 'salt', 'envelope', 'hmac']],
+    ['Database', ['prisma', 'query', 'queries', 'db', 'database', 'repository', 'knex', 'sequelize', 'drizzle', 'typeorm', 'migration', 'seed']],
+    ['API', ['api', 'endpoint', 'middleware', 'handler', 'route', 'controller', 'request', 'response', 'rest', 'openapi']],
+    ['Validation', ['validate', 'validator', 'schema', 'assert', 'sanitize', 'zod', 'yup', 'joi']],
+    ['Config', ['config', 'env', 'settings', 'constants', 'options', 'feature', 'flag']],
+    ['Utils', ['util', 'utils', 'helper', 'helpers', 'format', 'convert', 'transform', 'lib', 'common', 'shared']],
+    ['Secrets', ['secret', 'vault', 'credential', 'key', 'keychain', 'encrypt', 'kms']],
+    ['Testing', ['test', 'spec', 'mock', 'fixture', 'stub', 'fake', 'factory', 'seed']],
+
+    // Frontend / UI
+    ['Navigation', ['sidebar', 'header', 'footer', 'nav', 'breadcrumb', 'menu', 'topbar', 'toolbar', 'appbar']],
+    ['Layout', ['layout', 'shell', 'frame', 'wrapper', 'page', 'container', 'grid', 'template']],
+    ['Forms', ['form', 'input', 'select', 'checkbox', 'radio', 'textarea', 'field', 'datepicker']],
+    ['Hooks', ['hook', 'useauth', 'usestate', 'useeffect', 'usememo', 'usequery', 'usemutation', 'useform', 'composable']],
+    ['Providers', ['provider', 'context', 'theme', 'store', 'reducer', 'zustand', 'pinia']],
+    ['Components', ['component', 'button', 'modal', 'dialog', 'card', 'toast', 'toggle', 'badge', 'tab', 'alert', 'avatar', 'widget']],
+    ['Dashboard', ['dashboard', 'chart', 'metric', 'stat', 'analytics', 'widget', 'overview', 'report']],
+    ['Media', ['image', 'video', 'audio', 'upload', 'gallery', 'zoom', 'embed', 'asset']],
+    ['Notifications', ['notification', 'toast', 'alert', 'snackbar', 'banner', 'push']],
+
+    // Business domains
+    ['Project Management', ['project', 'member', 'team', 'workspace', 'organization', 'invite', 'role', 'permission']],
+    ['Portfolio', ['portfolio', 'resume', 'experience', 'certification', 'award', 'testimonial', 'social', 'profile', 'bio']],
+    ['Blog', ['blog', 'post', 'article', 'mdx', 'markdown', 'rss', 'feed', 'author', 'category', 'tag', 'comment']],
+    ['Sponsors', ['sponsor', 'donation', 'patron', 'tier', 'backer']],
+    ['Search', ['search', 'filter', 'sort', 'query', 'autocomplete', 'fuzzy', 'index', 'algolia']],
+    ['Payments', ['payment', 'stripe', 'billing', 'invoice', 'subscription', 'checkout', 'cart', 'price', 'order']],
+
+    // CLI / Tooling
+    ['CLI', ['command', 'arg', 'flag', 'prompt', 'subcommand', 'repl', 'cli', 'yargs', 'commander', 'inquirer']],
+
+    // AI / ML
+    ['AI & ML', ['model', 'train', 'predict', 'inference', 'pipeline', 'tokenizer', 'embedding', 'llm', 'openai', 'anthropic', 'vector']],
+
+    // Messaging / Queue
+    ['Messaging', ['queue', 'worker', 'consumer', 'producer', 'broker', 'pubsub', 'event', 'subscriber', 'publisher', 'bullmq', 'kafka', 'rabbitmq']],
+
+    // Caching
+    ['Caching', ['cache', 'redis', 'memcached', 'ttl', 'invalidate', 'lru']],
+
+    // Logging / Monitoring
+    ['Logging', ['logger', 'log', 'trace', 'metric', 'telemetry', 'sentry', 'monitor', 'span']],
+
+    // Scheduling
+    ['Scheduling', ['cron', 'job', 'scheduler', 'background', 'recurring', 'interval']],
+
+    // Storage / Files
+    ['Storage', ['storage', 's3', 'bucket', 'blob', 'upload', 'download', 'stream', 'file', 'archive']],
+
+    // Email
+    ['Email', ['email', 'mail', 'smtp', 'sendgrid', 'mailer', 'template', 'newsletter']],
+
+    // GraphQL / gRPC
+    ['GraphQL', ['resolver', 'mutation', 'subscription', 'typedef', 'graphql', 'gql', 'apollo']],
+    ['gRPC', ['grpc', 'rpc', 'protobuf', 'service', 'stub', 'proto']],
+
+    // i18n / a11y
+    ['Internationalization', ['i18n', 'locale', 'translation', 'intl', 'language', 'l10n']],
+    ['Accessibility', ['a11y', 'aria', 'screenreader', 'focus', 'keyboard']],
+]
+
 /**
  * ClusterDetector — analyzes the dependency graph and groups files
  * into natural module clusters using greedy agglomeration with coupling scores.
@@ -39,7 +106,7 @@ export class ClusterDetector {
 
             // Start a new cluster with this file as seed
             const cluster: string[] = [seedFile]
-            assigned.add(seedFile)
+            const tentative = new Set<string>([seedFile])
 
             // Expand: find files strongly coupled to any file in this cluster
             let expanded = true
@@ -50,7 +117,7 @@ export class ClusterDetector {
                     const partners = couplingMatrix.get(clusterFile) || new Map()
 
                     for (const [candidate, score] of partners) {
-                        if (assigned.has(candidate)) continue
+                        if (assigned.has(candidate) || tentative.has(candidate)) continue
                         if (score < this.minCouplingScore) continue
 
                         // Is this candidate more coupled to this cluster than to others?
@@ -63,7 +130,7 @@ export class ClusterDetector {
 
                         if (clusterAffinity > bestOutsideAffinity) {
                             cluster.push(candidate)
-                            assigned.add(candidate)
+                            tentative.add(candidate)
                             expanded = true
                         }
                     }
@@ -71,13 +138,16 @@ export class ClusterDetector {
             }
 
             if (cluster.length >= this.minClusterSize) {
+                // Mark all files in this cluster as assigned
+                for (const f of cluster) assigned.add(f)
                 const filePathsForCluster = cluster.map(id => this.getNodeFile(id))
+                const functionIds = this.getFunctionIdsForFiles(cluster)
                 clusters.push({
                     id: this.inferClusterId(filePathsForCluster),
                     files: filePathsForCluster,
                     confidence: this.computeClusterConfidence(cluster),
-                    suggestedName: this.inferClusterName(filePathsForCluster),
-                    functions: this.getFunctionIdsForFiles(cluster),
+                    suggestedName: this.inferSemanticName(filePathsForCluster, functionIds),
+                    functions: functionIds,
                 })
             }
         }
@@ -86,17 +156,59 @@ export class ClusterDetector {
         for (const file of files) {
             if (!assigned.has(file)) {
                 const filePath = this.getNodeFile(file)
+                const functionIds = this.getFunctionIdsForFiles([file])
                 clusters.push({
                     id: this.inferClusterId([filePath]),
                     files: [filePath],
                     confidence: 0.3,
-                    suggestedName: this.inferClusterName([filePath]),
-                    functions: this.getFunctionIdsForFiles([file]),
+                    suggestedName: this.inferSemanticName([filePath], functionIds),
+                    functions: functionIds,
                 })
             }
         }
 
-        return clusters.sort((a, b) => b.confidence - a.confidence)
+        // ── Post-process: merge clusters with the same base directory ──
+        // Without this, a directory like `lib/` often fragments into
+        // "Lib", "Lib (2)", "Lib (3)" which is useless for AI.
+        const merged = this.mergeSiblingClusters(clusters)
+
+        // Deduplicate cluster IDs — append numeric suffix if collision
+        const seenIds = new Map<string, number>()
+        for (const cluster of merged) {
+            const baseId = cluster.id
+            const count = seenIds.get(baseId) || 0
+            seenIds.set(baseId, count + 1)
+            if (count > 0) {
+                cluster.id = `${baseId}-${count + 1}`
+            }
+        }
+
+        // ── Disambiguate duplicate module names ──
+        // When semantic naming produces the same label for different clusters
+        // (e.g. "Search" × 3), append the distinctive directory segment.
+        const nameCount = new Map<string, ModuleCluster[]>()
+        for (const cluster of merged) {
+            const existing = nameCount.get(cluster.suggestedName) || []
+            existing.push(cluster)
+            nameCount.set(cluster.suggestedName, existing)
+        }
+        for (const [name, dupes] of nameCount) {
+            if (dupes.length <= 1) continue
+            for (const cluster of dupes) {
+                // Try to find a distinctive directory segment from the cluster ID
+                // e.g. "packages-diagram-generator" → "Diagram Generator"
+                const segments = cluster.id.split('-')
+                    .filter(s => s !== 'packages' && s !== 'apps' && s !== 'src')
+                const suffix = segments
+                    .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+                    .join(' ')
+                if (suffix && suffix !== name) {
+                    cluster.suggestedName = `${name} (${suffix})`
+                }
+            }
+        }
+
+        return merged.sort((a, b) => b.confidence - a.confidence)
     }
 
     // ─── Coupling Matrix ──────────────────────────────────────────
@@ -276,7 +388,7 @@ export class ClusterDetector {
     private inferClusterId(filePaths: string[]): string {
         if (filePaths.length === 0) return 'unknown'
         if (filePaths.length === 1) {
-            return this.getDirSegment(filePaths[0])
+            return this.getDirSegments(filePaths[0])
         }
         // Find the longest common directory prefix
         const segments = filePaths.map(f => f.split('/'))
@@ -290,23 +402,179 @@ export class ClusterDetector {
             }
         }
         const commonPath = firstSegments.slice(0, commonLen).join('/')
-        return this.getDirSegment(commonPath || filePaths[0])
+        return this.getDirSegments(commonPath || filePaths[0])
     }
 
-    /** Get the most meaningful directory segment from a path */
-    private getDirSegment(filePath: string): string {
+    /**
+     * Build a hyphenated module ID from the meaningful directory segments.
+     * Skips "src" since it's a trivial container. Returns at most 3 segments.
+     * e.g. "src/components/ui/button.tsx" → "components-ui"
+     *      "src/lib/hooks/use-auth.ts"    → "lib-hooks"
+     *      "features/auth/api/route.ts"   → "features-auth-api"
+     */
+    private getDirSegments(filePath: string): string {
         const parts = filePath.split('/')
-        // Skip 'src' if present
-        if (parts[0] === 'src' && parts.length >= 2) return parts[1]
-        if (parts.length > 1) return parts[0]
-        return path.basename(filePath, path.extname(filePath))
+        // Remove filename (last part with an extension)
+        const dirs = parts.filter((p, i) => i < parts.length - 1 || !p.includes('.'))
+        // Drop 'src' prefix — it carries no semantic meaning
+        const meaningful = dirs.filter(d => d !== 'src' && d !== '')
+        if (meaningful.length === 0) {
+            // Fallback: use the filename without extension
+            const last = parts[parts.length - 1]
+            return last.replace(/\.[^.]+$/, '') || 'unknown'
+        }
+        // Take up to 3 segments for a unique but concise ID
+        return meaningful.slice(0, 3).join('-')
+    }
+
+    // ─── Cluster Merging ──────────────────────────────────────────
+
+    /**
+     * Merge clusters that share the same base directory (first 1-2 segments).
+     * This prevents fragmentation like "Lib", "Lib (2)", "Lib (3)" from
+     * clumsy coupling-based splitting of files in the same directory.
+     */
+    private mergeSiblingClusters(clusters: ModuleCluster[]): ModuleCluster[] {
+        const byBaseDir = new Map<string, ModuleCluster[]>()
+
+        for (const cluster of clusters) {
+            const base = this.getBaseDir(cluster.files)
+            const existing = byBaseDir.get(base) || []
+            existing.push(cluster)
+            byBaseDir.set(base, existing)
+        }
+
+        const result: ModuleCluster[] = []
+        for (const [baseDir, siblings] of byBaseDir) {
+            if (siblings.length <= 1) {
+                result.push(...siblings)
+                continue
+            }
+
+            // Merge all siblings into one cluster
+            const allFiles = siblings.flatMap(c => c.files)
+            const allFunctions = siblings.flatMap(c => c.functions)
+            const avgConfidence = siblings.reduce((sum, c) => sum + c.confidence, 0) / siblings.length
+            const uniqueFiles = [...new Set(allFiles)]
+            const uniqueFunctions = [...new Set(allFunctions)]
+
+            result.push({
+                id: this.getDirSegments(uniqueFiles[0]),
+                files: uniqueFiles,
+                confidence: avgConfidence,
+                suggestedName: this.inferSemanticName(uniqueFiles, uniqueFunctions),
+                functions: uniqueFunctions,
+            })
+        }
+
+        return result
+    }
+
+    /** Get the base directory (first meaningful segment) for a set of files */
+    private getBaseDir(files: string[]): string {
+        if (files.length === 0) return 'unknown'
+        // Find common prefix of all file paths
+        const segments = files.map(f => f.split('/'))
+        const first = segments[0]
+        let commonLen = 0
+        for (let i = 0; i < first.length - 1; i++) {
+            if (segments.every(s => s[i] === first[i])) {
+                commonLen = i + 1
+            } else {
+                break
+            }
+        }
+        const common = first.slice(0, commonLen)
+            .filter(d => d !== 'src' && d !== '')
+        // Use the first 2 meaningful path segments as the "base"
+        return common.slice(0, 2).join('/') || first.filter(d => d !== 'src' && d !== '')[0] || 'root'
+    }
+
+    // ─── Semantic Naming ──────────────────────────────────────────
+
+    /**
+     * Produce a human-meaningful module name by analyzing function names
+     * and file basenames. Falls back to title-cased directory name.
+     *
+     * Algorithm:
+     *   1. Collect all words from function labels and file basenames
+     *   2. Score each domain from DOMAIN_KEYWORDS against the word bag
+     *   3. Pick top 1–2 domains above threshold; combine them
+     *   4. If no domain matches, fall back to directory-based name
+     */
+    private inferSemanticName(filePaths: string[], functionIds: string[]): string {
+        // Collect words from function names
+        const fnLabels = functionIds
+            .map(id => this.graph.nodes.get(id)?.label ?? '')
+            .filter(Boolean)
+
+        // Collect file basenames without extension
+        const fileNames = filePaths.map(f => {
+            const basename = f.split('/').pop() || ''
+            return basename.replace(/\.[^.]+$/, '')
+        })
+
+        // Also include directory segments (e.g. "blog" from "features/blog/hooks")
+        const dirNames = filePaths.flatMap(f => {
+            const parts = f.split('/')
+            return parts.slice(0, -1).filter(d => d !== 'src' && d !== '')
+        })
+
+        // Build a lowercased word bag from all sources
+        const wordBag = this.buildWordBag([...fnLabels, ...fileNames, ...dirNames])
+
+        // Score each domain
+        const scores: [string, number][] = []
+        for (const [domain, keywords] of DOMAIN_KEYWORDS) {
+            let score = 0
+            for (const kw of keywords) {
+                for (const word of wordBag) {
+                    // Exact match or word contains keyword (e.g. "hooks" contains "hook")
+                    // Do NOT check kw.includes(word) — too loose ("use" would match "usequery")
+                    if (word === kw || word.includes(kw)) {
+                        score++
+                    }
+                }
+            }
+            if (score > 0) scores.push([domain, score])
+        }
+
+        scores.sort((a, b) => b[1] - a[1])
+
+        if (scores.length >= 2 && scores[0][1] > 1 && scores[1][1] > 1 &&
+            scores[1][1] >= scores[0][1] * 0.5) {
+            // Two strong domains — combine them
+            return `${scores[0][0]} & ${scores[1][0]}`
+        }
+        if (scores.length >= 1 && scores[0][1] > 0) {
+            return scores[0][0]
+        }
+
+        // Fallback: directory-based name
+        return this.inferClusterNameFromDir(filePaths)
     }
 
-    /** Infer a human-readable cluster name */
-    private inferClusterName(filePaths: string[]): string {
+    /** Fallback: infer a human-readable cluster name from directory paths */
+    private inferClusterNameFromDir(filePaths: string[]): string {
         const dir = this.inferClusterId(filePaths)
         return dir
             .replace(/[-_]/g, ' ')
             .replace(/\b\w/g, c => c.toUpperCase())
     }
+
+    /** Split identifiers and file names into lowercase words */
+    private buildWordBag(identifiers: string[]): string[] {
+        const words: string[] = []
+        for (const id of identifiers) {
+            // Split camelCase/PascalCase
+            const split = id
+                .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+                .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+                .split(/[\s_\-\.]+/)
+                .map(w => w.toLowerCase())
+                .filter(w => w.length > 1)
+            words.push(...split)
+        }
+        return words
+    }
 }

package/src/graph/graph-builder.ts

@@ -66,6 +66,8 @@ export class GraphBuilder {
                 isAsync: fn.isAsync,
                 hash: fn.hash,
                 purpose: fn.purpose,
+                params: fn.params?.map(p => ({ name: p.name, type: p.type, ...(p.optional ? { optional: true } : {}) })),
+                returnType: fn.returnType !== 'void' ? fn.returnType : undefined,
                 edgeCasesHandled: fn.edgeCasesHandled,
                 errorHandling: fn.errorHandling,
                 detailedLines: fn.detailedLines,

package/src/graph/types.ts

@@ -19,6 +19,8 @@ export interface GraphNode {
         isAsync?: boolean
         hash?: string
         purpose?: string
+        params?: { name: string; type: string; optional?: boolean }[]
+        returnType?: string
         edgeCasesHandled?: string[]
         errorHandling?: { line: number; type: 'try-catch' | 'throw'; detail: string }[]
         detailedLines?: { startLine: number; endLine: number; blockType: string }[]

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './contract/index.js'
 export * from './hash/index.js'
 export * from './utils/errors.js'
 export * from './utils/logger.js'
-export { discoverFiles, readFileContent, writeFileContent, fileExists, setupMikkDirectory } from './utils/fs.js'
+export { discoverFiles, discoverContextFiles, readFileContent, writeFileContent, fileExists, setupMikkDirectory, readMikkIgnore, parseMikkIgnore, detectProjectLanguage, getDiscoveryPatterns, generateMikkIgnore } from './utils/fs.js'
+export type { ContextFile, ContextFileType, ProjectLanguage } from './utils/fs.js'
 export { minimatch } from './utils/minimatch.js'
 export { scoreFunctions, findFuzzyMatches, levenshtein, splitCamelCase, extractKeywords } from './utils/fuzzy-match.js'

package/src/parser/boundary-checker.ts

@@ -115,7 +115,7 @@ export class BoundaryChecker {
     check(): BoundaryCheckResult {
         const violations: BoundaryViolation[] = []
 
-        // Collect all cross-module calls
+        // Pass 1: Check cross-module function calls
         for (const fn of Object.values(this.lock.functions)) {
             for (const calleeId of fn.calls) {
                 const callee = this.lock.functions[calleeId]
@@ -128,11 +128,24 @@ export class BoundaryChecker {
             }
         }
 
+        // Pass 2: Check cross-module file-level imports
+        for (const file of Object.values(this.lock.files)) {
+            if (!file.imports || file.imports.length === 0) continue
+            for (const importedPath of file.imports) {
+                const importedFile = this.lock.files[importedPath]
+                if (!importedFile) continue
+                if (file.moduleId === importedFile.moduleId) continue // same module — fine
+
+                const violation = this.checkFileImport(file, importedFile)
+                if (violation) violations.push(violation)
+            }
+        }
+
         const errorCount = violations.filter(v => v.severity === 'error').length
         const warnCount = violations.filter(v => v.severity === 'warning').length
 
         const summary = violations.length === 0
-            ? `✓ All module boundaries respected (${Object.keys(this.lock.functions).length} functions checked)`
+            ? `✓ All module boundaries respected (${Object.keys(this.lock.functions).length} functions, ${Object.keys(this.lock.files).length} files checked)`
             : `✗ ${errorCount} boundary error(s), ${warnCount} warning(s) found`
 
         return {
@@ -191,9 +204,56 @@ export class BoundaryChecker {
         return null
     }
 
+    /**
+     * Check a single cross-module file import against parsed rules.
+     * Returns a violation if the import is forbidden, null if it's allowed.
+     */
+    private checkFileImport(
+        sourceFile: { path: string; moduleId: string },
+        targetFile: { path: string; moduleId: string }
+    ): BoundaryViolation | null {
+        for (const rule of this.rules) {
+            if (rule.fromModuleId !== sourceFile.moduleId) continue
+
+            let forbidden = false
+
+            if (rule.type === 'isolated') {
+                forbidden = true
+            } else if (rule.type === 'deny') {
+                forbidden = rule.toModuleIds.includes(targetFile.moduleId)
+            } else if (rule.type === 'allow_only') {
+                forbidden = !rule.toModuleIds.includes(targetFile.moduleId)
+            }
+
+            if (forbidden) {
+                return {
+                    from: {
+                        functionId: `file:${sourceFile.path}`,
+                        functionName: path.basename(sourceFile.path),
+                        file: sourceFile.path,
+                        moduleId: sourceFile.moduleId,
+                        moduleName: this.moduleNames.get(sourceFile.moduleId) ?? sourceFile.moduleId,
+                    },
+                    to: {
+                        functionId: `file:${targetFile.path}`,
+                        functionName: path.basename(targetFile.path),
+                        file: targetFile.path,
+                        moduleId: targetFile.moduleId,
+                        moduleName: this.moduleNames.get(targetFile.moduleId) ?? targetFile.moduleId,
+                    },
+                    rule: rule.raw,
+                    severity: 'error',
+                }
+            }
+        }
+        return null
+    }
+
     /** Return all cross-module call pairs (useful for generating allow rules) */
     allCrossModuleCalls(): { from: string; to: string; count: number }[] {
         const counts = new Map<string, number>()
+
+        // Count function-level cross-module calls
         for (const fn of Object.values(this.lock.functions)) {
             for (const calleeId of fn.calls) {
                 const callee = this.lock.functions[calleeId]
@@ -202,6 +262,18 @@ export class BoundaryChecker {
                 counts.set(key, (counts.get(key) ?? 0) + 1)
             }
         }
+
+        // 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) continue
+                const key = `${file.moduleId}→${importedFile.moduleId}`
+                counts.set(key, (counts.get(key) ?? 0) + 1)
+            }
+        }
+
         return [...counts.entries()]
             .map(([key, count]) => {
                 const [from, to] = key.split('→')

package/src/parser/types.ts

@@ -63,6 +63,16 @@ export interface ParsedClass {
     errorHandling?: { line: number, type: 'try-catch' | 'throw', detail: string }[]
 }
 
+/** A detected HTTP route registration (Express/Koa/Hono style) */
+export interface ParsedRoute {
+    method: string            // "GET", "POST", "PUT", "DELETE", "USE", etc.
+    path: string              // "/upload", "/:shortId", "/api"
+    handler: string           // "createZap" or "anonymous"
+    middlewares: string[]     // ["uploadLimiter", "upload.single"]
+    file: string              // "src/Routes/zap.routes.ts"
+    line: number              // 15
+}
+
 /** A generic declaration like interface, type, or constant with metadata */
 export interface ParsedGeneric {
     id: string
@@ -85,6 +95,7 @@ export interface ParsedFile {
     generics: ParsedGeneric[]
     imports: ParsedImport[]
     exports: ParsedExport[]
+    routes: ParsedRoute[]    // Detected HTTP route registrations
     hash: string            // SHA-256 of the entire file content
     parsedAt: number        // Date.now()
 }