@getmikk/intent-engine 1.8.0 → 2.0.0

package/src/pre-edit-validation.ts

@@ -0,0 +1,295 @@
+import type { MikkContract, MikkLock, DependencyGraph, ImpactResult } from '@getmikk/core'
+import { ImpactAnalyzer } from '@getmikk/core'
+import { IntentUnderstanding, type IntentContext } from './intent-understanding.js'
+import { AutoCorrectionEngine } from './auto-correction.js'
+import { EnforcedSafetyGates, type SafetyGateConfig } from './enforced-safety.js'
+
+/**
+ * PreEditValidation — intercepts edits before they are applied.
+ *
+ * Combines:
+ *  1. Intent understanding  (is this intentional?)
+ *  2. Real impact analysis  (what breaks?)
+ *  3. Auto-correction       (can we fix issues automatically?)
+ *  4. Safety gates          (should we block this?)
+ *
+ * This is the single entry point for mikk_before_edit.
+ */
+export interface EditProposal {
+    files: string[]
+    description: string
+    author: string
+    intent?: Partial<IntentContext>
+}
+
+export interface ValidationResult {
+    allowed: boolean
+    confidence: number
+
+    intent: {
+        isIntentionalBreakingChange: boolean
+        confidence: number
+        reasoning: string[]
+        riskAcceptance: 'none' | 'low' | 'medium' | 'high'
+    }
+
+    impact: {
+        totalFiles: number
+        totalFunctions: number
+        riskScore: number
+        criticalPaths: string[]
+        blastRadius: string[]
+    }
+
+    gates: Array<{
+        name: string
+        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
+}
+
+export class PreEditValidation {
+    private intentEngine: IntentUnderstanding
+    private autoCorrection: AutoCorrectionEngine
+    private safetyGates: EnforcedSafetyGates
+    private impactAnalyzer: ImpactAnalyzer
+
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock,
+        graph: DependencyGraph,
+        private projectRoot: string,
+        safetyConfig?: Partial<SafetyGateConfig>,
+    ) {
+        this.intentEngine   = new IntentUnderstanding(contract, lock)
+        this.impactAnalyzer = new ImpactAnalyzer(graph)
+
+        // Build protected modules list from constraints that mention "protected".
+        // Constraints may be strings OR objects — guard both cases.
+        const protectedModules = (contract.declared?.constraints ?? [])
+            .filter(c => {
+                if (typeof c === 'string') return c.toLowerCase().includes('protected')
+                return false // object-style constraints don't auto-map to module names
+            })
+            .flatMap(c => {
+                const parts = (c as string).split('::')
+                return parts[0] ? [parts[0]] : []
+            })
+
+        const defaultConfig: SafetyGateConfig = {
+            enforceOnSave: true,
+            enforceOnCommit: true,
+            enforceInCI: true,
+            maxRiskScore: 70,
+            maxImpactNodes: 10,
+            requireTestsForChangedFiles: true,
+            requireDocumentationForApiChanges: true,
+            protectedModules,
+        }
+
+        this.safetyGates   = new EnforcedSafetyGates(contract, lock, graph, { ...defaultConfig, ...safetyConfig })
+        this.autoCorrection = new AutoCorrectionEngine(contract, lock, graph, projectRoot)
+    }
+
+    /** Main validation method — call this BEFORE any edit. */
+    async validate(proposal: EditProposal): Promise<ValidationResult> {
+        const { files } = proposal
+
+        // 1. Real impact analysis from the graph
+        const fileNodeIds = this.collectFileNodeIds(files)
+        const impact = fileNodeIds.length > 0
+            ? this.impactAnalyzer.analyze(fileNodeIds)
+            : this.emptyImpact(files)
+
+        // 2. Intent analysis — receives the real ImpactResult so field shapes match
+        const intentAnalysis = this.intentEngine.analyzeIntent(impact, {
+            commitMessage: proposal.intent?.commitMessage,
+            branchName:    proposal.intent?.branchName,
+            author:        proposal.author,
+            filesChanged:  files,
+            changeType:    this.inferChangeType(proposal),
+            confidence:    0.7,
+        })
+
+        // 3. Safety gates
+        const gateResults = await this.safetyGates.validateEdits(files, {
+            commitMessage: proposal.intent?.commitMessage,
+            branchName:    proposal.intent?.branchName,
+        })
+
+        // 4. Auto-correction
+        const corrections = await this.autoCorrection.analyzeAndFix(files)
+
+        // 5. Allowed?
+        const { allowed, blockingGates } = this.safetyGates.canProceed(gateResults)
+
+        // 6. Recommendations
+        const recommendations = this.buildRecommendations(intentAnalysis, impact, gateResults, corrections)
+
+        // 7. Token savings estimate
+        const tokenSavings = this.calculateTokenSavings(files, impact)
+
+        // 8. Impact summary for the response
+        const impactSummary = this.summariseImpact(files, impact)
+
+        return {
+            allowed,
+            confidence: intentAnalysis.confidence,
+
+            intent: {
+                isIntentionalBreakingChange: intentAnalysis.isIntentionalBreakingChange,
+                confidence: intentAnalysis.confidence,
+                reasoning:  intentAnalysis.reasoning,
+                riskAcceptance: intentAnalysis.riskAcceptance,
+            },
+
+            impact: impactSummary,
+
+            gates: gateResults.map(g => ({
+                name:      g.gate,
+                passed:    g.canProceed,
+                severity:  g.severity,
+                message:   g.reason,
+                bypassable: g.bypassable,
+            })),
+
+            corrections: {
+                available:   corrections.issues.length > 0,
+                issuesFound: corrections.issues.length,
+                autoFixable: corrections.appliedFixes.length,
+                applied:     corrections.appliedFixes.slice(0, 5),
+                suggested:   corrections.issues
+                    .filter(i => !i.autoFixable)
+                    .map(i => `${i.file}:${i.line} — ${i.message}`)
+                    .slice(0, 5),
+            },
+
+            recommendations,
+
+            nextSteps: allowed
+                ? ['Proceed with edit', 'Run tests after changes']
+                : [
+                    `Address blocking gates: ${blockingGates.join(', ')}`,
+                    ...gateResults
+                        .filter(g => !g.canProceed && g.suggestedFix)
+                        .map(g => g.suggestedFix!)
+                        .slice(0, 3),
+                ],
+
+            tokenSavings,
+        }
+    }
+
+    // ─── Private helpers ────────────────────────────────────────────────────
+
+    /** Collect graph IDs for every tracked function in the given files. */
+    private collectFileNodeIds(files: string[]): string[] {
+        const ids: string[] = []
+        for (const file of files) {
+            const norm = file.replace(/\\/g, '/')
+            for (const fn of Object.values(this.lock.functions)) {
+                if (fn.file === norm || fn.file.endsWith('/' + norm)) ids.push(fn.id)
+            }
+        }
+        return ids
+    }
+
+    /** Build a zero-impact result when no tracked functions exist. */
+    private emptyImpact(files: string[]): ImpactResult {
+        return {
+            changed:        [],
+            impacted:       [],
+            allImpacted:    [],
+            depth:          0,
+            entryPoints:    [],
+            criticalModules: [],
+            paths:          [],
+            confidence:     1.0,
+            riskScore:      0,
+            classified:     { critical: [], high: [], medium: [], low: [] },
+        }
+    }
+
+    private summariseImpact(files: string[], impact: ImpactResult) {
+        const fileFunctions = this.collectFileNodeIds(files)
+            .map(id => this.lock.functions[id])
+            .filter(Boolean)
+
+        const criticalPaths = fileFunctions
+            .filter(f => f.calledBy.length > 10)
+            .map(f => `${f.moduleId}::${f.name}`)
+            .slice(0, 5)
+
+        const blastRadius = [...new Set(
+            fileFunctions
+                .flatMap(f => f.calledBy)
+                .map(id => this.lock.functions[id])
+                .filter(Boolean)
+                .map(f => `${f.moduleId}::${f.name}`),
+        )].slice(0, 10)
+
+        return {
+            totalFiles:     files.length,
+            totalFunctions: fileFunctions.length,
+            riskScore:      impact.riskScore,
+            criticalPaths,
+            blastRadius,
+        }
+    }
+
+    private buildRecommendations(intent: any, impact: ImpactResult, gates: any[], corrections: any): string[] {
+        const recs: string[] = []
+
+        if (intent.isIntentionalBreakingChange && intent.confidence > 0.7) {
+            recs.push('✓ Breaking change appears intentional — ensure migration guide exists')
+        }
+        if (impact.riskScore > 70) {
+            recs.push('⚠ High risk — consider breaking into smaller changes')
+        }
+
+        const summaryImpact = this.summariseImpact([], impact)
+        if (summaryImpact.criticalPaths.length > 0) {
+            recs.push(`Critical paths affected: ${summaryImpact.criticalPaths.join(', ')}`)
+        }
+
+        const warnings = gates.filter(g => g.severity === 'WARNING' && !g.canProceed)
+        if (warnings.length > 0) {
+            recs.push(`Address warnings: ${warnings.map((w: any) => w.gate).join(', ')}`)
+        }
+        if (corrections.issues.length > 0) {
+            recs.push(`Found ${corrections.issues.length} issue(s) — ${corrections.appliedFixes.length} auto-fixed`)
+        }
+
+        return recs
+    }
+
+    private calculateTokenSavings(files: string[], impact: ImpactResult): number {
+        // Naive estimate: without Mikk the AI reads all impacted + changed files
+        const fileCount = impact.impacted.length + files.length
+        const naiveCost = fileCount * 500
+        return Math.max(0, naiveCost - 500) // 500 tokens for the validation result itself
+    }
+
+    private inferChangeType(proposal: EditProposal): IntentContext['changeType'] {
+        const desc = `${proposal.description} ${proposal.intent?.commitMessage ?? ''}`.toLowerCase()
+        if (desc.includes('refactor') || desc.includes('restructure')) return 'refactor'
+        if (desc.includes('feat') || desc.includes('add') || desc.includes('new')) return 'feature'
+        if (desc.includes('fix') || desc.includes('bug') || desc.includes('patch')) return 'bugfix'
+        if (desc.includes('breaking') || desc.includes('api change')) return 'breaking'
+        return 'unknown'
+    }
+}

package/src/preflight.ts

@@ -1,59 +1,88 @@
-import type { MikkContract, MikkLock } from '@getmikk/core'
+import { 
+    MikkContract, MikkLock, GraphBuilder, ImpactAnalyzer 
+} from '@getmikk/core'
 import { IntentInterpreter } from './interpreter.js'
 import { ConflictDetector } from './conflict-detector.js'
 import { Suggester } from './suggester.js'
+import { DecisionEngine } from './decision-engine.js'
+import { ExplanationEngine } from './explanation-engine.js'
 import type { PreflightResult } from './types.js'
 
 /**
  * PreflightPipeline — orchestrates the full intent pipeline:
- * interpret → conflict-detect → suggest.
- * Single function call for the CLI.
+ * interpret → impact/risk analysis → decide → explain → conflict-detect → suggest.
  */
 export class PreflightPipeline {
-    private interpreter: IntentInterpreter
+    private interpreter:     IntentInterpreter
     private conflictDetector: ConflictDetector
-    private suggester: Suggester
+    private suggester:       Suggester
+    private decisionEngine:  DecisionEngine
+    private explanationEngine: ExplanationEngine
 
     constructor(
         private contract: MikkContract,
-        private lock: MikkLock
+        private lock: MikkLock,
     ) {
-        this.interpreter = new IntentInterpreter(contract, lock)
+        this.interpreter      = new IntentInterpreter(contract, lock)
         this.conflictDetector = new ConflictDetector(contract, lock)
-        this.suggester = new Suggester(contract, lock)
+        this.suggester        = new Suggester(contract, lock)
+        this.decisionEngine   = new DecisionEngine(contract)
+        // Pass lock so ExplanationEngine can resolve module names accurately
+        this.explanationEngine = new ExplanationEngine(lock)
     }
 
-    /** Run the full preflight pipeline */
+    /** Run the full preflight pipeline for a natural-language prompt. */
     async run(prompt: string): Promise<PreflightResult> {
-        // 1. Interpret prompt into structured intents
+        // 1. Interpret prompt → structured intents
         const intents = await this.interpreter.interpret(prompt)
 
-        // 2. Check for conflicts
+        // 2. Build graph from lock (no file re-parsing) and run impact analysis
+        const graph    = new GraphBuilder().buildFromLock(this.lock)
+        const analyzer = new ImpactAnalyzer(graph)
+
+        const targetIds: string[] = []
+        for (const intent of intents) {
+            const match = [...graph.nodes.values()].find(n =>
+                n.name.toLowerCase() === intent.target.name.toLowerCase() &&
+                (intent.target.type === 'function' ? n.type === 'function' : true),
+            )
+            if (match) targetIds.push(match.id)
+        }
+
+        const impact = analyzer.analyze(targetIds)
+
+        // 3. Decide and explain
+        const decision    = this.decisionEngine.evaluate(impact)
+        const explanation = this.explanationEngine.explain(impact, decision)
+
+        // 4. Static conflict detection
         const conflicts = this.conflictDetector.detect(intents)
 
-        // 3. Low-confidence rejection: if the best intent has very low confidence,
-        //    add a warning so the AI doesn't blindly proceed
-        const maxConfidence = intents.length > 0
+        // 5. Low-confidence rejection
+        const maxConf = intents.length > 0
             ? Math.max(...intents.map(i => i.confidence))
             : 0
-        if (maxConfidence < 0.4 && intents.length > 0) {
+
+        if (maxConf < 0.4 && intents.length > 0) {
             conflicts.conflicts.push({
-                type: 'low-confidence',
-                severity: 'warning',
-                message: `Low confidence (${(maxConfidence * 100).toFixed(0)}%) — the intent could not be reliably matched to existing code. The suggestion may be inaccurate.`,
-                relatedIntent: intents[0],
-                suggestedFix: 'Be more specific about the function or module name in your prompt.',
+                type:           'low-confidence',
+                severity:       'warning',
+                message:        `Low confidence (${(maxConf * 100).toFixed(0)}%) — matching to existing code was ambiguous.`,
+                relatedIntent:  intents[0],
+                suggestedFix:   'Be more specific about the function or module name.',
             })
         }
 
-        // 4. Generate suggestions
+        // 6. Implementation suggestions
         const suggestions = this.suggester.suggest(intents)
 
         return {
             intents,
             conflicts,
             suggestions,
-            approved: !conflicts.hasConflicts && maxConfidence >= 0.4,
+            decision,
+            explanation,
+            approved: !conflicts.hasConflicts && decision.status !== 'BLOCKED' && maxConf >= 0.4,
         }
     }
 }

package/src/types.ts

@@ -38,6 +38,25 @@ export interface Suggestion {
     implementation: string
 }
 
+export type DecisionStatus = 'APPROVED' | 'WARNING' | 'BLOCKED';
+
+export interface DecisionResult {
+    status: DecisionStatus
+    reasons: string[]
+    riskScore: number
+    impactNodes: number
+}
+
+export interface Explanation {
+    summary: string
+    details: string[]
+    riskBreakdown: {
+        symbol: string
+        reason: string
+        score: number
+    }[]
+}
+
 /** Configuration for the AI provider */
 export interface AIProviderConfig {
     provider: 'anthropic' | 'openai' | 'local'
@@ -50,5 +69,7 @@ export interface PreflightResult {
     intents: Intent[]
     conflicts: ConflictResult
     suggestions: Suggestion[]
+    decision: DecisionResult
+    explanation: Explanation
     approved: boolean
 }

package/src/xeno-transformers.d.ts

@@ -1,7 +1,7 @@
 /**
- * Ambient stub for the optional peer dependency @xenova/transformers.
- * The real types are only available when the package is installed.
- * We use dynamic import + `any` everywhere so this stub is sufficient.
+ * Ambient stub for the direct dependency @xenova/transformers.
+ * Provides basic types for the library and documents that SemanticSearcher.isAvailable() 
+ * is used to test runtime loadability (e.g. WASM support) for graceful error handling.
  */
 declare module '@xenova/transformers' {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/tests/semantic-searcher.test.ts

@@ -1,6 +1,9 @@
 import { describe, test, expect, beforeAll } from 'bun:test'
 import { SemanticSearcher } from '../src/semantic-searcher'
 import type { MikkLock } from '@getmikk/core'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as fs from 'node:fs/promises'
 
 // ── Minimal mock lock ─────────────────────────────────────────────────────────
 const mockLock: MikkLock = {
@@ -72,9 +75,10 @@ describe('SemanticSearcher', () => {
 
     describe('with indexed lock', () => {
         beforeAll(async () => {
-            searcher = new SemanticSearcher('/tmp/mikk-test-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-test-' + Math.random().toString(36).slice(2))
+            searcher = new SemanticSearcher(uniquePath)
             await searcher.index(mockLock)
-        }, 60_000) // model download can take time on first run
+        }, 120_000) // Increase timeout for CI model download
 
         test('returns results for any query', async () => {
             const results = await searcher.search('authenticate user', mockLock, 4)
@@ -154,25 +158,30 @@ describe('SemanticSearcher', () => {
                 ...mockLock,
                 functions: { ...mockLock.functions, 'fn:new:brandNewFn': newFn },
             }
-            const freshSearcher = new SemanticSearcher('/tmp/mikk-reindex-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-reindex-' + Math.random().toString(36).slice(2))
+            const freshSearcher = new SemanticSearcher(uniquePath)
             await freshSearcher.index(changedLock) // fingerprint differs → full recompute
             const results = await freshSearcher.search('unique purpose', changedLock, 5)
             expect(results.some(r => r.name === 'brandNewFn')).toBe(true)
-        }, 30_000)
+            await fs.rm(uniquePath, { recursive: true, force: true })
+        }, 120_000)
     })
 
     describe('edge cases', () => {
         test('search() before index() throws', async () => {
-            const fresh = new SemanticSearcher('/tmp/mikk-never-indexed-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-never-' + Math.random().toString(36).slice(2))
+            const fresh = new SemanticSearcher(uniquePath)
             await expect(fresh.search('query', mockLock)).rejects.toThrow('Call index() before search()')
         })
 
         test('empty lock: index() and search() succeed, return empty array', async () => {
             const emptyLock: MikkLock = { ...mockLock, functions: {} }
-            const s = new SemanticSearcher('/tmp/mikk-empty-' + Date.now())
+            const uniquePath = path.join(os.tmpdir(), 'mikk-empty-' + Math.random().toString(36).slice(2))
+            const s = new SemanticSearcher(uniquePath)
             await s.index(emptyLock)
             const results = await s.search('anything', emptyLock, 5)
             expect(results).toEqual([])
-        })
+            await fs.rm(uniquePath, { recursive: true, force: true })
+        }, 120_000)
     })
 })