kiro-spec-engine 1.4.4 → 1.5.5

package/lib/commands/doctor.js

@@ -1,16 +1,19 @@
 const chalk = require('chalk');
 const pythonChecker = require('../python-checker');
 const { getI18n } = require('../i18n');
+const DiagnosticEngine = require('../governance/diagnostic-engine');
+const ConfigManager = require('../governance/config-manager');
+const path = require('path');
 
 /**
  * CLI Doctor Command Component
  * 
  * Verifies system requirements and provides diagnostics.
- * Checks Node.js version and Python availability.
+ * Checks Node.js version, Python availability, and document compliance.
  * 
- * Requirements: 7.5
+ * Requirements: 7.5, 10.2
  */
-function doctorCommand() {
+async function doctorCommand(options = {}) {
   const i18n = getI18n();
   
   console.log(chalk.red('🔥') + ' ' + i18n.t('cli.commands.doctor.title'));
@@ -43,6 +46,13 @@ function doctorCommand() {
   console.log(chalk.blue('─'.repeat(60)));
   console.log();
   
+  // Check document compliance
+  await checkDocumentCompliance(options);
+  
+  console.log();
+  console.log(chalk.blue('─'.repeat(60)));
+  console.log();
+  
   // Summary
   if (pythonStatus.available) {
     console.log(chalk.green('✅ ' + i18n.t('cli.commands.doctor.all_good')));
@@ -56,4 +66,132 @@ function doctorCommand() {
   console.log();
 }
 
+/**
+ * Check document compliance
+ * 
+ * @param {Object} options - Command options
+ * @param {boolean} options.docs - Whether to show detailed diagnostics
+ */
+async function checkDocumentCompliance(options = {}) {
+  try {
+    const projectPath = process.cwd();
+    
+    // Load configuration
+    const configManager = new ConfigManager(projectPath);
+    const config = await configManager.load();
+    
+    // Run diagnostic scan
+    const diagnosticEngine = new DiagnosticEngine(projectPath, config);
+    const report = await diagnosticEngine.scan();
+    
+    // Display results based on options
+    if (options.docs) {
+      // Detailed diagnostics mode
+      displayDetailedDiagnostics(report);
+    } else {
+      // Brief compliance status
+      displayBriefCompliance(report);
+    }
+  } catch (error) {
+    console.log(chalk.yellow('⚠️  Document compliance check failed:'), error.message);
+  }
+}
+
+/**
+ * Display brief document compliance status
+ * 
+ * @param {Object} report - Diagnostic report
+ */
+function displayBriefCompliance(report) {
+  console.log(chalk.bold('Document Compliance:'));
+  
+  if (report.compliant) {
+    console.log(chalk.green('  ✓ All documents follow lifecycle management rules'));
+  } else {
+    const errorCount = report.summary.bySeverity.error || 0;
+    const warningCount = report.summary.bySeverity.warning || 0;
+    
+    if (errorCount > 0) {
+      console.log(chalk.red(`  ✗ ${errorCount} error(s) found`));
+    }
+    if (warningCount > 0) {
+      console.log(chalk.yellow(`  ⚠ ${warningCount} warning(s) found`));
+    }
+    
+    console.log(chalk.cyan(`  → Run 'kse doctor --docs' for detailed diagnostics`));
+  }
+}
+
+/**
+ * Display detailed document diagnostics
+ * 
+ * @param {Object} report - Diagnostic report
+ */
+function displayDetailedDiagnostics(report) {
+  console.log(chalk.bold.cyan('Document Governance Diagnostic:'));
+  console.log();
+  
+  if (report.compliant) {
+    console.log(chalk.green('  ✅ Project is compliant'));
+    console.log('  All documents follow the lifecycle management rules.');
+    return;
+  }
+  
+  console.log(chalk.yellow(`  ⚠️  Found ${report.violations.length} violation(s)`));
+  console.log();
+  
+  // Group violations by type
+  const byType = groupBy(report.violations, 'type');
+  
+  for (const [type, violations] of Object.entries(byType)) {
+    console.log(chalk.blue(`  ${formatType(type)} (${violations.length})`));
+    
+    for (const violation of violations) {
+      const icon = violation.severity === 'error' ? '❌' : '⚠️';
+      const relativePath = path.relative(process.cwd(), violation.path);
+      console.log(`    ${icon} ${chalk.gray(relativePath)}`);
+      console.log(`       ${violation.description}`);
+      console.log(`       ${chalk.cyan('→ ' + violation.recommendation)}`);
+    }
+    
+    console.log();
+  }
+  
+  // Display recommendations
+  if (report.recommendations && report.recommendations.length > 0) {
+    console.log(chalk.blue('  💡 Recommended Actions:'));
+    report.recommendations.forEach(rec => {
+      console.log(`    • ${rec}`);
+    });
+  }
+}
+
+/**
+ * Helper: Group array by property
+ * 
+ * @param {Array} array - Array to group
+ * @param {string} property - Property to group by
+ * @returns {Object} - Grouped object
+ */
+function 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
+ */
+function formatType(type) {
+  return type.split('_').map(word => 
+    word.charAt(0).toUpperCase() + word.slice(1)
+  ).join(' ');
+}
+
 module.exports = doctorCommand;

package/lib/commands/status.js

@@ -9,6 +9,8 @@ const path = require('path');
 const fs = require('fs-extra');
 const TaskClaimer = require('../task/task-claimer');
 const WorkspaceManager = require('../workspace/workspace-manager');
+const DiagnosticEngine = require('../governance/diagnostic-engine');
+const ConfigManager = require('../governance/config-manager');
 
 /**
  * Executes the status command
@@ -57,7 +59,10 @@ async function statusCommand(options = {}) {
     
     console.log();
     
-    // 3. List specs
+    // 3. Document compliance status
+    await displayDocumentCompliance(projectPath);
+    
+    // 4. List specs
     const specsPath = path.join(projectPath, '.kiro/specs');
     const specsExist = await fs.pathExists(specsPath);
     
@@ -83,7 +88,7 @@ async function statusCommand(options = {}) {
     console.log(chalk.blue(`📁 Specs (${specDirs.length})`));
     console.log();
     
-    // 4. Analyze each spec
+    // 5. Analyze each spec
     const taskClaimer = new TaskClaimer();
     const allClaimedTasks = [];
     
@@ -145,7 +150,7 @@ async function statusCommand(options = {}) {
       console.log();
     }
     
-    // 5. Team activity view
+    // 6. Team activity view
     if (team && allClaimedTasks.length > 0) {
       console.log(chalk.blue('👥 Team Activity'));
       console.log();
@@ -186,7 +191,7 @@ async function statusCommand(options = {}) {
       });
     }
     
-    // 6. Summary
+    // 7. Summary
     if (allClaimedTasks.length > 0) {
       const staleClaims = allClaimedTasks.filter(t => t.isStale);
       
@@ -202,7 +207,7 @@ async function statusCommand(options = {}) {
       }
     }
     
-    // 7. Next steps
+    // 8. Next steps
     console.log(chalk.blue('💡 Commands'));
     console.log('  View team activity: ' + chalk.cyan('kse status --team'));
     console.log('  Detailed view: ' + chalk.cyan('kse status --verbose'));
@@ -222,4 +227,71 @@ async function statusCommand(options = {}) {
   }
 }
 
+/**
+ * Display document compliance status
+ * 
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<void>}
+ */
+async function displayDocumentCompliance(projectPath) {
+  try {
+    // Load configuration
+    const configManager = new ConfigManager(projectPath);
+    await configManager.load();
+    
+    // Run diagnostic scan
+    const diagnosticEngine = new DiagnosticEngine(projectPath, configManager.config);
+    const report = await diagnosticEngine.scan();
+    
+    // Display compliance status
+    console.log(chalk.blue('📄 Document Compliance'));
+    
+    if (report.compliant) {
+      console.log(`  Status: ${chalk.green('✅ Compliant')}`);
+      console.log(`  ${chalk.gray('All documents follow lifecycle management rules')}`);
+    } else {
+      const errorCount = report.violations.filter(v => v.severity === 'error').length;
+      const warningCount = report.violations.filter(v => v.severity === 'warning').length;
+      
+      console.log(`  Status: ${chalk.red('❌ Non-Compliant')}`);
+      console.log(`  Violations: ${chalk.red(errorCount)} error(s), ${chalk.yellow(warningCount)} warning(s)`);
+      
+      // Show violation breakdown by type
+      const byType = {};
+      report.violations.forEach(v => {
+        byType[v.type] = (byType[v.type] || 0) + 1;
+      });
+      
+      const typeNames = {
+        'root_violation': 'Root directory',
+        'spec_violation': 'Spec structure',
+        'missing_file': 'Missing files',
+        'misplaced_artifact': 'Misplaced artifacts',
+        'temporary_document': 'Temporary documents'
+      };
+      
+      Object.entries(byType).forEach(([type, count]) => {
+        const name = typeNames[type] || type;
+        console.log(`    • ${name}: ${count}`);
+      });
+      
+      console.log();
+      console.log(chalk.cyan('  Quick Fix Commands:'));
+      console.log(`    ${chalk.gray('•')} Run diagnostics: ${chalk.cyan('kse doctor --docs')}`);
+      console.log(`    ${chalk.gray('•')} Clean temporary files: ${chalk.cyan('kse cleanup')}`);
+      console.log(`    ${chalk.gray('•')} Validate structure: ${chalk.cyan('kse validate --all')}`);
+      console.log(`    ${chalk.gray('•')} Archive artifacts: ${chalk.cyan('kse archive --spec <name>')}`);
+    }
+    
+    console.log();
+  } catch (error) {
+    // Silently skip if governance components not available
+    // This allows status to work even if governance is not fully set up
+    if (error.code !== 'MODULE_NOT_FOUND') {
+      console.log(chalk.gray('  (Document compliance check skipped)'));
+      console.log();
+    }
+  }
+}
+
 module.exports = statusCommand;

package/lib/governance/archive-tool.js

@@ -0,0 +1,231 @@
+/**
+ * Archive Tool
+ * 
+ * Organizes Spec artifacts into proper subdirectories
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const FileScanner = require('./file-scanner');
+
+class ArchiveTool {
+  constructor(projectPath, config) {
+    this.projectPath = projectPath;
+    this.config = config;
+    this.scanner = new FileScanner(projectPath);
+    this.movedFiles = [];
+    this.errors = [];
+  }
+  
+  /**
+   * Archive artifacts in a Spec directory
+   * 
+   * @param {string} specName - Spec name
+   * @param {Object} options - Archive options
+   * @param {boolean} options.dryRun - Preview without moving
+   * @returns {Promise<ArchiveReport>}
+   */
+  async archive(specName, options = {}) {
+    const specPath = this.scanner.getSpecDirectory(specName);
+    
+    // Check if Spec directory exists
+    if (!await this.scanner.exists(specPath)) {
+      this.errors.push({
+        path: specPath,
+        error: `Spec directory does not exist: ${specName}`
+      });
+      return this.generateReport();
+    }
+    
+    const artifacts = await this.identifyArtifacts(specPath);
+    
+    if (options.dryRun) {
+      return this.generateDryRunReport(artifacts);
+    }
+    
+    for (const artifact of artifacts) {
+      await this.moveArtifact(artifact);
+    }
+    
+    return this.generateReport();
+  }
+  
+  /**
+   * Identify artifacts to archive
+   * 
+   * @param {string} specPath - Path to Spec directory
+   * @returns {Promise<Artifact[]>}
+   */
+  async identifyArtifacts(specPath) {
+    const artifacts = [];
+    const files = await this.scanner.getFiles(specPath);
+    const requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
+    
+    for (const filePath of files) {
+      const basename = path.basename(filePath);
+      
+      // Skip required files
+      if (requiredFiles.includes(basename)) {
+        continue;
+      }
+      
+      const targetSubdir = this.determineTargetSubdir(basename);
+      artifacts.push({
+        sourcePath: filePath,
+        targetSubdir: targetSubdir,
+        filename: basename
+      });
+    }
+    
+    return artifacts;
+  }
+  
+  /**
+   * Determine target subdirectory for a file
+   * 
+   * @param {string} filename - File name
+   * @returns {string}
+   */
+  determineTargetSubdir(filename) {
+    const lower = filename.toLowerCase();
+    
+    // Results - check for result keywords FIRST (before test patterns)
+    // This ensures "test-results.json" goes to results, not tests
+    if (lower.includes('result') || lower.includes('output')) {
+      return 'results';
+    }
+    
+    // Tests - check for test patterns (test files, not result files)
+    if (lower.endsWith('.test.js') || lower.endsWith('.spec.js') || 
+        lower.includes('.test.') || lower.includes('.spec.') ||
+        (lower.includes('test') && (lower.endsWith('.js') || lower.endsWith('.py')))) {
+      return 'tests';
+    }
+    
+    // Scripts - check for script extensions and keywords
+    if (lower.endsWith('.js') || lower.endsWith('.py') || 
+        lower.endsWith('.sh') || lower.endsWith('.bat') ||
+        lower.includes('script')) {
+      return 'scripts';
+    }
+    
+    // Reports - check for report keywords
+    if (lower.includes('report') || lower.includes('analysis') || 
+        lower.includes('summary') || lower.includes('diagnostic')) {
+      return 'reports';
+    }
+    
+    // Data files
+    if (lower.includes('data')) {
+      return 'results';
+    }
+    
+    // Default to docs for markdown and other documentation files
+    return 'docs';
+  }
+  
+  /**
+   * Move an artifact to its target subdirectory
+   * 
+   * @param {Artifact} artifact - Artifact to move
+   * @returns {Promise<void>}
+   */
+  async moveArtifact(artifact) {
+    try {
+      const targetDir = path.join(
+        path.dirname(artifact.sourcePath),
+        artifact.targetSubdir
+      );
+      
+      // Ensure target directory exists
+      await fs.ensureDir(targetDir);
+      
+      const targetPath = path.join(targetDir, artifact.filename);
+      
+      // Check if target file already exists
+      if (await fs.pathExists(targetPath)) {
+        this.errors.push({
+          path: artifact.sourcePath,
+          error: `Target file already exists: ${targetPath}`
+        });
+        return;
+      }
+      
+      await fs.move(artifact.sourcePath, targetPath);
+      
+      this.movedFiles.push({
+        from: artifact.sourcePath,
+        to: targetPath
+      });
+    } catch (error) {
+      this.errors.push({
+        path: artifact.sourcePath,
+        error: error.message
+      });
+    }
+  }
+  
+  /**
+   * Generate dry run report
+   * 
+   * @param {Artifact[]} artifacts - Artifacts that would be moved
+   * @returns {ArchiveReport}
+   */
+  generateDryRunReport(artifacts) {
+    const movedFiles = artifacts.map(artifact => ({
+      from: artifact.sourcePath,
+      to: path.join(
+        path.dirname(artifact.sourcePath),
+        artifact.targetSubdir,
+        artifact.filename
+      )
+    }));
+    
+    return {
+      success: true,
+      movedFiles: movedFiles,
+      errors: [],
+      summary: {
+        totalMoved: movedFiles.length,
+        totalErrors: 0
+      },
+      dryRun: true
+    };
+  }
+  
+  /**
+   * Generate archive report
+   * 
+   * @returns {ArchiveReport}
+   */
+  generateReport() {
+    return {
+      success: this.errors.length === 0,
+      movedFiles: this.movedFiles,
+      errors: this.errors,
+      summary: {
+        totalMoved: this.movedFiles.length,
+        totalErrors: this.errors.length
+      },
+      dryRun: false
+    };
+  }
+}
+
+/**
+ * @typedef {Object} Artifact
+ * @property {string} sourcePath - Current file path
+ * @property {string} targetSubdir - Target subdirectory name
+ * @property {string} filename - File name
+ */
+
+/**
+ * @typedef {Object} ArchiveReport
+ * @property {boolean} success - Whether archiving succeeded
+ * @property {Object[]} movedFiles - Files that were moved
+ * @property {Object[]} errors - Errors encountered
+ * @property {Object} summary - Summary statistics
+ * @property {boolean} dryRun - Whether this was a dry run
+ */
+
+module.exports = ArchiveTool;