scene-capability-engine 3.0.0

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;

package/lib/governance/validation-engine.js

@@ -0,0 +1,181 @@
+/**
+ * Validation Engine
+ * 
+ * Validates project documentation structure
+ */
+
+const path = require('path');
+const FileScanner = require('./file-scanner');
+
+class ValidationEngine {
+  constructor(projectPath, config) {
+    this.projectPath = projectPath;
+    this.config = config;
+    this.scanner = new FileScanner(projectPath);
+    this.validationErrors = [];
+    this.validationWarnings = [];
+  }
+  
+  /**
+   * Validate project structure
+   * 
+   * @param {Object} options - Validation options
+   * @param {string} options.spec - Specific Spec to validate
+   * @param {boolean} options.all - Validate all Specs
+   * @returns {Promise<ValidationReport>}
+   */
+  async validate(options = {}) {
+    this.validationErrors = []; // Reset
+    this.validationWarnings = []; // Reset
+    
+    await this.validateRootDirectory();
+    
+    if (options.spec) {
+      await this.validateSpec(options.spec);
+    } else if (options.all) {
+      await this.validateAllSpecs();
+    }
+    
+    return this.generateReport();
+  }
+  
+  /**
+   * Validate root directory
+   * 
+   * @returns {Promise<void>}
+   */
+  async validateRootDirectory() {
+    const mdFiles = await this.scanner.findMarkdownFiles(this.projectPath);
+    const allowedFiles = this.config.rootAllowedFiles || [];
+    
+    for (const filePath of mdFiles) {
+      const basename = path.basename(filePath);
+      
+      if (!allowedFiles.includes(basename)) {
+        this.validationErrors.push({
+          type: 'root_violation',
+          path: filePath,
+          message: `Unexpected markdown file in root: ${basename}`,
+          recommendation: 'Move to appropriate location or delete if temporary'
+        });
+      }
+    }
+  }
+  
+  /**
+   * Validate all Spec directories
+   * 
+   * @returns {Promise<void>}
+   */
+  async validateAllSpecs() {
+    const specDirs = await this.scanner.findSpecDirectories();
+    
+    for (const specDir of specDirs) {
+      const specName = path.basename(specDir);
+      await this.validateSpec(specName);
+    }
+  }
+  
+  /**
+   * Validate a Spec directory
+   * 
+   * @param {string} specName - Spec name
+   * @returns {Promise<void>}
+   */
+  async validateSpec(specName) {
+    const specPath = this.scanner.getSpecDirectory(specName);
+    
+    // Check if Spec directory exists
+    if (!await this.scanner.exists(specPath)) {
+      this.validationErrors.push({
+        type: 'missing_spec',
+        path: specPath,
+        message: `Spec directory does not exist: ${specName}`,
+        recommendation: `Create Spec directory at ${specPath}`
+      });
+      return;
+    }
+    
+    // Check required files
+    const requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
+    for (const file of requiredFiles) {
+      const filePath = path.join(specPath, file);
+      if (!await this.scanner.exists(filePath)) {
+        this.validationErrors.push({
+          type: 'missing_required_file',
+          path: filePath,
+          message: `Missing required file: ${file}`,
+          recommendation: `Create ${file} in ${specName}`
+        });
+      }
+    }
+    
+    // Check for misplaced artifacts
+    const files = await this.scanner.getFiles(specPath);
+    const allowedSubdirs = this.config.specSubdirs || [];
+    
+    for (const filePath of files) {
+      const basename = path.basename(filePath);
+      
+      // Skip required files
+      if (requiredFiles.includes(basename)) {
+        continue;
+      }
+      
+      this.validationWarnings.push({
+        type: 'misplaced_artifact',
+        path: filePath,
+        message: `Artifact not in subdirectory: ${basename}`,
+        recommendation: `Move to appropriate subdirectory (${allowedSubdirs.join(', ')})`
+      });
+    }
+    
+    // Check subdirectory naming
+    const subdirs = await this.scanner.getSubdirectories(specPath);
+    
+    for (const subdirPath of subdirs) {
+      const subdirName = path.basename(subdirPath);
+      
+      // Skip hidden directories
+      if (subdirName.startsWith('.')) {
+        continue;
+      }
+      
+      if (!allowedSubdirs.includes(subdirName)) {
+        this.validationWarnings.push({
+          type: 'invalid_subdirectory',
+          path: subdirPath,
+          message: `Non-standard subdirectory: ${subdirName}`,
+          recommendation: `Rename to one of: ${allowedSubdirs.join(', ')}, or remove if not needed`
+        });
+      }
+    }
+  }
+  
+  /**
+   * Generate validation report
+   * 
+   * @returns {ValidationReport}
+   */
+  generateReport() {
+    return {
+      valid: this.validationErrors.length === 0,
+      errors: this.validationErrors,
+      warnings: this.validationWarnings,
+      summary: {
+        totalErrors: this.validationErrors.length,
+        totalWarnings: this.validationWarnings.length
+      }
+    };
+  }
+}
+
+/**
+ * @typedef {Object} ValidationReport
+ * @property {boolean} valid - Whether validation passed
+ * @property {Object[]} errors - Validation errors
+ * @property {Object[]} warnings - Validation warnings
+ * @property {Object} summary - Summary statistics
+ */
+
+module.exports = ValidationEngine;

package/lib/i18n.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+
+class I18n {
+  constructor() {
+    this.locale = this.detectLocale();
+    this.messages = this.loadMessages(this.locale);
+  }
+
+  detectLocale() {
+    // 优先级: 环境变量 > 系统语言 > 默认英文
+    const envLocale = process.env.KIRO_LANG || process.env.LANG;
+    
+    if (envLocale) {
+      if (envLocale.startsWith('zh')) return 'zh';
+      if (envLocale.startsWith('en')) return 'en';
+    }
+
+    // 检测系统语言
+    const systemLocale = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (systemLocale.startsWith('zh')) return 'zh';
+    
+    return 'en'; // 默认英文
+  }
+
+  loadMessages(locale) {
+    try {
+      const messagesPath = path.join(__dirname, '../locales', `${locale}.json`);
+      return JSON.parse(fs.readFileSync(messagesPath, 'utf8'));
+    } catch (error) {
+      // 如果加载失败，回退到英文
+      const fallbackPath = path.join(__dirname, '../locales', 'en.json');
+      return JSON.parse(fs.readFileSync(fallbackPath, 'utf8'));
+    }
+  }
+
+  t(key, params = {}) {
+    const keys = key.split('.');
+    let value = this.messages;
+
+    for (const k of keys) {
+      if (value && typeof value === 'object') {
+        value = value[k];
+      } else {
+        return key; // 如果找不到，返回 key 本身
+      }
+    }
+
+    // 替换参数
+    if (typeof value === 'string') {
+      return value.replace(/\{(\w+)\}/g, (match, param) => {
+        return params[param] !== undefined ? params[param] : match;
+      });
+    }
+
+    return value || key;
+  }
+
+  setLocale(locale) {
+    this.locale = locale;
+    this.messages = this.loadMessages(locale);
+  }
+
+  getLocale() {
+    return this.locale;
+  }
+}
+
+// 单例模式
+let instance = null;
+
+function getI18n() {
+  if (!instance) {
+    instance = new I18n();
+  }
+  return instance;
+}
+
+module.exports = { getI18n, I18n };