@getmikk/core 1.5.1 → 1.6.0

package/src/parser/go/go-parser.ts

@@ -0,0 +1,41 @@
+import { BaseParser } from '../base-parser.js'
+import { GoExtractor } from './go-extractor.js'
+import { GoResolver } from './go-resolver.js'
+import { hashContent } from '../../hash/file-hasher.js'
+import type { ParsedFile } from '../types.js'
+
+/**
+ * GoParser — implements BaseParser for .go files.
+ * Uses GoExtractor (regex-based) to pull structured data from Go source
+ * without requiring the Go toolchain.
+ */
+export class GoParser extends BaseParser {
+    parse(filePath: string, content: string): ParsedFile {
+        const extractor = new GoExtractor(filePath, content)
+
+        return {
+            path: filePath,
+            language: 'go',
+            functions: extractor.extractFunctions(),
+            classes: extractor.extractClasses(),
+            generics: [], // Go type aliases handled as classes/exports
+            imports: extractor.extractImports(),
+            exports: extractor.extractExports(),
+            routes: extractor.extractRoutes(),
+            hash: hashContent(content),
+            parsedAt: Date.now(),
+        }
+    }
+
+    resolveImports(files: ParsedFile[], projectRoot: string): ParsedFile[] {
+        const resolver = new GoResolver(projectRoot)
+        return files.map(file => ({
+            ...file,
+            imports: resolver.resolveAll(file.imports),
+        }))
+    }
+
+    getSupportedExtensions(): string[] {
+        return ['.go']
+    }
+}

package/src/parser/go/go-resolver.ts

@@ -0,0 +1,70 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import type { ParsedImport } from '../types.js'
+
+/**
+ * GoResolver — resolves Go import paths to project-relative file paths.
+ *
+ * Go import paths follow the module path declared in go.mod:
+ *   module github.com/user/project
+ *
+ * An import "github.com/user/project/internal/auth" resolves to
+ * the directory internal/auth/ relative to the project root.
+ *
+ * Third-party imports (not matching the module path) are left unresolved.
+ */
+export class GoResolver {
+    private modulePath: string
+
+    constructor(private readonly projectRoot: string) {
+        this.modulePath = readModulePath(projectRoot)
+    }
+
+    /** Resolve a list of imports for a single file */
+    resolveAll(imports: ParsedImport[]): ParsedImport[] {
+        return imports.map(imp => this.resolve(imp))
+    }
+
+    private resolve(imp: ParsedImport): ParsedImport {
+        const src = imp.source
+
+        // Third-party (doesn't start with our module path) → leave as-is
+        if (this.modulePath && !src.startsWith(this.modulePath)) {
+            return { ...imp, resolvedPath: '' }
+        }
+
+        // Internal import: strip module path prefix, map to relative dir
+        const relPath = this.modulePath
+            ? src.slice(this.modulePath.length).replace(/^\//, '')
+            : src
+
+        // Try to find the entry file in the directory
+        const dirPath = relPath.replace(/\//g, path.sep)
+        const candidates = [
+            path.join(dirPath, path.basename(dirPath) + '.go'),
+            path.join(dirPath, 'index.go'),
+            dirPath + '.go',
+        ]
+
+        for (const candidate of candidates) {
+            if (fs.existsSync(path.join(this.projectRoot, candidate))) {
+                return { ...imp, resolvedPath: candidate.replace(/\\/g, '/') }
+            }
+        }
+
+        // Fallback: point to directory (graph builder handles directories separately)
+        return { ...imp, resolvedPath: relPath.replace(/\\/g, '/') }
+    }
+}
+
+/** Read module path from go.mod (e.g. "module github.com/user/myapp") */
+function readModulePath(projectRoot: string): string {
+    const goModPath = path.join(projectRoot, 'go.mod')
+    try {
+        const content = fs.readFileSync(goModPath, 'utf-8')
+        const m = /^module\s+(\S+)/m.exec(content)
+        return m ? m[1] : ''
+    } catch {
+        return ''
+    }
+}

package/src/parser/index.ts

@@ -1,6 +1,7 @@
 import * as path from 'node:path'
 import { BaseParser } from './base-parser.js'
 import { TypeScriptParser } from './typescript/ts-parser.js'
+import { GoParser } from './go/go-parser.js'
 import { UnsupportedLanguageError } from '../utils/errors.js'
 import type { ParsedFile } from './types.js'
 
@@ -9,6 +10,9 @@ export { BaseParser } from './base-parser.js'
 export { TypeScriptParser } from './typescript/ts-parser.js'
 export { TypeScriptExtractor } from './typescript/ts-extractor.js'
 export { TypeScriptResolver } from './typescript/ts-resolver.js'
+export { GoParser } from './go/go-parser.js'
+export { GoExtractor } from './go/go-extractor.js'
+export { GoResolver } from './go/go-resolver.js'
 export { BoundaryChecker } from './boundary-checker.js'
 
 /** Get the appropriate parser for a file based on its extension */
@@ -18,6 +22,8 @@ export function getParser(filePath: string): BaseParser {
         case '.ts':
         case '.tsx':
             return new TypeScriptParser()
+        case '.go':
+            return new GoParser()
         default:
             throw new UnsupportedLanguageError(ext)
     }
@@ -30,17 +36,32 @@ export async function parseFiles(
     readFile: (fp: string) => Promise<string>
 ): Promise<ParsedFile[]> {
     const tsParser = new TypeScriptParser()
-    const files: ParsedFile[] = []
+    const goParser = new GoParser()
+    const tsFiles: ParsedFile[] = []
+    const goFiles: ParsedFile[] = []
 
     for (const fp of filePaths) {
         const ext = path.extname(fp)
         if (ext === '.ts' || ext === '.tsx') {
-            const content = await readFile(path.join(projectRoot, fp))
-            const parsed = tsParser.parse(fp, content)
-            files.push(parsed)
+            try {
+                const content = await readFile(path.join(projectRoot, fp))
+                tsFiles.push(tsParser.parse(fp, content))
+            } catch {
+                // Skip unreadable files (permissions, binary, etc.) — don't abort the whole parse
+            }
+        } else if (ext === '.go') {
+            try {
+                const content = await readFile(path.join(projectRoot, fp))
+                goFiles.push(goParser.parse(fp, content))
+            } catch {
+                // Skip unreadable files
+            }
         }
     }
 
-    // Resolve all imports after all files are parsed
-    return tsParser.resolveImports(files, projectRoot)
+    // Resolve imports per language after all files of that language are parsed
+    const resolvedTs = tsParser.resolveImports(tsFiles, projectRoot)
+    const resolvedGo = goParser.resolveImports(goFiles, projectRoot)
+
+    return [...resolvedTs, ...resolvedGo]
 }

package/src/parser/types.ts

@@ -89,7 +89,7 @@ export interface ParsedGeneric {
 /** Everything extracted from a single file */
 export interface ParsedFile {
     path: string            // "src/auth/verify.ts"
-    language: 'typescript' | 'python'
+    language: 'typescript' | 'python' | 'go'
     functions: ParsedFunction[]
     classes: ParsedClass[]
     generics: ParsedGeneric[]

package/src/parser/typescript/ts-extractor.ts

@@ -530,31 +530,53 @@ export class TypeScriptExtractor {
         return [...new Set(calls)] // deduplicate
     }
 
-    /** Extract the purpose from JSDoc comments or preceding single-line comments */
+    /** Extract the purpose from JSDoc comments or preceding single-line comments.
+     *  Falls back to deriving a human-readable sentence from the function name. */
     private extractPurpose(node: ts.Node): string {
         const fullText = this.sourceFile.getFullText()
         const commentRanges = ts.getLeadingCommentRanges(fullText, node.getFullStart())
-        if (!commentRanges || commentRanges.length === 0) return ''
-
-        const meaningfulLines: string[] = []
-        for (const range of commentRanges) {
-            const comment = fullText.slice(range.pos, range.end)
-            let clean = ''
-            if (comment.startsWith('/**') || comment.startsWith('/*')) {
-                clean = comment.replace(/[\/\*]/g, '').trim()
-            } else if (comment.startsWith('//')) {
-                clean = comment.replace(/\/\//g, '').trim()
-            }
+        if (commentRanges && commentRanges.length > 0) {
+            const meaningfulLines: string[] = []
+            for (const range of commentRanges) {
+                const comment = fullText.slice(range.pos, range.end)
+                let clean = ''
+                if (comment.startsWith('/**') || comment.startsWith('/*')) {
+                    clean = comment.replace(/[\/\*]/g, '').trim()
+                } else if (comment.startsWith('//')) {
+                    clean = comment.replace(/\/\//g, '').trim()
+                }
 
-            // Skip divider lines (lines with 3+ repeated special characters)
-            if (/^[─\-_=\*]{3,}$/.test(clean)) continue
+                // Skip divider lines (lines with 3+ repeated special characters)
+                if (/^[─\-_=\*]{3,}$/.test(clean)) continue
+
+                if (clean) meaningfulLines.push(clean)
+            }
 
-            if (clean) meaningfulLines.push(clean)
+            // Return the first meaningful line — in JSDoc, the first line is the summary.
+            const fromComment = meaningfulLines.length > 0 ? meaningfulLines[0].split('\n')[0].trim() : ''
+            if (fromComment) return fromComment
         }
 
-        // Return the first meaningful line — in JSDoc, the first line is the summary.
-        // e.g. "Decrypt data using AES-256-GCM" (not a later detail line)
-        return meaningfulLines.length > 0 ? meaningfulLines[0].split('\n')[0].trim() : ''
+        // Fallback: derive a human-readable sentence from the function/identifier name
+        const name = this.getNodeName(node)
+        return name ? derivePurposeFromName(name) : ''
+    }
+
+    /** Get the identifier name from common declaration node types */
+    private getNodeName(node: ts.Node): string {
+        if (ts.isFunctionDeclaration(node) && node.name) return node.name.text
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+            const parent = node.parent
+            if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+                return parent.name.text
+            }
+        }
+        if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name)) return node.name.text
+        if (ts.isConstructorDeclaration(node)) return 'constructor'
+        if ((ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
+            return (node as any).name.text
+        }
+        return ''
     }
 
     /** Extract edge cases handled (if statements returning early) */
@@ -679,3 +701,28 @@ export class TypeScriptExtractor {
         })
     }
 }
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Derive a human-readable purpose sentence from a camelCase/PascalCase identifier.
+ * Examples:
+ *   validateJwtToken   → "Validate jwt token"
+ *   buildGraphFromLock → "Build graph from lock"
+ *   UserRepository     → "User repository"
+ *   parseFiles         → "Parse files"
+ */
+function derivePurposeFromName(name: string): string {
+    if (!name || name === 'constructor') return ''
+    // Split on camelCase/PascalCase boundaries and underscores
+    const words = name
+        .replace(/_+/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+    if (words.length === 0) return ''
+    words[0] = words[0].charAt(0).toUpperCase() + words[0].slice(1)
+    return words.join(' ')
+}

package/src/parser/typescript/ts-parser.ts

@@ -1,3 +1,5 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs'
 import { BaseParser } from '../base-parser.js'
 import { TypeScriptExtractor } from './ts-extractor.js'
 import { TypeScriptResolver } from './ts-resolver.js'
@@ -54,7 +56,8 @@ export class TypeScriptParser extends BaseParser {
 
     /** Resolve all import paths in parsed files to absolute project paths */
     resolveImports(files: ParsedFile[], projectRoot: string): ParsedFile[] {
-        const resolver = new TypeScriptResolver(projectRoot)
+        const tsConfigPaths = loadTsConfigPaths(projectRoot)
+        const resolver = new TypeScriptResolver(projectRoot, tsConfigPaths)
         const allFilePaths = files.map(f => f.path)
         return files.map(file => ({
             ...file,
@@ -66,3 +69,40 @@ export class TypeScriptParser extends BaseParser {
         return ['.ts', '.tsx']
     }
 }
+
+/**
+ * Read compilerOptions.paths from the nearest tsconfig.json in projectRoot.
+ * Handles baseUrl prefix so aliases like "@/*" → ["src/*"] resolve correctly.
+ */
+function loadTsConfigPaths(projectRoot: string): Record<string, string[]> {
+    const candidates = ['tsconfig.json', 'tsconfig.base.json']
+    for (const name of candidates) {
+        const tsConfigPath = path.join(projectRoot, name)
+        try {
+            const raw = fs.readFileSync(tsConfigPath, 'utf-8')
+            // Strip line comments before JSON.parse (tsconfig allows them)
+            const stripped = raw.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '')
+            let tsConfig: any
+            try {
+                tsConfig = JSON.parse(stripped)
+            } catch {
+                // Stripping may have broken a URL (e.g. "https://...") — fall back to raw
+                tsConfig = JSON.parse(raw)
+            }
+            const options = tsConfig.compilerOptions ?? {}
+            const rawPaths: Record<string, string[]> = options.paths ?? {}
+            if (Object.keys(rawPaths).length === 0) continue
+
+            const baseUrl: string = options.baseUrl ?? '.'
+            // Prefix each target with baseUrl so relative resolution works
+            const resolved: Record<string, string[]> = {}
+            for (const [alias, targets] of Object.entries(rawPaths)) {
+                resolved[alias] = (targets as string[]).map(t =>
+                    t.startsWith('.') ? path.posix.join(baseUrl, t) : t
+                )
+            }
+            return resolved
+        } catch { /* tsconfig not found or invalid — continue */ }
+    }
+    return {}
+}

package/tests/adr-manager.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'bun:test'
+import { AdrManager } from '../src/contract/adr-manager'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+
+describe('AdrManager', () => {
+    const TEMP_DIR = path.join(process.cwd(), '.test-temp')
+    const CONTRACT_PATH = path.join(TEMP_DIR, 'mikk.json')
+
+    beforeAll(async () => {
+        await fs.mkdir(TEMP_DIR, { recursive: true })
+    })
+
+    afterAll(async () => {
+        await fs.rm(TEMP_DIR, { recursive: true, force: true })
+    })
+
+    beforeEach(async () => {
+        // Create a fresh mikk.json for each test
+        const initialContract = {
+            version: '1.0.0',
+            project: { name: 'test', description: 'test', language: 'ts', entryPoints: [] },
+            declared: {
+                modules: [],
+                decisions: [
+                    { id: 'ADR-1', title: 'First ADR', reason: 'Because', date: '2024-01-01' }
+                ]
+            },
+            overwrite: { mode: 'never' as const }
+        }
+        await fs.writeFile(CONTRACT_PATH, JSON.stringify(initialContract))
+    })
+
+    it('lists decisions', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        const decisions = await manager.list()
+        expect(decisions).toHaveLength(1)
+        expect(decisions[0].id).toBe('ADR-1')
+    })
+
+    it('gets a decision by id', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        const decision = await manager.get('ADR-1')
+        expect(decision?.title).toBe('First ADR')
+
+        const missing = await manager.get('NOT-FOUND')
+        expect(missing).toBeNull()
+    })
+
+    it('adds a new decision', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        await manager.add({
+            id: 'ADR-2',
+            title: 'Second ADR',
+            reason: 'Why not',
+            date: '2024-01-02'
+        })
+
+        const decisions = await manager.list()
+        expect(decisions).toHaveLength(2)
+        expect(decisions[1].id).toBe('ADR-2')
+    })
+
+    it('fails to add if id already exists', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        await expect(manager.add({
+            id: 'ADR-1',
+            title: 'Duplicate',
+            reason: 'Will fail',
+            date: '2024-01-03'
+        })).rejects.toThrow(/already exists/)
+    })
+
+    it('updates an existing decision', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        await manager.update('ADR-1', { title: 'Updated Title' })
+
+        const decision = await manager.get('ADR-1')
+        expect(decision?.title).toBe('Updated Title')
+        expect(decision?.reason).toBe('Because') // Preserved
+        expect(decision?.id).toBe('ADR-1')
+    })
+
+    it('fails to update missing decision', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        await expect(manager.update('ADR-99', { title: 'Nope' })).rejects.toThrow(/not found/)
+    })
+
+    it('removes a decision', async () => {
+        const manager = new AdrManager(CONTRACT_PATH)
+        const success = await manager.remove('ADR-1')
+        expect(success).toBe(true)
+
+        const decisions = await manager.list()
+        expect(decisions).toHaveLength(0)
+    })
+})

package/tests/dead-code.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'bun:test'
+import { DeadCodeDetector } from '../src/graph/dead-code-detector'
+import { buildTestGraph, mockFunction } from './helpers'
+import { GraphBuilder } from '../src/graph/graph-builder'
+import type { MikkLock } from '../src/contract/schema'
+
+/** Helper to generate a dummy lock file from graph nodes for the detector */
+function generateDummyLock(graphNodes: Map<string, any>): MikkLock {
+    const lock: MikkLock = {
+        version: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        generatorVersion: '1.0.0',
+        projectRoot: '/test',
+        syncState: {
+            status: 'clean',
+            lastSyncAt: new Date().toISOString(),
+            lockHash: 'x',
+            contractHash: 'x',
+        },
+        graph: {
+            nodes: 0,
+            edges: 0,
+            rootHash: 'x',
+        },
+        functions: {},
+        classes: {},
+        files: {},
+        modules: {},
+        routes: [],
+    }
+
+    for (const [id, node] of graphNodes.entries()) {
+        if (node.type === 'function') {
+            const name = node.label
+            const file = node.file
+            // We need to populate `calledBy` for transitive liveness checks
+
+            lock.functions[id] = {
+                id,
+                name,
+                file,
+                moduleId: node.moduleId ?? 'unknown',
+                startLine: 1, endLine: 10, hash: 'x',
+                calls: [],
+                calledBy: [],
+                isExported: node.metadata?.isExported ?? false,
+                isAsync: false,
+                params: [],
+            }
+        }
+    }
+    return lock
+}
+
+describe('DeadCodeDetector', () => {
+
+    it('detects uncalled functions', () => {
+        // A calls B. C is isolated.
+        const graph = buildTestGraph([
+            ['A', 'B'],
+            ['B', 'nothing'],
+            ['C', 'nothing']
+        ])
+
+        const lock = generateDummyLock(graph.nodes)
+
+        // Add calledBy relationships since GraphBuilder test helper doesn't do reverse 
+        // lookups for the lock structure (it only does it for the graph)
+        Object.values(lock.functions).forEach(fn => {
+            const inEdges = graph.inEdges.get(fn.id) ?? []
+            fn.calledBy = inEdges.filter(e => e.type === 'calls').map(e => e.source)
+        })
+
+        const detector = new DeadCodeDetector(graph, lock)
+        const result = detector.detect()
+
+        expect(result.deadFunctions.map(f => f.name)).toContain('C')
+        expect(result.deadFunctions.map(f => f.name)).toContain('A') // A has no callers, so it is dead code
+        expect(result.deadFunctions.map(f => f.name)).not.toContain('B') // B has a caller
+    })
+
+    it('exempts exported functions', () => {
+        const graph = buildTestGraph([
+            ['D', 'nothing']
+        ])
+        graph.nodes.get('fn:src/D.ts:D')!.metadata!.isExported = true
+
+        const lock = generateDummyLock(graph.nodes)
+
+        const detector = new DeadCodeDetector(graph, lock)
+        const result = detector.detect()
+
+        expect(result.deadFunctions).toHaveLength(0) // D is exported
+    })
+
+    it('exempts entry point name patterns', () => {
+        const graph = buildTestGraph([
+            ['main', 'nothing'],
+            ['loginHandler', 'nothing'],
+            ['useAuth', 'nothing'] // React hook
+        ])
+
+        const lock = generateDummyLock(graph.nodes)
+
+        const detector = new DeadCodeDetector(graph, lock)
+        const result = detector.detect()
+
+        expect(result.deadFunctions).toHaveLength(0) // All match exempt patterns
+    })
+
+    it('exempts functions called by exported functions in the same file', () => {
+        const graph = buildTestGraph([
+            ['ExportedFn', 'InternalHelper'],
+            ['InternalHelper', 'nothing']
+        ])
+
+        // Both in same file by default from buildTestGraph
+        graph.nodes.get('fn:src/ExportedFn.ts:ExportedFn')!.metadata!.isExported = true
+
+        // In the lock, we must place them in the SAME file manually because buildTestGraph 
+        // puts them in separate files based on name
+        const lock = generateDummyLock(graph.nodes)
+        lock.functions['fn:src/ExportedFn.ts:ExportedFn'].file = 'src/shared.ts'
+        lock.functions['fn:src/InternalHelper.ts:InternalHelper'].file = 'src/shared.ts'
+
+        // Set up the calledBy relation
+        lock.functions['fn:src/InternalHelper.ts:InternalHelper'].calledBy = ['fn:src/ExportedFn.ts:ExportedFn']
+
+        const detector = new DeadCodeDetector(graph, lock)
+        const result = detector.detect()
+
+        expect(result.deadFunctions).toHaveLength(0) // InternalHelper is called by exported fn in same file
+    })
+})