kiro-spec-engine 1.4.4 → 1.5.2

package/lib/governance/cleanup-tool.js

@@ -0,0 +1,237 @@
+/**
+ * Cleanup Tool
+ * 
+ * Removes temporary and non-compliant documents
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const inquirer = require('inquirer');
+const FileScanner = require('./file-scanner');
+
+class CleanupTool {
+  constructor(projectPath, config) {
+    this.projectPath = projectPath;
+    this.config = config;
+    this.scanner = new FileScanner(projectPath);
+    this.deletedFiles = [];
+    this.errors = [];
+  }
+  
+  /**
+   * Execute cleanup operation
+   * 
+   * @param {Object} options - Cleanup options
+   * @param {boolean} options.dryRun - Preview without deleting
+   * @param {boolean} options.interactive - Prompt for each file
+   * @param {string} options.spec - Specific Spec to clean
+   * @returns {Promise<CleanupReport>}
+   */
+  async cleanup(options = {}) {
+    const filesToDelete = await this.identifyFilesToDelete(options.spec);
+    
+    if (options.dryRun) {
+      return this.generateDryRunReport(filesToDelete);
+    }
+    
+    for (const file of filesToDelete) {
+      if (options.interactive) {
+        const shouldDelete = await this.promptForConfirmation(file);
+        if (!shouldDelete) continue;
+      }
+      
+      await this.deleteFile(file);
+    }
+    
+    return this.generateReport();
+  }
+  
+  /**
+   * Identify files to delete
+   * 
+   * @param {string} specName - Optional specific Spec
+   * @returns {Promise<string[]>}
+   */
+  async identifyFilesToDelete(specName = null) {
+    const files = [];
+    
+    // Scan root directory
+    files.push(...await this.scanRootForTemporary());
+    
+    // Scan Spec directories
+    if (specName) {
+      files.push(...await this.scanSpecForTemporary(specName));
+    } else {
+      files.push(...await this.scanAllSpecsForTemporary());
+    }
+    
+    return files;
+  }
+  
+  /**
+   * Scan root directory for temporary files
+   * 
+   * @returns {Promise<string[]>}
+   */
+  async scanRootForTemporary() {
+    const temporaryFiles = [];
+    const mdFiles = await this.scanner.findMarkdownFiles(this.projectPath);
+    const allowedFiles = this.config.rootAllowedFiles || [];
+    const temporaryPatterns = this.config.temporaryPatterns || [];
+    
+    for (const filePath of mdFiles) {
+      const basename = path.basename(filePath);
+      
+      // If not in allowed list, check if it matches temporary patterns
+      if (!allowedFiles.includes(basename)) {
+        // Check if it matches any temporary pattern
+        if (this.scanner.matchesPattern(filePath, temporaryPatterns)) {
+          temporaryFiles.push(filePath);
+        }
+      }
+    }
+    
+    return temporaryFiles;
+  }
+  
+  /**
+   * Scan a specific Spec directory for temporary files
+   * 
+   * @param {string} specName - Spec name
+   * @returns {Promise<string[]>}
+   */
+  async scanSpecForTemporary(specName) {
+    const temporaryFiles = [];
+    const specPath = this.scanner.getSpecDirectory(specName);
+    
+    // Check if Spec directory exists
+    if (!await this.scanner.exists(specPath)) {
+      return temporaryFiles;
+    }
+    
+    const mdFiles = await this.scanner.findMarkdownFiles(specPath);
+    const temporaryPatterns = this.config.temporaryPatterns || [];
+    const requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
+    
+    for (const filePath of mdFiles) {
+      const basename = path.basename(filePath);
+      
+      // Don't delete required files even if they match patterns
+      if (requiredFiles.includes(basename)) {
+        continue;
+      }
+      
+      // Check if it matches any temporary pattern
+      if (this.scanner.matchesPattern(filePath, temporaryPatterns)) {
+        temporaryFiles.push(filePath);
+      }
+    }
+    
+    return temporaryFiles;
+  }
+  
+  /**
+   * Scan all Spec directories for temporary files
+   * 
+   * @returns {Promise<string[]>}
+   */
+  async scanAllSpecsForTemporary() {
+    const temporaryFiles = [];
+    const specDirs = await this.scanner.findSpecDirectories();
+    
+    for (const specDir of specDirs) {
+      const specName = path.basename(specDir);
+      const specTemporaryFiles = await this.scanSpecForTemporary(specName);
+      temporaryFiles.push(...specTemporaryFiles);
+    }
+    
+    return temporaryFiles;
+  }
+  
+  /**
+   * Prompt user for confirmation to delete a file
+   * 
+   * @param {string} filePath - Path to file
+   * @returns {Promise<boolean>}
+   */
+  async promptForConfirmation(filePath) {
+    const relativePath = this.scanner.getRelativePath(filePath);
+    
+    const answer = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'shouldDelete',
+        message: `Delete ${relativePath}?`,
+        default: false
+      }
+    ]);
+    
+    return answer.shouldDelete;
+  }
+  
+  /**
+   * Delete a file safely
+   * 
+   * @param {string} filePath - Path to file
+   * @returns {Promise<void>}
+   */
+  async deleteFile(filePath) {
+    try {
+      await fs.remove(filePath);
+      this.deletedFiles.push(filePath);
+    } catch (error) {
+      this.errors.push({ 
+        path: filePath, 
+        error: error.message 
+      });
+    }
+  }
+  
+  /**
+   * Generate dry run report
+   * 
+   * @param {string[]} filesToDelete - Files that would be deleted
+   * @returns {CleanupReport}
+   */
+  generateDryRunReport(filesToDelete) {
+    return {
+      success: true,
+      deletedFiles: filesToDelete,
+      errors: [],
+      summary: {
+        totalDeleted: filesToDelete.length,
+        totalErrors: 0
+      },
+      dryRun: true
+    };
+  }
+  
+  /**
+   * Generate cleanup report
+   * 
+   * @returns {CleanupReport}
+   */
+  generateReport() {
+    return {
+      success: this.errors.length === 0,
+      deletedFiles: this.deletedFiles,
+      errors: this.errors,
+      summary: {
+        totalDeleted: this.deletedFiles.length,
+        totalErrors: this.errors.length
+      },
+      dryRun: false
+    };
+  }
+}
+
+/**
+ * @typedef {Object} CleanupReport
+ * @property {boolean} success - Whether cleanup succeeded
+ * @property {string[]} deletedFiles - Files that were deleted
+ * @property {Object[]} errors - Errors encountered
+ * @property {Object} summary - Summary statistics
+ * @property {boolean} dryRun - Whether this was a dry run
+ */
+
+module.exports = CleanupTool;

package/lib/governance/config-manager.js

@@ -0,0 +1,186 @@
+/**
+ * Configuration Manager
+ * 
+ * Manages document governance configuration
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+
+class ConfigManager {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.configPath = path.join(projectPath, '.kiro/config/docs.json');
+    this.config = null;
+  }
+  
+  /**
+   * Load configuration
+   * 
+   * @returns {Promise<Object>}
+   */
+  async load() {
+    if (await fs.pathExists(this.configPath)) {
+      try {
+        this.config = await fs.readJson(this.configPath);
+        
+        // Validate and merge with defaults to ensure all required fields exist
+        const defaults = this.getDefaults();
+        this.config = { ...defaults, ...this.config };
+        
+      } catch (error) {
+        console.warn('Config file corrupted, using defaults');
+        this.config = this.getDefaults();
+      }
+    } else {
+      this.config = this.getDefaults();
+    }
+    
+    return this.config;
+  }
+  
+  /**
+   * Get default configuration
+   * 
+   * @returns {Object}
+   */
+  getDefaults() {
+    return {
+      rootAllowedFiles: [
+        'README.md',
+        'README.zh.md',
+        'CHANGELOG.md',
+        'CONTRIBUTING.md'
+      ],
+      specSubdirs: [
+        'reports',
+        'scripts',
+        'tests',
+        'results',
+        'docs'
+      ],
+      temporaryPatterns: [
+        '*-SUMMARY.md',
+        'SESSION-*.md',
+        '*-COMPLETE.md',
+        'TEMP-*.md',
+        'WIP-*.md',
+        'MVP-*.md'
+      ]
+    };
+  }
+  
+  /**
+   * Save configuration
+   * 
+   * @param {Object} config - Configuration to save
+   * @returns {Promise<void>}
+   */
+  async save(config) {
+    await fs.ensureDir(path.dirname(this.configPath));
+    await fs.writeJson(this.configPath, config, { spaces: 2 });
+    this.config = config;
+  }
+  
+  /**
+   * Update a configuration value
+   * 
+   * @param {string} key - Configuration key
+   * @param {any} value - New value
+   * @returns {Promise<void>}
+   */
+  async set(key, value) {
+    if (!this.config) {
+      await this.load();
+    }
+    
+    this.config[key] = value;
+    await this.save(this.config);
+  }
+  
+  /**
+   * Get a configuration value
+   * 
+   * @param {string} key - Configuration key
+   * @returns {any} - Configuration value
+   */
+  get(key) {
+    if (!this.config) {
+      throw new Error('Configuration not loaded. Call load() first.');
+    }
+    
+    return this.config[key];
+  }
+  
+  /**
+   * Get all configuration
+   * 
+   * @returns {Object} - Complete configuration object
+   */
+  getAll() {
+    if (!this.config) {
+      throw new Error('Configuration not loaded. Call load() first.');
+    }
+    
+    return { ...this.config };
+  }
+  
+  /**
+   * Reset to defaults
+   * 
+   * @returns {Promise<void>}
+   */
+  async reset() {
+    this.config = this.getDefaults();
+    await this.save(this.config);
+  }
+  
+  /**
+   * Validate configuration structure
+   * 
+   * @param {Object} config - Configuration to validate
+   * @returns {Object} - Validation result { valid: boolean, errors: string[] }
+   */
+  validate(config) {
+    const errors = [];
+    
+    // Check required fields
+    if (!config.rootAllowedFiles || !Array.isArray(config.rootAllowedFiles)) {
+      errors.push('rootAllowedFiles must be an array');
+    }
+    
+    if (!config.specSubdirs || !Array.isArray(config.specSubdirs)) {
+      errors.push('specSubdirs must be an array');
+    }
+    
+    if (!config.temporaryPatterns || !Array.isArray(config.temporaryPatterns)) {
+      errors.push('temporaryPatterns must be an array');
+    }
+    
+    // Check array contents
+    if (config.rootAllowedFiles && Array.isArray(config.rootAllowedFiles)) {
+      if (config.rootAllowedFiles.some(f => typeof f !== 'string')) {
+        errors.push('rootAllowedFiles must contain only strings');
+      }
+    }
+    
+    if (config.specSubdirs && Array.isArray(config.specSubdirs)) {
+      if (config.specSubdirs.some(d => typeof d !== 'string')) {
+        errors.push('specSubdirs must contain only strings');
+      }
+    }
+    
+    if (config.temporaryPatterns && Array.isArray(config.temporaryPatterns)) {
+      if (config.temporaryPatterns.some(p => typeof p !== 'string')) {
+        errors.push('temporaryPatterns must contain only strings');
+      }
+    }
+    
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+}
+
+module.exports = ConfigManager;

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 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;