@getmikk/intent-engine 1.9.0 → 1.9.1

package/src/decision-engine.ts

@@ -2,68 +2,73 @@ 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.
+ * 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 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 ?? [],
+            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 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}.`);
+        const reasons: string[] = []
+        let status: DecisionStatus = 'APPROVED'
+        const promote = (next: DecisionStatus) => {
+            if (next === 'BLOCKED' || (next === 'WARNING' && status === 'APPROVED')) status = next
         }
 
-        // 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}.`);
+        // 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}.`)
         }
 
-        // 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);
+        // 2. Impact scale
+        if (impact.impacted.length > policy.maxImpactNodes) {
+            promote('WARNING')
+            reasons.push(`Impact spread (${impact.impacted.length} symbols) exceeds limit of ${policy.maxImpactNodes}.`)
+        }
 
-        const uniqueProtected = [...new Set(touchedProtectedModules)];
-        if (uniqueProtected.length > 0) {
-            status = status === 'BLOCKED' ? 'BLOCKED' : 'WARNING';
-            reasons.push(`Change affects protected modules: ${uniqueProtected.join(', ')}.`);
+        // 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. Force BLOCKED for critical cross-boundary impacts if enforcement is on
+        // 4. Strict boundary enforcement
         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.`);
+            promote('BLOCKED')
+            reasons.push(
+                `Strict boundary enforcement: ${impact.classified.critical.length} critical cross-module impact(s) detected.`,
+            )
         }
 
-        return {
-            status,
-            reasons,
-            riskScore: maxRisk,
-            impactNodes: impactCount
-        };
+        return { status, reasons, riskScore: impact.riskScore, impactNodes: impact.impacted.length }
     }
 }

package/src/enforced-safety.ts

@@ -0,0 +1,305 @@
+import type { MikkContract, MikkLock, DependencyGraph } from '@getmikk/core'
+import { ImpactAnalyzer } from '@getmikk/core'
+
+/**
+ * EnforcedSafetyGates — blocks unsafe edits at edit-time.
+ *
+ * Unlike warnings, blocking gates PREVENT edits from being applied
+ * unless explicitly bypassed.
+ *
+ * Integration points:
+ * - Pre-commit hooks
+ * - IDE save handlers
+ * - CI/CD gates
+ * - MCP tool validation (mikk_before_edit)
+ */
+export interface SafetyGateResult {
+    canProceed: boolean
+    gate: string
+    reason: string
+    severity: 'BLOCKING' | 'WARNING'
+    bypassable: boolean
+    bypassCommand?: string
+    autoFixable: boolean
+    suggestedFix?: string
+}
+
+export interface SafetyGateConfig {
+    enforceOnSave: boolean
+    enforceOnCommit: boolean
+    enforceInCI: boolean
+    maxRiskScore: number
+    maxImpactNodes: number
+    requireTestsForChangedFiles: boolean
+    requireDocumentationForApiChanges: boolean
+    protectedModules: string[]
+}
+
+export class EnforcedSafetyGates {
+    private analyzer: ImpactAnalyzer
+
+    constructor(
+        private contract: MikkContract,
+        private lock: MikkLock,
+        graph: DependencyGraph,
+        private config: SafetyGateConfig,
+    ) {
+        this.analyzer = new ImpactAnalyzer(graph)
+    }
+
+    /** Run all safety gates before allowing edits. */
+    async validateEdits(
+        files: string[],
+        context?: { commitMessage?: string; branchName?: string; isTestRun?: boolean },
+    ): Promise<SafetyGateResult[]> {
+        return [
+            await this.checkRiskGate(files),
+            await this.checkScaleGate(files),
+            await this.checkProtectedModuleGate(files),
+            await this.checkBreakingChangeGate(files, context),
+            await this.checkTestCoverageGate(files),
+            await this.checkDocumentationGate(files),
+        ]
+    }
+
+    /** Returns whether all blocking gates passed. */
+    canProceed(results: SafetyGateResult[]): { allowed: boolean; blockingGates: string[] } {
+        const blocking = results.filter(r => !r.canProceed && r.severity === 'BLOCKING')
+        return { allowed: blocking.length === 0, blockingGates: blocking.map(r => r.gate) }
+    }
+
+    // ─── Gate implementations ──────────────────────────────────────────────
+
+    private async checkRiskGate(files: string[]): Promise<SafetyGateResult> {
+        const fileNodes = this.getFileNodes(files)
+
+        if (fileNodes.length === 0) {
+            return this.pass('RISK_SCORE', 'No tracked functions in modified files')
+        }
+
+        const impact = this.analyzer.analyze(fileNodes.map(n => n.id))
+        const risk = impact.riskScore
+
+        if (risk >= 90) {
+            return {
+                canProceed: false,
+                gate: 'RISK_SCORE',
+                reason: `Critical risk score: ${risk}/100. Changes could break significant portions of the system.`,
+                severity: 'BLOCKING',
+                bypassable: false,
+                autoFixable: false,
+                suggestedFix: 'Break changes into smaller increments or add comprehensive tests',
+            }
+        }
+        if (risk > this.config.maxRiskScore) {
+            return {
+                canProceed: false,
+                gate: 'RISK_SCORE',
+                reason: `High risk: ${risk}/100 exceeds threshold of ${this.config.maxRiskScore}`,
+                severity: 'BLOCKING',
+                bypassable: true,
+                bypassCommand: 'mikk safety bypass --gate=RISK_SCORE --reason="<explanation>"',
+                autoFixable: false,
+            }
+        }
+
+        return this.pass('RISK_SCORE', `Risk score ${risk} within acceptable limits`)
+    }
+
+    private async checkScaleGate(files: string[]): Promise<SafetyGateResult> {
+        const fileNodes = this.getFileNodes(files)
+
+        if (fileNodes.length === 0) {
+            return this.pass('IMPACT_SCALE', 'No tracked functions in modified files')
+        }
+
+        const impact = this.analyzer.analyze(fileNodes.map(n => n.id))
+        const count = impact.impacted.length
+        const hardLimit = this.config.maxImpactNodes * 2
+
+        if (count > hardLimit) {
+            return {
+                canProceed: false,
+                gate: 'IMPACT_SCALE',
+                reason: `Massive blast radius: ${count} functions affected. Hard limit: ${hardLimit}`,
+                severity: 'BLOCKING',
+                bypassable: false,
+                autoFixable: false,
+                suggestedFix: 'Split into multiple PRs or create a migration plan',
+            }
+        }
+        if (count > this.config.maxImpactNodes) {
+            return {
+                canProceed: false,
+                gate: 'IMPACT_SCALE',
+                reason: `Large impact: ${count} functions affected. Threshold: ${this.config.maxImpactNodes}`,
+                severity: 'BLOCKING',
+                bypassable: true,
+                bypassCommand: 'mikk safety bypass --gate=IMPACT_SCALE --reason="<explanation>"',
+                autoFixable: false,
+            }
+        }
+
+        return this.pass('IMPACT_SCALE', `Impact scale acceptable: ${count} functions`)
+    }
+
+    private async checkProtectedModuleGate(files: string[]): Promise<SafetyGateResult> {
+        const touchedProtected: string[] = []
+
+        for (const file of files) {
+            const norm = file.replace(/\\/g, '/')
+            const fileEntry = Object.values(this.lock.files).find(
+                f => f.path === norm || norm.endsWith(f.path),
+            )
+            // Guard: moduleId may be absent on file entries
+            if (fileEntry?.moduleId && this.config.protectedModules.includes(fileEntry.moduleId)) {
+                touchedProtected.push(fileEntry.moduleId)
+            }
+        }
+
+        const unique = [...new Set(touchedProtected)]
+        if (unique.length > 0) {
+            return {
+                canProceed: false,
+                gate: 'PROTECTED_MODULE',
+                reason: `Modified protected modules: ${unique.join(', ')}. These require architecture review.`,
+                severity: 'BLOCKING',
+                bypassable: false,
+                autoFixable: false,
+                suggestedFix: 'Request architecture review or schedule a change review meeting',
+            }
+        }
+
+        return this.pass('PROTECTED_MODULE', 'No protected modules touched')
+    }
+
+    private async checkBreakingChangeGate(
+        files: string[],
+        context?: { commitMessage?: string; branchName?: string },
+    ): Promise<SafetyGateResult> {
+        const fileNodes = this.getFileNodes(files)
+
+        // An exported function with callers is a breaking-change candidate
+        const exportedWithCallers = fileNodes.filter(n => {
+            const fn = this.lock.functions[n.id]
+            return fn?.isExported && fn.calledBy.length > 0
+        })
+
+        if (exportedWithCallers.length === 0) {
+            return this.pass('BREAKING_CHANGE', 'No exported API changes with existing callers detected')
+        }
+
+        const hasExplicitIntent =
+            context?.commitMessage?.toLowerCase().includes('breaking:') ||
+            context?.branchName?.toLowerCase().includes('breaking') ||
+            context?.commitMessage?.toLowerCase().includes('api change')
+
+        if (hasExplicitIntent) {
+            return this.pass(
+                'BREAKING_CHANGE',
+                `Exported API changes (${exportedWithCallers.length} functions) with explicit breaking intent`,
+            )
+        }
+
+        return {
+            canProceed: false,
+            gate: 'BREAKING_CHANGE',
+            reason: `${exportedWithCallers.length} exported function(s) with callers modified without explicit intent marker. Add "BREAKING:" to commit message.`,
+            severity: 'BLOCKING',
+            bypassable: true,
+            bypassCommand: 'git commit -m "BREAKING: <your message>"',
+            autoFixable: false,
+        }
+    }
+
+    private async checkTestCoverageGate(files: string[]): Promise<SafetyGateResult> {
+        if (!this.config.requireTestsForChangedFiles) {
+            return this.pass('TEST_COVERAGE', 'Test coverage gate disabled')
+        }
+
+        const fileNodes = this.getFileNodes(files)
+        if (fileNodes.length === 0) return this.pass('TEST_COVERAGE', 'No tracked functions in modified files')
+
+        const impact = this.analyzer.analyze(fileNodes.map(n => n.id))
+
+        const highRisk = impact.impacted.filter(id => {
+            const fn = this.lock.functions[id]
+            return fn && (fn.calledBy.length > 10 || fn.isExported)
+        })
+
+        const hasTests = files.some(
+            f => f.includes('.test.') || f.includes('.spec.') || f.includes('__tests__'),
+        )
+
+        if (highRisk.length > 0 && !hasTests) {
+            return {
+                canProceed: false,
+                gate: 'TEST_COVERAGE',
+                reason: `${highRisk.length} high-risk change(s) without test modifications`,
+                severity: 'BLOCKING',
+                bypassable: true,
+                bypassCommand: 'mikk safety bypass --gate=TEST_COVERAGE',
+                autoFixable: true,
+                suggestedFix: 'Add tests for changed functions or affected call paths',
+            }
+        }
+
+        return this.pass(
+            'TEST_COVERAGE',
+            hasTests ? 'Tests modified alongside changes' : 'No high-risk changes requiring tests',
+        )
+    }
+
+    private async checkDocumentationGate(files: string[]): Promise<SafetyGateResult> {
+        if (!this.config.requireDocumentationForApiChanges) {
+            return this.pass('DOCUMENTATION', 'Documentation gate disabled')
+        }
+
+        const docFiles = ['README.md', 'API.md', 'CHANGELOG.md', 'AGENTS.md']
+        const docsUpdated = files.some(f => docFiles.some(d => f.endsWith(d)))
+
+        const fileNodes = this.getFileNodes(files)
+        const hasSignificantApiChanges = fileNodes.some(n => {
+            const fn = this.lock.functions[n.id]
+            return fn?.isExported && fn.calledBy.length > 5
+        })
+
+        if (hasSignificantApiChanges && !docsUpdated) {
+            return {
+                canProceed: false,
+                gate: 'DOCUMENTATION',
+                reason: 'Significant API changes detected without documentation updates',
+                severity: 'BLOCKING',
+                bypassable: true,
+                bypassCommand: 'mikk safety bypass --gate=DOCUMENTATION',
+                autoFixable: false,
+                suggestedFix: 'Update README.md, API.md, or AGENTS.md with the changes',
+            }
+        }
+
+        return this.pass(
+            'DOCUMENTATION',
+            docsUpdated ? 'Documentation updated' : 'No significant API changes requiring docs',
+        )
+    }
+
+    // ─── Helpers ───────────────────────────────────────────────────────────
+
+    /** Collect graph-node IDs for every tracked function in the given files. */
+    private getFileNodes(files: string[]): Array<{ id: string }> {
+        const nodes: Array<{ id: 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)) {
+                    nodes.push({ id: fn.id })
+                }
+            }
+        }
+        return nodes
+    }
+
+    private pass(gate: string, reason: string): SafetyGateResult {
+        return { canProceed: true, gate, reason, severity: 'WARNING', bypassable: true, autoFixable: false }
+    }
+}

package/src/explanation-engine.ts

@@ -1,4 +1,4 @@
-import type { ImpactResult } from '@getmikk/core'
+import type { ImpactResult, MikkLock } from '@getmikk/core'
 import type { DecisionResult, Explanation } from './types.js'
 
 /**
@@ -7,74 +7,94 @@ import type { DecisionResult, Explanation } from './types.js'
  */
 export class ExplanationEngine {
     /**
-     * Generate an explanation for the decision and impact.
+     * @param lock  Optional lock reference — used to resolve module names accurately.
+     *              If omitted, module count is estimated from file paths.
      */
-    explain(impact: ImpactResult, decision: DecisionResult): Explanation {
-        const summary = this.getSummary(decision);
-        const details = this.getDetails(impact, decision);
-        const riskBreakdown = this.getRiskBreakdown(impact);
+    constructor(private lock?: MikkLock) {}
 
+    explain(impact: ImpactResult, decision: DecisionResult): Explanation {
         return {
-            summary,
-            details,
-            riskBreakdown
-        };
+            summary:       this.getSummary(decision),
+            details:       this.getDetails(impact, decision),
+            riskBreakdown: this.getRiskBreakdown(impact),
+        }
     }
 
     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.';
+            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[] = [];
+        const details: string[] = []
 
         if (impact.allImpacted.length === 0) {
-            details.push('No downstream symbols are affected by this change.');
+            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.`);
+            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.`);
+            details.push(`⚠ Critical: affects ${impact.classified.critical.length} symbol(s) in separate modules.`)
         }
 
-        if (decision.reasons.length > 0) {
-            decision.reasons.forEach(r => details.push(`Policy: ${r}`));
+        for (const r of decision.reasons) {
+            details.push(`Policy: ${r}`)
         }
 
-        return details;
+        return details
     }
 
     private getRiskBreakdown(impact: ImpactResult): { symbol: string; reason: string; score: number }[] {
-        // Return top 3 riskiest affected symbols
-        return impact.allImpacted
+        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)
-            }));
+                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';
+        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'
     }
 
+    /**
+     * Count distinct modules touched by the impact set.
+     *
+     * Preference order:
+     *  1. lock.functions[nodeId].moduleId  — accurate
+     *  2. heuristic from file path         — fallback when lock is absent
+     */
     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;
+        const modules = new Set<string>()
+
+        for (const node of impact.allImpacted) {
+            let moduleId: string | undefined
+
+            // Try to resolve via lock first
+            if (this.lock) {
+                moduleId = this.lock.functions[node.nodeId]?.moduleId
+            }
+
+            if (!moduleId) {
+                // Fallback: first meaningful path segment after stripping common prefixes
+                const parts = node.file.replace(/\\/g, '/').split('/')
+                const segIdx = parts.findIndex(p => p !== 'src' && p !== 'packages' && p !== 'apps')
+                moduleId = segIdx >= 0 ? parts[segIdx] : (parts[0] ?? 'root')
+            }
+
+            modules.add(moduleId)
+        }
+
+        return modules.size
     }
 }

package/src/index.ts

@@ -3,6 +3,16 @@ export { ConflictDetector } from './conflict-detector.js'
 export { Suggester } from './suggester.js'
 export { PreflightPipeline } from './preflight.js'
 export { SemanticSearcher } from './semantic-searcher.js'
+export { IntentUnderstanding } from './intent-understanding.js'
+export { AutoCorrectionEngine } from './auto-correction.js'
+export { EnforcedSafetyGates } from './enforced-safety.js'
+export { PreEditValidation } from './pre-edit-validation.js'
+
 export type { SemanticMatch } from './semantic-searcher.js'
+export type { IntentContext, IntentAnalysis } from './intent-understanding.js'
+export type { CorrectionIssue, CorrectionResult } from './auto-correction.js'
+export type { SafetyGateResult, SafetyGateConfig } from './enforced-safety.js'
+export type { EditProposal, ValidationResult } from './pre-edit-validation.js'
+
 export type { Intent, Conflict, ConflictResult, Suggestion, PreflightResult, AIProviderConfig } from './types.js'
 export { IntentSchema } from './types.js'