@getmikk/intent-engine 1.8.0 → 1.9.1

package/README.md

@@ -1,84 +1,190 @@
-# @getmikk/intent-engine
+# @getmikk/intent-engine
 
-> Parse developer intent, detect constraint conflicts, and find functions by meaning.
+> Parse developer intent, enforce safety gates, run the Decision Engine, auto-correct issues, and find functions by meaning.
 
 [![npm](https://img.shields.io/npm/v/@getmikk/intent-engine)](https://www.npmjs.com/package/@getmikk/intent-engine)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
 
-Two capabilities in one package: a pre-flight pipeline that catches architectural conflicts before code is written, and a semantic search engine that finds functions by natural-language description using local vector embeddings.
+The Intent Engine is the safety layer that validates every edit before it lands. It combines:
+
+1. **PreflightPipeline** — pre-flight check for plain-English plans
+2. **PreEditValidation** — full pre-edit safety validation (used by `mikk_before_edit`)
+3. **IntentUnderstanding** — analyzes commit/branch context for intentional breaking changes
+4. **EnforcedSafetyGates** — six gates that block or warn on risky edits
+5. **DecisionEngine** — aggregates all signals into `APPROVED` / `WARNING` / `BLOCKED`
+6. **AutoCorrectionEngine** — detects and auto-fixes broken references, imports, boundary violations
+7. **SemanticSearcher** — local vector search for functions by natural-language description
 
 > Part of [Mikk](../../README.md) — live architectural context for your AI agent.
 
 ---
 
-## Pre-flight Pipeline
+## Pre-Edit Validation (`mikk_before_edit`)
 
-Takes a plain-English prompt describing a refactor or new feature, and returns a structured verdict before any code is written.
+The main entry point for the MCP `mikk_before_edit` tool. Runs the full pipeline against a set of files the AI intends to edit.
 
-### Usage
+```typescript
+import { PreEditValidation } from '@getmikk/intent-engine'
+
+const validator = new PreEditValidation(contract, lock, graph, projectRoot, {
+  maxRiskScore: 70,
+  maxImpactNodes: 10,
+  protectedModules: ['auth', 'billing'],
+  requireTestsForChangedFiles: true,
+  requireDocumentationForApiChanges: false,
+})
+
+const result = await validator.validate({
+  files: ['src/auth/login.ts', 'src/auth/session.ts'],
+  description: 'Refactor JWT validation to use new token format',
+  author: 'dev@example.com',
+  intent: {
+    commitMessage: 'REFACTOR: update JWT validation',
+    branchName: 'refactor/jwt-v2',
+  },
+})
 
-```bash
-mikk intent "Move user validation into a shared utils module"
-mikk intent "Extract auth logic into middleware" --json
+console.log(result.allowed)          // true | false
+console.log(result.intent)           // { isIntentionalBreakingChange, confidence, reasoning }
+console.log(result.gates)            // per-gate pass/fail with reason and bypassable flag
+console.log(result.corrections)      // auto-fixed issues and suggestions
+console.log(result.recommendations)  // contextual next steps
 ```
 
-Or programmatically:
+### Response shape
 
 ```typescript
-import { PreflightPipeline } from '@getmikk/intent-engine'
+{
+  allowed: boolean,
+  confidence: number,          // 0–1 intent confidence
+
+  intent: {
+    isIntentionalBreakingChange: boolean,
+    confidence: number,
+    reasoning: string[],
+    riskAcceptance: 'none' | 'low' | 'medium' | 'high'
+  },
 
-const pipeline = new PreflightPipeline(contract, lock)
-const result = await pipeline.run("Add rate limiting to all API routes")
+  impact: {
+    totalFiles: number,
+    totalFunctions: number,
+    riskScore: number,          // 0–100
+    criticalPaths: string[],    // high-calledBy functions
+    blastRadius: string[]       // functions in calledBy chain
+  },
 
-console.log(result.approved)     // true | false
-console.log(result.conflicts)    // constraint violations found
-console.log(result.suggestions)  // implementation suggestions with affected files
+  gates: Array<{
+    name: string,               // RISK_SCORE | IMPACT_SCALE | PROTECTED_MODULE | ...
+    passed: boolean,
+    severity: 'BLOCKING' | 'WARNING',
+    message: string,
+    bypassable: boolean
+  }>,
+
+  corrections: {
+    available: boolean,
+    issuesFound: number,
+    autoFixable: number,
+    applied: string[],
+    suggested: string[]
+  },
+
+  recommendations: string[],
+  nextSteps: string[],
+  tokenSavings: number
+}
 ```
 
-### What it returns
+---
+
+## Safety Gates
+
+Six gates enforced by `EnforcedSafetyGates`. Use standalone or via `PreEditValidation`:
 
 ```typescript
-{
-  intents: [
-    {
-      action: 'add' | 'move' | 'extract' | 'refactor' | 'remove' | ...,
-      target: { type: 'function' | 'module' | 'file', name: string, moduleId?: string },
-      confidence: number  // 0-1
-    }
-  ],
-  conflicts: {
-    hasConflicts: boolean,
-    conflicts: [
-      {
-        type: string,
-        severity: 'error' | 'warning',
-        message: string,
-        suggestedFix: string
-      }
-    ]
-  },
-  suggestions: [
-    {
-      intent: Intent,
-      implementation: string,
-      affectedFiles: string[],
-      newFiles: string[],
-      estimatedImpact: number
-    }
-  ],
-  approved: boolean
-}
+import { EnforcedSafetyGates } from '@getmikk/intent-engine'
+
+const gates = new EnforcedSafetyGates(contract, lock, graph, {
+  maxRiskScore: 70,
+  maxImpactNodes: 10,
+  protectedModules: ['auth'],
+  enforceOnSave: true,
+  enforceOnCommit: true,
+  enforceInCI: true,
+  requireTestsForChangedFiles: true,
+  requireDocumentationForApiChanges: false,
+})
+
+const results = await gates.validateEdits(['src/auth/login.ts'])
+const { allowed, blockingGates } = gates.canProceed(results)
+```
+
+| Gate | Blocks when | Bypassable |
+|------|------------|-----------|
+| `RISK_SCORE` | Risk ≥ 90, or > `maxRiskScore` | Yes (except ≥ 90) |
+| `IMPACT_SCALE` | Impact > `maxImpactNodes × 2` | Yes |
+| `PROTECTED_MODULE` | Protected module touched | **Never** |
+| `BREAKING_CHANGE` | Exported API changed without `BREAKING:` marker | Yes |
+| `TEST_COVERAGE` | High-risk changes with no test file edits | Yes |
+| `DOCUMENTATION` | Significant API changes with no doc updates | Yes |
+
+---
+
+## Decision Engine
+
+Evaluates an `ImpactResult` against your policies:
+
+```typescript
+import { DecisionEngine } from '@getmikk/intent-engine'
+
+const engine = new DecisionEngine(contract)
+const decision = engine.evaluate(impactResult)
+
+// { status: 'APPROVED' | 'WARNING' | 'BLOCKED', reasons: string[], riskScore: number, impactNodes: number }
 ```
 
-### Constraint checks
+---
+
+## Auto-Correction
 
-The pipeline checks against all 6 declared constraint types: `no-import`, `must-use`, `no-call`, `layer`, `naming`, `max-files`. If the proposed change would violate any of them, it surfaces as a conflict with a suggested fix.
+Detects and fixes common issues in source files:
+
+```typescript
+import { AutoCorrectionEngine } from '@getmikk/intent-engine'
+
+const corrector = new AutoCorrectionEngine(contract, lock, graph, projectRoot)
+const result = await corrector.analyzeAndFix(['src/auth/login.ts'])
+
+console.log(result.issues)         // all detected issues
+console.log(result.appliedFixes)   // auto-applied fixes
+console.log(result.failedFixes)    // fixes that failed to apply
+```
+
+Issues detected: `broken_reference` · `missing_import` · `boundary_violation`
+
+---
+
+## Pre-flight Pipeline
+
+For plain-English intent validation before writing any code:
+
+```typescript
+import { PreflightPipeline } from '@getmikk/intent-engine'
+
+const pipeline = new PreflightPipeline(contract, lock)
+const result = await pipeline.run("Add rate limiting to all API routes")
+
+console.log(result.approved)    // true | false
+console.log(result.conflicts)   // constraint violations
+console.log(result.decision)    // DecisionResult from DecisionEngine
+console.log(result.explanation) // human-readable summary
+```
 
 ---
 
 ## Semantic Search
 
-Find functions by natural-language description using local vector embeddings. No external API — runs entirely on-device.
+Find functions by natural-language description using local vector embeddings. Runs entirely on-device — no external API.
 
 ### Setup
 
@@ -90,36 +196,19 @@ The model (`Xenova/all-MiniLM-L6-v2`, ~22MB) downloads once to `~/.cache/hugging
 
 ### Usage
 
-Exposed via the MCP tool `mikk_semantic_search`, or directly:
-
 ```typescript
 import { SemanticSearcher } from '@getmikk/intent-engine'
 
 const searcher = new SemanticSearcher(projectRoot)
-
-// Build (or load from cache) embeddings for the lock
 await searcher.index(lock)
 
-// Find the 10 most semantically similar functions
 const results = await searcher.search('validate a JWT token', lock, 10)
 // Returns: [{ name, file, moduleId, purpose, lines, score }]
 ```
 
-### How it works
-
-1. For each function in the lock, concatenates: function name + purpose string (if present) + param names + return type
-2. Generates embeddings in batches of 64 using the pipeline
-3. Caches to `.mikk/embeddings.json` — fingerprinted by function count + first 20 sorted IDs
-4. Cache is valid until the lock changes; recomputes only what changed
-5. At search time, embeds the query and ranks all functions by cosine similarity
-
-All vectors are unit-normalized at generation time so similarity is a simple dot product.
-
-### Check availability
+Embeddings are cached to `.mikk/embeddings.json` and only recomputed when the lock changes.
 
 ```typescript
 const available = await SemanticSearcher.isAvailable()
-// true if @xenova/transformers is installed and importable
+// true if @xenova/transformers is installed
 ```
-
-The MCP server calls `isAvailable()` before registering the tool — if the package is missing, the tool is not exposed and the response explains how to install it.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/intent-engine",
-    "version": "1.8.0",
+    "version": "1.9.1",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -21,16 +21,9 @@
         "dev": "tsc --watch"
     },
     "dependencies": {
-        "@getmikk/core": "^1.8.0",
-        "zod": "^3.22.0"
-    },
-    "peerDependencies": {
-        "@xenova/transformers": ""
-    },
-    "peerDependenciesMeta": {
-        "@xenova/transformers": {
-            "optional": true
-        }
+        "@getmikk/core": "^1.9.0",
+        "zod": "^3.22.0",
+        "@xenova/transformers": "^2.17.2"
     },
     "devDependencies": {
         "@types/bun": "^1.3.10",

package/src/auto-correction.ts

@@ -0,0 +1,284 @@
+import * as nodePath from 'node:path'
+import * as fs from 'node:fs/promises'
+import type { MikkContract, MikkLock, DependencyGraph } from '@getmikk/core'
+
+/**
+ * AutoCorrectionEngine — detects and auto-fixes common code issues.
+ *
+ * Capabilities:
+ *  1. Broken call references (pointing to IDs that no longer exist in the lock)
+ *  2. Missing imports (resolved path absent from lock)
+ *  3. Boundary violations (cross-module calls that break declared constraints)
+ */
+export interface CorrectionIssue {
+    type: 'missing_import' | 'broken_reference' | 'boundary_violation' | 'missing_type' | 'null_safety'
+    severity: 'error' | 'warning'
+    file: string
+    line: number
+    column: number
+    message: string
+    autoFixable: boolean
+    suggestedFix: string
+}
+
+export interface CorrectionResult {
+    issues: CorrectionIssue[]
+    appliedFixes: string[]
+    failedFixes: string[]
+    filesModified: string[]
+    tokenCost: number
+}
+
+export class AutoCorrectionEngine {
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock,
+        private _graph: DependencyGraph,
+        private projectRoot: string,
+    ) {}
+
+    /** Analyze files and auto-apply safe fixes. */
+    async analyzeAndFix(files: string[]): Promise<CorrectionResult> {
+        const issues: CorrectionIssue[] = []
+        const appliedFixes: string[] = []
+        const failedFixes: string[] = []
+        const filesModified = new Set<string>()
+        let tokenCost = 0
+
+        for (const file of files) {
+            const fileIssues = await this.analyzeFile(file)
+            issues.push(...fileIssues)
+
+            for (const issue of fileIssues) {
+                if (!issue.autoFixable) continue
+                try {
+                    const ok = await this.applyFix(issue)
+                    if (ok) {
+                        appliedFixes.push(`${file}:${issue.line} — ${issue.message}`)
+                        filesModified.add(file)
+                        tokenCost += 100 // ~100 tokens per fix
+                    } else {
+                        failedFixes.push(`${file}:${issue.line} — ${issue.message}`)
+                    }
+                } catch {
+                    failedFixes.push(`${file}:${issue.line} — ${issue.message}`)
+                }
+            }
+        }
+
+        return { issues, appliedFixes, failedFixes, filesModified: [...filesModified], tokenCost }
+    }
+
+    // ─── Private: analysis ──────────────────────────────────────────────────
+
+    private async analyzeFile(file: string): Promise<CorrectionIssue[]> {
+        const issues: CorrectionIssue[] = []
+        const norm = file.replace(/\\/g, '/')
+
+        const fileFunctions = Object.values(this.lock.functions).filter(
+            f => f.file === norm || f.file.endsWith('/' + norm),
+        )
+
+        for (const fn of fileFunctions) {
+            // Broken call references
+            for (const callId of fn.calls) {
+                if (!this.lock.functions[callId]) {
+                    // Extract the plain name from the ID (fn:path:Name → Name)
+                    const calleeName = callId.split(':').pop() ?? callId
+                    const similar = this.findSimilarFunction(calleeName)
+                    issues.push({
+                        type: 'broken_reference',
+                        severity: 'error',
+                        file: norm,
+                        line: fn.startLine,
+                        column: 1,
+                        message: `Function "${calleeName}" not found in lock.${similar ? ` Did you mean "${similar}"?` : ''}`,
+                        autoFixable: !!similar,
+                        suggestedFix: similar ?? '',
+                    })
+                }
+            }
+
+            // Boundary violations
+            for (const v of this.checkBoundaryViolations(fn)) {
+                issues.push({
+                    type: 'boundary_violation',
+                    severity: 'warning',
+                    file: norm,
+                    line: fn.startLine,
+                    column: 1,
+                    message: v.message,
+                    autoFixable: true,
+                    suggestedFix: v.suggestedAdapter,
+                })
+            }
+        }
+
+        // Missing imports
+        const fileEntry = this.lock.files[norm]
+        if (fileEntry) {
+            for (const imp of fileEntry.imports ?? []) {
+                if (imp.resolvedPath && !this.lock.files[imp.resolvedPath]) {
+                    const corrected = this.findCorrectedImportPath(imp.resolvedPath)
+                    if (corrected && corrected !== imp.resolvedPath) {
+                        issues.push({
+                            type: 'missing_import',
+                            severity: 'error',
+                            file: norm,
+                            line: 1,
+                            column: 1,
+                            message: `Import "${imp.source}" resolves to missing file "${imp.resolvedPath}"`,
+                            autoFixable: true,
+                            suggestedFix: corrected,
+                        })
+                    }
+                }
+            }
+        }
+
+        return issues
+    }
+
+    // ─── Private: fix application ───────────────────────────────────────────
+
+    private async applyFix(issue: CorrectionIssue): Promise<boolean> {
+        // Only operate on files inside the project root
+        const abs = nodePath.resolve(this.projectRoot, issue.file)
+        const rootResolved = nodePath.resolve(this.projectRoot)
+        if (!abs.startsWith(rootResolved + nodePath.sep) && abs !== rootResolved) return false
+
+        let content: string
+        try {
+            content = await fs.readFile(abs, 'utf-8')
+        } catch {
+            return false
+        }
+
+        let newContent: string
+        switch (issue.type) {
+            case 'broken_reference':
+                newContent = this.fixBrokenReference(content, issue)
+                break
+            case 'missing_import':
+                newContent = this.fixMissingImport(content, issue)
+                break
+            case 'boundary_violation':
+                newContent = this.addBoundaryWarningComment(content, issue)
+                break
+            default:
+                return false
+        }
+
+        if (newContent === content) return false
+        await fs.writeFile(abs, newContent, 'utf-8')
+        return true
+    }
+
+    /**
+     * Replace the old function name with the suggested name.
+     *
+     * The issue message is: `Function "<calleeName>" not found...`
+     * We extract calleeName from the quotes and do a whole-word replace.
+     * We use a simple string-literal escaping so no regex injection occurs.
+     */
+    private fixBrokenReference(content: string, issue: CorrectionIssue): string {
+        const oldName = issue.message.match(/^Function "([^"]+)"/)?.[1]
+        const newName = issue.suggestedFix
+
+        if (!oldName || !newName || oldName === newName) return content
+
+        // Escape any regex metacharacters in the name (names can contain `.` for methods)
+        const escaped = oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        return content.replace(new RegExp(`\\b${escaped}\\b`, 'g'), newName)
+    }
+
+    /**
+     * Replace the old resolved path with the corrected one in import statements.
+     */
+    private fixMissingImport(content: string, issue: CorrectionIssue): string {
+        // Extract the old path from the message: `...missing file "<path>"`
+        const oldPath = issue.message.match(/missing file "([^"]+)"/)?.[1]
+        const newPath = issue.suggestedFix
+        if (!oldPath || !newPath) return content
+        // Only replace inside string literals (quoted) to avoid broad substitution
+        return content.split(oldPath).join(newPath)
+    }
+
+    /**
+     * Prepend a TODO comment flagging the boundary violation.
+     * Real adapter generation would go here in a future iteration.
+     */
+    private addBoundaryWarningComment(content: string, issue: CorrectionIssue): string {
+        const comment = `// TODO [mikk]: Boundary violation — ${issue.message}\n// Suggested: ${issue.suggestedFix}\n`
+        return comment + content
+    }
+
+    // ─── Private: helpers ───────────────────────────────────────────────────
+
+    private findSimilarFunction(missingName: string): string | null {
+        // Strip class prefix (Class.method → method) for matching
+        const simpleName = missingName.includes('.') ? missingName.split('.').pop()! : missingName
+
+        const candidates = Object.values(this.lock.functions)
+            .map(f => {
+                const name = f.name.includes('.') ? f.name.split('.').pop()! : f.name
+                return { fn: f, dist: this.levenshtein(simpleName, name) }
+            })
+            .filter(x => x.dist <= 3)
+            .sort((a, b) => a.dist - b.dist)
+
+        return candidates[0]?.fn.name ?? null
+    }
+
+    private checkBoundaryViolations(fn: MikkLock['functions'][string]): Array<{ message: string; suggestedAdapter: string }> {
+        const violations: Array<{ message: string; suggestedAdapter: string }> = []
+        const constraints = this.contract.declared?.constraints ?? []
+
+        for (const callId of fn.calls) {
+            const target = this.lock.functions[callId]
+            if (!target || fn.moduleId === target.moduleId) continue
+
+            // Check if any constraint text mentions both modules with "no-import"
+            const violated = constraints.some(c => {
+                const lower = typeof c === 'string' ? c.toLowerCase() : ''
+                return (
+                    lower.includes('no-import') &&
+                    lower.includes(fn.moduleId.toLowerCase()) &&
+                    lower.includes(target.moduleId.toLowerCase())
+                )
+            })
+
+            if (violated) {
+                violations.push({
+                    message: `Boundary violation: ${fn.moduleId} → ${target.moduleId} breaks a declared constraint`,
+                    suggestedAdapter: `Create adapter in ${fn.moduleId} that wraps ${target.moduleId}::${target.name}`,
+                })
+            }
+        }
+
+        return violations
+    }
+
+    private findCorrectedImportPath(oldPath: string): string | null {
+        const fileName = oldPath.split('/').pop()
+        if (!fileName) return null
+        const matches = Object.keys(this.lock.files).filter(p => p.endsWith('/' + fileName))
+        return matches.length === 1 ? matches[0] : null
+    }
+
+    /** O(n·m) Levenshtein with early exit when distance exceeds threshold. */
+    private levenshtein(a: string, b: string, threshold = 4): number {
+        if (Math.abs(a.length - b.length) > threshold) return threshold + 1
+        const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+        for (let i = 1; i <= a.length; i++) {
+            let prev = i
+            for (let j = 1; j <= b.length; j++) {
+                const val = a[i - 1] === b[j - 1] ? row[j - 1] : Math.min(row[j - 1], row[j], prev) + 1
+                row[j - 1] = prev
+                prev = val
+            }
+            row[b.length] = prev
+        }
+        return row[b.length]
+    }
+}

package/src/decision-engine.ts

@@ -0,0 +1,74 @@
+import type { ImpactResult, MikkContract } from '@getmikk/core'
+import type { DecisionResult, DecisionStatus } from './types.js'
+
+/**
+ * DecisionEngine — evaluates quantitative impact analysis against project policies.
+ *
+ * Policies live in contract.policies (all optional with safe defaults):
+ *   - maxRiskScore       (default 70)  — WARNING above, BLOCKED at ≥ 90
+ *   - maxImpactNodes     (default 10)  — WARNING/BLOCKED when exceeded
+ *   - protectedModules   (default [])  — BLOCKED if a CRITICAL/HIGH-risk node's
+ *                                        file path matches a protected module name
+ *   - enforceStrictBoundaries (false)  — BLOCKED on any critical cross-module hit
+ */
+export class DecisionEngine {
+    constructor(private contract: MikkContract) {}
+
+    evaluate(impact: ImpactResult): DecisionResult {
+        const policy = {
+            maxRiskScore:            this.contract.policies?.maxRiskScore           ?? 70,
+            maxImpactNodes:          this.contract.policies?.maxImpactNodes         ?? 10,
+            protectedModules:        this.contract.policies?.protectedModules       ?? [] as string[],
+            enforceStrictBoundaries: this.contract.policies?.enforceStrictBoundaries ?? false,
+        }
+
+        const reasons: string[] = []
+        let status: DecisionStatus = 'APPROVED'
+        const promote = (next: DecisionStatus) => {
+            if (next === 'BLOCKED' || (next === 'WARNING' && status === 'APPROVED')) status = next
+        }
+
+        // 1. Absolute risk threshold
+        if (impact.riskScore >= 90) {
+            promote('BLOCKED')
+            reasons.push(`Critical risk detected (${impact.riskScore}/100). Changes exceeding 90 are always blocked.`)
+        } else if (impact.riskScore > policy.maxRiskScore) {
+            promote('WARNING')
+            reasons.push(`High risk (${impact.riskScore}) exceeds policy threshold of ${policy.maxRiskScore}.`)
+        }
+
+        // 2. Impact scale
+        if (impact.impacted.length > policy.maxImpactNodes) {
+            promote('WARNING')
+            reasons.push(`Impact spread (${impact.impacted.length} symbols) exceeds limit of ${policy.maxImpactNodes}.`)
+        }
+
+        // 3. Protected modules
+        // allImpacted entries are ClassifiedImpact objects — they have `nodeId`
+        // and `riskScore` (numeric), NOT a `.risk` string field.
+        const touched = new Set<string>()
+        for (const node of impact.allImpacted) {
+            // Only act on nodes above the HIGH threshold (riskScore ≥ 60)
+            if (node.riskScore < 60) continue
+            for (const pm of policy.protectedModules) {
+                if (node.file.toLowerCase().includes(pm.toLowerCase())) {
+                    touched.add(pm)
+                }
+            }
+        }
+        if (touched.size > 0) {
+            promote('WARNING')
+            reasons.push(`Change affects protected modules: ${[...touched].join(', ')}.`)
+        }
+
+        // 4. Strict boundary enforcement
+        if (policy.enforceStrictBoundaries && impact.classified.critical.length > 0) {
+            promote('BLOCKED')
+            reasons.push(
+                `Strict boundary enforcement: ${impact.classified.critical.length} critical cross-module impact(s) detected.`,
+            )
+        }
+
+        return { status, reasons, riskScore: impact.riskScore, impactNodes: impact.impacted.length }
+    }
+}