scene-capability-engine 3.0.0

package/lib/governance/archive-tool.js

@@ -0,0 +1,284 @@
+/**
+ * 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 this.resolveConfiguredSubdir('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 this.resolveConfiguredSubdir('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 this.resolveConfiguredSubdir('scripts');
+    }
+    
+    // Reports - check for report keywords
+    if (lower.includes('report') || lower.includes('analysis') || 
+        lower.includes('summary') || lower.includes('diagnostic')) {
+      return this.resolveConfiguredSubdir('reports');
+    }
+    
+    // Data files
+    if (lower.includes('data')) {
+      return this.resolveConfiguredSubdir('results');
+    }
+    
+    // Default to docs for markdown and other documentation files
+    return this.resolveConfiguredSubdir('docs');
+  }
+
+  /**
+   * Resolve preferred subdirectory against project governance config
+   *
+   * @param {string} preferredSubdir - Preferred subdirectory name
+   * @returns {string}
+   */
+  resolveConfiguredSubdir(preferredSubdir) {
+    const allowedSubdirs = this.getAllowedSpecSubdirs();
+
+    // Backward compatibility when no config is available
+    if (allowedSubdirs.length === 0) {
+      return preferredSubdir;
+    }
+
+    if (allowedSubdirs.includes(preferredSubdir)) {
+      return preferredSubdir;
+    }
+
+    // Generic safe fallback for governance-customized projects
+    if (allowedSubdirs.includes('custom')) {
+      return 'custom';
+    }
+
+    // Semantic fallback when custom bucket is unavailable
+    const fallbackMap = {
+      docs: 'reports',
+      tests: 'scripts',
+      results: 'reports'
+    };
+
+    const mappedSubdir = fallbackMap[preferredSubdir];
+    if (mappedSubdir && allowedSubdirs.includes(mappedSubdir)) {
+      return mappedSubdir;
+    }
+
+    return allowedSubdirs[0];
+  }
+
+  /**
+   * Get normalized allowed Spec subdirectories from config
+   *
+   * @returns {string[]}
+   */
+  getAllowedSpecSubdirs() {
+    const configured = this.config && Array.isArray(this.config.specSubdirs)
+      ? this.config.specSubdirs
+      : [];
+
+    return configured
+      .filter(subdir => typeof subdir === 'string' && subdir.trim().length > 0)
+      .map(subdir => subdir.trim().toLowerCase());
+  }
+  
+  /**
+   * 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;

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;