@getmikk/ai-context 1.2.0

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "@getmikk/ai-context",
+    "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:*",
+        "@getmikk/intent-engine": "workspace:*"
+    },
+    "devDependencies": {
+        "typescript": "^5.7.0",
+        "@types/node": "^22.0.0"
+    }
+}

package/src/claude-md-generator.ts

@@ -0,0 +1,265 @@
+import type { MikkContract, MikkLock, MikkLockFunction } from '@getmikk/core'
+
+/** Default token budget for claude.md — prevents bloating the context window */
+const DEFAULT_TOKEN_BUDGET = 6000
+
+/** Rough token estimation: ~4 chars per token */
+function estimateTokens(text: string): number {
+    return Math.ceil(text.length / 4)
+}
+
+/**
+ * ClaudeMdGenerator — generates an always-accurate `claude.md` and `AGENTS.md`
+ * from the lock file and contract. Every function name, file path, and module
+ * relationship is sourced from the AST-derived lock file — never hand-authored.
+ *
+ * Tiered system per spec:
+ *  Tier 1: Summary (~500 tokens) — always included
+ *  Tier 2: Module details (~300 tokens/module) — included if budget allows
+ *  Tier 3: Recent changes (~50 tokens/change) — last section added
+ */
+export class ClaudeMdGenerator {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock,
+        private tokenBudget: number = DEFAULT_TOKEN_BUDGET
+    ) { }
+
+    /** Generate the full claude.md content */
+    generate(): string {
+        const sections: string[] = []
+        let usedTokens = 0
+
+        // ── Tier 1: Summary (always included) ──────────────────────
+        const summary = this.generateSummary()
+        sections.push(summary)
+        usedTokens += estimateTokens(summary)
+
+        // ── Tier 2: Module details (if budget allows) ──────────────
+        const modules = this.getModulesSortedByDependencyOrder()
+        for (const module of modules) {
+            const moduleSection = this.generateModuleSection(module.id)
+            const tokens = estimateTokens(moduleSection)
+            if (usedTokens + tokens > this.tokenBudget) {
+                sections.push('\n> Full details available in `mikk.lock.json`\n')
+                break
+            }
+            sections.push(moduleSection)
+            usedTokens += tokens
+        }
+
+        // ── Tier 3: Constraints & decisions ────────────────────────
+        const constraintsSection = this.generateConstraintsSection()
+        const constraintTokens = estimateTokens(constraintsSection)
+        if (usedTokens + constraintTokens <= this.tokenBudget) {
+            sections.push(constraintsSection)
+            usedTokens += constraintTokens
+        }
+
+        const decisionsSection = this.generateDecisionsSection()
+        const decisionTokens = estimateTokens(decisionsSection)
+        if (usedTokens + decisionTokens <= this.tokenBudget) {
+            sections.push(decisionsSection)
+            usedTokens += decisionTokens
+        }
+
+        return sections.join('\n')
+    }
+
+    // ── Tier 1: Summary ───────────────────────────────────────────
+
+    private generateSummary(): string {
+        const lines: string[] = []
+        const moduleCount = this.contract.declared.modules.length
+        const functionCount = Object.keys(this.lock.functions).length
+        const fileCount = Object.keys(this.lock.files).length
+
+        lines.push(`# ${this.contract.project.name} — Architecture Overview`)
+        lines.push('')
+
+        if (this.contract.project.description) {
+            lines.push('## What this project does')
+            lines.push(this.contract.project.description)
+            lines.push('')
+        }
+
+        lines.push('## Modules')
+        for (const module of this.contract.declared.modules) {
+            const fnCount = Object.values(this.lock.functions)
+                .filter(f => f.moduleId === module.id).length
+            const desc = module.intent || module.description || ''
+            const descStr = desc ? ` — ${desc}` : ''
+            lines.push(`- **${module.name}** (\`${module.id}\`): ${fnCount} functions${descStr}`)
+        }
+        lines.push('')
+
+        lines.push(`## Stats`)
+        lines.push(`- ${fileCount} files, ${functionCount} functions, ${moduleCount} modules`)
+        lines.push(`- Language: ${this.contract.project.language}`)
+        lines.push('')
+
+        // Critical constraints summary
+        if (this.contract.declared.constraints.length > 0) {
+            lines.push('## Critical Constraints')
+            for (const c of this.contract.declared.constraints) {
+                lines.push(`- ${c}`)
+            }
+            lines.push('')
+        }
+
+        return lines.join('\n')
+    }
+
+    // ── Tier 2: Module Details ────────────────────────────────────
+
+    private generateModuleSection(moduleId: string): string {
+        const module = this.contract.declared.modules.find(m => m.id === moduleId)
+        if (!module) return ''
+
+        const lines: string[] = []
+        const moduleFunctions = Object.values(this.lock.functions)
+            .filter(f => f.moduleId === moduleId)
+
+        lines.push(`## ${module.name} module`)
+
+        // Location
+        if (module.paths.length > 0) {
+            lines.push(`**Location:** ${module.paths.join(', ')}`)
+        }
+
+        // Intent
+        if (module.intent) {
+            lines.push(`**Purpose:** ${module.intent}`)
+        } else if (module.description) {
+            lines.push(`**Purpose:** ${module.description}`)
+        }
+
+        lines.push('')
+
+        // Entry points: functions with no calledBy (likely public API surface)
+        const entryPoints = moduleFunctions
+            .filter(fn => fn.calledBy.length === 0)
+            .sort((a, b) => b.calls.length - a.calls.length)
+            .slice(0, 5)
+
+        if (entryPoints.length > 0) {
+            lines.push('**Entry points:**')
+            for (const fn of entryPoints) {
+                const sig = this.formatSignature(fn)
+                const purpose = fn.purpose ? ` — ${fn.purpose}` : ''
+                lines.push(`  - \`${sig}\`${purpose}`)
+            }
+            lines.push('')
+        }
+
+        // Key functions: top 5 by calledBy count (most depended upon)
+        const keyFunctions = [...moduleFunctions]
+            .sort((a, b) => b.calledBy.length - a.calledBy.length)
+            .filter(fn => fn.calledBy.length > 0)
+            .slice(0, 5)
+
+        if (keyFunctions.length > 0) {
+            lines.push('**Key internal functions:**')
+            for (const fn of keyFunctions) {
+                const callerCount = fn.calledBy.length
+                const purpose = fn.purpose ? ` — ${fn.purpose}` : ''
+                lines.push(`  - \`${fn.name}\` (called by ${callerCount})${purpose}`)
+            }
+            lines.push('')
+        }
+
+        // Dependencies: other modules this module imports from
+        const depModuleIds = new Set<string>()
+        for (const fn of moduleFunctions) {
+            for (const callId of fn.calls) {
+                const target = this.lock.functions[callId]
+                if (target && target.moduleId !== moduleId) {
+                    depModuleIds.add(target.moduleId)
+                }
+            }
+        }
+
+        if (depModuleIds.size > 0) {
+            const depNames = [...depModuleIds].map(id => {
+                const mod = this.contract.declared.modules.find(m => m.id === id)
+                return mod?.name || id
+            })
+            lines.push(`**Depends on:** ${depNames.join(', ')}`)
+            lines.push('')
+        }
+
+        // Module-specific constraints
+        const moduleConstraints = this.contract.declared.constraints.filter(c =>
+            c.toLowerCase().includes(moduleId.toLowerCase()) ||
+            c.toLowerCase().includes(module.name.toLowerCase())
+        )
+        if (moduleConstraints.length > 0) {
+            lines.push('**Constraints:**')
+            for (const c of moduleConstraints) {
+                lines.push(`  - ${c}`)
+            }
+            lines.push('')
+        }
+
+        return lines.join('\n')
+    }
+
+    // ── Tier 3: Constraints & Decisions ───────────────────────────
+
+    private generateConstraintsSection(): string {
+        if (this.contract.declared.constraints.length === 0) return ''
+        const lines: string[] = []
+        lines.push('## Cross-Cutting Constraints')
+        for (const c of this.contract.declared.constraints) {
+            lines.push(`- ${c}`)
+        }
+        lines.push('')
+        return lines.join('\n')
+    }
+
+    private generateDecisionsSection(): string {
+        if (this.contract.declared.decisions.length === 0) return ''
+        const lines: string[] = []
+        lines.push('## Architectural Decisions')
+        for (const d of this.contract.declared.decisions) {
+            lines.push(`- **${d.title}:** ${d.reason}`)
+        }
+        lines.push('')
+        return lines.join('\n')
+    }
+
+    // ── Helpers ───────────────────────────────────────────────────
+
+    /** Format a function into a readable signature */
+    private formatSignature(fn: MikkLockFunction): string {
+        return `${fn.name}() [${fn.file}:${fn.startLine}]`
+    }
+
+    /** Sort modules by inter-module dependency order (depended-on modules first) */
+    private getModulesSortedByDependencyOrder(): typeof this.contract.declared.modules {
+        const modules = [...this.contract.declared.modules]
+        const dependencyCount = new Map<string, number>()
+
+        for (const mod of modules) {
+            dependencyCount.set(mod.id, 0)
+        }
+
+        // Count how many other modules depend on each module
+        for (const fn of Object.values(this.lock.functions)) {
+            for (const callId of fn.calls) {
+                const target = this.lock.functions[callId]
+                if (target && target.moduleId !== fn.moduleId) {
+                    dependencyCount.set(
+                        target.moduleId,
+                        (dependencyCount.get(target.moduleId) || 0) + 1
+                    )
+                }
+            }
+        }
+
+        // Sort: most depended-on first
+        return modules.sort((a, b) =>
+            (dependencyCount.get(b.id) || 0) - (dependencyCount.get(a.id) || 0)
+        )
+    }
+}

package/src/context-builder.ts

@@ -0,0 +1,399 @@
+import type { MikkContract, MikkLock, MikkLockFunction } from '@getmikk/core'
+import type { AIContext, ContextQuery, ContextModule, ContextFunction } from './types.js'
+
+// ---------------------------------------------------------------------------
+// Scoring weights — tune these to adjust what "relevant" means
+// ---------------------------------------------------------------------------
+const WEIGHT = {
+    // Call-graph proximity (closer = more relevant)
+    DIRECT_CALL: 1.00,   // fn directly calls or is called by focus node
+    HOP_2: 0.60,   // 2 hops away
+    HOP_3: 0.35,
+    HOP_4: 0.15,
+    // Name/keyword match
+    KEYWORD_EXACT: 0.90,   // function name exactly matches a task keyword
+    KEYWORD_PARTIAL: 0.45,   // function name contains a task keyword
+    // Entry-point bonus — functions nothing calls deserve attention
+    ENTRY_POINT: 0.20,
+    // Exported function bonus
+    EXPORTED: 0.10,
+}
+
+// Default token budget per context payload
+const DEFAULT_TOKEN_BUDGET = 6000
+
+/**
+ * Rough token estimator: 1 token ≈ 4 chars for code/identifiers
+ */
+function estimateTokens(text: string): number {
+    return Math.ceil(text.length / 4)
+}
+
+// ---------------------------------------------------------------------------
+// Graph traversal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * BFS from a set of seed node IDs, walking BOTH upstream and downstream
+ * edges up to `maxDepth` hops. Returns a Map<nodeId, depth>.
+ */
+function bfsNeighbors(
+    seeds: string[],
+    functions: Record<string, MikkLockFunction>,
+    maxDepth: number
+): Map<string, number> {
+    const visited = new Map<string, number>()
+    const queue: { id: string; depth: number }[] = seeds.map(id => ({ id, depth: 0 }))
+
+    while (queue.length > 0) {
+        const { id, depth } = queue.shift()!
+        if (visited.has(id)) continue
+        visited.set(id, depth)
+        if (depth >= maxDepth) continue
+
+        const fn = functions[id]
+        if (!fn) continue
+
+        // Walk downstream (what this fn calls)
+        for (const callee of fn.calls) {
+            if (!visited.has(callee)) {
+                queue.push({ id: callee, depth: depth + 1 })
+            }
+        }
+        // Walk upstream (what calls this fn)
+        for (const caller of fn.calledBy) {
+            if (!visited.has(caller)) {
+                queue.push({ id: caller, depth: depth + 1 })
+            }
+        }
+    }
+
+    return visited
+}
+
+/**
+ * Convert a depth value to a relevance score using the WEIGHT table.
+ */
+function depthToScore(depth: number): number {
+    switch (depth) {
+        case 0: return 1.0
+        case 1: return WEIGHT.DIRECT_CALL
+        case 2: return WEIGHT.HOP_2
+        case 3: return WEIGHT.HOP_3
+        default: return WEIGHT.HOP_4
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Keyword extraction — pull meaningful tokens from the task string
+// ---------------------------------------------------------------------------
+
+const STOP_WORDS = new Set([
+    'a', 'an', 'the', 'and', 'or', 'for', 'in', 'on', 'of', 'to',
+    'how', 'does', 'do', 'is', 'are', 'add', 'new', 'create', 'make',
+    'update', 'fix', 'get', 'set', 'this', 'that', 'with', 'from',
+    'what', 'where', 'when', 'why', 'should', 'can', 'will', 'need',
+    'want', 'like', 'just', 'also', 'some', 'all', 'any', 'my', 'your',
+])
+
+function extractKeywords(task: string): string[] {
+    return task
+        .toLowerCase()
+        .replace(/[^a-z0-9\s_-]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length > 2 && !STOP_WORDS.has(w))
+}
+
+/**
+ * Keyword score for a function: exact match > partial match
+ */
+function keywordScore(fn: MikkLockFunction, keywords: string[]): number {
+    if (keywords.length === 0) return 0
+    const nameLower = fn.name.toLowerCase()
+    const fileLower = fn.file.toLowerCase()
+    let score = 0
+
+    for (const kw of keywords) {
+        if (nameLower === kw) {
+            score = Math.max(score, WEIGHT.KEYWORD_EXACT)
+        } else if (nameLower.includes(kw) || fileLower.includes(kw)) {
+            score = Math.max(score, WEIGHT.KEYWORD_PARTIAL)
+        }
+    }
+    return score
+}
+
+// ---------------------------------------------------------------------------
+// Seed resolution — find the best starting nodes for graph traversal
+// ---------------------------------------------------------------------------
+
+/**
+ * Find seed function IDs from focusFiles, focusModules, or task keywords.
+ * Seeds are the "center of gravity" for the BFS walk.
+ */
+function resolveSeeds(
+    query: ContextQuery,
+    contract: MikkContract,
+    lock: MikkLock
+): string[] {
+    const seeds = new Set<string>()
+
+    // 1. Explicit focus files → all functions in those files
+    if (query.focusFiles && query.focusFiles.length > 0) {
+        for (const filePath of query.focusFiles) {
+            for (const fn of Object.values(lock.functions)) {
+                if (fn.file.includes(filePath) || filePath.includes(fn.file)) {
+                    seeds.add(fn.id)
+                }
+            }
+        }
+    }
+
+    // 2. Explicit focus modules → all functions in those modules
+    if (query.focusModules && query.focusModules.length > 0) {
+        for (const modId of query.focusModules) {
+            for (const fn of Object.values(lock.functions)) {
+                if (fn.moduleId === modId) seeds.add(fn.id)
+            }
+        }
+    }
+
+    // 3. Keyword match against function names and file paths
+    if (seeds.size === 0) {
+        const keywords = extractKeywords(query.task)
+        for (const fn of Object.values(lock.functions)) {
+            if (keywordScore(fn, keywords) >= WEIGHT.KEYWORD_PARTIAL) {
+                seeds.add(fn.id)
+            }
+        }
+    }
+
+    // 4. Module name match against task
+    if (seeds.size === 0) {
+        const taskLower = query.task.toLowerCase()
+        for (const mod of contract.declared.modules) {
+            if (
+                taskLower.includes(mod.id.toLowerCase()) ||
+                taskLower.includes(mod.name.toLowerCase())
+            ) {
+                for (const fn of Object.values(lock.functions)) {
+                    if (fn.moduleId === mod.id) seeds.add(fn.id)
+                }
+            }
+        }
+    }
+
+    return [...seeds]
+}
+
+// ---------------------------------------------------------------------------
+// Main ContextBuilder
+// ---------------------------------------------------------------------------
+
+export class ContextBuilder {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock
+    ) { }
+
+    /**
+     * Build AI context for a given query.
+     *
+     * Algorithm:
+     * 1. Resolve seed nodes from focusFiles / focusModules / keyword match
+     * 2. BFS outward up to maxHops, collecting proximity scores
+     * 3. Add keyword scores on top
+     * 4. Sort all functions by total score, descending
+     * 5. Fill a token budget greedily — highest-scored functions first
+     * 6. Group survivors by module, emit structured context
+     */
+    build(query: ContextQuery): AIContext {
+        const tokenBudget = query.tokenBudget ?? DEFAULT_TOKEN_BUDGET
+        const maxHops = query.maxHops ?? 4
+
+        // ── Step 1: Resolve seeds ──────────────────────────────────────────
+        const seeds = resolveSeeds(query, this.contract, this.lock)
+
+        // ── Step 2: BFS proximity scores ──────────────────────────────────
+        const proximityMap = seeds.length > 0
+            ? bfsNeighbors(seeds, this.lock.functions, maxHops)
+            : new Map<string, number>()
+
+        // ── Step 3: Score every function ──────────────────────────────────
+        const keywords = extractKeywords(query.task)
+        const allFunctions = Object.values(this.lock.functions)
+
+        const scored: { fn: MikkLockFunction; score: number }[] = allFunctions.map(fn => {
+            let score = 0
+
+            // Proximity from BFS
+            const depth = proximityMap.get(fn.id)
+            if (depth !== undefined) {
+                score += depthToScore(depth)
+            }
+
+            // Keyword match
+            score += keywordScore(fn, keywords)
+
+            // Entry-point bonus
+            if (fn.calledBy.length === 0) score += WEIGHT.ENTRY_POINT
+
+            return { fn, score }
+        })
+
+        // ── Step 4: Sort by score descending ──────────────────────────────
+        scored.sort((a, b) => b.score - a.score)
+
+        // ── Step 5: Fill token budget ──────────────────────────────────────
+        const selected: MikkLockFunction[] = []
+        let usedTokens = 0
+
+        for (const { fn, score } of scored) {
+            if (score <= 0 && seeds.length > 0) break // Nothing relevant left
+            if (selected.length >= (query.maxFunctions ?? 80)) break
+
+            const snippet = this.buildFunctionSnippet(fn, query)
+            const tokens = estimateTokens(snippet)
+
+            if (usedTokens + tokens > tokenBudget) continue  // skip, try smaller ones later
+            selected.push(fn)
+            usedTokens += tokens
+        }
+
+        // ── Step 6: Group by module ────────────────────────────────────────
+        const byModule = new Map<string, MikkLockFunction[]>()
+        for (const fn of selected) {
+            if (!byModule.has(fn.moduleId)) byModule.set(fn.moduleId, [])
+            byModule.get(fn.moduleId)!.push(fn)
+        }
+
+        const contextModules: ContextModule[] = []
+        for (const [modId, fns] of byModule) {
+            const modDef = this.contract.declared.modules.find(m => m.id === modId)
+            const moduleFiles = Object.values(this.lock.files)
+                .filter(f => f.moduleId === modId)
+                .map(f => f.path)
+
+            contextModules.push({
+                id: modId,
+                name: modDef?.name ?? modId,
+                description: modDef?.description ?? '',
+                intent: modDef?.intent,
+                functions: fns.map(fn => this.toContextFunction(fn, query)),
+                files: moduleFiles,
+            })
+        }
+
+        // Sort modules: ones with more selected functions first
+        contextModules.sort((a, b) => b.functions.length - a.functions.length)
+
+        return {
+            project: {
+                name: this.contract.project.name,
+                language: this.contract.project.language,
+                description: this.contract.project.description,
+                moduleCount: this.contract.declared.modules.length,
+                functionCount: Object.keys(this.lock.functions).length,
+            },
+            modules: contextModules,
+            constraints: this.contract.declared.constraints,
+            decisions: this.contract.declared.decisions.map(d => ({
+                title: d.title,
+                reason: d.reason,
+            })),
+            prompt: this.generatePrompt(query, contextModules),
+            meta: {
+                seedCount: seeds.length,
+                totalFunctionsConsidered: allFunctions.length,
+                selectedFunctions: selected.length,
+                estimatedTokens: usedTokens,
+                keywords,
+            },
+        }
+    }
+
+    // ── Private helpers ────────────────────────────────────────────────────
+
+    private toContextFunction(fn: MikkLockFunction, query: ContextQuery): ContextFunction {
+        return {
+            name: fn.name,
+            file: fn.file,
+            startLine: fn.startLine,
+            endLine: fn.endLine,
+            calls: query.includeCallGraph !== false ? fn.calls : [],
+            calledBy: query.includeCallGraph !== false ? fn.calledBy : [],
+            purpose: fn.purpose,
+            errorHandling: fn.errorHandling?.map(e => `${e.type} @ line ${e.line}: ${e.detail}`),
+            edgeCases: fn.edgeCasesHandled,
+        }
+    }
+
+    /**
+     * Build a compact text snippet for token estimation.
+     * Mirrors what the providers will emit.
+     */
+    private buildFunctionSnippet(fn: MikkLockFunction, query: ContextQuery): string {
+        const parts = [`${fn.name}(${fn.file}:${fn.startLine}-${fn.endLine})`]
+        if (fn.purpose) parts.push(` — ${fn.purpose}`)
+        if (query.includeCallGraph !== false && fn.calls.length > 0) {
+            parts.push(` calls:[${fn.calls.join(',')}]`)
+        }
+        return parts.join('')
+    }
+
+    /** Generate the natural-language prompt section */
+    private generatePrompt(query: ContextQuery, modules: ContextModule[]): string {
+        const lines: string[] = []
+
+        lines.push('=== ARCHITECTURAL CONTEXT ===')
+        lines.push(`Project: ${this.contract.project.name} (${this.contract.project.language})`)
+        if (this.contract.project.description) {
+            lines.push(`Description: ${this.contract.project.description}`)
+        }
+        lines.push(`Task: ${query.task}`)
+        lines.push('')
+
+        for (const mod of modules) {
+            lines.push(`--- Module: ${mod.name} (${mod.id}) ---`)
+            if (mod.description) lines.push(mod.description)
+            if (mod.intent) lines.push(`Intent: ${mod.intent}`)
+            lines.push('')
+
+            for (const fn of mod.functions) {
+                const callStr = fn.calls.length > 0
+                    ? ` → [${fn.calls.join(', ')}]`
+                    : ''
+                const calledByStr = fn.calledBy.length > 0
+                    ? ` ← called by [${fn.calledBy.join(', ')}]`
+                    : ''
+                lines.push(`  ${fn.name}  ${fn.file}:${fn.startLine}-${fn.endLine}${callStr}${calledByStr}`)
+                if (fn.purpose) lines.push(`    purpose: ${fn.purpose}`)
+                if (fn.edgeCases && fn.edgeCases.length > 0) {
+                    lines.push(`    edge cases: ${fn.edgeCases.join('; ')}`)
+                }
+                if (fn.errorHandling && fn.errorHandling.length > 0) {
+                    lines.push(`    error handling: ${fn.errorHandling.join('; ')}`)
+                }
+            }
+            lines.push('')
+        }
+
+        if (this.contract.declared.constraints.length > 0) {
+            lines.push('=== CONSTRAINTS (MUST follow) ===')
+            for (const c of this.contract.declared.constraints) {
+                lines.push(`  • ${c}`)
+            }
+            lines.push('')
+        }
+
+        if (this.contract.declared.decisions.length > 0) {
+            lines.push('=== ARCHITECTURAL DECISIONS ===')
+            for (const d of this.contract.declared.decisions) {
+                lines.push(`  • ${d.title}: ${d.reason}`)
+            }
+            lines.push('')
+        }
+
+        return lines.join('\n')
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { ContextBuilder } from './context-builder.js'
+export { ClaudeMdGenerator } from './claude-md-generator.js'
+export { ClaudeProvider, GenericProvider, getProvider } from './providers.js'
+export type { AIContext, ContextModule, ContextFunction, ContextQuery, ContextProvider } from './types.js'

package/src/providers.ts

@@ -0,0 +1,155 @@
+import type { AIContext, ContextProvider } from './types.js'
+
+/**
+ * ClaudeProvider — formats context for Anthropic Claude models.
+ *
+ * Uses structured XML tags so Claude can parse boundaries clearly.
+ * Includes meta block so the model knows how much context was trimmed.
+ */
+export class ClaudeProvider implements ContextProvider {
+    name = 'claude'
+    maxTokens = 200000
+
+    formatContext(context: AIContext): string {
+        const lines: string[] = []
+
+        lines.push('<mikk_context>')
+
+        // ── Project ────────────────────────────────────────────────────────
+        lines.push(`<project name="${esc(context.project.name)}" language="${esc(context.project.language)}">`)
+        lines.push(`  <description>${esc(context.project.description)}</description>`)
+        lines.push(`  <stats modules="${context.project.moduleCount}" functions="${context.project.functionCount}"/>`)
+        lines.push('</project>')
+        lines.push('')
+
+        // ── Context quality meta ───────────────────────────────────────────
+        lines.push('<context_meta>')
+        lines.push(`  <task>${esc(context.meta?.keywords?.join(', ') ?? '')}</task>`)
+        lines.push(`  <seeds_found>${context.meta?.seedCount ?? 0}</seeds_found>`)
+        lines.push(`  <functions_selected>${context.meta?.selectedFunctions ?? 0} of ${context.meta?.totalFunctionsConsidered ?? 0}</functions_selected>`)
+        lines.push(`  <estimated_tokens>${context.meta?.estimatedTokens ?? 0}</estimated_tokens>`)
+        lines.push('</context_meta>')
+        lines.push('')
+
+        // ── Modules ────────────────────────────────────────────────────────
+        for (const mod of context.modules) {
+            lines.push(`<module id="${esc(mod.id)}" name="${esc(mod.name)}">`)
+            lines.push(`  <description>${esc(mod.description)}</description>`)
+            if (mod.intent) lines.push(`  <intent>${esc(mod.intent)}</intent>`)
+            lines.push(`  <files count="${mod.files.length}">`)
+            for (const f of mod.files) {
+                lines.push(`    <file>${esc(f)}</file>`)
+            }
+            lines.push('  </files>')
+
+            if (mod.functions.length > 0) {
+                lines.push('  <functions>')
+                for (const fn of mod.functions) {
+                    const calls = fn.calls.length > 0
+                        ? ` calls="${esc(fn.calls.join(','))}"`
+                        : ''
+                    const calledBy = fn.calledBy.length > 0
+                        ? ` calledBy="${esc(fn.calledBy.join(','))}"`
+                        : ''
+                    lines.push(`    <fn name="${esc(fn.name)}" file="${esc(fn.file)}" lines="${fn.startLine}-${fn.endLine}"${calls}${calledBy}>`)
+                    if (fn.purpose) lines.push(`      <purpose>${esc(fn.purpose)}</purpose>`)
+                    if (fn.edgeCases && fn.edgeCases.length > 0) {
+                        lines.push(`      <edge_cases>${esc(fn.edgeCases.join('; '))}</edge_cases>`)
+                    }
+                    if (fn.errorHandling && fn.errorHandling.length > 0) {
+                        lines.push(`      <error_handling>${esc(fn.errorHandling.join('; '))}</error_handling>`)
+                    }
+                    lines.push('    </fn>')
+                }
+                lines.push('  </functions>')
+            }
+            lines.push('</module>')
+            lines.push('')
+        }
+
+        // ── Constraints ────────────────────────────────────────────────────
+        if (context.constraints.length > 0) {
+            lines.push('<constraints>')
+            for (const c of context.constraints) {
+                lines.push(`  <constraint>${esc(c)}</constraint>`)
+            }
+            lines.push('</constraints>')
+            lines.push('')
+        }
+
+        // ── Decisions ─────────────────────────────────────────────────────
+        if (context.decisions.length > 0) {
+            lines.push('<architectural_decisions>')
+            for (const d of context.decisions) {
+                lines.push(`  <decision title="${esc(d.title)}">${esc(d.reason)}</decision>`)
+            }
+            lines.push('</architectural_decisions>')
+        }
+
+        lines.push('</mikk_context>')
+        return lines.join('\n')
+    }
+}
+
+/**
+ * GenericProvider — clean plain-text format for any model.
+ * Identical to the natural-language prompt generated by ContextBuilder.
+ */
+export class GenericProvider implements ContextProvider {
+    name = 'generic'
+    maxTokens = 128000
+
+    formatContext(context: AIContext): string {
+        return context.prompt
+    }
+}
+
+/**
+ * CompactProvider — ultra-minimal format for small context windows.
+ * One line per function, no XML, no prose.
+ */
+export class CompactProvider implements ContextProvider {
+    name = 'compact'
+    maxTokens = 16000
+
+    formatContext(context: AIContext): string {
+        const lines: string[] = [
+            `# ${context.project.name} (${context.project.language})`,
+            `Task keywords: ${context.meta?.keywords?.join(', ') ?? ''}`,
+            '',
+        ]
+        for (const mod of context.modules) {
+            lines.push(`## ${mod.name}`)
+            for (const fn of mod.functions) {
+                const calls = fn.calls.length > 0 ? ` → ${fn.calls.join(',')}` : ''
+                lines.push(`  ${fn.name} [${fn.file}:${fn.startLine}]${calls}`)
+            }
+            lines.push('')
+        }
+        if (context.constraints.length > 0) {
+            lines.push('CONSTRAINTS: ' + context.constraints.join(' | '))
+        }
+        return lines.join('\n')
+    }
+}
+
+export function getProvider(name: string): ContextProvider {
+    switch (name.toLowerCase()) {
+        case 'claude':
+        case 'anthropic':
+            return new ClaudeProvider()
+        case 'compact':
+            return new CompactProvider()
+        default:
+            return new GenericProvider()
+    }
+}
+
+/** Minimal XML attribute escaping */
+function esc(s: string): string {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+import type { MikkContract, MikkLock, MikkLockFunction } from '@getmikk/core'
+
+/** The structured context object passed to AI models */
+export interface AIContext {
+    project: {
+        name: string
+        language: string
+        description: string
+        moduleCount: number
+        functionCount: number
+    }
+    modules: ContextModule[]
+    constraints: string[]
+    decisions: { title: string; reason: string }[]
+    prompt: string
+    /** Diagnostic info — helpful for debugging context quality */
+    meta: {
+        seedCount: number
+        totalFunctionsConsidered: number
+        selectedFunctions: number
+        estimatedTokens: number
+        keywords: string[]
+    }
+}
+
+export interface ContextModule {
+    id: string
+    name: string
+    description: string
+    intent?: string
+    functions: ContextFunction[]
+    files: string[]
+}
+
+export interface ContextFunction {
+    name: string
+    file: string
+    startLine: number
+    endLine: number
+    calls: string[]
+    calledBy: string[]
+    purpose?: string
+    errorHandling?: string[]
+    edgeCases?: string[]
+}
+
+/** Query options for context generation */
+export interface ContextQuery {
+    /** The user's task description — the primary relevance signal */
+    task: string
+    /** Specific files to anchor the graph traversal from */
+    focusFiles?: string[]
+    /** Specific modules to include */
+    focusModules?: string[]
+    /** Max functions to include in output (hard cap) */
+    maxFunctions?: number
+    /** Max BFS hops from seed nodes (default 4) */
+    maxHops?: number
+    /** Approximate token budget for function listings (default 6000) */
+    tokenBudget?: number
+    /** Include call graph arrows (default true) */
+    includeCallGraph?: boolean
+}
+
+/** Context provider interface for different AI platforms */
+export interface ContextProvider {
+    name: string
+    formatContext(context: AIContext): string
+    maxTokens: number
+}

package/tests/claude-md.test.ts

@@ -0,0 +1,137 @@
+import { describe, test, expect } from 'bun:test'
+import { ClaudeMdGenerator } from '../src/claude-md-generator'
+import type { MikkContract, MikkLock } from '@getmikk/core'
+
+const mockContract: MikkContract = {
+    version: '1.0.0',
+    project: {
+        name: 'TestProject',
+        description: 'A test project for validating claude.md generation',
+        language: 'TypeScript',
+        entryPoints: ['src/index.ts'],
+    },
+    declared: {
+        modules: [
+            { id: 'auth', name: 'Authentication', description: 'Handles user authentication', intent: 'JWT-based auth flow', paths: ['src/auth/**'] },
+            { id: 'api', name: 'API', description: 'REST API layer', paths: ['src/api/**'] },
+        ],
+        constraints: [
+            'No direct DB access outside db/',
+            'All auth must go through auth.middleware',
+        ],
+        decisions: [
+            { id: 'd1', title: 'Use JWT', reason: 'Stateless auth for scalability', date: '2024-01-01' },
+        ],
+    },
+    overwrite: { mode: 'never', requireConfirmation: true },
+}
+
+const mockLock: MikkLock = {
+    version: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    generatorVersion: '1.1.0',
+    projectRoot: '/test',
+    syncState: { status: 'clean', lastSyncAt: new Date().toISOString(), lockHash: 'a', contractHash: 'b' },
+    modules: {
+        auth: { id: 'auth', files: ['src/auth/verify.ts'], hash: 'h1', fragmentPath: '.mikk/fragments/auth.json' },
+        api: { id: 'api', files: ['src/api/login.ts'], hash: 'h2', fragmentPath: '.mikk/fragments/api.json' },
+    },
+    functions: {
+        'fn:auth:verifyToken': {
+            id: 'fn:auth:verifyToken', name: 'verifyToken', file: 'src/auth/verify.ts',
+            startLine: 1, endLine: 10, hash: 'h1', calls: [], calledBy: ['fn:api:handleLogin'],
+            moduleId: 'auth', purpose: 'Verify JWT tokens',
+        },
+        'fn:auth:refreshToken': {
+            id: 'fn:auth:refreshToken', name: 'refreshToken', file: 'src/auth/refresh.ts',
+            startLine: 1, endLine: 15, hash: 'h2', calls: [], calledBy: [],
+            moduleId: 'auth',
+        },
+        'fn:api:handleLogin': {
+            id: 'fn:api:handleLogin', name: 'handleLogin', file: 'src/api/login.ts',
+            startLine: 1, endLine: 20, hash: 'h3', calls: ['fn:auth:verifyToken'], calledBy: [],
+            moduleId: 'api',
+        },
+    },
+    files: {
+        'src/auth/verify.ts': { path: 'src/auth/verify.ts', hash: 'fh1', moduleId: 'auth', lastModified: new Date().toISOString() },
+        'src/api/login.ts': { path: 'src/api/login.ts', hash: 'fh2', moduleId: 'api', lastModified: new Date().toISOString() },
+    },
+    graph: { nodes: 3, edges: 1, rootHash: 'root' },
+}
+
+describe('ClaudeMdGenerator', () => {
+    test('generates valid markdown', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('# TestProject')
+        expect(md).toContain('Architecture Overview')
+    })
+
+    test('includes project description', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('A test project for validating claude.md generation')
+    })
+
+    test('includes module sections', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('Authentication module')
+        expect(md).toContain('API module')
+    })
+
+    test('includes function names', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('verifyToken')
+        expect(md).toContain('handleLogin')
+    })
+
+    test('includes constraints', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('No direct DB access outside db/')
+    })
+
+    test('includes decisions', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('Use JWT')
+        expect(md).toContain('Stateless auth for scalability')
+    })
+
+    test('includes dependency info', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        // API depends on Auth (handleLogin calls verifyToken)
+        expect(md).toContain('Depends on')
+    })
+
+    test('respects token budget', () => {
+        // Use a very small budget — should truncate
+        const gen = new ClaudeMdGenerator(mockContract, mockLock, 200)
+        const md = gen.generate()
+        // Should have the summary but may be truncated
+        expect(md).toContain('TestProject')
+    })
+
+    test('includes stats', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('3 functions')
+        expect(md).toContain('2 modules')
+    })
+
+    test('shows purpose when available', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('Verify JWT tokens')
+    })
+
+    test('shows calledBy count for key functions', () => {
+        const gen = new ClaudeMdGenerator(mockContract, mockLock)
+        const md = gen.generate()
+        expect(md).toContain('called by 1')
+    })
+})

package/tests/smoke.test.ts

@@ -0,0 +1,5 @@
+import { expect, test } from "bun:test";
+
+test("smoke test - ai-context", () => {
+    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"
+    ]
+}