kiro-spec-engine 1.4.3 → 1.5.2

package/lib/governance/hooks-manager.js

@@ -0,0 +1,333 @@
+/**
+ * Hooks Manager
+ * 
+ * Manages Git hooks for document governance
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+class HooksManager {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.gitDir = path.join(projectPath, '.git');
+    this.hooksDir = path.join(this.gitDir, 'hooks');
+    this.preCommitPath = path.join(this.hooksDir, 'pre-commit');
+    this.backupPath = path.join(this.hooksDir, 'pre-commit.backup');
+    
+    // Marker to identify our hook content
+    this.hookMarkerStart = '# BEGIN kiro-spec-engine document governance';
+    this.hookMarkerEnd = '# END kiro-spec-engine document governance';
+  }
+  
+  /**
+   * Check if Git hooks are installed
+   * 
+   * @returns {Promise<Object>}
+   */
+  async checkHooksInstalled() {
+    try {
+      // Check if .git directory exists
+      if (!await fs.pathExists(this.gitDir)) {
+        return {
+          installed: false,
+          reason: 'not_git_repo',
+          message: 'Not a Git repository'
+        };
+      }
+      
+      // Check if hooks directory exists
+      if (!await fs.pathExists(this.hooksDir)) {
+        return {
+          installed: false,
+          reason: 'no_hooks_dir',
+          message: 'Git hooks directory does not exist'
+        };
+      }
+      
+      // Check if pre-commit hook exists
+      if (!await fs.pathExists(this.preCommitPath)) {
+        return {
+          installed: false,
+          reason: 'no_hook',
+          message: 'Pre-commit hook not installed'
+        };
+      }
+      
+      // Check if our hook content is present
+      const content = await fs.readFile(this.preCommitPath, 'utf8');
+      const hasOurHook = content.includes(this.hookMarkerStart);
+      
+      return {
+        installed: hasOurHook,
+        reason: hasOurHook ? 'installed' : 'other_hook',
+        message: hasOurHook 
+          ? 'Document governance hook is installed' 
+          : 'Pre-commit hook exists but is not ours',
+        hasExistingHook: !hasOurHook
+      };
+    } catch (error) {
+      return {
+        installed: false,
+        reason: 'error',
+        message: `Error checking hooks: ${error.message}`,
+        error: error.message
+      };
+    }
+  }
+  
+  /**
+   * Install pre-commit hook
+   * 
+   * @returns {Promise<Object>}
+   */
+  async installHooks() {
+    try {
+      // Check if .git directory exists
+      if (!await fs.pathExists(this.gitDir)) {
+        return {
+          success: false,
+          reason: 'not_git_repo',
+          message: 'Not a Git repository. Initialize Git first with: git init'
+        };
+      }
+      
+      // Create hooks directory if it doesn't exist
+      if (!await fs.pathExists(this.hooksDir)) {
+        await fs.ensureDir(this.hooksDir);
+      }
+      
+      // Check if pre-commit hook already exists
+      let existingContent = '';
+      let hasExistingHook = false;
+      
+      if (await fs.pathExists(this.preCommitPath)) {
+        existingContent = await fs.readFile(this.preCommitPath, 'utf8');
+        
+        // Check if our hook is already installed
+        if (existingContent.includes(this.hookMarkerStart)) {
+          return {
+            success: true,
+            reason: 'already_installed',
+            message: 'Document governance hook is already installed'
+          };
+        }
+        
+        hasExistingHook = true;
+        
+        // Backup existing hook
+        await fs.writeFile(this.backupPath, existingContent);
+      }
+      
+      // Generate our hook content
+      const ourHookContent = this.generateHookContent();
+      
+      // Combine with existing hook if present
+      let finalContent;
+      if (hasExistingHook) {
+        // Preserve existing hook and add ours
+        finalContent = this.combineHooks(existingContent, ourHookContent);
+      } else {
+        // Just use our hook with shebang
+        finalContent = `#!/bin/sh\n\n${ourHookContent}`;
+      }
+      
+      // Write the hook file
+      await fs.writeFile(this.preCommitPath, finalContent);
+      
+      // Make it executable (Unix-like systems)
+      if (process.platform !== 'win32') {
+        await fs.chmod(this.preCommitPath, 0o755);
+      }
+      
+      return {
+        success: true,
+        reason: hasExistingHook ? 'installed_with_preservation' : 'installed',
+        message: hasExistingHook 
+          ? 'Document governance hook installed. Existing hook preserved and backed up.'
+          : 'Document governance hook installed successfully.',
+        backupCreated: hasExistingHook
+      };
+    } catch (error) {
+      return {
+        success: false,
+        reason: 'error',
+        message: `Failed to install hooks: ${error.message}`,
+        error: error.message
+      };
+    }
+  }
+  
+  /**
+   * Uninstall pre-commit hook
+   * 
+   * @returns {Promise<Object>}
+   */
+  async uninstallHooks() {
+    try {
+      // Check if hook exists
+      if (!await fs.pathExists(this.preCommitPath)) {
+        return {
+          success: true,
+          reason: 'not_installed',
+          message: 'Document governance hook is not installed'
+        };
+      }
+      
+      // Read current hook content
+      const content = await fs.readFile(this.preCommitPath, 'utf8');
+      
+      // Check if our hook is present
+      if (!content.includes(this.hookMarkerStart)) {
+        return {
+          success: false,
+          reason: 'not_our_hook',
+          message: 'Pre-commit hook exists but is not ours. Manual removal required.'
+        };
+      }
+      
+      // Remove our hook content
+      const newContent = this.removeOurHook(content);
+      
+      // If nothing left (or just shebang), remove the file
+      const trimmedContent = newContent.trim();
+      if (trimmedContent === '' || trimmedContent === '#!/bin/sh') {
+        await fs.remove(this.preCommitPath);
+        
+        // Restore backup if it exists
+        if (await fs.pathExists(this.backupPath)) {
+          await fs.remove(this.backupPath);
+        }
+        
+        return {
+          success: true,
+          reason: 'removed',
+          message: 'Document governance hook removed successfully.'
+        };
+      } else {
+        // Write back the remaining content
+        await fs.writeFile(this.preCommitPath, newContent);
+        
+        return {
+          success: true,
+          reason: 'removed_preserved',
+          message: 'Document governance hook removed. Other hooks preserved.'
+        };
+      }
+    } catch (error) {
+      return {
+        success: false,
+        reason: 'error',
+        message: `Failed to uninstall hooks: ${error.message}`,
+        error: error.message
+      };
+    }
+  }
+  
+  /**
+   * Generate hook content
+   * 
+   * @returns {string}
+   */
+  generateHookContent() {
+    // Use Node.js to run validation
+    // This works on both Windows and Unix-like systems
+    return `${this.hookMarkerStart}
+
+# Run document governance validation
+node -e "
+const path = require('path');
+const ConfigManager = require('./lib/governance/config-manager');
+const ValidationEngine = require('./lib/governance/validation-engine');
+
+(async () => {
+  try {
+    const projectPath = process.cwd();
+    const configManager = new ConfigManager(projectPath);
+    const config = await configManager.load();
+    const validator = new ValidationEngine(projectPath, config);
+    
+    // Validate root directory and all specs
+    const report = await validator.validate({ all: true });
+    
+    if (!report.valid) {
+      console.error('\\n❌ Document governance validation failed!\\n');
+      console.error('Found ' + report.errors.length + ' error(s):\\n');
+      
+      report.errors.forEach(err => {
+        console.error('  • ' + err.path);
+        console.error('    ' + err.message);
+        console.error('    → ' + err.recommendation + '\\n');
+      });
+      
+      console.error('Fix these issues before committing:');
+      console.error('  kse doctor --docs    # Diagnose issues');
+      console.error('  kse cleanup          # Remove temporary files');
+      console.error('  kse validate --all   # Validate structure\\n');
+      
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('Error running document validation:', error.message);
+    // Don't block commit on validation errors
+    process.exit(0);
+  }
+})();
+"
+
+${this.hookMarkerEnd}
+`;
+  }
+  
+  /**
+   * Combine existing hook with our hook
+   * 
+   * @param {string} existingContent - Existing hook content
+   * @param {string} ourContent - Our hook content
+   * @returns {string}
+   */
+  combineHooks(existingContent, ourContent) {
+    // Ensure shebang is present
+    let combined = existingContent;
+    
+    if (!combined.startsWith('#!/')) {
+      combined = '#!/bin/sh\n\n' + combined;
+    }
+    
+    // Add our hook at the end
+    combined += '\n\n' + ourContent;
+    
+    return combined;
+  }
+  
+  /**
+   * Remove our hook from combined content
+   * 
+   * @param {string} content - Hook content
+   * @returns {string}
+   */
+  removeOurHook(content) {
+    const startIndex = content.indexOf(this.hookMarkerStart);
+    const endIndex = content.indexOf(this.hookMarkerEnd);
+    
+    if (startIndex === -1 || endIndex === -1) {
+      return content;
+    }
+    
+    // Remove our hook section (including markers and newlines)
+    const before = content.substring(0, startIndex).trimEnd();
+    const after = content.substring(endIndex + this.hookMarkerEnd.length).trimStart();
+    
+    if (before && after) {
+      return before + '\n\n' + after;
+    } else if (before) {
+      return before;
+    } else if (after) {
+      return after;
+    } else {
+      return '';
+    }
+  }
+}
+
+module.exports = HooksManager;

package/lib/governance/reporter.js

@@ -0,0 +1,337 @@
+/**
+ * Reporter
+ * 
+ * Formats and displays governance operation results
+ */
+
+const chalk = require('chalk');
+const path = require('path');
+
+class Reporter {
+  constructor() {
+    this.chalk = chalk;
+  }
+  
+  /**
+   * Display diagnostic report
+   * 
+   * @param {DiagnosticReport} report - Diagnostic report
+   */
+  displayDiagnostic(report) {
+    console.log(this.chalk.bold.cyan('\n📋 Document Governance Diagnostic\n'));
+    
+    if (report.compliant) {
+      console.log(this.chalk.green('✅ Project is compliant'));
+      console.log('All documents follow the lifecycle management rules.\n');
+      return;
+    }
+    
+    console.log(this.chalk.yellow(`⚠️  Found ${report.violations.length} violation(s)\n`));
+    
+    // Group violations by type
+    const byType = this.groupBy(report.violations, 'type');
+    
+    for (const [type, violations] of Object.entries(byType)) {
+      console.log(this.chalk.bold.blue(`${this.formatType(type)} (${violations.length})`));
+      
+      for (const violation of violations) {
+        const icon = violation.severity === 'error' ? '❌' : '⚠️';
+        console.log(`  ${icon} ${this.chalk.gray(violation.path)}`);
+        console.log(`     ${violation.description}`);
+        console.log(`     ${this.chalk.cyan('→ ' + violation.recommendation)}`);
+      }
+      
+      console.log();
+    }
+    
+    // Display recommendations
+    if (report.recommendations && report.recommendations.length > 0) {
+      console.log(this.chalk.bold.blue('💡 Recommended Actions'));
+      report.recommendations.forEach(rec => {
+        console.log(`  • ${rec}`);
+      });
+      console.log();
+    }
+    
+    // Display summary
+    if (report.summary) {
+      console.log(this.chalk.bold('Summary:'));
+      console.log(`  Total violations: ${report.summary.totalViolations}`);
+      if (report.summary.bySeverity) {
+        console.log(`  Errors: ${report.summary.bySeverity.error || 0}`);
+        console.log(`  Warnings: ${report.summary.bySeverity.warning || 0}`);
+        console.log(`  Info: ${report.summary.bySeverity.info || 0}`);
+      }
+      console.log();
+    }
+  }
+  
+  /**
+   * Display cleanup report
+   * 
+   * @param {CleanupReport} report - Cleanup report
+   * @param {boolean} dryRun - Whether this was a dry run
+   */
+  displayCleanup(report, dryRun = false) {
+    const title = dryRun ? 'Cleanup Preview (Dry Run)' : 'Cleanup Complete';
+    console.log(this.chalk.bold.cyan(`\n🧹 ${title}\n`));
+    
+    if (report.deletedFiles.length === 0) {
+      console.log(this.chalk.green('✅ No files to clean\n'));
+      return;
+    }
+    
+    const verb = dryRun ? 'Would delete' : 'Deleted';
+    console.log(this.chalk.yellow(`${verb} ${report.deletedFiles.length} file(s):\n`));
+    
+    report.deletedFiles.forEach(file => {
+      console.log(`  🗑️  ${this.chalk.gray(file)}`);
+    });
+    
+    if (report.errors && report.errors.length > 0) {
+      console.log();
+      console.log(this.chalk.red(`❌ ${report.errors.length} error(s):`));
+      report.errors.forEach(err => {
+        console.log(`  • ${this.chalk.gray(err.path)}: ${err.error}`);
+      });
+    }
+    
+    console.log();
+    
+    if (dryRun) {
+      console.log(this.chalk.cyan('💡 Run without --dry-run to actually delete these files\n'));
+    } else if (report.success) {
+      console.log(this.chalk.green('✅ Cleanup completed successfully\n'));
+    } else {
+      console.log(this.chalk.yellow('⚠️  Cleanup completed with errors\n'));
+    }
+  }
+  
+  /**
+   * Display validation report
+   * 
+   * @param {ValidationReport} report - Validation report
+   */
+  displayValidation(report) {
+    console.log(this.chalk.bold.cyan('\n✓ Document Structure Validation\n'));
+    
+    // Check if there are any errors or warnings
+    const hasErrors = report.errors && report.errors.length > 0;
+    const hasWarnings = report.warnings && report.warnings.length > 0;
+    
+    if (report.valid && !hasWarnings) {
+      console.log(this.chalk.green('✅ Validation passed'));
+      console.log('All document structures are compliant.\n');
+      return;
+    }
+    
+    if (hasErrors) {
+      console.log(this.chalk.red(`❌ ${report.errors.length} error(s):\n`));
+      
+      report.errors.forEach(err => {
+        console.log(`  ❌ ${this.chalk.gray(err.path)}`);
+        console.log(`     ${err.message}`);
+        console.log(`     ${this.chalk.cyan('→ ' + err.recommendation)}`);
+        console.log();
+      });
+    }
+    
+    if (hasWarnings) {
+      console.log(this.chalk.yellow(`⚠️  ${report.warnings.length} warning(s):\n`));
+      
+      report.warnings.forEach(warn => {
+        console.log(`  ⚠️  ${this.chalk.gray(warn.path)}`);
+        console.log(`     ${warn.message}`);
+        console.log(`     ${this.chalk.cyan('→ ' + warn.recommendation)}`);
+        console.log();
+      });
+    }
+    
+    // Display summary
+    if (report.summary) {
+      console.log(this.chalk.bold('Summary:'));
+      console.log(`  Errors: ${report.summary.totalErrors}`);
+      console.log(`  Warnings: ${report.summary.totalWarnings}`);
+      console.log();
+    }
+  }
+  
+  /**
+   * Display archive report
+   * 
+   * @param {ArchiveReport} report - Archive report
+   * @param {boolean} dryRun - Whether this was a dry run
+   */
+  displayArchive(report, dryRun = false) {
+    const title = dryRun ? 'Archive Preview (Dry Run)' : 'Archive Complete';
+    console.log(this.chalk.bold.cyan(`\n📦 ${title}\n`));
+    
+    // Check if there are errors even with no moved files
+    const hasErrors = report.errors && report.errors.length > 0;
+    
+    if (report.movedFiles.length === 0 && !hasErrors) {
+      console.log(this.chalk.green('✅ No files to archive\n'));
+      return;
+    }
+    
+    if (report.movedFiles.length > 0) {
+      const verb = dryRun ? 'Would move' : 'Moved';
+      console.log(this.chalk.yellow(`${verb} ${report.movedFiles.length} file(s):\n`));
+      
+      report.movedFiles.forEach(move => {
+        const fromBasename = path.basename(move.from);
+        const toRelative = this.chalk.gray(move.to);
+        console.log(`  📦 ${fromBasename}`);
+        console.log(`     ${this.chalk.gray('→')} ${toRelative}`);
+      });
+      
+      console.log();
+    }
+    
+    if (hasErrors) {
+      console.log(this.chalk.red(`❌ ${report.errors.length} error(s):`));
+      report.errors.forEach(err => {
+        console.log(`  • ${this.chalk.gray(err.path)}: ${err.error}`);
+      });
+      console.log();
+    }
+    
+    if (dryRun && report.movedFiles.length > 0) {
+      console.log(this.chalk.cyan('💡 Run without --dry-run to actually move these files\n'));
+    } else if (report.success && report.movedFiles.length > 0) {
+      console.log(this.chalk.green('✅ Archive completed successfully\n'));
+    } else if (!report.success) {
+      console.log(this.chalk.yellow('⚠️  Archive completed with errors\n'));
+    }
+  }
+  
+  /**
+   * Display error message
+   * 
+   * @param {string} message - Error message
+   */
+  displayError(message) {
+    console.log(this.chalk.red(`\n❌ Error: ${message}\n`));
+  }
+  
+  /**
+   * Display statistics
+   * 
+   * @param {Object} stats - Statistics object
+   */
+  displayStats(stats) {
+    console.log(this.chalk.bold.cyan('\n📊 Document Compliance Statistics\n'));
+    
+    // Overall Summary
+    console.log(this.chalk.bold('Overall Summary:'));
+    console.log(`  Total Executions: ${stats.totalExecutions}`);
+    console.log(`  Total Violations Found: ${stats.totalViolations}`);
+    console.log(`  Total Cleanup Actions: ${stats.totalCleanupActions}`);
+    console.log(`  Total Archive Actions: ${stats.totalArchiveActions}`);
+    console.log(`  Total Errors: ${stats.totalErrors}`);
+    console.log();
+    
+    // Time Range
+    if (stats.firstExecution && stats.lastExecution) {
+      console.log(this.chalk.bold('Time Range:'));
+      console.log(`  First Execution: ${new Date(stats.firstExecution).toLocaleString()}`);
+      console.log(`  Last Execution: ${new Date(stats.lastExecution).toLocaleString()}`);
+      console.log();
+    }
+    
+    // Executions by Tool
+    if (Object.keys(stats.executionsByTool).length > 0) {
+      console.log(this.chalk.bold('Executions by Tool:'));
+      Object.entries(stats.executionsByTool)
+        .sort((a, b) => b[1] - a[1])
+        .forEach(([tool, count]) => {
+          console.log(`  ${tool}: ${count}`);
+        });
+      console.log();
+    }
+    
+    // Violations by Type
+    if (Object.keys(stats.violationsByType).length > 0) {
+      console.log(this.chalk.bold('Violations by Type:'));
+      Object.entries(stats.violationsByType)
+        .sort((a, b) => b[1] - a[1])
+        .forEach(([type, count]) => {
+          console.log(`  ${this.formatType(type)}: ${count}`);
+        });
+      console.log();
+    }
+    
+    // Violations Over Time (last 5)
+    if (stats.violationsOverTime.length > 0) {
+      console.log(this.chalk.bold('Recent Violations:'));
+      const recent = stats.violationsOverTime.slice(-5);
+      recent.forEach(entry => {
+        const date = new Date(entry.timestamp).toLocaleString();
+        console.log(`  ${date}: ${entry.count} violation(s)`);
+      });
+      console.log();
+    }
+    
+    // Cleanup Actions Over Time (last 5)
+    if (stats.cleanupActionsOverTime.length > 0) {
+      console.log(this.chalk.bold('Recent Cleanup Actions:'));
+      const recent = stats.cleanupActionsOverTime.slice(-5);
+      recent.forEach(entry => {
+        const date = new Date(entry.timestamp).toLocaleString();
+        console.log(`  ${date}: ${entry.count} file(s) deleted`);
+      });
+      console.log();
+    }
+    
+    // Recommendations
+    console.log(this.chalk.cyan('💡 Run "kse docs report" to generate a detailed compliance report\n'));
+  }
+  
+  /**
+   * Display success message
+   * 
+   * @param {string} message - Success message
+   */
+  displaySuccess(message) {
+    console.log(this.chalk.green(`\n✅ ${message}\n`));
+  }
+  
+  /**
+   * Display info message
+   * 
+   * @param {string} message - Info message
+   */
+  displayInfo(message) {
+    console.log(this.chalk.cyan(`\nℹ️  ${message}\n`));
+  }
+  
+  /**
+   * Helper: Group array by property
+   * 
+   * @param {Array} array - Array to group
+   * @param {string} property - Property to group by
+   * @returns {Object} - Grouped object
+   */
+  groupBy(array, property) {
+    return array.reduce((acc, item) => {
+      const key = item[property];
+      if (!acc[key]) acc[key] = [];
+      acc[key].push(item);
+      return acc;
+    }, {});
+  }
+  
+  /**
+   * Helper: Format violation type
+   * 
+   * @param {string} type - Violation type
+   * @returns {string} - Formatted type
+   */
+  formatType(type) {
+    return type.split('_').map(word => 
+      word.charAt(0).toUpperCase() + word.slice(1)
+    ).join(' ');
+  }
+}
+
+module.exports = Reporter;