sumulige-claude 1.1.0 → 1.1.1

package/lib/config-validator.js

@@ -0,0 +1,330 @@
+/**
+ * Configuration Validator
+ *
+ * AJV-based configuration validation with detailed error reporting.
+ * Provides structured error messages, severity levels, and auto-fix suggestions.
+ *
+ * @module lib/config-validator
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { CONFIG_SCHEMA, SETTINGS_SCHEMA, QUALITY_GATE_SCHEMA } = require('./config-schema');
+const { ConfigError, parseAJVErrors } = require('./errors');
+
+// Try to load AJV, provide fallback if not available
+let Ajv = null;
+let addFormats = null;
+
+try {
+  Ajv = require('ajv');
+  addFormats = require('ajv-formats');
+} catch {
+  // AJV not installed - will use basic validation
+}
+
+/**
+ * Configuration Validator class
+ */
+class ConfigValidator {
+  /**
+   * @param {Object} options - Validator options
+   * @param {boolean} options.strict - Strict mode (default: false)
+   * @param {boolean} options.allErrors - Collect all errors (default: true)
+   * @param {boolean} options.coerceTypes - Coerce types (default: true)
+   * @param {boolean} options.useDefaults - Use default values (default: false)
+   */
+  constructor(options = {}) {
+    this.strict = options.strict !== false;
+    this.allErrors = options.allErrors !== false;
+    this.coerceTypes = options.coerceTypes !== false;
+    this.useDefaults = options.useDefaults || false;
+
+    // Initialize AJV if available
+    if (Ajv) {
+      this.ajv = new Ajv({
+        allErrors: this.allErrors,
+        verbose: true,
+        coerceTypes: this.coerceTypes,
+        useDefaults: this.useDefaults,
+        allowUnionTypes: true,
+        strict: false,
+        removeAdditional: false  // Keep additional properties
+      });
+
+      // Add formats if available
+      if (addFormats) {
+        addFormats(this.ajv);
+      }
+
+      // Compile schemas
+      this.configValidate = this.ajv.compile(CONFIG_SCHEMA);
+      this.settingsValidate = this.ajv.compile(SETTINGS_SCHEMA);
+      this.qualityGateValidate = this.ajv.compile(QUALITY_GATE_SCHEMA);
+    } else {
+      // Fallback: basic validation without AJV
+      this.configValidate = null;
+      this.settingsValidate = null;
+      this.qualityGateValidate = null;
+    }
+  }
+
+  /**
+   * Validate configuration object
+   * @param {Object} config - Configuration to validate
+   * @param {string} schemaName - Schema name ('config' | 'settings' | 'quality-gate')
+   * @returns {Object} Validation result
+   */
+  validate(config, schemaName = 'config') {
+    // If AJV not available, do basic validation
+    if (!this.ajv) {
+      return this._basicValidate(config, schemaName);
+    }
+
+    const validate = this._getValidator(schemaName);
+
+    if (!validate) {
+      return {
+        valid: false,
+        errors: [{
+          path: 'schema',
+          message: `Unknown schema: ${schemaName}`,
+          severity: 'critical',
+          fix: `Use valid schema name: config, settings, quality-gate`
+        }],
+        warnings: [],
+        fixes: []
+      };
+    }
+
+    const valid = validate(config);
+
+    if (valid) {
+      return { valid: true, errors: [], warnings: [], fixes: [] };
+    }
+
+    // Process AJV errors
+    const result = {
+      valid: false,
+      errors: [],
+      warnings: [],
+      fixes: []
+    };
+
+    const processedErrors = parseAJVErrors(validate.errors);
+
+    for (const error of processedErrors) {
+      if (error.severity === 'warn' || error.severity === 'info') {
+        result.warnings.push(error);
+      } else {
+        result.errors.push(error);
+      }
+      if (error.fix) {
+        result.fixes.push(error.fix);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Validate configuration file
+   * @param {string} configPath - Path to config file
+   * @param {string} schemaName - Schema name to use
+   * @returns {Object} Validation result
+   */
+  validateFile(configPath, schemaName = null) {
+    // Auto-detect schema from filename if not provided
+    if (!schemaName) {
+      const filename = path.basename(configPath);
+      if (filename === 'config.json') {
+        schemaName = 'config';
+      } else if (filename === 'settings.json' || filename === 'settings.local.json') {
+        schemaName = 'settings';
+      } else if (filename === 'quality-gate.json') {
+        schemaName = 'quality-gate';
+      } else {
+        schemaName = 'config';
+      }
+    }
+
+    if (!fs.existsSync(configPath)) {
+      return {
+        valid: false,
+        errors: [{
+          path: configPath,
+          message: 'Configuration file not found',
+          severity: 'critical',
+          fix: `Create config at: ${configPath}`
+        }],
+        warnings: [],
+        fixes: []
+      };
+    }
+
+    try {
+      const content = fs.readFileSync(configPath, 'utf-8');
+      const config = JSON.parse(content);
+      return this.validate(config, schemaName);
+    } catch (e) {
+      if (e instanceof SyntaxError) {
+        return {
+          valid: false,
+          errors: [{
+            path: configPath,
+            message: `JSON parse error: ${e.message}`,
+            severity: 'critical',
+            fix: this._suggestJsonFix(e, configPath)
+          }],
+          warnings: [],
+          fixes: []
+        };
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Validate with error throwing
+   * @param {Object} config - Configuration to validate
+   * @param {string} schemaName - Schema name
+   * @throws {ConfigError} If validation fails
+   */
+  validateOrThrow(config, schemaName = 'config') {
+    const result = this.validate(config, schemaName);
+    if (!result.valid) {
+      throw new ConfigError(
+        'Configuration validation failed',
+        result.errors,
+        result.fixes
+      );
+    }
+    return config;
+  }
+
+  /**
+   * Get validator for schema name
+   * @param {string} schemaName - Schema name
+   * @returns {Function|null} Validator function
+   */
+  _getValidator(schemaName) {
+    const validators = {
+      config: this.configValidate,
+      settings: this.settingsValidate,
+      'quality-gate': this.qualityGateValidate
+    };
+    return validators[schemaName] || null;
+  }
+
+  /**
+   * Basic validation without AJV
+   * @param {Object} config - Configuration to validate
+   * @param {string} schemaName - Schema name
+   * @returns {Object} Validation result
+   */
+  _basicValidate(config, schemaName) {
+    const result = {
+      valid: true,
+      errors: [],
+      warnings: [],
+      fixes: []
+    };
+
+    // Basic type check
+    if (!config || typeof config !== 'object') {
+      result.valid = false;
+      result.errors.push({
+        path: 'root',
+        message: 'Configuration must be an object',
+        severity: 'critical',
+        fix: 'Ensure config is valid JSON object'
+      });
+      return result;
+    }
+
+    // Schema-specific basic validation
+    if (schemaName === 'config') {
+      if (!config.version) {
+        result.valid = false;
+        result.errors.push({
+          path: 'version',
+          message: 'Missing required field: version',
+          severity: 'critical',
+          fix: 'Add "version": "1.0.0" to config'
+        });
+      } else if (typeof config.version === 'string' &&
+                 !/^\d+\.\d+\.\d+/.test(config.version)) {
+        result.valid = false;
+        result.errors.push({
+          path: 'version',
+          message: 'Invalid version format',
+          severity: 'error',
+          expected: 'X.Y.Z',
+          actual: config.version,
+          fix: 'Use semantic version format (e.g., 1.0.0)'
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Suggest fix for JSON parsing errors
+   * @param {Error} error - JSON parse error
+   * @param {string} filePath - Path to file
+   * @returns {string} Fix suggestion
+   */
+  _suggestJsonFix(error, filePath) {
+    const match = error.message.match(/position (\d+)/);
+    if (match) {
+      const pos = parseInt(match[1]);
+      try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const line = content.substring(0, pos).split('\n').length;
+        const col = pos - content.lastIndexOf('\n', pos - 1);
+        return `Check line ${line}, column ${col} for syntax errors (missing comma, quote, bracket, etc.)`;
+      } catch {
+        return `Check around position ${pos} for syntax errors`;
+      }
+    }
+    return 'Verify JSON syntax (commas, quotes, brackets are properly closed)';
+  }
+
+  /**
+   * Check if AJV is available
+   * @returns {boolean}
+   */
+  static isAJVAvailable() {
+    return Ajv !== null;
+  }
+}
+
+/**
+ * Create a default validator instance
+ */
+const defaultValidator = new ConfigValidator();
+
+/**
+ * Convenience functions using default validator
+ */
+function validate(config, schemaName) {
+  return defaultValidator.validate(config, schemaName);
+}
+
+function validateFile(configPath, schemaName) {
+  return defaultValidator.validateFile(configPath, schemaName);
+}
+
+function validateOrThrow(config, schemaName) {
+  return defaultValidator.validateOrThrow(config, schemaName);
+}
+
+module.exports = {
+  ConfigValidator,
+  defaultValidator,
+  validate,
+  validateFile,
+  validateOrThrow,
+  isAJVAvailable: ConfigValidator.isAJVAvailable
+};

package/lib/config.js

@@ -2,6 +2,9 @@
  * Config - Configuration management
  *
  * Loads default config and merges with user config from ~/.claude/config.json
+ *
+ * v2.0: Supports new ConfigManager with validation, backup, and rollback.
+ *       Enable with SMC_USE_NEW_CONFIG=1 environment variable.
  */
 
 const fs = require('fs');
@@ -11,6 +14,25 @@ const defaults = require('../config/defaults.json');
 const CONFIG_DIR = path.join(process.env.HOME, '.claude');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
+// Try to load new ConfigManager (v2.0)
+let ConfigManager = null;
+let newManager = null;
+
+try {
+  ({ ConfigManager } = require('./config-manager'));
+} catch {
+  // New system not available, use legacy
+}
+
+/**
+ * Check if new config system should be used
+ */
+function useNewSystem() {
+  return process.env.SMC_USE_NEW_CONFIG === '1' ||
+         process.env.SMC_CONFIG_V2 === '1' ||
+         process.env.SMC_STRICT_CONFIG === '1';
+}
+
 /**
  * Deep merge two objects
  */
@@ -31,6 +53,24 @@ function deepMerge(target, source) {
  * @returns {Object} Merged configuration
  */
 exports.loadConfig = function() {
+  // Use new system if enabled and available
+  if (useNewSystem() && ConfigManager) {
+    if (!newManager) {
+      newManager = new ConfigManager();
+    }
+    try {
+      return newManager.load({ expandEnv: true });
+    } catch (e) {
+      console.warn(`[Config] ${e.message}`);
+      if (process.env.SMC_STRICT_CONFIG === '1') {
+        throw e;
+      }
+      // Fall back to legacy on validation error
+      console.warn('[Config] Falling back to legacy config system');
+    }
+  }
+
+  // Legacy implementation
   if (fs.existsSync(CONFIG_FILE)) {
     try {
       const userConfig = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
@@ -47,10 +87,21 @@ exports.loadConfig = function() {
 /**
  * Save configuration to file
  * @param {Object} config - Configuration to save
+ * @param {Object} options - Save options
  */
-exports.saveConfig = function(config) {
+exports.saveConfig = function(config, options = {}) {
+  // Use new system if enabled and available
+  if (useNewSystem() && ConfigManager) {
+    if (!newManager) {
+      newManager = new ConfigManager();
+    }
+    return newManager.save(config, options);
+  }
+
+  // Legacy implementation
   exports.ensureDir(CONFIG_DIR);
   fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  return { success: true };
 };
 
 /**

package/lib/errors.js

@@ -0,0 +1,305 @@
+/**
+ * Structured Error Types
+ *
+ * Provides structured error information with recovery hints.
+ * All errors include:
+ * - Error code for programmatic handling
+ * - Severity level (info/warn/error/critical)
+ * - Details object with context
+ * - Hints array with recovery suggestions
+ * - Optional documentation URL
+ *
+ * @module lib/errors
+ */
+
+/**
+ * Base SMC Error class
+ */
+class SMCError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} options - Error options
+   * @param {string} options.code - Error code (e.g., 'ERR_CONFIG')
+   * @param {string} options.severity - Severity level: 'info' | 'warn' | 'error' | 'critical'
+   * @param {Object} options.details - Additional error details
+   * @param {string[]} options.hints - Recovery hints
+   * @param {string} options.docUrl - Documentation URL
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options.code || 'ERR_UNKNOWN';
+    this.severity = options.severity || 'error';
+    this.details = options.details || {};
+    this.hints = options.hints || [];
+    this.docUrl = options.docUrl;
+
+    // Maintain proper stack trace
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+
+  /**
+   * Convert error to JSON-serializable object
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      severity: this.severity,
+      details: this.details,
+      hints: this.hints,
+      docUrl: this.docUrl
+    };
+  }
+
+  /**
+   * Format error for console output
+   */
+  toString() {
+    let output = `[${this.code}] ${this.message}`;
+    if (this.hints.length > 0) {
+      output += '\n\nSuggestions:\n';
+      this.hints.forEach((h, i) => {
+        output += `  ${i + 1}. ${h}\n`;
+      });
+    }
+    if (this.docUrl) {
+      output += `\nDocs: ${this.docUrl}\n`;
+    }
+    return output;
+  }
+
+  /**
+   * Check if this error has a specific severity level or higher
+   * @param {string} minSeverity - Minimum severity to check against
+   * @returns {boolean}
+   */
+  hasSeverity(minSeverity) {
+    const levels = { info: 0, warn: 1, error: 2, critical: 3 };
+    return levels[this.severity] >= levels[minSeverity];
+  }
+}
+
+/**
+ * Configuration-related errors
+ * Used for config file parsing, validation, and loading issues
+ */
+class ConfigError extends SMCError {
+  /**
+   * @param {string} message - Error message
+   * @param {Object[]} errors - Array of validation errors
+   * @param {string[]} fixes - Array of auto-fix suggestions
+   * @param {Object} options - Additional options passed to SMCError
+   */
+  constructor(message, errors = [], fixes = [], options = {}) {
+    super(message, {
+      code: 'ERR_CONFIG',
+      severity: 'critical',
+      ...options
+    });
+    this.errors = errors;
+    this.fixes = fixes;
+    this.details = {
+      errorCount: errors.length,
+      fixCount: fixes.length,
+      criticalCount: errors.filter(e => e.severity === 'critical').length,
+      errorCount: errors.length,
+      fixCount: fixes.length,
+      criticalCount: errors.filter(e => e.severity === 'critical').length
+    };
+  }
+
+  /**
+   * Format config error for console output
+   */
+  toString() {
+    let output = `ConfigError: ${this.message}\n`;
+
+    if (this.details.errorCount > 0) {
+      output += `\nErrors (${this.details.errorCount}):\n`;
+      this.errors.forEach(e => {
+        const icon = e.severity === 'critical' ? 'X' : e.severity === 'error' ? 'E' : 'W';
+        output += `  [${icon}] ${e.path}: ${e.message}\n`;
+        if (e.fix) {
+          output += `      Fix: ${e.fix}\n`;
+        }
+      });
+    }
+
+    if (this.details.fixCount > 0) {
+      output += `\nSuggested fixes:\n`;
+      this.fixes.forEach((f, i) => {
+        output += `  ${i + 1}. ${f}\n`;
+      });
+    }
+
+    return output;
+  }
+}
+
+/**
+ * Validation errors
+ * Used when data validation fails
+ */
+class ValidationError extends SMCError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'ERR_VALIDATION',
+      severity: 'error',
+      ...options
+    });
+  }
+}
+
+/**
+ * Quality gate errors
+ * Used when quality checks fail
+ */
+class QualityGateError extends SMCError {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} results - Quality check results
+   * @param {Object} options - Additional options
+   */
+  constructor(message, results = {}, options = {}) {
+    super(message, {
+      code: 'ERR_QUALITY_GATE',
+      severity: 'error',
+      ...options
+    });
+    this.results = results;
+    this.details = {
+      passed: results.passed || false,
+      total: results.summary?.total || 0,
+      critical: results.summary?.critical || 0,
+      error: results.summary?.error || 0,
+      warn: results.summary?.warn || 0
+    };
+  }
+}
+
+/**
+ * Migration errors
+ * Used during config migration
+ */
+class MigrationError extends SMCError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'ERR_MIGRATION',
+      severity: 'critical',
+      ...options
+    });
+  }
+}
+
+/**
+ * File operation errors
+ * Used for file read/write issues
+ */
+class FileError extends SMCError {
+  constructor(message, filePath, options = {}) {
+    super(message, {
+      code: 'ERR_FILE',
+      severity: 'error',
+      ...options
+    });
+    this.filePath = filePath;
+    this.details.file = filePath;
+  }
+}
+
+/**
+ * Rule execution errors
+ * Used when a quality rule fails to execute
+ */
+class RuleError extends SMCError {
+  constructor(message, ruleId, options = {}) {
+    super(message, {
+      code: 'ERR_RULE',
+      severity: 'warn',
+      ...options
+    });
+    this.ruleId = ruleId;
+    this.details.rule = ruleId;
+  }
+}
+
+/**
+ * Parse error details from AJV validation output
+ * @param {Object[]} ajvErrors - AJV validation errors
+ * @returns {Object[]} Parsed error objects
+ */
+function parseAJVErrors(ajvErrors) {
+  return ajvErrors.map(error => {
+    const path = error.instancePath || 'root';
+    const message = error.message || 'Validation failed';
+
+    return {
+      path,
+      message,
+      severity: getSeverityFromKeyword(error.keyword),
+      expected: error.schema?.type || error.schema?.enum?.join('|'),
+      actual: error.data,
+      keyword: error.keyword,
+      fix: generateFixFromError(error)
+    };
+  });
+}
+
+/**
+ * Map AJV keyword to severity level
+ * @param {string} keyword - AJV error keyword
+ * @returns {string} Severity level
+ */
+function getSeverityFromKeyword(keyword) {
+  const severityMap = {
+    required: 'critical',
+    type: 'error',
+    enum: 'error',
+    pattern: 'warn',
+    format: 'warn',
+    minimum: 'warn',
+    maximum: 'warn',
+    minLength: 'warn',
+    maxLength: 'warn'
+  };
+  return severityMap[keyword] || 'warn';
+}
+
+/**
+ * Generate auto-fix suggestion from AJV error
+ * @param {Object} error - AJV error object
+ * @returns {string|null} Fix suggestion
+ */
+function generateFixFromError(error) {
+  const fixes = {
+    required: `Add missing field: ${error.params?.missingProperty}`,
+    pattern: `Value must match pattern: ${error.schema?.pattern}`,
+    enum: `Value must be one of: ${error.schema?.enum?.join(', ')}`,
+    type: `Change type to: ${error.schema?.type}`,
+    minimum: `Value must be >= ${error.schema?.minimum}`,
+    maximum: `Value must be <= ${error.schema?.maximum}`,
+    minLength: `Length must be >= ${error.schema?.minLength}`,
+    maxLength: `Length must be <= ${error.schema?.maxLength}`
+  };
+  return fixes[error.keyword] || null;
+}
+
+module.exports = {
+  // Base class
+  SMCError,
+
+  // Specific error types
+  ConfigError,
+  ValidationError,
+  QualityGateError,
+  MigrationError,
+  FileError,
+  RuleError,
+
+  // Utility functions
+  parseAJVErrors,
+  getSeverityFromKeyword,
+  generateFixFromError
+};