scene-capability-engine 3.0.0

package/lib/governance/diagnostic-engine.js

@@ -0,0 +1,271 @@
+/**
+ * Diagnostic Engine
+ * 
+ * Scans and analyzes project documentation structure
+ */
+
+const path = require('path');
+const FileScanner = require('./file-scanner');
+const ConfigManager = require('./config-manager');
+
+class DiagnosticEngine {
+  constructor(projectPath, config) {
+    this.projectPath = projectPath;
+    this.config = config;
+    this.scanner = new FileScanner(projectPath);
+    this.violations = [];
+  }
+  
+  /**
+   * Run full diagnostic scan
+   * 
+   * @returns {Promise<DiagnosticReport>}
+   */
+  async scan() {
+    this.violations = []; // Reset violations
+    
+    await this.scanRootDirectory();
+    await this.scanSpecDirectories();
+    
+    return this.generateReport();
+  }
+  
+  /**
+   * Scan root directory for violations
+   * 
+   * @returns {Promise<void>}
+   */
+  async scanRootDirectory() {
+    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)) {
+        // Check if it's a temporary document
+        const isTemporary = this.scanner.matchesPattern(filePath, this.config.temporaryPatterns || []);
+        
+        this.violations.push({
+          type: 'root_violation',
+          path: filePath,
+          description: `Unexpected markdown file in root directory: ${basename}`,
+          severity: isTemporary ? 'warning' : 'error',
+          recommendation: isTemporary 
+            ? `Delete temporary file: ${basename}` 
+            : `Move ${basename} to appropriate location or delete if temporary`
+        });
+      }
+    }
+  }
+  
+  /**
+   * Scan all Spec directories
+   * 
+   * @returns {Promise<void>}
+   */
+  async scanSpecDirectories() {
+    const specDirs = await this.scanner.findSpecDirectories();
+    
+    for (const specDir of specDirs) {
+      await this.scanSpecDirectory(specDir);
+    }
+  }
+  
+  /**
+   * Scan a single Spec directory
+   * 
+   * @param {string} specPath - Path to Spec directory
+   * @returns {Promise<void>}
+   */
+  async scanSpecDirectory(specPath) {
+    const specName = path.basename(specPath);
+    const requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
+    
+    // Check for missing required files
+    for (const requiredFile of requiredFiles) {
+      const filePath = path.join(specPath, requiredFile);
+      const exists = await this.scanner.exists(filePath);
+      
+      if (!exists) {
+        this.violations.push({
+          type: 'missing_required_file',
+          path: filePath,
+          description: `Missing required file in Spec ${specName}: ${requiredFile}`,
+          severity: 'error',
+          recommendation: `Create ${requiredFile} in ${specName}`
+        });
+      }
+    }
+    
+    // Check for temporary documents in Spec directory
+    const mdFiles = await this.scanner.findMarkdownFiles(specPath);
+    const temporaryFiles = this.scanner.matchPatterns(mdFiles, this.config.temporaryPatterns || []);
+    
+    for (const tempFile of temporaryFiles) {
+      const basename = path.basename(tempFile);
+      
+      // Don't flag required files as temporary even if they match patterns
+      if (!requiredFiles.includes(basename)) {
+        this.violations.push({
+          type: 'temporary_document',
+          path: tempFile,
+          description: `Temporary document should be deleted: ${basename}`,
+          severity: 'warning',
+          recommendation: `Delete temporary file: ${basename} from ${specName}`
+        });
+      }
+    }
+    
+    // Check for misplaced artifacts (files not in subdirectories)
+    const allFiles = await this.scanner.getFiles(specPath);
+    
+    for (const filePath of allFiles) {
+      const basename = path.basename(filePath);
+      
+      // Skip required files
+      if (requiredFiles.includes(basename)) {
+        continue;
+      }
+      
+      // Skip temporary files (already flagged as temporary_document)
+      if (this.scanner.matchesPattern(filePath, this.config.temporaryPatterns || [])) {
+        continue;
+      }
+      
+      // This is a misplaced artifact
+      this.violations.push({
+        type: 'misplaced_artifact',
+        path: filePath,
+        description: `Artifact not in subdirectory: ${basename}`,
+        severity: 'warning',
+        recommendation: `Move ${basename} to appropriate subdirectory (${this.config.specSubdirs.join(', ')})`
+      });
+    }
+    
+    // Check subdirectory naming
+    const subdirs = await this.scanner.getSubdirectories(specPath);
+    const allowedSubdirs = this.config.specSubdirs || [];
+    
+    for (const subdirPath of subdirs) {
+      const subdirName = path.basename(subdirPath);
+      
+      // Skip hidden directories
+      if (subdirName.startsWith('.')) {
+        continue;
+      }
+      
+      if (!allowedSubdirs.includes(subdirName)) {
+        this.violations.push({
+          type: 'invalid_subdirectory',
+          path: subdirPath,
+          description: `Non-standard subdirectory in Spec ${specName}: ${subdirName}`,
+          severity: 'info',
+          recommendation: `Rename to one of: ${allowedSubdirs.join(', ')}, or remove if not needed`
+        });
+      }
+    }
+  }
+  
+  /**
+   * Generate diagnostic report
+   * 
+   * @returns {DiagnosticReport}
+   */
+  generateReport() {
+    const compliant = this.violations.length === 0;
+    
+    return {
+      compliant,
+      violations: this.violations,
+      summary: this.generateSummary(),
+      recommendations: this.generateRecommendations()
+    };
+  }
+  
+  /**
+   * Generate summary statistics
+   * 
+   * @returns {Object}
+   */
+  generateSummary() {
+    const summary = {
+      totalViolations: this.violations.length,
+      byType: {},
+      bySeverity: {
+        error: 0,
+        warning: 0,
+        info: 0
+      }
+    };
+    
+    // Count by type
+    for (const violation of this.violations) {
+      summary.byType[violation.type] = (summary.byType[violation.type] || 0) + 1;
+      summary.bySeverity[violation.severity] = (summary.bySeverity[violation.severity] || 0) + 1;
+    }
+    
+    return summary;
+  }
+  
+  /**
+   * Generate actionable recommendations
+   * 
+   * @returns {string[]}
+   */
+  generateRecommendations() {
+    const recommendations = [];
+    const summary = this.generateSummary();
+    
+    // Root violations
+    if (summary.byType.root_violation > 0) {
+      recommendations.push('Run `kse cleanup` to remove temporary files from root directory');
+    }
+    
+    // Temporary documents
+    if (summary.byType.temporary_document > 0) {
+      recommendations.push('Run `kse cleanup` to remove temporary documents from Spec directories');
+    }
+    
+    // Misplaced artifacts
+    if (summary.byType.misplaced_artifact > 0) {
+      recommendations.push('Run `kse docs archive --spec <spec-name>` to organize artifacts into subdirectories');
+    }
+    
+    // Missing required files
+    if (summary.byType.missing_required_file > 0) {
+      recommendations.push('Create missing required files (requirements.md, design.md, tasks.md) in affected Specs');
+    }
+    
+    // Invalid subdirectories
+    if (summary.byType.invalid_subdirectory > 0) {
+      recommendations.push('Rename non-standard subdirectories to match allowed names');
+    }
+    
+    // General recommendation
+    if (recommendations.length > 0) {
+      recommendations.push('Run `kse validate --all` after fixes to confirm compliance');
+    }
+    
+    return recommendations;
+  }
+}
+
+/**
+ * @typedef {Object} DiagnosticReport
+ * @property {boolean} compliant - Whether project is compliant
+ * @property {Violation[]} violations - List of violations found
+ * @property {Object} summary - Summary statistics
+ * @property {string[]} recommendations - Actionable recommendations
+ */
+
+/**
+ * @typedef {Object} Violation
+ * @property {string} type - Violation type (root_violation, spec_violation, etc.)
+ * @property {string} path - File or directory path
+ * @property {string} description - Human-readable description
+ * @property {string} severity - Severity level (error, warning, info)
+ * @property {string} recommendation - How to fix
+ */
+
+module.exports = DiagnosticEngine;

package/lib/governance/doc-reference-checker.js

@@ -0,0 +1,200 @@
+/**
+ * Document Reference Checker
+ * 
+ * Checks for incorrect project references and unresolved placeholders in documentation
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+class DocReferenceChecker {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    
+    // Common incorrect references to check
+    this.incorrectReferences = [
+      '上海图书馆',
+      'MinIO',
+      '测试项目',
+      '简化测试项目',
+      'Kiro AI-OS'
+    ];
+    
+    // Placeholder patterns to check
+    this.placeholderPatterns = [
+      /\[TODO:.*?\]/g,
+      /\[项目名称.*?\]/g,
+      /\[请修改.*?\]/g,
+      /\[根据项目.*?\]/g
+    ];
+    
+    // Files to check
+    this.filesToCheck = [
+      '.kiro/specs/SPEC_WORKFLOW_GUIDE.md',
+      '.kiro/steering/ENVIRONMENT.md',
+      '.kiro/steering/CURRENT_CONTEXT.md',
+      '.kiro/README.md',
+      'README.md',
+      'package.json'
+    ];
+  }
+  
+  /**
+   * Check all documentation files
+   * 
+   * @returns {Promise<Object>} Check results
+   */
+  async checkAll() {
+    const results = {
+      incorrectReferences: [],
+      unresolvedPlaceholders: [],
+      filesChecked: 0,
+      issuesFound: 0
+    };
+    
+    for (const file of this.filesToCheck) {
+      const filePath = path.join(this.projectRoot, file);
+      
+      if (await fs.pathExists(filePath)) {
+        results.filesChecked++;
+        const fileResults = await this.checkFile(filePath);
+        
+        if (fileResults.incorrectReferences.length > 0) {
+          results.incorrectReferences.push({
+            file,
+            references: fileResults.incorrectReferences
+          });
+          results.issuesFound += fileResults.incorrectReferences.length;
+        }
+        
+        if (fileResults.unresolvedPlaceholders.length > 0) {
+          results.unresolvedPlaceholders.push({
+            file,
+            placeholders: fileResults.unresolvedPlaceholders
+          });
+          results.issuesFound += fileResults.unresolvedPlaceholders.length;
+        }
+      }
+    }
+    
+    return results;
+  }
+  
+  /**
+   * Check a single file
+   * 
+   * @param {string} filePath - Path to file
+   * @returns {Promise<Object>} File check results
+   */
+  async checkFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const lines = content.split('\n');
+    
+    const results = {
+      incorrectReferences: [],
+      unresolvedPlaceholders: []
+    };
+    
+    // Check for incorrect references
+    lines.forEach((line, index) => {
+      this.incorrectReferences.forEach(ref => {
+        if (line.includes(ref)) {
+          results.incorrectReferences.push({
+            line: index + 1,
+            content: line.trim(),
+            reference: ref
+          });
+        }
+      });
+    });
+    
+    // Check for unresolved placeholders (only in non-template files)
+    if (!filePath.includes('template/')) {
+      lines.forEach((line, index) => {
+        this.placeholderPatterns.forEach(pattern => {
+          const matches = line.match(pattern);
+          if (matches) {
+            matches.forEach(match => {
+              results.unresolvedPlaceholders.push({
+                line: index + 1,
+                content: line.trim(),
+                placeholder: match
+              });
+            });
+          }
+        });
+      });
+    }
+    
+    return results;
+  }
+  
+  /**
+   * Generate report
+   * 
+   * @param {Object} results - Check results
+   * @returns {string} Formatted report
+   */
+  generateReport(results) {
+    let report = '# Document Reference Check Report\n\n';
+    report += `**Date**: ${new Date().toISOString().split('T')[0]}\n`;
+    report += `**Files Checked**: ${results.filesChecked}\n`;
+    report += `**Issues Found**: ${results.issuesFound}\n\n`;
+    
+    if (results.issuesFound === 0) {
+      report += '✅ **No issues found!** All documentation is clean.\n';
+      return report;
+    }
+    
+    // Incorrect references
+    if (results.incorrectReferences.length > 0) {
+      report += '## 🔴 Incorrect Project References\n\n';
+      results.incorrectReferences.forEach(item => {
+        report += `### ${item.file}\n\n`;
+        item.references.forEach(ref => {
+          report += `- **Line ${ref.line}**: Found "${ref.reference}"\n`;
+          report += `  \`\`\`\n  ${ref.content}\n  \`\`\`\n\n`;
+        });
+      });
+    }
+    
+    // Unresolved placeholders
+    if (results.unresolvedPlaceholders.length > 0) {
+      report += '## 🟡 Unresolved Placeholders\n\n';
+      results.unresolvedPlaceholders.forEach(item => {
+        report += `### ${item.file}\n\n`;
+        item.placeholders.forEach(ph => {
+          report += `- **Line ${ph.line}**: ${ph.placeholder}\n`;
+          report += `  \`\`\`\n  ${ph.content}\n  \`\`\`\n\n`;
+        });
+      });
+    }
+    
+    // Recommendations
+    report += '## 💡 Recommendations\n\n';
+    if (results.incorrectReferences.length > 0) {
+      report += '1. Remove or replace incorrect project references\n';
+      report += '2. Ensure all documentation reflects the correct project identity\n';
+    }
+    if (results.unresolvedPlaceholders.length > 0) {
+      report += '3. Replace all [TODO: ...] placeholders with actual project information\n';
+      report += '4. Update ENVIRONMENT.md with correct project details\n';
+    }
+    
+    return report;
+  }
+  
+  /**
+   * Save report to file
+   * 
+   * @param {string} report - Report content
+   * @param {string} outputPath - Output file path
+   * @returns {Promise<void>}
+   */
+  async saveReport(report, outputPath) {
+    await fs.ensureDir(path.dirname(outputPath));
+    await fs.writeFile(outputPath, report, 'utf-8');
+  }
+}
+
+module.exports = DocReferenceChecker;

package/lib/governance/execution-logger.js

@@ -0,0 +1,243 @@
+/**
+ * Execution Logger
+ * 
+ * Tracks governance tool executions for metrics and reporting
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+class ExecutionLogger {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.logDir = path.join(projectPath, '.kiro', 'logs');
+    this.logFile = path.join(this.logDir, 'governance-history.json');
+    this.maxLogSize = 10 * 1024 * 1024; // 10MB
+    this.maxRotatedLogs = 5;
+  }
+  
+  /**
+   * Log a governance tool execution
+   * 
+   * @param {string} tool - Tool name (diagnostic, cleanup, validation, archive)
+   * @param {string} operation - Operation performed
+   * @param {Object} results - Operation results
+   * @returns {Promise<void>}
+   */
+  async logExecution(tool, operation, results) {
+    try {
+      // Ensure log directory exists
+      await fs.ensureDir(this.logDir);
+      
+      // Check if log rotation is needed
+      await this.rotateLogIfNeeded();
+      
+      // Create log entry
+      const entry = {
+        timestamp: new Date().toISOString(),
+        tool,
+        operation,
+        results: this.sanitizeResults(results)
+      };
+      
+      // Read existing log or create new array
+      let logEntries = [];
+      if (await fs.pathExists(this.logFile)) {
+        try {
+          const content = await fs.readFile(this.logFile, 'utf8');
+          logEntries = JSON.parse(content);
+          
+          // Ensure it's an array
+          if (!Array.isArray(logEntries)) {
+            logEntries = [];
+          }
+        } catch (error) {
+          // If log file is corrupted, start fresh
+          console.warn('Log file corrupted, starting fresh');
+          logEntries = [];
+        }
+      }
+      
+      // Append new entry
+      logEntries.push(entry);
+      
+      // Write back to file
+      await fs.writeFile(this.logFile, JSON.stringify(logEntries, null, 2), 'utf8');
+    } catch (error) {
+      // Log errors should not break the main operation
+      console.error('Failed to log execution:', error.message);
+    }
+  }
+  
+  /**
+   * Get execution history
+   * 
+   * @param {Object} options - Filter options
+   * @param {string} options.tool - Filter by tool name
+   * @param {Date} options.since - Filter by date
+   * @param {number} options.limit - Limit number of entries
+   * @returns {Promise<Array>}
+   */
+  async getHistory(options = {}) {
+    try {
+      // Check if log file exists
+      if (!await fs.pathExists(this.logFile)) {
+        return [];
+      }
+      
+      // Read log file
+      const content = await fs.readFile(this.logFile, 'utf8');
+      let entries = JSON.parse(content);
+      
+      // Ensure it's an array
+      if (!Array.isArray(entries)) {
+        return [];
+      }
+      
+      // Apply filters
+      if (options.tool) {
+        entries = entries.filter(entry => entry.tool === options.tool);
+      }
+      
+      if (options.since) {
+        const sinceTime = options.since.getTime();
+        entries = entries.filter(entry => {
+          const entryTime = new Date(entry.timestamp).getTime();
+          return entryTime >= sinceTime;
+        });
+      }
+      
+      // Apply limit
+      if (options.limit && options.limit > 0) {
+        entries = entries.slice(-options.limit);
+      }
+      
+      return entries;
+    } catch (error) {
+      console.error('Failed to read execution history:', error.message);
+      return [];
+    }
+  }
+  
+  /**
+   * Rotate log file if it exceeds max size
+   * 
+   * @returns {Promise<void>}
+   */
+  async rotateLogIfNeeded() {
+    try {
+      // Check if log file exists
+      if (!await fs.pathExists(this.logFile)) {
+        return;
+      }
+      
+      // Check file size
+      const stats = await fs.stat(this.logFile);
+      
+      if (stats.size < this.maxLogSize) {
+        return;
+      }
+      
+      // Rotate logs
+      await this.rotateLog();
+    } catch (error) {
+      console.error('Failed to check log size:', error.message);
+    }
+  }
+  
+  /**
+   * Rotate log file
+   * 
+   * @returns {Promise<void>}
+   */
+  async rotateLog() {
+    try {
+      // Remove oldest rotated log if we have max number
+      const oldestLog = path.join(this.logDir, `governance-history.${this.maxRotatedLogs}.json`);
+      if (await fs.pathExists(oldestLog)) {
+        await fs.remove(oldestLog);
+      }
+      
+      // Shift existing rotated logs
+      for (let i = this.maxRotatedLogs - 1; i >= 1; i--) {
+        const currentLog = path.join(this.logDir, `governance-history.${i}.json`);
+        const nextLog = path.join(this.logDir, `governance-history.${i + 1}.json`);
+        
+        if (await fs.pathExists(currentLog)) {
+          await fs.move(currentLog, nextLog, { overwrite: true });
+        }
+      }
+      
+      // Rotate current log to .1
+      const rotatedLog = path.join(this.logDir, 'governance-history.1.json');
+      await fs.move(this.logFile, rotatedLog, { overwrite: true });
+      
+      // Create new empty log
+      await fs.writeFile(this.logFile, '[]', 'utf8');
+    } catch (error) {
+      console.error('Failed to rotate log:', error.message);
+    }
+  }
+  
+  /**
+   * Sanitize results for logging (remove sensitive data, limit size)
+   * 
+   * @param {Object} results - Operation results
+   * @returns {Object}
+   */
+  sanitizeResults(results) {
+    // Create a shallow copy
+    const sanitized = { ...results };
+    
+    // Limit array sizes to prevent huge logs
+    const maxArraySize = 100;
+    
+    if (Array.isArray(sanitized.violations) && sanitized.violations.length > maxArraySize) {
+      sanitized.violations = sanitized.violations.slice(0, maxArraySize);
+      sanitized.violationsTruncated = true;
+    }
+    
+    if (Array.isArray(sanitized.deletedFiles) && sanitized.deletedFiles.length > maxArraySize) {
+      sanitized.deletedFiles = sanitized.deletedFiles.slice(0, maxArraySize);
+      sanitized.deletedFilesTruncated = true;
+    }
+    
+    if (Array.isArray(sanitized.movedFiles) && sanitized.movedFiles.length > maxArraySize) {
+      sanitized.movedFiles = sanitized.movedFiles.slice(0, maxArraySize);
+      sanitized.movedFilesTruncated = true;
+    }
+    
+    if (Array.isArray(sanitized.errors) && sanitized.errors.length > maxArraySize) {
+      sanitized.errors = sanitized.errors.slice(0, maxArraySize);
+      sanitized.errorsTruncated = true;
+    }
+    
+    return sanitized;
+  }
+  
+  /**
+   * Clear all logs (for testing or reset)
+   * 
+   * @returns {Promise<void>}
+   */
+  async clearLogs() {
+    try {
+      // Remove main log file
+      if (await fs.pathExists(this.logFile)) {
+        await fs.remove(this.logFile);
+      }
+      
+      // Remove rotated logs
+      for (let i = 1; i <= this.maxRotatedLogs; i++) {
+        const rotatedLog = path.join(this.logDir, `governance-history.${i}.json`);
+        if (await fs.pathExists(rotatedLog)) {
+          await fs.remove(rotatedLog);
+        }
+      }
+    } catch (error) {
+      console.error('Failed to clear logs:', error.message);
+    }
+  }
+}
+
+module.exports = ExecutionLogger;