scene-capability-engine 3.0.0

package/lib/commands/value.js

@@ -0,0 +1,569 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const MetricContractLoader = require('../value/metric-contract-loader');
+const WeeklySnapshotBuilder = require('../value/weekly-snapshot-builder');
+const RiskEvaluator = require('../value/risk-evaluator');
+const GateSummaryEmitter = require('../value/gate-summary-emitter');
+const { parsePeriodKey } = require('../value/risk-evaluator');
+
+function toProjectPath(projectPath, maybePath) {
+  if (!maybePath) {
+    return null;
+  }
+
+  return path.isAbsolute(maybePath)
+    ? maybePath
+    : path.join(projectPath, maybePath);
+}
+
+function toPortablePath(projectPath, filePath) {
+  return path.relative(projectPath, filePath).replace(/\\/g, '/');
+}
+
+async function loadJson(filePath) {
+  try {
+    return await fs.readJson(filePath);
+  } catch (error) {
+    throw new Error(`Failed to read JSON file (${filePath}): ${error.message}`);
+  }
+}
+
+async function loadHistorySnapshots(historyDir) {
+  if (!await fs.pathExists(historyDir)) {
+    return [];
+  }
+
+  const entries = await fs.readdir(historyDir);
+  const snapshots = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) {
+      continue;
+    }
+
+    if (entry.startsWith('gate-summary.') || entry.includes('risk-evaluation')) {
+      continue;
+    }
+
+    const filePath = path.join(historyDir, entry);
+
+    let parsed;
+    try {
+      parsed = await fs.readJson(filePath);
+    } catch (error) {
+      continue;
+    }
+
+    if (parsed && typeof parsed.period === 'string') {
+      snapshots.push(parsed);
+    }
+  }
+
+  return snapshots;
+}
+
+function sortSnapshotsByPeriod(snapshots = []) {
+  return [...snapshots].sort((left, right) => parsePeriodKey(left.period) - parsePeriodKey(right.period));
+}
+
+function parsePositiveInteger(input, fallbackValue) {
+  const parsed = Number.parseInt(input, 10);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return parsed;
+  }
+
+  return fallbackValue;
+}
+
+function inferMetricDirection(metric = {}) {
+  if (typeof metric.better_direction === 'string' && metric.better_direction.trim()) {
+    return metric.better_direction.trim().toLowerCase();
+  }
+
+  const targetRule = metric.target_rule;
+  if (!targetRule || typeof targetRule.operator !== 'string') {
+    return 'higher';
+  }
+
+  if (targetRule.operator.includes('<')) {
+    return 'lower';
+  }
+
+  return 'higher';
+}
+
+function evaluateTarget(value, targetRule) {
+  const numericValue = Number(value);
+  if (!Number.isFinite(numericValue) || !targetRule) {
+    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;
+  }
+}
+
+function getImprovement(delta, direction) {
+  if (!Number.isFinite(delta) || delta === 0) {
+    return 'flat';
+  }
+
+  if (direction === 'lower') {
+    return delta < 0 ? 'improved' : 'degraded';
+  }
+
+  return delta > 0 ? 'improved' : 'degraded';
+}
+
+function resolveMetricInput(inputPayload) {
+  if (inputPayload && typeof inputPayload.metrics === 'object' && inputPayload.metrics !== null) {
+    return inputPayload.metrics;
+  }
+
+  return inputPayload;
+}
+
+function defaultHistoryDir(projectPath) {
+  return path.join(
+    projectPath,
+    '.kiro',
+    'specs',
+    '114-00-kpi-automation-and-observability',
+    'custom',
+    'weekly-metrics'
+  );
+}
+
+function getIsoWeekPeriod(date = new Date()) {
+  const utcDate = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  const day = utcDate.getUTCDay() || 7;
+  utcDate.setUTCDate(utcDate.getUTCDate() + 4 - day);
+
+  const yearStart = new Date(Date.UTC(utcDate.getUTCFullYear(), 0, 1));
+  const week = Math.ceil((((utcDate - yearStart) / 86400000) + 1) / 7);
+
+  return `${utcDate.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+
+function createSampleMetricsInput(period) {
+  return {
+    period,
+    metrics: {
+      ttfv_minutes: 25,
+      batch_success_rate: 0.86,
+      cycle_reduction_rate: 0.34,
+      manual_takeover_rate: 0.16
+    },
+    notes: 'sample metrics input generated by kse value metrics sample'
+  };
+}
+
+async function runValueMetricsSample(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const period = options.period || getIsoWeekPeriod();
+  const sampleInput = createSampleMetricsInput(period);
+
+  const outputPath = toProjectPath(projectPath, options.out) || path.join(projectPath, 'kpi-input.json');
+  await fs.ensureDir(path.dirname(outputPath));
+  await fs.writeJson(outputPath, sampleInput, { spaces: 2 });
+
+  const result = {
+    success: true,
+    period,
+    sample_path: toPortablePath(projectPath, outputPath),
+    generated_at: new Date().toISOString()
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✅ KPI sample input generated'));
+    console.log(chalk.gray(`  period: ${result.period}`));
+    console.log(chalk.gray(`  sample: ${result.sample_path}`));
+  }
+
+  return result;
+}
+
+async function runValueMetricsSnapshot(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+
+  if (!options.input) {
+    throw new Error('--input <path> is required for snapshot generation. Tip: run "kse value metrics sample --out ./kpi-input.json" first.');
+  }
+
+  const loader = dependencies.metricContractLoader || new MetricContractLoader(projectPath);
+  const builder = dependencies.weeklySnapshotBuilder || new WeeklySnapshotBuilder();
+  const evaluator = dependencies.riskEvaluator || new RiskEvaluator();
+  const gateEmitter = dependencies.gateSummaryEmitter || new GateSummaryEmitter();
+
+  const { contract, contractPath } = await loader.load({
+    path: options.definitions
+  });
+
+  const inputPath = toProjectPath(projectPath, options.input);
+  const inputPayload = await loadJson(inputPath);
+
+  const period = options.period || inputPayload.period;
+  const notes = options.notes || inputPayload.notes || '';
+
+  const snapshot = builder.build({
+    period,
+    metrics: resolveMetricInput(inputPayload),
+    notes,
+    contract
+  });
+
+  const historyDir = toProjectPath(projectPath, options.historyDir) || defaultHistoryDir(projectPath);
+  await fs.ensureDir(historyDir);
+
+  const historySnapshots = await loadHistorySnapshots(historyDir);
+  const riskResult = evaluator.evaluate({
+    historySnapshots,
+    currentSnapshot: snapshot
+  });
+
+  snapshot.risk_level = riskResult.risk_level;
+  snapshot.reasons = riskResult.reasons;
+
+  const snapshotPath = toProjectPath(projectPath, options.out)
+    || path.join(historyDir, `${snapshot.period}.json`);
+
+  await fs.ensureDir(path.dirname(snapshotPath));
+  await fs.writeJson(snapshotPath, snapshot, { spaces: 2 });
+
+  const checkpoint = options.checkpoint || 'day-30';
+  const gateSummary = gateEmitter.build({
+    checkpoint,
+    snapshot,
+    contract,
+    evidence: [toPortablePath(projectPath, snapshotPath)]
+  });
+
+  const gateSummaryPath = toProjectPath(projectPath, options.gateOut)
+    || path.join(path.dirname(snapshotPath), `gate-summary.${snapshot.period}.${checkpoint}.json`);
+  await fs.writeJson(gateSummaryPath, gateSummary, { spaces: 2 });
+
+  const result = {
+    success: true,
+    period: snapshot.period,
+    risk_level: snapshot.risk_level,
+    triggered_metrics: riskResult.triggered_metrics,
+    snapshot_path: toPortablePath(projectPath, snapshotPath),
+    gate_summary_path: toPortablePath(projectPath, gateSummaryPath),
+    contract_path: toPortablePath(projectPath, contractPath)
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✅ KPI snapshot generated'));
+    console.log(chalk.gray(`  period: ${result.period}`));
+    console.log(chalk.gray(`  risk: ${result.risk_level}`));
+    console.log(chalk.gray(`  snapshot: ${result.snapshot_path}`));
+    console.log(chalk.gray(`  gate summary: ${result.gate_summary_path}`));
+  }
+
+  return result;
+}
+
+async function runValueMetricsBaseline(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const loader = dependencies.metricContractLoader || new MetricContractLoader(projectPath);
+  const builder = dependencies.weeklySnapshotBuilder || new WeeklySnapshotBuilder();
+
+  const { contract, contractPath } = await loader.load({
+    path: options.definitions
+  });
+
+  const historyDir = toProjectPath(projectPath, options.historyDir) || defaultHistoryDir(projectPath);
+  await fs.ensureDir(historyDir);
+
+  let period;
+  let notes;
+  let metricInput;
+  let baselineSource;
+
+  if (options.input) {
+    const inputPath = toProjectPath(projectPath, options.input);
+    const inputPayload = await loadJson(inputPath);
+
+    period = options.period || inputPayload.period;
+    notes = options.notes || inputPayload.notes || '';
+    metricInput = resolveMetricInput(inputPayload);
+    baselineSource = `input:${toPortablePath(projectPath, inputPath)}`;
+  } else {
+    const allSnapshots = sortSnapshotsByPeriod(await loadHistorySnapshots(historyDir));
+    if (allSnapshots.length === 0) {
+      throw new Error('--input is required when history directory has no snapshots. Tip: run "kse value metrics sample --out ./kpi-input.json" and then "kse value metrics snapshot --input ./kpi-input.json".');
+    }
+
+    const fromHistory = parsePositiveInteger(options.fromHistory, Math.min(3, allSnapshots.length));
+    const selected = allSnapshots.slice(0, Math.min(fromHistory, allSnapshots.length));
+
+    metricInput = {};
+    for (const metric of contract.metrics) {
+      const values = selected
+        .map(snapshot => Number(snapshot[metric.id]))
+        .filter(value => Number.isFinite(value));
+
+      if (values.length === 0) {
+        throw new Error(`Unable to derive baseline metric from history: ${metric.id}`);
+      }
+
+      const average = values.reduce((sum, value) => sum + value, 0) / values.length;
+      metricInput[metric.id] = Number(average.toFixed(6));
+    }
+
+    const startPeriod = selected[0].period;
+    const endPeriod = selected[selected.length - 1].period;
+    period = options.period || endPeriod;
+    notes = options.notes || `Baseline derived from ${selected.length} snapshots (${startPeriod} -> ${endPeriod})`;
+    baselineSource = `history:${startPeriod}-${endPeriod}`;
+  }
+
+  const baselineSnapshot = builder.build({
+    period,
+    metrics: metricInput,
+    notes,
+    contract
+  });
+
+  baselineSnapshot.is_baseline = true;
+  baselineSnapshot.baseline_source = baselineSource;
+
+  const baselinePath = toProjectPath(projectPath, options.out)
+    || path.join(historyDir, `${baselineSnapshot.period}.baseline.json`);
+  await fs.ensureDir(path.dirname(baselinePath));
+  await fs.writeJson(baselinePath, baselineSnapshot, { spaces: 2 });
+
+  const result = {
+    success: true,
+    period: baselineSnapshot.period,
+    baseline_source: baselineSource,
+    baseline_path: toPortablePath(projectPath, baselinePath),
+    contract_path: toPortablePath(projectPath, contractPath)
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✅ KPI baseline generated'));
+    console.log(chalk.gray(`  period: ${result.period}`));
+    console.log(chalk.gray(`  source: ${result.baseline_source}`));
+    console.log(chalk.gray(`  baseline: ${result.baseline_path}`));
+  }
+
+  return result;
+}
+
+async function runValueMetricsTrend(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const loader = dependencies.metricContractLoader || new MetricContractLoader(projectPath);
+  const evaluator = dependencies.riskEvaluator || new RiskEvaluator();
+
+  const { contract, contractPath } = await loader.load({
+    path: options.definitions
+  });
+
+  const historyDir = toProjectPath(projectPath, options.historyDir) || defaultHistoryDir(projectPath);
+  const allSnapshots = sortSnapshotsByPeriod(await loadHistorySnapshots(historyDir));
+
+  if (allSnapshots.length < 2) {
+    throw new Error('At least 2 snapshots are required to calculate trends. Tip: generate snapshots first with "kse value metrics snapshot --input ./kpi-input.json".');
+  }
+
+  const window = parsePositiveInteger(options.window, allSnapshots.length);
+  const selected = allSnapshots.slice(-Math.min(window, allSnapshots.length));
+  const latest = selected[selected.length - 1];
+  const previous = selected[selected.length - 2];
+
+  const metricTrends = contract.metrics.map(metric => {
+    const latestValue = Number(latest[metric.id]);
+    const previousValue = Number(previous[metric.id]);
+
+    const delta = Number.isFinite(latestValue) && Number.isFinite(previousValue)
+      ? Number((latestValue - previousValue).toFixed(6))
+      : null;
+
+    const direction = inferMetricDirection(metric);
+    const trend = !Number.isFinite(delta) || delta === 0
+      ? 'flat'
+      : (delta > 0 ? 'up' : 'down');
+
+    const targetPassed = evaluateTarget(latestValue, metric.target_rule);
+
+    return {
+      metric_id: metric.id,
+      latest: latestValue,
+      previous: previousValue,
+      delta,
+      trend,
+      better_direction: direction,
+      status: getImprovement(delta, direction),
+      target: metric.target_rule ? metric.target_rule.raw : metric.target,
+      target_passed: targetPassed
+    };
+  });
+
+  const riskResult = evaluator.evaluate({
+    historySnapshots: selected.slice(0, -1),
+    currentSnapshot: latest
+  });
+
+  const result = {
+    success: true,
+    period: latest.period,
+    window_size: selected.length,
+    range: {
+      from: selected[0].period,
+      to: latest.period
+    },
+    risk_level: riskResult.risk_level,
+    triggered_metrics: riskResult.triggered_metrics,
+    reasons: riskResult.reasons,
+    metrics: metricTrends,
+    contract_path: toPortablePath(projectPath, contractPath)
+  };
+
+  const outputPath = toProjectPath(projectPath, options.out)
+    || path.join(historyDir, 'trend.latest.json');
+  await fs.ensureDir(path.dirname(outputPath));
+  await fs.writeJson(outputPath, result, { spaces: 2 });
+  result.trend_path = toPortablePath(projectPath, outputPath);
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✅ KPI trend calculated'));
+    console.log(chalk.gray(`  period: ${result.period}`));
+    console.log(chalk.gray(`  range: ${result.range.from} -> ${result.range.to}`));
+    console.log(chalk.gray(`  risk: ${result.risk_level}`));
+    console.log(chalk.gray(`  trend: ${result.trend_path}`));
+  }
+
+  return result;
+}
+
+function registerValueCommands(program) {
+  const value = program
+    .command('value')
+    .description('Spec value realization utilities');
+
+  const metrics = value
+    .command('metrics')
+    .description('KPI metrics and observability commands');
+
+  metrics
+    .command('sample')
+    .description('Generate sample KPI input JSON')
+    .option('--period <YYYY-WNN>', 'Week period, e.g. 2026-W10')
+    .option('--out <path>', 'Output path for sample input JSON', 'kpi-input.json')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async options => {
+      try {
+        await runValueMetricsSample(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Value metrics sample failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
+  metrics
+    .command('snapshot')
+    .description('Generate weekly KPI snapshot and gate summary')
+    .requiredOption('--input <path>', 'Input JSON with metric values')
+    .option('--period <YYYY-WNN>', 'Week period, e.g. 2026-W08')
+    .option('--definitions <path>', 'Metric definition YAML/JSON path')
+    .option('--history-dir <path>', 'History snapshots directory')
+    .option('--out <path>', 'Output path for snapshot JSON')
+    .option('--gate-out <path>', 'Output path for gate summary JSON')
+    .option('--checkpoint <name>', 'Gate checkpoint (day-30/day-60)', 'day-30')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async options => {
+      try {
+        await runValueMetricsSnapshot(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Value metrics snapshot failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
+  metrics
+    .command('baseline')
+    .description('Generate baseline snapshot from input or history')
+    .option('--input <path>', 'Input JSON with metric values')
+    .option('--from-history <n>', 'Derive baseline from earliest N history snapshots', parseInt)
+    .option('--period <YYYY-WNN>', 'Baseline period, e.g. 2026-W07')
+    .option('--definitions <path>', 'Metric definition YAML/JSON path')
+    .option('--history-dir <path>', 'History snapshots directory')
+    .option('--out <path>', 'Output path for baseline JSON')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async options => {
+      try {
+        await runValueMetricsBaseline(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Value metrics baseline failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
+  metrics
+    .command('trend')
+    .description('Analyze KPI trends from historical snapshots')
+    .option('--definitions <path>', 'Metric definition YAML/JSON path')
+    .option('--history-dir <path>', 'History snapshots directory')
+    .option('--window <n>', 'Use latest N snapshots for trend analysis', parseInt)
+    .option('--out <path>', 'Output path for trend JSON')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async options => {
+      try {
+        await runValueMetricsTrend(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Value metrics trend failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  registerValueCommands,
+  runValueMetricsSample,
+  runValueMetricsSnapshot,
+  runValueMetricsBaseline,
+  runValueMetricsTrend,
+  _loadHistorySnapshots: loadHistorySnapshots,
+  _resolveMetricInput: resolveMetricInput,
+  _sortSnapshotsByPeriod: sortSnapshotsByPeriod,
+  _getIsoWeekPeriod: getIsoWeekPeriod,
+  _createSampleMetricsInput: createSampleMetricsInput
+};