scene-capability-engine 3.0.0

package/lib/value/risk-evaluator.js

@@ -0,0 +1,117 @@
+const DEFAULT_METRIC_DIRECTIONS = {
+  ttfv_minutes: 'lower',
+  batch_success_rate: 'higher',
+  cycle_reduction_rate: 'higher',
+  manual_takeover_rate: 'lower'
+};
+
+function parsePeriodKey(period) {
+  const match = /^(\d{4})-W(\d{2})$/.exec(period || '');
+  if (!match) {
+    return Number.MAX_SAFE_INTEGER;
+  }
+
+  const year = Number(match[1]);
+  const week = Number(match[2]);
+  return (year * 100) + week;
+}
+
+function isWorse(current, previous, direction) {
+  if (!Number.isFinite(current) || !Number.isFinite(previous)) {
+    return false;
+  }
+
+  if (direction === 'lower') {
+    return current > previous;
+  }
+
+  return current < previous;
+}
+
+class RiskEvaluator {
+  constructor(options = {}) {
+    this.metricDirections = {
+      ...DEFAULT_METRIC_DIRECTIONS,
+      ...(options.metricDirections || {})
+    };
+  }
+
+  evaluate(options = {}) {
+    const {
+      historySnapshots = [],
+      currentSnapshot
+    } = options;
+
+    if (!currentSnapshot || typeof currentSnapshot !== 'object' || !currentSnapshot.period) {
+      throw new Error('currentSnapshot with valid period is required');
+    }
+
+    const dedupedByPeriod = new Map();
+    historySnapshots.forEach(snapshot => {
+      if (snapshot && snapshot.period) {
+        dedupedByPeriod.set(snapshot.period, snapshot);
+      }
+    });
+    dedupedByPeriod.set(currentSnapshot.period, currentSnapshot);
+
+    const snapshots = Array.from(dedupedByPeriod.values())
+      .sort((left, right) => parsePeriodKey(left.period) - parsePeriodKey(right.period));
+
+    const details = {};
+    const streaks = {};
+
+    Object.entries(this.metricDirections).forEach(([metricId, direction]) => {
+      details[metricId] = {
+        better_direction: direction,
+        max_consecutive_worse: 0,
+        triggered: false
+      };
+      streaks[metricId] = 0;
+    });
+
+    for (let index = 1; index < snapshots.length; index += 1) {
+      const previous = snapshots[index - 1];
+      const current = snapshots[index];
+
+      Object.entries(this.metricDirections).forEach(([metricId, direction]) => {
+        const currentValue = Number(current[metricId]);
+        const previousValue = Number(previous[metricId]);
+
+        if (isWorse(currentValue, previousValue, direction)) {
+          streaks[metricId] += 1;
+        } else {
+          streaks[metricId] = 0;
+        }
+
+        details[metricId].max_consecutive_worse = Math.max(
+          details[metricId].max_consecutive_worse,
+          streaks[metricId]
+        );
+
+        if (streaks[metricId] >= 2) {
+          details[metricId].triggered = true;
+        }
+      });
+    }
+
+    const triggeredMetrics = Object.entries(details)
+      .filter(([, value]) => value.triggered)
+      .map(([metricId]) => metricId);
+
+    const reasons = triggeredMetrics.map(metricId => (
+      `${metricId} worsened for 2 consecutive weeks`
+    ));
+
+    return {
+      evaluated_period: currentSnapshot.period,
+      risk_level: triggeredMetrics.length > 0 ? 'high' : 'medium',
+      triggered_metrics: triggeredMetrics,
+      reasons,
+      details
+    };
+  }
+}
+
+module.exports = RiskEvaluator;
+module.exports.parsePeriodKey = parsePeriodKey;
+

package/lib/value/weekly-snapshot-builder.js

@@ -0,0 +1,61 @@
+const PERIOD_REGEX = /^\d{4}-W(0[1-9]|[1-4]\d|5[0-3])$/;
+
+function isValidPeriod(period) {
+  return typeof period === 'string' && PERIOD_REGEX.test(period.trim());
+}
+
+class WeeklySnapshotBuilder {
+  constructor(options = {}) {
+    this.now = typeof options.now === 'function'
+      ? options.now
+      : (() => new Date().toISOString());
+  }
+
+  build(options = {}) {
+    const {
+      period,
+      metrics,
+      notes = '',
+      contract
+    } = options;
+
+    if (!isValidPeriod(period)) {
+      throw new Error(`Invalid period format: ${period}. Expected YYYY-WNN.`);
+    }
+
+    if (!contract || !Array.isArray(contract.metrics)) {
+      throw new Error('Metric contract is required to build snapshot');
+    }
+
+    if (!metrics || typeof metrics !== 'object') {
+      throw new Error('Snapshot metrics input must be an object');
+    }
+
+    const metricValues = {};
+    contract.metrics.forEach(metric => {
+      if (!Object.prototype.hasOwnProperty.call(metrics, metric.id)) {
+        throw new Error(`Missing metric value: ${metric.id}`);
+      }
+
+      const numericValue = Number(metrics[metric.id]);
+      if (!Number.isFinite(numericValue)) {
+        throw new Error(`Metric value must be numeric: ${metric.id}`);
+      }
+
+      metricValues[metric.id] = numericValue;
+    });
+
+    return {
+      period,
+      ...metricValues,
+      risk_level: 'medium',
+      reasons: [],
+      notes,
+      generated_at: this.now()
+    };
+  }
+}
+
+module.exports = WeeklySnapshotBuilder;
+module.exports.isValidPeriod = isValidPeriod;
+

package/lib/version/version-checker.js

@@ -0,0 +1,156 @@
+/**
+ * Version Checker
+ * 
+ * Automatically detects version mismatches between project and installed kse.
+ * Displays warnings and upgrade suggestions.
+ */
+
+const chalk = require('chalk');
+const VersionManager = require('./version-manager');
+
+class VersionChecker {
+  constructor() {
+    this.versionManager = new VersionManager();
+    this.suppressWarnings = false;
+  }
+
+  /**
+   * Checks for version mismatch and displays warning if needed
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {Object} options - Check options
+   * @param {boolean} options.noVersionCheck - Suppress warnings
+   * @returns {Promise<VersionCheckResult>}
+   */
+  async checkVersion(projectPath, options = {}) {
+    const { noVersionCheck = false } = options;
+    
+    if (noVersionCheck || this.suppressWarnings) {
+      return { mismatch: false, shouldUpgrade: false };
+    }
+    
+    try {
+      // Read project version
+      const projectVersionInfo = await this.versionManager.readVersion(projectPath);
+      
+      if (!projectVersionInfo) {
+        // No version.json - project might not be initialized
+        return { mismatch: false, shouldUpgrade: false };
+      }
+      
+      const projectVersion = projectVersionInfo['kse-version'];
+      
+      // Get current kse version
+      const packageJson = require('../../package.json');
+      const kseVersion = packageJson.version;
+      
+      // Check if upgrade is needed
+      const needsUpgrade = this.versionManager.needsUpgrade(projectVersion, kseVersion);
+      
+      if (needsUpgrade) {
+        this.displayWarning(projectVersion, kseVersion);
+      }
+      
+      return {
+        mismatch: needsUpgrade,
+        shouldUpgrade: needsUpgrade,
+        projectVersion,
+        kseVersion
+      };
+    } catch (error) {
+      // Silently fail - don't block commands if version check fails
+      return { mismatch: false, shouldUpgrade: false, error: error.message };
+    }
+  }
+
+  /**
+   * Displays version mismatch warning
+   * 
+   * @param {string} projectVersion - Project version
+   * @param {string} kseVersion - Current kse version
+   */
+  displayWarning(projectVersion, kseVersion) {
+    console.log();
+    console.log(chalk.yellow('⚠️  Version Mismatch Detected'));
+    console.log(chalk.gray('  Project initialized with kse'), chalk.cyan(`v${projectVersion}`));
+    console.log(chalk.gray('  Current kse version:'), chalk.cyan(`v${kseVersion}`));
+    console.log();
+    console.log(chalk.blue('💡 Tip:'), chalk.gray('Run'), chalk.cyan('kse upgrade'), chalk.gray('to update project templates'));
+    console.log(chalk.gray('  Or use'), chalk.cyan('--no-version-check'), chalk.gray('to suppress this warning'));
+    console.log();
+  }
+
+  /**
+   * Checks version and displays detailed information
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<void>}
+   */
+  async displayVersionInfo(projectPath) {
+    try {
+      const projectVersionInfo = await this.versionManager.readVersion(projectPath);
+      
+      if (!projectVersionInfo) {
+        console.log(chalk.yellow('⚠️  No version information found'));
+        console.log(chalk.gray('  This project may not be initialized with kse'));
+        console.log(chalk.gray('  Run'), chalk.cyan('kse adopt'), chalk.gray('to adopt this project'));
+        return;
+      }
+      
+      const packageJson = require('../../package.json');
+      const kseVersion = packageJson.version;
+      
+      console.log(chalk.blue('📦 Version Information'));
+      console.log();
+      console.log(chalk.gray('Project:'));
+      console.log(`  kse version: ${chalk.cyan(projectVersionInfo['kse-version'])}`);
+      console.log(`  Template version: ${chalk.cyan(projectVersionInfo['template-version'])}`);
+      console.log(`  Created: ${chalk.gray(new Date(projectVersionInfo.created).toLocaleString())}`);
+      console.log(`  Last upgraded: ${chalk.gray(new Date(projectVersionInfo['last-upgraded']).toLocaleString())}`);
+      
+      console.log();
+      console.log(chalk.gray('Installed:'));
+      console.log(`  kse version: ${chalk.cyan(kseVersion)}`);
+      
+      if (projectVersionInfo['upgrade-history'].length > 0) {
+        console.log();
+        console.log(chalk.gray('Upgrade History:'));
+        projectVersionInfo['upgrade-history'].forEach((entry, index) => {
+          const icon = entry.success ? chalk.green('✅') : chalk.red('❌');
+          const date = new Date(entry.date).toLocaleString();
+          console.log(`  ${icon} ${entry.from} → ${entry.to} (${date})`);
+          if (entry.error) {
+            console.log(`     ${chalk.red('Error:')} ${entry.error}`);
+          }
+        });
+      }
+      
+      console.log();
+      
+      const needsUpgrade = this.versionManager.needsUpgrade(
+        projectVersionInfo['kse-version'],
+        kseVersion
+      );
+      
+      if (needsUpgrade) {
+        console.log(chalk.yellow('⚠️  Upgrade available'));
+        console.log(chalk.gray('  Run'), chalk.cyan('kse upgrade'), chalk.gray('to update to'), chalk.cyan(`v${kseVersion}`));
+      } else {
+        console.log(chalk.green('✅ Project is up to date'));
+      }
+    } catch (error) {
+      console.log(chalk.red('❌ Error:'), error.message);
+    }
+  }
+
+  /**
+   * Suppresses version check warnings
+   * 
+   * @param {boolean} suppress - Whether to suppress warnings
+   */
+  setSuppressWarnings(suppress) {
+    this.suppressWarnings = suppress;
+  }
+}
+
+module.exports = VersionChecker;

package/lib/version/version-manager.js

@@ -0,0 +1,327 @@
+/**
+ * Version Manager
+ * 
+ * Manages version tracking, compatibility checking, and upgrade path calculation
+ * for the kiro-spec-engine project adoption and upgrade system.
+ */
+
+const path = require('path');
+const semver = require('semver');
+const { readJSON, writeJSON, pathExists } = require('../utils/fs-utils');
+
+/**
+ * Compatibility matrix defining which versions can work together
+ * Format: { version: { compatible: [versions], breaking: boolean } }
+ */
+const COMPATIBILITY_MATRIX = {
+  '1.0.0': { compatible: ['1.0.0', '1.1.0', '1.2.0'], breaking: false },
+  '1.1.0': { compatible: ['1.0.0', '1.1.0', '1.2.0'], breaking: false },
+  '1.2.0': { compatible: ['1.0.0', '1.1.0', '1.2.0'], breaking: false },
+  '2.0.0': { compatible: ['2.0.0'], breaking: true, migration: 'required' }
+};
+
+class VersionManager {
+  constructor() {
+    this.versionFileName = 'version.json';
+  }
+
+  /**
+   * Gets the path to version.json in a project
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {string} - Absolute path to version.json
+   */
+  getVersionFilePath(projectPath) {
+    return path.join(projectPath, '.kiro', this.versionFileName);
+  }
+
+  /**
+   * Reads version information from project
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<VersionInfo|null>} - Version info or null if not found
+   */
+  async readVersion(projectPath) {
+    const versionPath = this.getVersionFilePath(projectPath);
+    
+    try {
+      const exists = await pathExists(versionPath);
+      if (!exists) {
+        return null;
+      }
+      
+      const versionInfo = await readJSON(versionPath);
+      
+      // Validate structure
+      if (!this.isValidVersionInfo(versionInfo)) {
+        throw new Error('Invalid version.json structure');
+      }
+      
+      return versionInfo;
+    } catch (error) {
+      throw new Error(`Failed to read version file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Writes version information to project
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {VersionInfo} versionInfo - Version information to write
+   * @returns {Promise<void>}
+   */
+  async writeVersion(projectPath, versionInfo) {
+    const versionPath = this.getVersionFilePath(projectPath);
+    
+    try {
+      // Validate structure before writing
+      if (!this.isValidVersionInfo(versionInfo)) {
+        throw new Error('Invalid version info structure');
+      }
+      
+      await writeJSON(versionPath, versionInfo, { spaces: 2 });
+    } catch (error) {
+      throw new Error(`Failed to write version file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Creates initial version info for a new project
+   * 
+   * @param {string} kseVersion - Current kse version
+   * @param {string} templateVersion - Template version (default: same as kse)
+   * @returns {VersionInfo}
+   */
+  createVersionInfo(kseVersion, templateVersion = null) {
+    const now = new Date().toISOString();
+    
+    return {
+      'kse-version': kseVersion,
+      'template-version': templateVersion || kseVersion,
+      'created': now,
+      'last-upgraded': now,
+      'upgrade-history': []
+    };
+  }
+
+  /**
+   * Validates version info structure
+   * 
+   * @param {Object} versionInfo - Version info to validate
+   * @returns {boolean}
+   */
+  isValidVersionInfo(versionInfo) {
+    if (!versionInfo || typeof versionInfo !== 'object') {
+      return false;
+    }
+    
+    const requiredFields = [
+      'kse-version',
+      'template-version',
+      'created',
+      'last-upgraded',
+      'upgrade-history'
+    ];
+    
+    for (const field of requiredFields) {
+      if (!(field in versionInfo)) {
+        return false;
+      }
+    }
+    
+    // Validate upgrade-history is an array
+    if (!Array.isArray(versionInfo['upgrade-history'])) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Checks if upgrade is needed
+   * 
+   * @param {string} projectVersion - Current project version
+   * @param {string} kseVersion - Installed kse version
+   * @returns {boolean}
+   */
+  needsUpgrade(projectVersion, kseVersion) {
+    if (!projectVersion || !kseVersion) {
+      return false;
+    }
+    
+    try {
+      // Use semver for comparison
+      return semver.lt(projectVersion, kseVersion);
+    } catch (error) {
+      // If semver comparison fails, do string comparison
+      return projectVersion !== kseVersion;
+    }
+  }
+
+  /**
+   * Checks compatibility between versions
+   * 
+   * @param {string} fromVersion - Source version
+   * @param {string} toVersion - Target version
+   * @returns {CompatibilityResult}
+   */
+  checkCompatibility(fromVersion, toVersion) {
+    // If versions are the same, always compatible
+    if (fromVersion === toVersion) {
+      return {
+        compatible: true,
+        breaking: false,
+        migration: 'none'
+      };
+    }
+    
+    // Check compatibility matrix first
+    const fromInfo = COMPATIBILITY_MATRIX[fromVersion];
+    
+    if (fromInfo) {
+      const isCompatible = fromInfo.compatible.includes(toVersion);
+      return {
+        compatible: isCompatible,
+        breaking: !isCompatible || fromInfo.breaking,
+        migration: !isCompatible ? 'required' : 'none'
+      };
+    }
+    
+    // Fallback: semver-based compatibility for versions not in matrix
+    try {
+      const fromMajor = semver.major(fromVersion);
+      const toMajor = semver.major(toVersion);
+      
+      if (fromMajor === toMajor) {
+        // Same major version — compatible, non-breaking
+        return {
+          compatible: true,
+          breaking: false,
+          migration: 'none'
+        };
+      }
+      
+      // Different major version — breaking change
+      return {
+        compatible: false,
+        breaking: true,
+        migration: 'required'
+      };
+    } catch (error) {
+      // Invalid semver — assume incompatible
+      return {
+        compatible: false,
+        breaking: true,
+        migration: 'unknown',
+        message: `Unknown source version: ${fromVersion}`
+      };
+    }
+  }
+
+  /**
+   * Calculates upgrade path for version gap
+   * Returns array of intermediate versions to upgrade through
+   * 
+   * @param {string} fromVersion - Current version
+   * @param {string} toVersion - Target version
+   * @returns {string[]} - Array of versions in upgrade order (including from and to)
+   */
+  calculateUpgradePath(fromVersion, toVersion) {
+    // If same version, no upgrade needed
+    if (fromVersion === toVersion) {
+      return [fromVersion];
+    }
+    
+    // Get all versions from compatibility matrix
+    const allVersions = Object.keys(COMPATIBILITY_MATRIX).sort((a, b) => {
+      try {
+        return semver.compare(a, b);
+      } catch (error) {
+        return a.localeCompare(b);
+      }
+    });
+    
+    // Find indices
+    const fromIndex = allVersions.indexOf(fromVersion);
+    const toIndex = allVersions.indexOf(toVersion);
+    
+    // If both versions are in the matrix, use the matrix path
+    if (fromIndex !== -1 && toIndex !== -1) {
+      if (fromIndex > toIndex) {
+        throw new Error('Cannot downgrade versions');
+      }
+      return allVersions.slice(fromIndex, toIndex + 1);
+    }
+    
+    // Fallback: semver-based direct upgrade for versions not in matrix
+    try {
+      const from = semver.valid(fromVersion);
+      const to = semver.valid(toVersion);
+      
+      if (!from) {
+        throw new Error(`Unknown source version: ${fromVersion}`);
+      }
+      if (!to) {
+        throw new Error(`Unknown target version: ${toVersion}`);
+      }
+      
+      if (semver.gt(fromVersion, toVersion)) {
+        throw new Error('Cannot downgrade versions');
+      }
+      
+      // Direct upgrade path
+      return [fromVersion, toVersion];
+    } catch (error) {
+      // Re-throw our own errors
+      if (error.message.includes('Unknown') || error.message.includes('downgrade')) {
+        throw error;
+      }
+      throw new Error(`Unknown source version: ${fromVersion}`);
+    }
+  }
+
+  /**
+   * Adds an upgrade entry to version history
+   * 
+   * @param {VersionInfo} versionInfo - Current version info
+   * @param {string} fromVersion - Version upgraded from
+   * @param {string} toVersion - Version upgraded to
+   * @param {boolean} success - Whether upgrade succeeded
+   * @param {string} error - Error message if failed
+   * @returns {VersionInfo} - Updated version info
+   */
+  addUpgradeHistory(versionInfo, fromVersion, toVersion, success, error = null) {
+    const entry = {
+      from: fromVersion,
+      to: toVersion,
+      date: new Date().toISOString(),
+      success
+    };
+    
+    if (error) {
+      entry.error = error;
+    }
+    
+    versionInfo['upgrade-history'].push(entry);
+    
+    // Update version and last-upgraded if successful
+    if (success) {
+      versionInfo['kse-version'] = toVersion;
+      versionInfo['template-version'] = toVersion;
+      versionInfo['last-upgraded'] = entry.date;
+    }
+    
+    return versionInfo;
+  }
+
+  /**
+   * Gets the compatibility matrix
+   * 
+   * @returns {Object} - Compatibility matrix
+   */
+  getCompatibilityMatrix() {
+    return { ...COMPATIBILITY_MATRIX };
+  }
+}
+
+module.exports = VersionManager;