@getmikk/intent-engine 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/intent-engine",
-    "version": "1.8.0",
+    "version": "1.9.0",
     "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/decision-engine.ts

@@ -0,0 +1,69 @@
+import type { ImpactResult, MikkContract } from '@getmikk/core'
+import type { DecisionResult, DecisionStatus } from './types.js'
+
+/**
+ * DecisionEngine — the "Brain" of Mikk 2.0.
+ * Evaluates quantitative impact analysis against project policies.
+ */
+export class DecisionEngine {
+    constructor(private contract: MikkContract) {}
+
+    /**
+     * Evaluate an impact result against the defined policies.
+     */
+    evaluate(impact: ImpactResult): DecisionResult {
+        const policy = {
+            maxRiskScore: this.contract.policies?.maxRiskScore ?? 70,
+            maxImpactNodes: this.contract.policies?.maxImpactNodes ?? 10,
+            protectedModules: this.contract.policies?.protectedModules ?? [],
+            enforceStrictBoundaries: this.contract.policies?.enforceStrictBoundaries ?? false,
+        };
+        const reasons: string[] = [];
+        let status: DecisionStatus = 'APPROVED';
+
+        const maxRisk = impact.riskScore;
+        const impactCount = impact.impacted.length;
+
+        // 1. Check absolute risk threshold
+        if (maxRisk >= 90) {
+            status = 'BLOCKED';
+            reasons.push(`Critical risk detected (${maxRisk}/100). Policy strictly blocks changes exceeding 90 risk.`);
+        } else if (maxRisk > policy.maxRiskScore) {
+            status = 'WARNING';
+            reasons.push(`High risk (${maxRisk}) exceeds policy threshold of ${policy.maxRiskScore}.`);
+        }
+
+        // 2. Check impact scale
+        if (impactCount > policy.maxImpactNodes) {
+             status = status === 'BLOCKED' ? 'BLOCKED' : 'WARNING';
+             reasons.push(`Impact spread (${impactCount} symbols) exceeds propagation limit of ${policy.maxImpactNodes}.`);
+        }
+
+        // 3. Check protected modules
+        const touchedProtectedModules = impact.allImpacted
+            .filter(node => node.risk === 'CRITICAL' || node.risk === 'HIGH')
+            .map(node => {
+                return policy.protectedModules.find(pm => node.file.toLowerCase().includes(pm.toLowerCase()));
+            })
+            .filter((m): m is string => !!m);
+
+        const uniqueProtected = [...new Set(touchedProtectedModules)];
+        if (uniqueProtected.length > 0) {
+            status = status === 'BLOCKED' ? 'BLOCKED' : 'WARNING';
+            reasons.push(`Change affects protected modules: ${uniqueProtected.join(', ')}.`);
+        }
+
+        // 4. Force BLOCKED for critical cross-boundary impacts if enforcement is on
+        if (policy.enforceStrictBoundaries && impact.classified.critical.length > 0) {
+            status = 'BLOCKED';
+            reasons.push(`Strict boundary enforcement: ${impact.classified.critical.length} critical cross-module impact(s) detected.`);
+        }
+
+        return {
+            status,
+            reasons,
+            riskScore: maxRisk,
+            impactNodes: impactCount
+        };
+    }
+}

package/src/explanation-engine.ts

@@ -0,0 +1,80 @@
+import type { ImpactResult } from '@getmikk/core'
+import type { DecisionResult, Explanation } from './types.js'
+
+/**
+ * ExplanationEngine — generates human-readable reasoning for code modification decisions.
+ * Explains WHY a change is safe or risky based on the quantitative graph analysis.
+ */
+export class ExplanationEngine {
+    /**
+     * Generate an explanation for the decision and impact.
+     */
+    explain(impact: ImpactResult, decision: DecisionResult): Explanation {
+        const summary = this.getSummary(decision);
+        const details = this.getDetails(impact, decision);
+        const riskBreakdown = this.getRiskBreakdown(impact);
+
+        return {
+            summary,
+            details,
+            riskBreakdown
+        };
+    }
+
+    private getSummary(decision: DecisionResult): string {
+        switch (decision.status) {
+            case 'APPROVED': return 'This change is safe and conforms to project policies.';
+            case 'WARNING': return 'Change detected with non-trivial impact — proceed with caution.';
+            case 'BLOCKED': return 'MODIFICATION BLOCKED: This change violates safety or architectural policies.';
+        }
+    }
+
+    private getDetails(impact: ImpactResult, decision: DecisionResult): string[] {
+        const details: string[] = [];
+
+        if (impact.allImpacted.length === 0) {
+            details.push('No downstream symbols are affected by this change.');
+        } else {
+            details.push(`Affects ${impact.allImpacted.length} symbols across ${this.countModules(impact)} modules.`);
+            details.push(`Maximum risk score is ${impact.riskScore}/100.`);
+        }
+
+        if (impact.classified.critical.length > 0) {
+            details.push(`⚠ Critical: affects ${impact.classified.critical.length} symbols in separate modules.`);
+        }
+
+        if (decision.reasons.length > 0) {
+            decision.reasons.forEach(r => details.push(`Policy: ${r}`));
+        }
+
+        return details;
+    }
+
+    private getRiskBreakdown(impact: ImpactResult): { symbol: string; reason: string; score: number }[] {
+        // Return top 3 riskiest affected symbols
+        return impact.allImpacted
+            .sort((a, b) => b.riskScore - a.riskScore)
+            .slice(0, 3)
+            .map(node => ({
+                symbol: node.label,
+                score: node.riskScore,
+                reason: this.getRiskReason(node.riskScore)
+            }));
+    }
+
+    private getRiskReason(score: number): string {
+        if (score >= 90) return 'Direct critical dependency in protected module';
+        if (score >= 80) return 'Large downstream reach (potential side effects)';
+        if (score >= 60) return 'Cross-module propagation';
+        return 'Standard functional dependency';
+    }
+
+    private countModules(impact: ImpactResult): number {
+        const modules = new Set(impact.allImpacted.map(n => {
+            // Heuristic to extract module from file path if moduleId not present
+            const parts = n.file.split('/');
+            return parts.length > 1 ? parts[0] : 'root';
+        }));
+        return modules.size;
+    }
+}

package/src/preflight.ts

@@ -1,18 +1,23 @@
-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 type { PreflightResult } from './types.js'
+import { DecisionEngine } from './decision-engine.js'
+import { ExplanationEngine } from './explanation-engine.js'
+import type { PreflightResult, DecisionResult, Explanation } from './types.js'
 
 /**
  * PreflightPipeline — orchestrates the full intent pipeline:
- * interpret → conflict-detect → suggest.
- * Single function call for the CLI.
+ * interpret → analyze (impact/risk) → decide → explain → conflict-detect → suggest.
  */
 export class PreflightPipeline {
     private interpreter: IntentInterpreter
     private conflictDetector: ConflictDetector
     private suggester: Suggester
+    private decisionEngine: DecisionEngine
+    private explanationEngine: ExplanationEngine
 
     constructor(
         private contract: MikkContract,
@@ -21,6 +26,8 @@ export class PreflightPipeline {
         this.interpreter = new IntentInterpreter(contract, lock)
         this.conflictDetector = new ConflictDetector(contract, lock)
         this.suggester = new Suggester(contract, lock)
+        this.decisionEngine = new DecisionEngine(contract)
+        this.explanationEngine = new ExplanationEngine()
     }
 
     /** Run the full preflight pipeline */
@@ -28,11 +35,32 @@ export class PreflightPipeline {
         // 1. Interpret prompt into structured intents
         const intents = await this.interpreter.interpret(prompt)
 
-        // 2. Check for conflicts
+        // 2. Perform Quantitative Impact Analysis
+        const graph = new GraphBuilder().buildFromLock(this.lock)
+        const analyzer = new ImpactAnalyzer(graph)
+        
+        // Find node IDs for the intents
+        const targetIds: string[] = []
+        for (const intent of intents) {
+            // Find better match by checking both name and type
+            // In Mikk 2.0, we have IDs like fn:src/file.ts:name
+            const matchedNode = [...graph.nodes.values()].find(n => 
+                n.name.toLowerCase() === intent.target.name.toLowerCase() && 
+                (intent.target.type === 'function' ? n.type === 'function' : true)
+            )
+            if (matchedNode) targetIds.push(matchedNode.id)
+        }
+
+        const impact = analyzer.analyze(targetIds)
+
+        // 3. Decide and Explain
+        const decision = this.decisionEngine.evaluate(impact)
+        const explanation = this.explanationEngine.explain(impact, decision)
+
+        // 4. Check for Static Conflicts
         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
+        // 5. Low-confidence rejection / Supplemental warnings
         const maxConfidence = intents.length > 0
             ? Math.max(...intents.map(i => i.confidence))
             : 0
@@ -40,20 +68,22 @@ export class PreflightPipeline {
             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.`,
+                message: `Low confidence (${(maxConfidence * 100).toFixed(0)}%) — matching to existing code was ambiguous.`,
                 relatedIntent: intents[0],
-                suggestedFix: 'Be more specific about the function or module name in your prompt.',
+                suggestedFix: 'Be more specific about the function or module name.',
             })
         }
 
-        // 4. Generate suggestions
+        // 6. Generate 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' && maxConfidence >= 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)
     })
 })