@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/plan-generator.js

@@ -0,0 +1,658 @@
+/**
+ * Plan generation service for creating structured implementation plans.
+ *
+ * This service generates detailed implementation plans informed by:
+ * - Context gathering results
+ * - Complexity analysis
+ * - Clarification answers (if any)
+ */
+import { v4 as uuidv4 } from 'uuid';
+import chalk from 'chalk';
+import { formatTimestamp } from '../utils/format.js';
+import { logger } from '../utils/logger.js';
+import { getSystemEventLogger } from './system-event-logger.js';
+const DEFAULT_OPTIONS = {
+    includeTestingPlan: true,
+    maxTasks: 20,
+    includeEdgeCases: true,
+    verboseDescriptions: true,
+};
+/**
+ * PlanGenerator creates structured implementation plans
+ * based on context, complexity, and clarification results.
+ */
+class PlanGenerator {
+    /**
+     * Generates an implementation plan.
+     */
+    generatePlan(context, complexity, clarification, options = {}) {
+        const startTime = Date.now();
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        logger.info('Generating implementation plan');
+        // Extract requirements
+        const requirements = this.extractRequirements(context, clarification);
+        // Generate problem statement
+        const problemStatement = this.generateProblemStatement(context, clarification);
+        // Identify edge cases
+        const edgeCases = opts.includeEdgeCases
+            ? this.identifyEdgeCases(context, requirements)
+            : [];
+        // Generate constraints and assumptions
+        const { constraints, assumptions } = this.generateConstraintsAndAssumptions(context, complexity, clarification);
+        // Determine file operations
+        const fileOperations = this.determineFileOperations(context, requirements);
+        // Generate tasks
+        const tasks = this.generateTasks(context, requirements, fileOperations, clarification, opts);
+        // Analyze risks
+        const risks = this.analyzeRisks(context, complexity, tasks);
+        // Generate testing requirements
+        const testing = opts.includeTestingPlan
+            ? this.generateTestingRequirements(tasks, context)
+            : { unitTests: [], integrationTests: [], testFiles: [], suggestedTests: [] };
+        // Generate impact assessment
+        const impact = this.generateImpactAssessment(fileOperations, context);
+        // Generate rollback strategy
+        const rollbackStrategy = this.generateRollbackStrategy(tasks, fileOperations);
+        // Calculate total complexity
+        const totalComplexity = this.calculateTotalComplexity(tasks, risks);
+        // Generate summary
+        const summary = this.generateSummary(problemStatement, tasks, risks, clarification);
+        // Generate title from problem statement
+        const title = problemStatement.split(/[.!?\n]/)[0].trim().substring(0, 80) || 'Implementation Plan';
+        const plan = {
+            id: uuidv4(),
+            createdAt: formatTimestamp(),
+            version: 1,
+            title,
+            problemStatement,
+            requirements,
+            edgeCases,
+            constraints,
+            assumptions,
+            impact,
+            tasks,
+            risks,
+            testing,
+            rollbackStrategy,
+            totalComplexity,
+            summary,
+        };
+        logger.info(`Plan generated with ${tasks.length} tasks`);
+        // Log the plan generation event
+        const systemEventLogger = getSystemEventLogger();
+        systemEventLogger.logPlanGenerated({
+            taskDescription: context.userRequest.substring(0, 100),
+            stepCount: tasks.length,
+            duration_ms: Date.now() - startTime,
+            contextFilesUsed: context.relevantFiles.length,
+        });
+        return plan;
+    }
+    /**
+     * Extracts requirements from context and clarification.
+     */
+    extractRequirements(context, clarification) {
+        const requirements = [];
+        let priority = 1;
+        // Primary requirement from user request
+        requirements.push({
+            id: `req-${uuidv4().slice(0, 8)}`,
+            description: context.userRequest,
+            priority: priority++,
+            source: 'user',
+        });
+        // Infer requirements from affected areas
+        for (const area of context.affectedAreas) {
+            if (area === 'tests') {
+                requirements.push({
+                    id: `req-${uuidv4().slice(0, 8)}`,
+                    description: 'Update or add tests for changed functionality',
+                    priority: priority++,
+                    source: 'inferred',
+                });
+            }
+            if (area === 'types') {
+                requirements.push({
+                    id: `req-${uuidv4().slice(0, 8)}`,
+                    description: 'Update type definitions to reflect changes',
+                    priority: priority++,
+                    source: 'inferred',
+                });
+            }
+        }
+        // Add requirements from clarification answers
+        if (clarification) {
+            for (const { question, answer } of clarification.qaRecords) {
+                if (question.category === 'scope' && answer.answer === 'comprehensive') {
+                    requirements.push({
+                        id: `req-${uuidv4().slice(0, 8)}`,
+                        description: 'Include comprehensive documentation and edge case handling',
+                        priority: priority++,
+                        source: 'clarification',
+                        clarificationRef: question.id,
+                    });
+                }
+                if (question.category === 'testing' && answer.answer !== 'none') {
+                    requirements.push({
+                        id: `req-${uuidv4().slice(0, 8)}`,
+                        description: `Include ${answer.answer === 'integration' ? 'unit and integration' : 'unit'} tests`,
+                        priority: priority++,
+                        source: 'clarification',
+                        clarificationRef: question.id,
+                    });
+                }
+            }
+        }
+        return requirements;
+    }
+    /**
+     * Generates the problem statement.
+     */
+    generateProblemStatement(context, clarification) {
+        let statement = `Goal: ${context.userRequest}\n\n`;
+        statement += `This change affects the ${context.affectedAreas.join(', ')} areas of the codebase.\n`;
+        statement += `Project type: ${context.projectType} (${context.languages.join(', ')})\n`;
+        if (clarification && clarification.qaRecords.length > 0) {
+            statement += '\nKey decisions from clarification:\n';
+            for (const { question, answer } of clarification.qaRecords) {
+                statement += `- ${question.category}: ${Array.isArray(answer.answer) ? answer.answer.join(', ') : answer.answer}\n`;
+            }
+        }
+        return statement;
+    }
+    /**
+     * Identifies potential edge cases.
+     */
+    identifyEdgeCases(context, _requirements) {
+        const edgeCases = [];
+        // Check for data-related edge cases
+        if (context.affectedAreas.includes('database') || context.affectedAreas.includes('data-models')) {
+            edgeCases.push({
+                description: 'Empty or null data handling',
+                handling: 'Add null checks and default values',
+                risk: 'medium',
+            });
+            edgeCases.push({
+                description: 'Large dataset performance',
+                handling: 'Consider pagination or lazy loading',
+                risk: 'medium',
+            });
+        }
+        // Check for UI edge cases
+        if (context.affectedAreas.includes('ui')) {
+            edgeCases.push({
+                description: 'Different screen sizes and responsive behavior',
+                handling: 'Test on multiple viewport sizes',
+                risk: 'low',
+            });
+            edgeCases.push({
+                description: 'Loading and error states',
+                handling: 'Implement proper loading indicators and error messages',
+                risk: 'low',
+            });
+        }
+        // Check for API edge cases
+        if (context.affectedAreas.includes('api') || context.affectedAreas.includes('backend')) {
+            edgeCases.push({
+                description: 'Network failures and timeouts',
+                handling: 'Implement retry logic and proper error handling',
+                risk: 'high',
+            });
+            edgeCases.push({
+                description: 'Invalid input validation',
+                handling: 'Add comprehensive input validation',
+                risk: 'high',
+            });
+        }
+        return edgeCases;
+    }
+    /**
+     * Generates constraints and assumptions.
+     */
+    generateConstraintsAndAssumptions(context, complexity, clarification) {
+        const constraints = [];
+        const assumptions = [];
+        // Project-based constraints
+        constraints.push(`Must work within existing ${context.projectType} project structure`);
+        constraints.push('Changes must not break existing functionality');
+        if (complexity.factors.breakingChanges) {
+            constraints.push('Breaking changes require version bump and migration path');
+        }
+        // Add constraints from clarification
+        if (clarification) {
+            for (const { question, answer } of clarification.qaRecords) {
+                if (question.id === 'feature_flag' && answer.answer === 'yes') {
+                    constraints.push('Feature must be behind a feature flag');
+                }
+            }
+        }
+        // Assumptions
+        assumptions.push('Project dependencies are up to date');
+        assumptions.push('Development environment is properly configured');
+        if (context.gitContext.isClean) {
+            assumptions.push('Git working directory is clean');
+        }
+        else {
+            assumptions.push('Uncommitted changes are unrelated to this task');
+        }
+        return { constraints, assumptions };
+    }
+    /**
+     * Determines file operations needed.
+     */
+    determineFileOperations(context, _requirements) {
+        const operations = [];
+        // Analyze relevant files to determine operations
+        for (const file of context.relevantFiles) {
+            if (file.relevanceScore >= 60) {
+                operations.push({
+                    path: file.path,
+                    operation: 'modify',
+                    changes: `Modify based on relevance to: ${file.reason}`,
+                    critical: file.areas.includes('config') || file.areas.includes('api'),
+                });
+            }
+        }
+        // Check if new files might be needed based on request
+        const requestLower = context.userRequest.toLowerCase();
+        if (requestLower.includes('add') || requestLower.includes('create') || requestLower.includes('new')) {
+            if (context.affectedAreas.includes('ui')) {
+                operations.push({
+                    path: 'src/components/NewComponent.tsx',
+                    operation: 'create',
+                    changes: 'New component file',
+                });
+            }
+            if (context.affectedAreas.includes('backend') || context.affectedAreas.includes('api')) {
+                operations.push({
+                    path: 'src/services/new-service.ts',
+                    operation: 'create',
+                    changes: 'New service file',
+                });
+            }
+        }
+        return operations;
+    }
+    /**
+     * Generates implementation tasks.
+     */
+    generateTasks(context, requirements, fileOperations, clarification, options) {
+        const tasks = [];
+        let order = 1;
+        // Group file operations by area
+        const createOps = fileOperations.filter(op => op.operation === 'create');
+        const modifyOps = fileOperations.filter(op => op.operation === 'modify');
+        const deleteOps = fileOperations.filter(op => op.operation === 'delete');
+        // Task 1: Create new files if needed
+        if (createOps.length > 0) {
+            tasks.push({
+                id: `task-${uuidv4().slice(0, 8)}`,
+                order: order++,
+                description: 'Create new files and scaffolding',
+                targetFiles: createOps.map(op => op.path),
+                targetElements: ['file structure', 'basic exports'],
+                changes: createOps.map(op => `Create ${op.path}: ${op.changes}`).join('\n'),
+                dependencies: [],
+                verificationCriteria: [
+                    'Files created successfully',
+                    'Proper TypeScript types defined',
+                    'Exports are correct',
+                ],
+                complexity: 2,
+                requirementRefs: requirements.filter(r => r.source === 'user').map(r => r.id),
+            });
+        }
+        // Task 2: Core implementation
+        const coreFiles = modifyOps.filter(op => !op.path.includes('test') && !op.path.includes('spec'));
+        if (coreFiles.length > 0 || createOps.length > 0) {
+            tasks.push({
+                id: `task-${uuidv4().slice(0, 8)}`,
+                order: order++,
+                description: 'Implement core functionality',
+                targetFiles: coreFiles.map(op => op.path),
+                targetElements: this.extractTargetElements(context, coreFiles),
+                changes: 'Implement the main logic as per requirements',
+                dependencies: tasks.length > 0 ? [tasks[0].id] : [],
+                verificationCriteria: [
+                    'Core functionality works as expected',
+                    'No TypeScript errors',
+                    'Follows existing code patterns',
+                ],
+                complexity: 4,
+                requirementRefs: requirements.filter(r => r.source === 'user').map(r => r.id),
+                clarificationRefs: clarification?.qaRecords
+                    .filter(qa => qa.question.category === 'approach')
+                    .map(qa => qa.question.id),
+            });
+        }
+        // Task 3: Type definitions
+        if (context.affectedAreas.includes('types')) {
+            tasks.push({
+                id: `task-${uuidv4().slice(0, 8)}`,
+                order: order++,
+                description: 'Update type definitions',
+                targetFiles: context.relevantFiles
+                    .filter(f => f.areas.includes('types'))
+                    .map(f => f.path),
+                targetElements: ['interfaces', 'types', 'enums'],
+                changes: 'Add or update type definitions to support new functionality',
+                dependencies: tasks.length > 0 ? [tasks[tasks.length - 1].id] : [],
+                verificationCriteria: [
+                    'Types are properly defined',
+                    'No TypeScript errors',
+                    'Types are exported correctly',
+                ],
+                complexity: 2,
+                requirementRefs: requirements.filter(r => r.description.includes('type')).map(r => r.id),
+            });
+        }
+        // Task 4: Integration/wiring
+        if (context.affectedAreas.length > 1) {
+            tasks.push({
+                id: `task-${uuidv4().slice(0, 8)}`,
+                order: order++,
+                description: 'Wire up components and integrate changes',
+                targetFiles: context.relevantFiles.filter(f => f.relevanceScore >= 50).map(f => f.path).slice(0, 5),
+                targetElements: ['imports', 'exports', 'registrations'],
+                changes: 'Connect new functionality with existing code',
+                dependencies: tasks.slice(-2).map(t => t.id),
+                verificationCriteria: [
+                    'Components are properly connected',
+                    'No circular dependencies',
+                    'Exports are updated',
+                ],
+                complexity: 3,
+                requirementRefs: requirements.map(r => r.id),
+            });
+        }
+        // Task 5: Testing (if requested)
+        const testingAnswer = clarification?.qaRecords.find(qa => qa.question.id === 'testing');
+        if (!testingAnswer || testingAnswer.answer.answer !== 'none') {
+            tasks.push({
+                id: `task-${uuidv4().slice(0, 8)}`,
+                order: order++,
+                description: 'Add or update tests',
+                targetFiles: context.relevantFiles
+                    .filter(f => f.areas.includes('tests'))
+                    .map(f => f.path),
+                targetElements: ['test suites', 'test cases', 'mocks'],
+                changes: 'Create tests to verify new functionality',
+                dependencies: tasks.slice(-1).map(t => t.id),
+                verificationCriteria: [
+                    'Tests pass',
+                    'Coverage is adequate',
+                    'Edge cases are tested',
+                ],
+                complexity: 3,
+                requirementRefs: requirements.filter(r => r.description.includes('test')).map(r => r.id),
+                clarificationRefs: testingAnswer ? [testingAnswer.question.id] : undefined,
+            });
+        }
+        // Task 6: Cleanup
+        if (deleteOps.length > 0) {
+            tasks.push({
+                id: `task-${uuidv4().slice(0, 8)}`,
+                order: order++,
+                description: 'Remove deprecated code and files',
+                targetFiles: deleteOps.map(op => op.path),
+                targetElements: ['deprecated functions', 'unused imports', 'old files'],
+                changes: deleteOps.map(op => `Delete ${op.path}`).join('\n'),
+                dependencies: tasks.slice(-1).map(t => t.id),
+                verificationCriteria: [
+                    'No orphaned references',
+                    'Build still succeeds',
+                    'Tests still pass',
+                ],
+                complexity: 2,
+                requirementRefs: [],
+            });
+        }
+        return tasks.slice(0, options.maxTasks);
+    }
+    /**
+     * Extracts target elements from files.
+     */
+    extractTargetElements(context, files) {
+        const elements = new Set();
+        for (const file of files) {
+            // Look for matching indexed file to get exports
+            const indexedFile = context.relevantFiles.find(f => f.path === file.path);
+            if (indexedFile) {
+                // Add generic element types based on file areas
+                for (const area of indexedFile.areas) {
+                    switch (area) {
+                        case 'ui':
+                            elements.add('components');
+                            elements.add('hooks');
+                            break;
+                        case 'backend':
+                        case 'api':
+                            elements.add('handlers');
+                            elements.add('routes');
+                            break;
+                        case 'utils':
+                            elements.add('functions');
+                            break;
+                        case 'types':
+                            elements.add('interfaces');
+                            elements.add('types');
+                            break;
+                    }
+                }
+            }
+        }
+        return Array.from(elements);
+    }
+    /**
+     * Analyzes risks associated with the plan.
+     */
+    analyzeRisks(context, complexity, tasks) {
+        const risks = [];
+        // Risk from complexity
+        if (complexity.factors.riskLevel >= 7) {
+            risks.push({
+                description: 'High overall complexity may lead to unexpected issues',
+                severity: 'high',
+                mitigation: 'Thorough code review and testing at each step',
+                rollback: 'Git revert to previous commit',
+            });
+        }
+        // Risk from breaking changes
+        if (complexity.factors.breakingChanges) {
+            risks.push({
+                description: 'Breaking changes may affect downstream consumers',
+                severity: 'critical',
+                mitigation: 'Communicate changes and provide migration guide',
+                rollback: 'Restore previous API alongside new one',
+            });
+        }
+        // Risk from multiple affected areas
+        if (context.affectedAreas.length >= 3) {
+            risks.push({
+                description: 'Changes span multiple subsystems increasing integration risk',
+                severity: 'medium',
+                mitigation: 'Test each integration point thoroughly',
+                rollback: 'Revert commits in reverse order',
+            });
+        }
+        // Risk from uncommitted changes
+        if (!context.gitContext.isClean) {
+            risks.push({
+                description: 'Uncommitted changes may conflict with new changes',
+                severity: 'low',
+                mitigation: 'Stash or commit existing changes before starting',
+                rollback: 'Pop stash to restore',
+            });
+        }
+        // Risk from large number of tasks
+        if (tasks.length > 10) {
+            risks.push({
+                description: 'Large number of tasks increases chance of errors',
+                severity: 'medium',
+                mitigation: 'Execute tasks incrementally with verification',
+                rollback: 'Roll back to last verified checkpoint',
+            });
+        }
+        return risks;
+    }
+    /**
+     * Generates testing requirements.
+     */
+    generateTestingRequirements(tasks, context) {
+        const unitTests = [];
+        const integrationTests = [];
+        const testFiles = [];
+        // Find existing test files
+        for (const file of context.relevantFiles) {
+            if (file.areas.includes('tests')) {
+                testFiles.push(file.path);
+            }
+        }
+        // Generate test suggestions based on tasks
+        for (const task of tasks) {
+            if (!task.description.toLowerCase().includes('test')) {
+                unitTests.push(`Test: ${task.description}`);
+            }
+        }
+        // Add integration tests for multi-area changes
+        if (context.affectedAreas.length > 1) {
+            integrationTests.push('Integration test: Verify all components work together');
+        }
+        if (context.affectedAreas.includes('api')) {
+            integrationTests.push('API integration test: Verify endpoints work correctly');
+        }
+        return {
+            unitTests,
+            integrationTests,
+            testFiles,
+        };
+    }
+    /**
+     * Generates impact assessment.
+     */
+    generateImpactAssessment(fileOperations, context) {
+        return {
+            fileOperations,
+            dependenciesAffected: [], // Would need deeper analysis
+            breakingChanges: fileOperations
+                .filter(op => op.operation === 'delete' || op.critical)
+                .map(op => op.path),
+            migrations: context.affectedAreas.includes('database')
+                ? ['Database schema migration may be required']
+                : undefined,
+        };
+    }
+    /**
+     * Generates rollback strategy.
+     */
+    generateRollbackStrategy(_tasks, fileOperations) {
+        const strategies = [];
+        strategies.push('1. Create git stash before execution to save current state');
+        strategies.push('2. Each task creates a commit for atomic rollback');
+        strategies.push('3. File backups are created before modifications');
+        const hasDelete = fileOperations.some(op => op.operation === 'delete');
+        if (hasDelete) {
+            strategies.push('4. Deleted files are preserved in backup directory');
+        }
+        strategies.push(`${hasDelete ? '5' : '4'}. Use "git revert" for individual task rollback`);
+        strategies.push(`${hasDelete ? '6' : '5'}. Use "git reset --hard" for complete rollback`);
+        return strategies.join('\n');
+    }
+    /**
+     * Calculates total complexity score.
+     */
+    calculateTotalComplexity(tasks, risks) {
+        // Base complexity from tasks
+        const taskComplexity = tasks.reduce((sum, t) => sum + t.complexity, 0) / tasks.length;
+        // Risk adjustment
+        const riskScore = risks.reduce((sum, r) => {
+            switch (r.severity) {
+                case 'critical': return sum + 3;
+                case 'high': return sum + 2;
+                case 'medium': return sum + 1;
+                default: return sum + 0.5;
+            }
+        }, 0);
+        const total = Math.min(10, Math.ceil(taskComplexity + riskScore / 2));
+        return total;
+    }
+    /**
+     * Generates plan summary.
+     */
+    generateSummary(problemStatement, tasks, risks, clarification) {
+        let summary = '';
+        summary += `This plan addresses: ${problemStatement.split('\n')[0]}\n\n`;
+        summary += `**Tasks:** ${tasks.length} implementation steps\n`;
+        summary += `**Risks:** ${risks.length} identified (${risks.filter(r => r.severity === 'high' || r.severity === 'critical').length} high/critical)\n`;
+        if (clarification && clarification.qaRecords.length > 0) {
+            summary += `\n**Key decisions:**\n${clarification.decisionSummary}`;
+        }
+        summary += '\n\n**Task Overview:**\n';
+        for (const task of tasks.slice(0, 5)) {
+            summary += `${task.order}. ${task.description}\n`;
+        }
+        if (tasks.length > 5) {
+            summary += `... and ${tasks.length - 5} more tasks\n`;
+        }
+        return summary;
+    }
+    /**
+     * Formats the plan for display.
+     */
+    formatPlanForDisplay(plan) {
+        const lines = [];
+        lines.push(chalk.bold.cyan('Implementation Plan'));
+        lines.push(chalk.gray('═'.repeat(50)));
+        lines.push('');
+        lines.push(chalk.bold('Problem Statement:'));
+        lines.push(plan.problemStatement);
+        lines.push('');
+        lines.push(chalk.bold('Requirements:'));
+        for (const req of plan.requirements) {
+            const source = req.source === 'clarification' ? chalk.blue('[Q&A]') : '';
+            lines.push(`  ${req.priority}. ${req.description} ${source}`);
+        }
+        lines.push('');
+        lines.push(chalk.bold('Tasks:'));
+        for (const task of plan.tasks) {
+            lines.push(`  ${chalk.green(task.order + '.')} ${task.description}`);
+            lines.push(`     Files: ${task.targetFiles.join(', ')}`);
+            lines.push(`     Complexity: ${'●'.repeat(task.complexity)}${'○'.repeat(5 - task.complexity)}`);
+        }
+        lines.push('');
+        lines.push(chalk.bold('Risks:'));
+        for (const risk of plan.risks) {
+            const severity = {
+                low: chalk.green('LOW'),
+                medium: chalk.yellow('MEDIUM'),
+                high: chalk.red('HIGH'),
+                critical: chalk.bgRed.white('CRITICAL'),
+            }[risk.severity];
+            lines.push(`  [${severity}] ${risk.description}`);
+            lines.push(`          Mitigation: ${risk.mitigation}`);
+        }
+        lines.push('');
+        lines.push(chalk.bold(`Total Complexity: ${plan.totalComplexity}/10`));
+        lines.push('');
+        return lines.join('\n');
+    }
+}
+// Singleton instance
+let planGeneratorInstance = null;
+/**
+ * Gets the singleton PlanGenerator instance.
+ */
+export function getPlanGenerator() {
+    if (!planGeneratorInstance) {
+        planGeneratorInstance = new PlanGenerator();
+    }
+    return planGeneratorInstance;
+}
+/**
+ * Creates a new PlanGenerator instance.
+ */
+export function createPlanGenerator() {
+    return new PlanGenerator();
+}
+export { PlanGenerator };
+//# sourceMappingURL=plan-generator.js.map