@getmikk/intent-engine 1.9.0 → 1.9.2

package/src/intent-understanding.ts

@@ -0,0 +1,227 @@
+import type { ImpactResult, MikkContract, MikkLock } from '@getmikk/core'
+
+/**
+ * IntentUnderstanding - Analyzes if breaking changes are intentional.
+ *
+ * Understands developer intent through:
+ * 1. Explicit intent declarations ("REFACTOR:", "BREAKING:" in commit messages)
+ * 2. Change pattern analysis (rename vs bugfix vs new feature)
+ * 3. Context clues (branch name, PR description, file patterns)
+ */
+export interface IntentContext {
+    commitMessage?: string
+    branchName?: string
+    prDescription?: string
+    author?: string
+    filesChanged: string[]
+    changeType: 'refactor' | 'feature' | 'bugfix' | 'breaking' | 'unknown'
+    confidence: number
+}
+
+export interface IntentAnalysis {
+    isIntentionalBreakingChange: boolean
+    confidence: number
+    reasoning: string[]
+    suggestedActions: string[]
+    riskAcceptance: 'none' | 'low' | 'medium' | 'high'
+}
+
+export class IntentUnderstanding {
+    constructor(private contract: MikkContract, private lock: MikkLock) {}
+
+    /**
+     * Analyze if breaking changes are intentional based on context.
+     *
+     * NOTE: `impact` is typed as ImpactResult. ClassifiedImpact nodes expose
+     * `nodeId` (not `id` or `functionId`) — all node lookups use that field.
+     */
+    analyzeIntent(impact: ImpactResult, context: Partial<IntentContext> = {}): IntentAnalysis {
+        const reasoning: string[] = []
+        let confidence = 0.5
+        let isIntentional = false
+        let riskAcceptance: IntentAnalysis['riskAcceptance'] = 'none'
+
+        // 1. Check explicit markers in commit message
+        if (context.commitMessage) {
+            const msg = context.commitMessage.toLowerCase()
+            const breakingMarkers = ['breaking:', 'breaking change', 'refactor:', 'migration:', 'api change']
+            const found = breakingMarkers.find(m => msg.includes(m))
+
+            if (found) {
+                isIntentional = true
+                confidence += 0.3
+                reasoning.push(`Explicit breaking change marker found: "${found}"`)
+                riskAcceptance = 'high'
+            }
+
+            const safetyMarkers = ['fix:', 'hotfix:', 'patch:', 'bugfix:']
+            if (safetyMarkers.some(m => msg.includes(m))) {
+                confidence += 0.2
+                reasoning.push('Safety fix detected — changes should be minimal and safe')
+                if (riskAcceptance === 'none') riskAcceptance = 'low'
+            }
+        }
+
+        // 2. Analyze branch naming patterns
+        if (context.branchName) {
+            const branch = context.branchName.toLowerCase()
+            if (branch.includes('refactor') || branch.includes('breaking') || branch.includes('v2')) {
+                isIntentional = true
+                confidence += 0.2
+                reasoning.push(`Branch name "${context.branchName}" suggests intentional restructuring`)
+                if (riskAcceptance === 'none') riskAcceptance = 'medium'
+            }
+            if (branch.includes('hotfix') || branch.includes('patch')) {
+                reasoning.push('Hotfix branch — expect minimal, safe changes')
+                if (riskAcceptance === 'none') riskAcceptance = 'low'
+            }
+        }
+
+        // 3. Analyze change patterns
+        const changePattern = this.analyzeChangePattern(impact, context.filesChanged ?? [])
+        if (changePattern.isRename) {
+            isIntentional = true
+            confidence += 0.15
+            reasoning.push('Pattern suggests systematic rename/refactor')
+        }
+        if (changePattern.isSignatureChange) {
+            reasoning.push('Function signature changes detected')
+            if (!isIntentional) confidence -= 0.1
+        }
+
+        // 4. Check against contract migration policies
+        const migrationPhase = this.detectMigrationPhase(impact)
+        if (migrationPhase === 'planned') {
+            isIntentional = true
+            confidence += 0.25
+            reasoning.push('Changes align with planned migration in contract')
+            riskAcceptance = 'high'
+        }
+
+        // 5. Historical analysis
+        if (context.author) {
+            const pattern = this.analyzeAuthorPattern(context.author)
+            if (pattern === 'careful') {
+                confidence += 0.1
+                reasoning.push(`${context.author} has history of careful, safe changes`)
+            }
+        }
+
+        confidence = Math.max(0, Math.min(1, confidence))
+
+        const suggestedActions = this.generateSuggestions(impact, isIntentional, confidence, riskAcceptance)
+
+        return { isIntentionalBreakingChange: isIntentional, confidence, reasoning, suggestedActions, riskAcceptance }
+    }
+
+    // ─── Private helpers ───────────────────────────────────────────────────
+
+    private detectMigrationPhase(impact: ImpactResult): 'none' | 'planned' {
+        const decisions = this.contract.declared?.decisions ?? []
+
+        for (const decision of decisions) {
+            const text = `${decision.title ?? ''} ${decision.reason ?? ''}`.toLowerCase()
+            if (!text.includes('migration') && !text.includes('deprecat')) continue
+
+            // Use `nodeId` — the correct field on ClassifiedImpact
+            const affectedModules = new Set<string>()
+            for (const node of impact.allImpacted) {
+                const fn = this.lock.functions[node.nodeId]
+                if (fn?.moduleId) affectedModules.add(fn.moduleId)
+            }
+
+            const decisionModules = this.extractModulesFromDecision(`${decision.title ?? ''} ${decision.reason ?? ''}`)
+            if ([...affectedModules].some(m => decisionModules.includes(m))) return 'planned'
+        }
+
+        return 'none'
+    }
+
+    private extractModulesFromDecision(decision: string): string[] {
+        const modules = this.contract.declared?.modules ?? []
+        const mentioned: string[] = []
+        for (const mod of modules) {
+            if (
+                decision.toLowerCase().includes(mod.id.toLowerCase()) ||
+                decision.toLowerCase().includes(mod.name.toLowerCase())
+            ) {
+                mentioned.push(mod.id)
+            }
+        }
+        return mentioned
+    }
+
+    private analyzeChangePattern(
+        impact: ImpactResult,
+        filesChanged: string[],
+    ): { isRename: boolean; isSignatureChange: boolean; isNewFeature: boolean } {
+        const result = { isRename: false, isSignatureChange: false, isNewFeature: false }
+
+        const lockFilePaths = new Set(Object.keys(this.lock.files))
+        const norm = (f: string) => f.replace(/\\/g, '/')
+        const deletedFiles = filesChanged.filter(f => !lockFilePaths.has(norm(f)))
+        const addedFiles   = filesChanged.filter(f =>  lockFilePaths.has(norm(f)))
+
+        if (deletedFiles.length > 0 && addedFiles.length > 0) {
+            for (const deleted of deletedFiles) {
+                const base = deleted.split('/').pop()?.split('.')[0]
+                if (base && addedFiles.some(a => norm(a).includes(base))) {
+                    result.isRename = true
+                    break
+                }
+            }
+        }
+
+        // Use `nodeId` — correct field on ClassifiedImpact
+        for (const node of impact.allImpacted) {
+            const fn = this.lock.functions[node.nodeId]
+            if (fn?.params && fn.params.length > 0) {
+                result.isSignatureChange = true
+                break
+            }
+        }
+
+        const newExports = filesChanged.flatMap(file => {
+            const n = norm(file)
+            return Object.values(this.lock.functions).filter(
+                f => (f.file === n || f.file.endsWith('/' + n)) && f.isExported && f.calledBy.length === 0,
+            )
+        })
+        if (newExports.length > 3) result.isNewFeature = true
+
+        return result
+    }
+
+    private analyzeAuthorPattern(_author: string): 'careful' | 'normal' | 'aggressive' {
+        return 'normal'
+    }
+
+    private generateSuggestions(
+        impact: ImpactResult,
+        isIntentional: boolean,
+        confidence: number,
+        riskAcceptance: IntentAnalysis['riskAcceptance'],
+    ): string[] {
+        const out: string[] = []
+
+        if (isIntentional && confidence > 0.7) {
+            out.push('✓ Breaking change appears intentional — proceeding with caution')
+            if (impact.impacted.length > 10) out.push('Consider breaking this into smaller PRs for easier review')
+            out.push('Ensure tests exist for all impacted call paths')
+            out.push('Update relevant documentation for API changes')
+            if (riskAcceptance === 'high') out.push('Schedule deployment during low-traffic period')
+        } else if (impact.riskScore > 80) {
+            out.push('⚠ HIGH RISK: Breaking changes without explicit intent detected')
+            out.push('Add "BREAKING:" prefix to commit message if intentional')
+            out.push('Run full test suite before committing')
+            out.push('Consider creating a migration guide for consumers')
+        } else if (impact.impacted.length > 5) {
+            out.push('Review impacted functions to ensure changes are necessary')
+            out.push('Check if any changes can be made backward-compatible')
+        } else {
+            out.push('Changes appear low-risk — standard review process recommended')
+        }
+
+        return out
+    }
+}

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

@@ -6,75 +6,74 @@ 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, DecisionResult, Explanation } from './types.js'
+import type { PreflightResult } from './types.js'
 
 /**
  * PreflightPipeline — orchestrates the full intent pipeline:
- * interpret → analyze (impact/risk) → decide → explain → conflict-detect → suggest.
+ * 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 decisionEngine: DecisionEngine
+    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.decisionEngine = new DecisionEngine(contract)
-        this.explanationEngine = new ExplanationEngine()
+        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. Perform Quantitative Impact Analysis
-        const graph = new GraphBuilder().buildFromLock(this.lock)
+        // 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)
-        
-        // 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)
+            const match = [...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)
+            if (match) targetIds.push(match.id)
         }
 
         const impact = analyzer.analyze(targetIds)
 
-        // 3. Decide and Explain
-        const decision = this.decisionEngine.evaluate(impact)
+        // 3. Decide and explain
+        const decision    = this.decisionEngine.evaluate(impact)
         const explanation = this.explanationEngine.explain(impact, decision)
 
-        // 4. Check for Static Conflicts
+        // 4. Static conflict detection
         const conflicts = this.conflictDetector.detect(intents)
 
-        // 5. Low-confidence rejection / Supplemental warnings
-        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)}%) — matching to existing code was ambiguous.`,
-                relatedIntent: intents[0],
-                suggestedFix: 'Be more specific about the function or module name.',
+                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.',
             })
         }
 
-        // 6. Generate implementation suggestions
+        // 6. Implementation suggestions
         const suggestions = this.suggester.suggest(intents)
 
         return {
@@ -83,7 +82,7 @@ export class PreflightPipeline {
             suggestions,
             decision,
             explanation,
-            approved: !conflicts.hasConflicts && decision.status !== 'BLOCKED' && maxConfidence >= 0.4,
+            approved: !conflicts.hasConflicts && decision.status !== 'BLOCKED' && maxConf >= 0.4,
         }
     }
 }