scene-capability-engine 3.0.0

package/lib/utils/validation.js

@@ -0,0 +1,324 @@
+/**
+ * Validation Utilities
+ * 
+ * Provides validation functions for project structure, version files,
+ * and dependencies. Used for post-operation validation.
+ */
+
+const path = require('path');
+const { pathExists, readJSON } = require('./fs-utils');
+const { spawn } = require('child_process');
+
+/**
+ * Validates project structure
+ * Checks if all required files and directories exist
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateProjectStructure(projectPath) {
+  const errors = [];
+  const warnings = [];
+  
+  try {
+    const kiroPath = path.join(projectPath, '.kiro');
+    
+    // Check if .kiro/ directory exists
+    const kiroExists = await pathExists(kiroPath);
+    if (!kiroExists) {
+      errors.push('.kiro/ directory not found');
+      return { success: false, errors, warnings };
+    }
+    
+    // Check required directories
+    const requiredDirs = [
+      { path: 'specs', required: false },
+      { path: 'steering', required: true },
+      { path: 'tools', required: true },
+      { path: 'backups', required: false }
+    ];
+    
+    for (const dir of requiredDirs) {
+      const dirPath = path.join(kiroPath, dir.path);
+      const exists = await pathExists(dirPath);
+      
+      if (!exists) {
+        if (dir.required) {
+          errors.push(`Required directory not found: ${dir.path}/`);
+        } else {
+          warnings.push(`Optional directory not found: ${dir.path}/`);
+        }
+      }
+    }
+    
+    // Check required steering files
+    const requiredSteeringFiles = [
+      { path: 'steering/CORE_PRINCIPLES.md', required: true },
+      { path: 'steering/ENVIRONMENT.md', required: true },
+      { path: 'steering/CURRENT_CONTEXT.md', required: true },
+      { path: 'steering/RULES_GUIDE.md', required: true }
+    ];
+    
+    for (const file of requiredSteeringFiles) {
+      const filePath = path.join(kiroPath, file.path);
+      const exists = await pathExists(filePath);
+      
+      if (!exists) {
+        if (file.required) {
+          errors.push(`Required file not found: ${file.path}`);
+        } else {
+          warnings.push(`Optional file not found: ${file.path}`);
+        }
+      }
+    }
+    
+    // Check required tool files
+    const requiredToolFiles = [
+      { path: 'tools/ultrawork_enhancer.py', required: true }
+    ];
+    
+    for (const file of requiredToolFiles) {
+      const filePath = path.join(kiroPath, file.path);
+      const exists = await pathExists(filePath);
+      
+      if (!exists) {
+        if (file.required) {
+          warnings.push(`Tool file not found: ${file.path}`);
+        }
+      }
+    }
+    
+    return {
+      success: errors.length === 0,
+      errors,
+      warnings
+    };
+  } catch (error) {
+    errors.push(`Validation failed: ${error.message}`);
+    return { success: false, errors, warnings };
+  }
+}
+
+/**
+ * Validates version.json file structure
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateVersionFile(projectPath) {
+  const errors = [];
+  const warnings = [];
+  
+  try {
+    const versionPath = path.join(projectPath, '.kiro', 'version.json');
+    
+    // Check if version.json exists
+    const exists = await pathExists(versionPath);
+    if (!exists) {
+      errors.push('version.json not found');
+      return { success: false, errors, warnings };
+    }
+    
+    // Read and validate structure
+    const versionInfo = await readJSON(versionPath);
+    
+    // Check required fields
+    const requiredFields = [
+      'kse-version',
+      'template-version',
+      'created',
+      'last-upgraded',
+      'upgrade-history'
+    ];
+    
+    for (const field of requiredFields) {
+      if (!(field in versionInfo)) {
+        errors.push(`Missing required field in version.json: ${field}`);
+      }
+    }
+    
+    // Validate field types
+    if (versionInfo['kse-version'] && typeof versionInfo['kse-version'] !== 'string') {
+      errors.push('kse-version must be a string');
+    }
+    
+    if (versionInfo['template-version'] && typeof versionInfo['template-version'] !== 'string') {
+      errors.push('template-version must be a string');
+    }
+    
+    if (versionInfo['upgrade-history'] && !Array.isArray(versionInfo['upgrade-history'])) {
+      errors.push('upgrade-history must be an array');
+    }
+    
+    // Validate upgrade history entries
+    if (Array.isArray(versionInfo['upgrade-history'])) {
+      versionInfo['upgrade-history'].forEach((entry, index) => {
+        if (!entry.from || !entry.to || !entry.date || typeof entry.success !== 'boolean') {
+          warnings.push(`Invalid upgrade history entry at index ${index}`);
+        }
+      });
+    }
+    
+    return {
+      success: errors.length === 0,
+      errors,
+      warnings
+    };
+  } catch (error) {
+    errors.push(`Failed to validate version.json: ${error.message}`);
+    return { success: false, errors, warnings };
+  }
+}
+
+/**
+ * Validates dependencies (Node.js and Python versions)
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateDependencies(projectPath) {
+  const errors = [];
+  const warnings = [];
+  
+  try {
+    // Check Node.js version
+    const nodeVersion = process.version;
+    const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0]);
+    
+    if (nodeMajor < 16) {
+      errors.push(`Node.js version ${nodeVersion} is not supported. Requires Node.js 16+`);
+    }
+    
+    // Check Python version (if Ultrawork tools are present)
+    const toolPath = path.join(projectPath, '.kiro/tools/ultrawork_enhancer.py');
+    const toolExists = await pathExists(toolPath);
+    
+    if (toolExists) {
+      try {
+        const pythonVersion = await checkPythonVersion();
+        
+        if (!pythonVersion) {
+          warnings.push('Python not found. Ultrawork tools require Python 3.8+');
+        } else {
+          const [major, minor] = pythonVersion.split('.').map(Number);
+          
+          if (major < 3 || (major === 3 && minor < 8)) {
+            warnings.push(`Python ${pythonVersion} found. Ultrawork tools require Python 3.8+`);
+          }
+        }
+      } catch (error) {
+        warnings.push('Could not check Python version');
+      }
+    }
+    
+    return {
+      success: errors.length === 0,
+      errors,
+      warnings
+    };
+  } catch (error) {
+    errors.push(`Failed to validate dependencies: ${error.message}`);
+    return { success: false, errors, warnings };
+  }
+}
+
+/**
+ * Checks Python version
+ * 
+ * @returns {Promise<string|null>} - Python version string or null if not found
+ */
+function checkPythonVersion() {
+  return new Promise((resolve) => {
+    const python = spawn('python', ['--version']);
+    let output = '';
+    let settled = false;
+    let timeoutId = null;
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      resolve(value);
+    };
+
+    python.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+    
+    python.stderr.on('data', (data) => {
+      output += data.toString();
+    });
+    
+    python.on('close', (code) => {
+      if (code === 0 && output) {
+        // Extract version number from "Python 3.x.x"
+        const match = output.match(/Python (\d+\.\d+\.\d+)/);
+        if (match) {
+          finish(match[1]);
+        } else {
+          finish(null);
+        }
+      } else {
+        finish(null);
+      }
+    });
+    
+    python.on('error', () => {
+      finish(null);
+    });
+    
+    // Timeout after 5 seconds
+    timeoutId = setTimeout(() => {
+      try {
+        python.kill();
+      } catch (_err) {
+        // Process may already be gone.
+      }
+      finish(null);
+    }, 5000);
+    if (typeof timeoutId.unref === 'function') {
+      timeoutId.unref();
+    }
+  });
+}
+
+/**
+ * Validates complete project (structure + version + dependencies)
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateProject(projectPath) {
+  const allErrors = [];
+  const allWarnings = [];
+  
+  // Run all validations
+  const structureResult = await validateProjectStructure(projectPath);
+  const versionResult = await validateVersionFile(projectPath);
+  const depsResult = await validateDependencies(projectPath);
+  
+  // Combine results
+  allErrors.push(...structureResult.errors);
+  allErrors.push(...versionResult.errors);
+  allErrors.push(...depsResult.errors);
+  
+  allWarnings.push(...structureResult.warnings);
+  allWarnings.push(...versionResult.warnings);
+  allWarnings.push(...depsResult.warnings);
+  
+  return {
+    success: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings
+  };
+}
+
+module.exports = {
+  validateProjectStructure,
+  validateVersionFile,
+  validateDependencies,
+  validateProject,
+  checkPythonVersion
+};

package/lib/value/gate-summary-emitter.js

@@ -0,0 +1,99 @@
+const { parseTargetExpression } = require('./metric-contract-loader');
+
+function evaluateTarget(value, targetRule) {
+  const numericValue = Number(value);
+  if (!Number.isFinite(numericValue)) {
+    return false;
+  }
+
+  switch (targetRule.operator) {
+    case '<=':
+      return numericValue <= targetRule.value;
+    case '>=':
+      return numericValue >= targetRule.value;
+    case '<':
+      return numericValue < targetRule.value;
+    case '>':
+      return numericValue > targetRule.value;
+    case '=':
+      return numericValue === targetRule.value;
+    default:
+      return false;
+  }
+}
+
+class GateSummaryEmitter {
+  constructor(options = {}) {
+    this.defaultThresholdRatio = options.defaultThresholdRatio || 0.75;
+  }
+
+  build(options = {}) {
+    const {
+      checkpoint = 'day-30',
+      snapshot,
+      contract,
+      evidence = []
+    } = options;
+
+    if (!snapshot || typeof snapshot !== 'object') {
+      throw new Error('snapshot is required');
+    }
+
+    if (!contract || !Array.isArray(contract.metrics)) {
+      throw new Error('metric contract is required');
+    }
+
+    const checks = contract.metrics.map(metric => {
+      const targetRule = metric.target_rule || parseTargetExpression(metric.target);
+      const value = Number(snapshot[metric.id]);
+
+      return {
+        metric_id: metric.id,
+        value,
+        target: targetRule.raw,
+        operator: targetRule.operator,
+        target_value: targetRule.value,
+        passed: evaluateTarget(value, targetRule)
+      };
+    });
+
+    const passedMetrics = checks.filter(item => item.passed).length;
+    const totalMetrics = checks.length;
+    const requiredPassedMetrics = this.resolveRequiredPassCount(checkpoint, totalMetrics, contract);
+    const decision = passedMetrics >= requiredPassedMetrics ? 'go' : 'no-go';
+
+    return {
+      checkpoint,
+      passed_metrics: passedMetrics,
+      total_metrics: totalMetrics,
+      required_passed_metrics: requiredPassedMetrics,
+      decision,
+      checks,
+      evidence
+    };
+  }
+
+  resolveRequiredPassCount(checkpoint, totalMetrics, contract) {
+    const goNoGo = contract
+      && contract.threshold_policy
+      && contract.threshold_policy.go_no_go
+      ? contract.threshold_policy.go_no_go
+      : {};
+
+    let configuredThreshold;
+    if (checkpoint === 'day-60') {
+      configuredThreshold = Number(goNoGo.day_60_min_passed_metrics);
+    } else if (checkpoint === 'day-30') {
+      configuredThreshold = Number(goNoGo.day_30_min_passed_metrics);
+    }
+
+    if (Number.isFinite(configuredThreshold) && configuredThreshold > 0) {
+      return Math.min(totalMetrics, Math.floor(configuredThreshold));
+    }
+
+    return Math.max(1, Math.ceil(totalMetrics * this.defaultThresholdRatio));
+  }
+}
+
+module.exports = GateSummaryEmitter;
+

package/lib/value/metric-contract-loader.js

@@ -0,0 +1,210 @@
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const REQUIRED_METRIC_IDS = [
+  'ttfv_minutes',
+  'batch_success_rate',
+  'cycle_reduction_rate',
+  'manual_takeover_rate'
+];
+
+const METRIC_DIRECTION_HINTS = {
+  ttfv_minutes: 'lower',
+  batch_success_rate: 'higher',
+  cycle_reduction_rate: 'higher',
+  manual_takeover_rate: 'lower'
+};
+
+function parseTargetExpression(target) {
+  if (typeof target === 'number' && Number.isFinite(target)) {
+    return {
+      operator: '=',
+      value: target,
+      raw: String(target)
+    };
+  }
+
+  if (typeof target !== 'string') {
+    throw new Error(`Invalid target expression type: ${typeof target}`);
+  }
+
+  const match = /^(<=|>=|<|>|=)\s*(-?\d+(?:\.\d+)?)$/.exec(target.trim());
+  if (!match) {
+    throw new Error(`Invalid target expression: ${target}`);
+  }
+
+  return {
+    operator: match[1],
+    value: Number(match[2]),
+    raw: target
+  };
+}
+
+class MetricContractLoader {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+  }
+
+  getDefaultPath() {
+    return path.join(
+      this.projectPath,
+      '.kiro',
+      'specs',
+      '112-00-spec-value-realization-program',
+      'custom',
+      'metric-definition.yaml'
+    );
+  }
+
+  resolvePath(contractPath) {
+    if (!contractPath) {
+      return this.getDefaultPath();
+    }
+
+    return path.isAbsolute(contractPath)
+      ? contractPath
+      : path.join(this.projectPath, contractPath);
+  }
+
+  async load(options = {}) {
+    const contractPath = this.resolvePath(options.path);
+
+    if (!await fs.pathExists(contractPath)) {
+      throw new Error(`Metric contract not found: ${contractPath}`);
+    }
+
+    const raw = await fs.readFile(contractPath, 'utf8');
+    const extension = path.extname(contractPath).toLowerCase();
+
+    let parsed;
+    try {
+      parsed = extension === '.json' ? JSON.parse(raw) : yaml.load(raw);
+    } catch (error) {
+      throw new Error(`Failed to parse metric contract: ${error.message}`);
+    }
+
+    const normalized = this.normalize(parsed);
+    const validation = this.validate(normalized);
+
+    if (!validation.valid) {
+      throw new Error(`Invalid metric contract: ${validation.errors.join('; ')}`);
+    }
+
+    return {
+      contract: normalized,
+      contractPath
+    };
+  }
+
+  normalize(contract = {}) {
+    const metrics = Array.isArray(contract.metrics) ? contract.metrics : [];
+
+    const normalizedMetrics = metrics.map(metric => {
+      const id = typeof metric.id === 'string' ? metric.id.trim() : '';
+      const targetRule = parseTargetExpression(metric.target);
+
+      return {
+        ...metric,
+        id,
+        unit: typeof metric.unit === 'string' ? metric.unit.trim().toLowerCase() : metric.unit,
+        better_direction: this.inferBetterDirection(id, metric, targetRule),
+        target_rule: targetRule
+      };
+    });
+
+    const metricMap = {};
+    normalizedMetrics.forEach(metric => {
+      metricMap[metric.id] = metric;
+    });
+
+    return {
+      ...contract,
+      metrics: normalizedMetrics,
+      metric_map: metricMap
+    };
+  }
+
+  inferBetterDirection(metricId, metric, targetRule) {
+    if (metric && typeof metric.better_direction === 'string') {
+      return metric.better_direction.trim().toLowerCase();
+    }
+
+    if (METRIC_DIRECTION_HINTS[metricId]) {
+      return METRIC_DIRECTION_HINTS[metricId];
+    }
+
+    if (targetRule.operator === '<=' || targetRule.operator === '<') {
+      return 'lower';
+    }
+
+    return 'higher';
+  }
+
+  validate(contract = {}) {
+    const errors = [];
+
+    if (!contract || typeof contract !== 'object') {
+      return {
+        valid: false,
+        errors: ['Contract must be an object']
+      };
+    }
+
+    if (!Array.isArray(contract.metrics) || contract.metrics.length === 0) {
+      errors.push('metrics must be a non-empty array');
+      return { valid: false, errors };
+    }
+
+    const presentMetricIds = new Set();
+
+    contract.metrics.forEach((metric, index) => {
+      if (!metric.id || typeof metric.id !== 'string') {
+        errors.push(`metrics[${index}].id is required`);
+      } else {
+        presentMetricIds.add(metric.id);
+      }
+
+      if (!metric.name || typeof metric.name !== 'string') {
+        errors.push(`metrics[${index}].name is required`);
+      }
+
+      if (!metric.unit || typeof metric.unit !== 'string') {
+        errors.push(`metrics[${index}].unit is required`);
+      }
+
+      if (!metric.target_rule) {
+        errors.push(`metrics[${index}].target is required`);
+        return;
+      }
+
+      if (!Number.isFinite(metric.target_rule.value)) {
+        errors.push(`metrics[${index}].target value must be numeric`);
+      }
+
+      if (metric.unit === 'ratio' && (metric.target_rule.value < 0 || metric.target_rule.value > 1)) {
+        errors.push(`metrics[${index}].target ratio must be between 0 and 1`);
+      }
+
+      if (metric.id === 'ttfv_minutes' && metric.target_rule.value < 0) {
+        errors.push('ttfv_minutes target must be >= 0');
+      }
+    });
+
+    REQUIRED_METRIC_IDS.forEach(metricId => {
+      if (!presentMetricIds.has(metricId)) {
+        errors.push(`required metric is missing: ${metricId}`);
+      }
+    });
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+}
+
+module.exports = MetricContractLoader;
+module.exports.REQUIRED_METRIC_IDS = REQUIRED_METRIC_IDS;
+module.exports.parseTargetExpression = parseTargetExpression;
+