kiro-spec-engine 1.4.4 → 1.5.2

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;

package/lib/governance/file-scanner.js

@@ -0,0 +1,285 @@
+/**
+ * File Scanner
+ * 
+ * Utility for scanning directories and detecting files based on patterns
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { minimatch } = require('minimatch');
+
+class FileScanner {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+  }
+  
+  /**
+   * Find all markdown files in a directory (non-recursive)
+   * 
+   * @param {string} dirPath - Directory path to scan
+   * @returns {Promise<string[]>} - Array of absolute file paths
+   */
+  async findMarkdownFiles(dirPath) {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      const mdFiles = [];
+      
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+          mdFiles.push(path.join(dirPath, entry.name));
+        }
+      }
+      
+      return mdFiles;
+    } catch (error) {
+      // If directory doesn't exist or can't be read, return empty array
+      return [];
+    }
+  }
+  
+  /**
+   * Find all markdown files in a directory recursively
+   * 
+   * @param {string} dirPath - Directory path to scan
+   * @param {Object} options - Scan options
+   * @param {string[]} options.excludeDirs - Directory names to exclude (e.g., ['node_modules', '.git'])
+   * @returns {Promise<string[]>} - Array of absolute file paths
+   */
+  async findMarkdownFilesRecursive(dirPath, options = {}) {
+    const excludeDirs = options.excludeDirs || ['node_modules', '.git'];
+    const mdFiles = [];
+    
+    try {
+      await this._scanRecursive(dirPath, mdFiles, excludeDirs);
+      return mdFiles;
+    } catch (error) {
+      // If directory doesn't exist or can't be read, return empty array
+      return [];
+    }
+  }
+  
+  /**
+   * Internal recursive scanning helper
+   * 
+   * @private
+   */
+  async _scanRecursive(dirPath, results, excludeDirs) {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        
+        if (entry.isDirectory()) {
+          // Skip excluded directories
+          if (!excludeDirs.includes(entry.name) && !entry.name.startsWith('.')) {
+            await this._scanRecursive(fullPath, results, excludeDirs);
+          }
+        } else if (entry.isFile() && entry.name.endsWith('.md')) {
+          results.push(fullPath);
+        }
+      }
+    } catch (error) {
+      // Skip directories that can't be read
+      return;
+    }
+  }
+  
+  /**
+   * Match files against glob patterns
+   * 
+   * @param {string[]} filePaths - Array of file paths to check
+   * @param {string[]} patterns - Array of glob patterns (e.g., ['*-SUMMARY.md', 'TEMP-*.md'])
+   * @returns {string[]} - Array of matching file paths
+   */
+  matchPatterns(filePaths, patterns) {
+    const matches = [];
+    
+    for (const filePath of filePaths) {
+      const basename = path.basename(filePath);
+      
+      for (const pattern of patterns) {
+        if (minimatch(basename, pattern, { nocase: false })) {
+          matches.push(filePath);
+          break; // Don't add the same file multiple times
+        }
+      }
+    }
+    
+    return matches;
+  }
+  
+  /**
+   * Check if a file matches any of the given patterns
+   * 
+   * @param {string} filePath - File path to check
+   * @param {string[]} patterns - Array of glob patterns
+   * @returns {boolean} - True if file matches any pattern
+   */
+  matchesPattern(filePath, patterns) {
+    const basename = path.basename(filePath);
+    
+    for (const pattern of patterns) {
+      if (minimatch(basename, pattern, { nocase: false })) {
+        return true;
+      }
+    }
+    
+    return false;
+  }
+  
+  /**
+   * Find all Spec directories in the project
+   * 
+   * @returns {Promise<string[]>} - Array of Spec directory paths
+   */
+  async findSpecDirectories() {
+    const specsPath = path.join(this.projectPath, '.kiro/specs');
+    
+    try {
+      const entries = await fs.readdir(specsPath, { withFileTypes: true });
+      const specDirs = [];
+      
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          specDirs.push(path.join(specsPath, entry.name));
+        }
+      }
+      
+      return specDirs;
+    } catch (error) {
+      // If .kiro/specs doesn't exist, return empty array
+      return [];
+    }
+  }
+  
+  /**
+   * Get Spec directory by name
+   * 
+   * @param {string} specName - Spec name
+   * @returns {string} - Spec directory path
+   */
+  getSpecDirectory(specName) {
+    return path.join(this.projectPath, '.kiro/specs', specName);
+  }
+  
+  /**
+   * Check if a path exists
+   * 
+   * @param {string} filePath - Path to check
+   * @returns {Promise<boolean>} - True if path exists
+   */
+  async exists(filePath) {
+    return await fs.pathExists(filePath);
+  }
+  
+  /**
+   * Check if a path is a directory
+   * 
+   * @param {string} dirPath - Path to check
+   * @returns {Promise<boolean>} - True if path is a directory
+   */
+  async isDirectory(dirPath) {
+    try {
+      const stat = await fs.stat(dirPath);
+      return stat.isDirectory();
+    } catch (error) {
+      return false;
+    }
+  }
+  
+  /**
+   * Check if a path is a file
+   * 
+   * @param {string} filePath - Path to check
+   * @returns {Promise<boolean>} - True if path is a file
+   */
+  async isFile(filePath) {
+    try {
+      const stat = await fs.stat(filePath);
+      return stat.isFile();
+    } catch (error) {
+      return false;
+    }
+  }
+  
+  /**
+   * Get all files in a directory (non-recursive)
+   * 
+   * @param {string} dirPath - Directory path
+   * @returns {Promise<string[]>} - Array of file paths
+   */
+  async getFiles(dirPath) {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      const files = [];
+      
+      for (const entry of entries) {
+        if (entry.isFile()) {
+          files.push(path.join(dirPath, entry.name));
+        }
+      }
+      
+      return files;
+    } catch (error) {
+      return [];
+    }
+  }
+  
+  /**
+   * Get all subdirectories in a directory (non-recursive)
+   * 
+   * @param {string} dirPath - Directory path
+   * @returns {Promise<string[]>} - Array of subdirectory paths
+   */
+  async getSubdirectories(dirPath) {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      const dirs = [];
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          dirs.push(path.join(dirPath, entry.name));
+        }
+      }
+      
+      return dirs;
+    } catch (error) {
+      return [];
+    }
+  }
+  
+  /**
+   * Normalize path for cross-platform compatibility
+   * 
+   * @param {string} filePath - Path to normalize
+   * @returns {string} - Normalized path
+   */
+  normalizePath(filePath) {
+    // First replace all backslashes with forward slashes for consistency
+    // Then use path.normalize to get platform-specific separators
+    return path.normalize(filePath.replace(/\\/g, '/'));
+  }
+  
+  /**
+   * Get relative path from project root
+   * 
+   * @param {string} filePath - Absolute file path
+   * @returns {string} - Relative path from project root
+   */
+  getRelativePath(filePath) {
+    return path.relative(this.projectPath, filePath);
+  }
+  
+  /**
+   * Get absolute path from relative path
+   * 
+   * @param {string} relativePath - Relative path from project root
+   * @returns {string} - Absolute path
+   */
+  getAbsolutePath(relativePath) {
+    return path.join(this.projectPath, relativePath);
+  }
+}
+
+module.exports = FileScanner;