claude-code-templates 1.21.13 → 1.22.1

package/src/validation/ValidationOrchestrator.js

@@ -0,0 +1,305 @@
+const StructuralValidator = require('./validators/StructuralValidator');
+const IntegrityValidator = require('./validators/IntegrityValidator');
+const SemanticValidator = require('./validators/SemanticValidator');
+const ReferenceValidator = require('./validators/ReferenceValidator');
+const ProvenanceValidator = require('./validators/ProvenanceValidator');
+const chalk = require('chalk');
+
+/**
+ * ValidationOrchestrator - Coordinates all validators and generates comprehensive reports
+ *
+ * Runs all validators in sequence and aggregates results
+ */
+class ValidationOrchestrator {
+  constructor() {
+    this.validators = {
+      structural: new StructuralValidator(),
+      integrity: new IntegrityValidator(),
+      semantic: new SemanticValidator(),
+      reference: new ReferenceValidator(),
+      provenance: new ProvenanceValidator()
+    };
+  }
+
+  /**
+   * Validate a single component with all validators
+   * @param {object} component - Component to validate
+   * @param {object} options - Validation options
+   * @param {Array<string>} options.validators - List of validators to run (default: all)
+   * @param {boolean} options.strict - Enable strict mode
+   * @param {boolean} options.updateRegistry - Update hash registry
+   * @returns {Promise<object>} Comprehensive validation results
+   */
+  async validateComponent(component, options = {}) {
+    const {
+      validators = ['structural', 'integrity', 'semantic', 'reference', 'provenance'],
+      strict = false,
+      updateRegistry = false
+    } = options;
+
+    const results = {
+      component: {
+        path: component.path,
+        type: component.type
+      },
+      timestamp: new Date().toISOString(),
+      overall: {
+        valid: true,
+        score: 0,
+        errorCount: 0,
+        warningCount: 0
+      },
+      validators: {}
+    };
+
+    // Run each validator
+    for (const validatorName of validators) {
+      if (!this.validators[validatorName]) {
+        console.warn(chalk.yellow(`⚠️  Unknown validator: ${validatorName}`));
+        continue;
+      }
+
+      try {
+        const validator = this.validators[validatorName];
+        let validatorOptions = {};
+
+        // Validator-specific options
+        if (validatorName === 'semantic') {
+          validatorOptions.strict = strict;
+        } else if (validatorName === 'integrity') {
+          validatorOptions.updateRegistry = updateRegistry;
+        }
+
+        const result = await validator.validate(component, validatorOptions);
+
+        results.validators[validatorName] = {
+          valid: result.valid,
+          score: result.score || 0,
+          errorCount: result.errorCount,
+          warningCount: result.warningCount,
+          errors: result.errors,
+          warnings: result.warnings,
+          info: result.info
+        };
+
+        // Add validator-specific metadata
+        if (result.hash) {
+          results.validators[validatorName].hash = result.hash;
+        }
+        if (result.metadata) {
+          results.validators[validatorName].metadata = result.metadata;
+        }
+
+        // Update overall results
+        if (!result.valid) {
+          results.overall.valid = false;
+        }
+        results.overall.errorCount += result.errorCount;
+        results.overall.warningCount += result.warningCount;
+
+      } catch (error) {
+        results.validators[validatorName] = {
+          valid: false,
+          error: error.message,
+          errorCount: 1,
+          warningCount: 0
+        };
+        results.overall.valid = false;
+        results.overall.errorCount++;
+      }
+    }
+
+    // Calculate overall score (average of all validator scores)
+    const scores = Object.values(results.validators)
+      .map(v => v.score || 0)
+      .filter(s => s > 0);
+
+    if (scores.length > 0) {
+      results.overall.score = Math.round(
+        scores.reduce((sum, score) => sum + score, 0) / scores.length
+      );
+    }
+
+    return results;
+  }
+
+  /**
+   * Validate multiple components
+   * @param {Array<object>} components - Components to validate
+   * @param {object} options - Validation options
+   * @returns {Promise<object>} Batch validation results
+   */
+  async validateComponents(components, options = {}) {
+    const results = {
+      summary: {
+        total: components.length,
+        passed: 0,
+        failed: 0,
+        warnings: 0
+      },
+      components: [],
+      timestamp: new Date().toISOString()
+    };
+
+    for (const component of components) {
+      const result = await this.validateComponent(component, options);
+
+      results.components.push(result);
+
+      if (result.overall.valid) {
+        results.summary.passed++;
+      } else {
+        results.summary.failed++;
+      }
+
+      results.summary.warnings += result.overall.warningCount;
+    }
+
+    return results;
+  }
+
+  /**
+   * Generate human-readable report
+   * @param {object} validationResults - Results from validateComponent or validateComponents
+   * @param {object} options - Report options
+   * @param {boolean} options.verbose - Include detailed information
+   * @param {boolean} options.colors - Use colored output (default: true)
+   * @returns {string} Formatted report
+   */
+  generateReport(validationResults, options = {}) {
+    const { verbose = false, colors = true } = options;
+    const lines = [];
+
+    // Helper functions for colored output
+    const success = (text) => colors ? chalk.green(text) : text;
+    const error = (text) => colors ? chalk.red(text) : text;
+    const warning = (text) => colors ? chalk.yellow(text) : text;
+    const info = (text) => colors ? chalk.blue(text) : text;
+    const dim = (text) => colors ? chalk.gray(text) : text;
+
+    // Check if this is a batch result or single component result
+    const isBatch = validationResults.summary && validationResults.components;
+
+    if (isBatch) {
+      // Batch report
+      lines.push('');
+      lines.push(info('🔒 Security Audit Report'));
+      lines.push(dim('━'.repeat(60)));
+      lines.push('');
+
+      lines.push(`📊 Summary:`);
+      lines.push(`   Total components: ${validationResults.summary.total}`);
+      lines.push(`   ${success('✅ Passed')}: ${validationResults.summary.passed}`);
+      lines.push(`   ${error('❌ Failed')}: ${validationResults.summary.failed}`);
+      lines.push(`   ${warning('⚠️  Warnings')}: ${validationResults.summary.warnings}`);
+      lines.push('');
+
+      // Component details
+      for (const component of validationResults.components) {
+        lines.push(this._formatComponentResult(component, verbose, { success, error, warning, info, dim }));
+      }
+    } else {
+      // Single component report
+      lines.push(this._formatComponentResult(validationResults, verbose, { success, error, warning, info, dim }));
+    }
+
+    lines.push(dim('━'.repeat(60)));
+    lines.push('');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format a single component result
+   * @private
+   */
+  _formatComponentResult(componentResult, verbose, colors) {
+    const { success, error, warning, info, dim } = colors;
+    const lines = [];
+
+    const status = componentResult.overall.valid ? success('✅ PASS') : error('❌ FAIL');
+    const scoreBadge = this._getScoreBadge(componentResult.overall.score, colors);
+
+    lines.push(`${status} ${componentResult.component.path} ${scoreBadge}`);
+
+    // Validator breakdown
+    for (const [validatorName, result] of Object.entries(componentResult.validators)) {
+      const validatorStatus = result.valid ? success('✅') : error('❌');
+      const validatorScore = result.score ? dim(`(${result.score}/100)`) : '';
+
+      lines.push(`   ├─ ${validatorStatus} ${validatorName}: ${result.errorCount === 0 ? 'PASS' : `${result.errorCount} errors`} ${validatorScore}`);
+
+      // Show errors
+      if (result.errors && result.errors.length > 0 && verbose) {
+        for (const err of result.errors.slice(0, 3)) {
+          lines.push(`   │  ${error('ERROR')}: ${err.message} ${dim(`[${err.code}]`)}`);
+        }
+        if (result.errors.length > 3) {
+          lines.push(`   │  ${dim(`... and ${result.errors.length - 3} more errors`)}`);
+        }
+      }
+
+      // Show warnings
+      if (result.warnings && result.warnings.length > 0 && verbose) {
+        for (const warn of result.warnings.slice(0, 2)) {
+          lines.push(`   │  ${warning('WARNING')}: ${warn.message} ${dim(`[${warn.code}]`)}`);
+        }
+        if (result.warnings.length > 2) {
+          lines.push(`   │  ${dim(`... and ${result.warnings.length - 2} more warnings`)}`);
+        }
+      }
+    }
+
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  /**
+   * Get score badge with color
+   * @private
+   */
+  _getScoreBadge(score, colors) {
+    const { success, error, warning, dim } = colors;
+
+    if (score >= 90) return success(`[${score}/100]`);
+    if (score >= 70) return warning(`[${score}/100]`);
+    if (score >= 50) return error(`[${score}/100]`);
+    return dim(`[${score}/100]`);
+  }
+
+  /**
+   * Generate JSON report
+   * @param {object} validationResults - Results from validateComponent or validateComponents
+   * @returns {string} JSON formatted report
+   */
+  generateJsonReport(validationResults) {
+    return JSON.stringify(validationResults, null, 2);
+  }
+
+  /**
+   * Get all error codes from results
+   * @param {object} validationResults - Validation results
+   * @returns {Array<string>} Unique error codes
+   */
+  getErrorCodes(validationResults) {
+    const codes = new Set();
+
+    const processResult = (result) => {
+      for (const validator of Object.values(result.validators)) {
+        if (validator.errors) {
+          validator.errors.forEach(err => codes.add(err.code));
+        }
+      }
+    };
+
+    if (validationResults.components) {
+      validationResults.components.forEach(processResult);
+    } else {
+      processResult(validationResults);
+    }
+
+    return Array.from(codes).sort();
+  }
+}
+
+module.exports = ValidationOrchestrator;

package/src/validation/validators/IntegrityValidator.js

@@ -0,0 +1,338 @@
+const BaseValidator = require('../BaseValidator');
+const crypto = require('crypto');
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * IntegrityValidator - Validates component integrity and versioning
+ *
+ * Checks:
+ * - SHA256 hash generation
+ * - Hash verification against stored hashes
+ * - Version tracking
+ * - Signature validation (future)
+ * - Tamper detection
+ */
+class IntegrityValidator extends BaseValidator {
+  constructor() {
+    super();
+
+    // Path to store component hashes (relative to project)
+    this.HASH_REGISTRY_PATH = '.claude/security/component-hashes.json';
+  }
+
+  /**
+   * Validate component integrity
+   * @param {object} component - Component data
+   * @param {string} component.content - Raw markdown content
+   * @param {string} component.path - File path
+   * @param {string} component.type - Component type
+   * @param {string} component.version - Component version (optional)
+   * @param {object} options - Validation options
+   * @param {boolean} options.updateRegistry - Update hash registry after validation
+   * @param {string} options.expectedHash - Expected hash to verify against
+   * @returns {Promise<object>} Validation results with hash
+   */
+  async validate(component, options = {}) {
+    this.reset();
+
+    const { content, path: filePath, type, version } = component;
+    const { updateRegistry = false, expectedHash = null } = options;
+
+    if (!content) {
+      this.addError('INT_E001', 'Component content is empty or missing', { path: filePath });
+      return this.getResults();
+    }
+
+    // 1. Generate SHA256 hash
+    const hash = this.generateHash(content);
+    this.addInfo('INT_I001', `Generated SHA256 hash`, {
+      path: filePath,
+      hash: hash.substring(0, 16) + '...',
+      fullHash: hash
+    });
+
+    // 2. Verify against expected hash if provided
+    if (expectedHash) {
+      this.verifyHash(hash, expectedHash, filePath);
+    }
+
+    // 3. Check hash registry for changes
+    await this.checkHashRegistry(filePath, hash, type, version);
+
+    // 4. Validate version if provided
+    // Note: Version is optional for components - metadata is stored in marketplace.json
+    if (version) {
+      this.validateVersion(version, filePath);
+    } else {
+      this.addInfo('INT_I009', 'No version in component (metadata in marketplace.json)', {
+        path: filePath
+      });
+    }
+
+    // 5. Update registry if requested
+    if (updateRegistry) {
+      await this.updateHashRegistry(filePath, hash, type, version);
+    }
+
+    // Add hash to results for external use
+    const results = this.getResults();
+    results.hash = hash;
+    results.version = version;
+
+    return results;
+  }
+
+  /**
+   * Generate SHA256 hash of content
+   * @param {string} content - Content to hash
+   * @returns {string} SHA256 hash in hex format
+   */
+  generateHash(content) {
+    return crypto
+      .createHash('sha256')
+      .update(content, 'utf8')
+      .digest('hex');
+  }
+
+  /**
+   * Verify hash matches expected hash
+   * @param {string} actualHash - Generated hash
+   * @param {string} expectedHash - Expected hash
+   * @param {string} filePath - File path for error reporting
+   */
+  verifyHash(actualHash, expectedHash, filePath) {
+    if (actualHash !== expectedHash) {
+      this.addError(
+        'INT_E002',
+        'Hash mismatch: Component content has been modified',
+        {
+          path: filePath,
+          expected: expectedHash.substring(0, 16) + '...',
+          actual: actualHash.substring(0, 16) + '...',
+          fullExpected: expectedHash,
+          fullActual: actualHash
+        }
+      );
+    } else {
+      this.addInfo('INT_I002', 'Hash verification passed', { path: filePath });
+    }
+  }
+
+  /**
+   * Check component hash against registry
+   * @param {string} filePath - File path
+   * @param {string} currentHash - Current hash
+   * @param {string} type - Component type
+   * @param {string} version - Component version
+   */
+  async checkHashRegistry(filePath, currentHash, type, version) {
+    try {
+      const registry = await this.loadHashRegistry();
+      const normalizedPath = this.normalizePath(filePath);
+
+      if (registry[normalizedPath]) {
+        const stored = registry[normalizedPath];
+
+        // Check if hash has changed
+        if (stored.hash !== currentHash) {
+          this.addWarning(
+            'INT_W001',
+            'Component hash has changed since last validation',
+            {
+              path: filePath,
+              previousHash: stored.hash.substring(0, 16) + '...',
+              currentHash: currentHash.substring(0, 16) + '...',
+              lastValidated: stored.timestamp
+            }
+          );
+        } else {
+          this.addInfo('INT_I003', 'Hash matches registry', {
+            path: filePath,
+            lastValidated: stored.timestamp
+          });
+        }
+
+        // Check version changes
+        if (version && stored.version && stored.version !== version) {
+          this.addInfo('INT_I004', 'Version updated', {
+            path: filePath,
+            previousVersion: stored.version,
+            currentVersion: version
+          });
+        }
+      } else {
+        this.addInfo('INT_I005', 'Component not in registry (new component)', {
+          path: filePath
+        });
+      }
+    } catch (error) {
+      // Registry doesn't exist or couldn't be read - this is OK for new setups
+      this.addInfo('INT_I006', 'Hash registry not found (first run)', {
+        path: filePath
+      });
+    }
+  }
+
+  /**
+   * Validate version format
+   * @param {string} version - Version string
+   * @param {string} filePath - File path for error reporting
+   */
+  validateVersion(version, filePath) {
+    // Support semantic versioning (X.Y.Z) and simple versions
+    const semverPattern = /^\d+\.\d+\.\d+$/;
+    const simplePattern = /^\d+(\.\d+)?$/;
+
+    if (!semverPattern.test(version) && !simplePattern.test(version)) {
+      this.addWarning(
+        'INT_W003',
+        `Version format "${version}" doesn't follow semantic versioning (X.Y.Z)`,
+        {
+          path: filePath,
+          version,
+          recommendation: 'Use semantic versioning (e.g., 1.0.0)'
+        }
+      );
+    } else {
+      this.addInfo('INT_I007', `Valid version: ${version}`, { path: filePath, version });
+    }
+  }
+
+  /**
+   * Update hash registry with new hash
+   * @param {string} filePath - File path
+   * @param {string} hash - Current hash
+   * @param {string} type - Component type
+   * @param {string} version - Component version
+   */
+  async updateHashRegistry(filePath, hash, type, version) {
+    try {
+      const registry = await this.loadHashRegistry();
+      const normalizedPath = this.normalizePath(filePath);
+
+      registry[normalizedPath] = {
+        hash,
+        type,
+        version: version || 'unversioned',
+        timestamp: new Date().toISOString(),
+        path: filePath
+      };
+
+      await this.saveHashRegistry(registry);
+
+      this.addInfo('INT_I008', 'Hash registry updated', {
+        path: filePath,
+        hash: hash.substring(0, 16) + '...'
+      });
+    } catch (error) {
+      this.addWarning(
+        'INT_W004',
+        `Failed to update hash registry: ${error.message}`,
+        { path: filePath, error: error.message }
+      );
+    }
+  }
+
+  /**
+   * Load hash registry from file
+   * @returns {Promise<object>} Registry object
+   */
+  async loadHashRegistry() {
+    const registryPath = path.join(process.cwd(), this.HASH_REGISTRY_PATH);
+
+    if (await fs.pathExists(registryPath)) {
+      return await fs.readJson(registryPath);
+    }
+
+    return {};
+  }
+
+  /**
+   * Save hash registry to file
+   * @param {object} registry - Registry object to save
+   */
+  async saveHashRegistry(registry) {
+    const registryPath = path.join(process.cwd(), this.HASH_REGISTRY_PATH);
+
+    // Ensure directory exists
+    await fs.ensureDir(path.dirname(registryPath));
+
+    // Save with pretty formatting
+    await fs.writeJson(registryPath, registry, { spaces: 2 });
+  }
+
+  /**
+   * Normalize file path for consistent registry keys
+   * @param {string} filePath - File path to normalize
+   * @returns {string} Normalized path
+   */
+  normalizePath(filePath) {
+    // Convert to relative path from project root
+    const cwd = process.cwd();
+    if (filePath.startsWith(cwd)) {
+      return path.relative(cwd, filePath);
+    }
+    return filePath;
+  }
+
+  /**
+   * Generate integrity report for a component
+   * @param {object} component - Component data
+   * @returns {Promise<object>} Integrity report
+   */
+  async generateIntegrityReport(component) {
+    const result = await this.validate(component);
+
+    return {
+      valid: result.valid,
+      hash: result.hash,
+      version: result.version,
+      timestamp: new Date().toISOString(),
+      issues: {
+        errors: result.errors,
+        warnings: result.warnings
+      }
+    };
+  }
+
+  /**
+   * Batch validate multiple components
+   * @param {Array<object>} components - Array of components to validate
+   * @param {object} options - Validation options
+   * @returns {Promise<object>} Batch validation results
+   */
+  async batchValidate(components, options = {}) {
+    const results = {
+      total: components.length,
+      passed: 0,
+      failed: 0,
+      warnings: 0,
+      components: []
+    };
+
+    for (const component of components) {
+      const result = await this.validate(component, options);
+
+      results.components.push({
+        path: component.path,
+        valid: result.valid,
+        hash: result.hash,
+        errors: result.errorCount,
+        warnings: result.warningCount
+      });
+
+      if (result.valid) {
+        results.passed++;
+      } else {
+        results.failed++;
+      }
+
+      results.warnings += result.warningCount;
+    }
+
+    return results;
+  }
+}
+
+module.exports = IntegrityValidator;