scene-capability-engine 3.0.0

package/lib/spec/pipeline/stage-runner.js

@@ -0,0 +1,146 @@
+const { STAGE_ORDER } = require('./constants');
+
+class StageRunner {
+  constructor(options = {}) {
+    this.stateStore = options.stateStore;
+    this.adapters = options.adapters || {};
+  }
+
+  async run(context) {
+    const selectedStages = this._selectStages({
+      fromStage: context.fromStage,
+      toStage: context.toStage
+    });
+
+    const stageResults = [];
+
+    for (const stageName of selectedStages) {
+      if (context.resume && this._isCompleted(context.state, stageName)) {
+        stageResults.push({
+          name: stageName,
+          status: 'skipped',
+          reason: 'already-completed'
+        });
+        continue;
+      }
+
+      const adapter = this.adapters[stageName];
+      if (typeof adapter !== 'function') {
+        const error = `No adapter registered for stage: ${stageName}`;
+        await this.stateStore.markStageResult(context.state, stageName, {
+          status: 'failed',
+          error
+        });
+        stageResults.push({ name: stageName, status: 'failed', error });
+        return {
+          status: 'failed',
+          stageResults,
+          failure: { stage: stageName, error }
+        };
+      }
+
+      await this.stateStore.markStageStart(context.state, stageName);
+
+      let adapterResult;
+      try {
+        adapterResult = context.dryRun
+          ? { success: true, details: { dry_run: true }, warnings: [] }
+          : await adapter(context);
+      } catch (error) {
+        adapterResult = {
+          success: false,
+          error: error.message,
+          warnings: []
+        };
+      }
+
+      const normalized = this._normalizeResult(adapterResult);
+      const status = normalized.success ? (normalized.warnings.length > 0 ? 'warning' : 'completed') : 'failed';
+
+      await this.stateStore.markStageResult(context.state, stageName, {
+        status,
+        warnings: normalized.warnings,
+        error: normalized.error,
+        output: normalized.details
+      });
+
+      stageResults.push({
+        name: stageName,
+        status,
+        warnings: normalized.warnings,
+        error: normalized.error,
+        output: normalized.details
+      });
+
+      if (status === 'failed' && context.failFast) {
+        return {
+          status: 'failed',
+          stageResults,
+          failure: {
+            stage: stageName,
+            error: normalized.error || 'stage failed'
+          }
+        };
+      }
+
+      if (status === 'warning' && !context.continueOnWarning) {
+        return {
+          status: 'failed',
+          stageResults,
+          failure: {
+            stage: stageName,
+            error: 'warning encountered with continue-on-warning disabled'
+          }
+        };
+      }
+    }
+
+    return {
+      status: 'completed',
+      stageResults,
+      failure: null
+    };
+  }
+
+  _selectStages(range = {}) {
+    const fromStage = range.fromStage || STAGE_ORDER[0];
+    const toStage = range.toStage || STAGE_ORDER[STAGE_ORDER.length - 1];
+
+    const fromIndex = STAGE_ORDER.indexOf(fromStage);
+    const toIndex = STAGE_ORDER.indexOf(toStage);
+
+    if (fromIndex < 0 || toIndex < 0 || fromIndex > toIndex) {
+      throw new Error(`Invalid stage range: from=${fromStage}, to=${toStage}`);
+    }
+
+    return STAGE_ORDER.slice(fromIndex, toIndex + 1);
+  }
+
+  _normalizeResult(result) {
+    if (!result || typeof result !== 'object') {
+      return {
+        success: false,
+        warnings: [],
+        error: 'Invalid stage result',
+        details: null
+      };
+    }
+
+    return {
+      success: !!result.success,
+      warnings: Array.isArray(result.warnings) ? result.warnings : [],
+      error: result.error || null,
+      details: result.details || null
+    };
+  }
+
+  _isCompleted(state, stageName) {
+    const stage = (state.stages || []).find(item => item.name === stageName);
+    return !!stage && stage.status === 'completed';
+  }
+}
+
+module.exports = {
+  StageRunner
+};
+

package/lib/spec/pipeline/state-store.js

@@ -0,0 +1,119 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { randomUUID } = require('crypto');
+
+class PipelineStateStore {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+  }
+
+  getStateDir(specId) {
+    return path.join(this.projectPath, '.kiro', 'state', 'spec-pipeline', specId);
+  }
+
+  getRunPath(specId, runId) {
+    return path.join(this.getStateDir(specId), `${runId}.json`);
+  }
+
+  getLatestPath(specId) {
+    return path.join(this.getStateDir(specId), 'latest.json');
+  }
+
+  async create(specId, options = {}) {
+    const runId = options.runId || randomUUID();
+    const state = {
+      spec_id: specId,
+      run_id: runId,
+      status: 'running',
+      strategy: {
+        fail_fast: options.failFast !== false,
+        continue_on_warning: !!options.continueOnWarning
+      },
+      stages: [],
+      started_at: new Date().toISOString(),
+      ended_at: null
+    };
+
+    await this.save(state);
+    return state;
+  }
+
+  async save(state) {
+    const runPath = this.getRunPath(state.spec_id, state.run_id);
+    const latestPath = this.getLatestPath(state.spec_id);
+
+    await fs.ensureDir(path.dirname(runPath));
+    await fs.writeJson(runPath, state, { spaces: 2 });
+    await fs.writeJson(latestPath, {
+      spec_id: state.spec_id,
+      run_id: state.run_id,
+      updated_at: new Date().toISOString()
+    }, { spaces: 2 });
+
+    return runPath;
+  }
+
+  async loadLatest(specId) {
+    const latestPath = this.getLatestPath(specId);
+    if (!await fs.pathExists(latestPath)) {
+      return null;
+    }
+
+    const latest = await fs.readJson(latestPath);
+    const runPath = this.getRunPath(specId, latest.run_id);
+    if (!await fs.pathExists(runPath)) {
+      return null;
+    }
+
+    return fs.readJson(runPath);
+  }
+
+  async markStageStart(state, stageName) {
+    const stage = this._getOrCreateStage(state, stageName);
+    stage.status = 'running';
+    stage.started_at = new Date().toISOString();
+    stage.ended_at = null;
+    stage.error = null;
+    stage.warnings = [];
+
+    await this.save(state);
+  }
+
+  async markStageResult(state, stageName, result) {
+    const stage = this._getOrCreateStage(state, stageName);
+    stage.status = result.status;
+    stage.ended_at = new Date().toISOString();
+    stage.error = result.error || null;
+    stage.warnings = result.warnings || [];
+    stage.output = result.output || null;
+
+    await this.save(state);
+  }
+
+  async markFinished(state, status) {
+    state.status = status;
+    state.ended_at = new Date().toISOString();
+    await this.save(state);
+  }
+
+  _getOrCreateStage(state, stageName) {
+    let stage = state.stages.find(item => item.name === stageName);
+    if (!stage) {
+      stage = {
+        name: stageName,
+        status: 'pending',
+        started_at: null,
+        ended_at: null,
+        warnings: []
+      };
+      state.stages.push(stage);
+    }
+
+    return stage;
+  }
+}
+
+module.exports = {
+  PipelineStateStore
+};
+

package/lib/spec-gate/engine/gate-engine.js

@@ -0,0 +1,165 @@
+const { randomUUID } = require('crypto');
+
+class GateEngine {
+  constructor(options = {}) {
+    this.registry = options.registry;
+    this.policy = options.policy;
+  }
+
+  async evaluate(input = {}) {
+    const specId = input.specId;
+    const runId = input.runId || randomUUID();
+    const startedAt = new Date().toISOString();
+
+    const policyRules = (this.policy && this.policy.rules) || {};
+    const enabledRules = this.registry.listEnabled(policyRules);
+
+    const rules = [];
+    const failedChecks = [];
+    const warnings = [];
+
+    let weightedScore = 0;
+    let totalWeight = 0;
+    let hardFailTriggered = false;
+
+    for (const rule of enabledRules) {
+      const policyEntry = policyRules[rule.id] || {};
+      const weight = Number(policyEntry.weight || 0);
+      const hardFail = !!policyEntry.hard_fail;
+
+      totalWeight += weight;
+      const execution = await rule.execute({
+        specId,
+        runId,
+        policy: this.policy
+      });
+
+      const passed = !!execution.passed;
+      const ratio = this._normalizeRatio(execution.ratio);
+      const ruleScore = passed ? weight : Number((weight * ratio).toFixed(2));
+
+      if (!passed) {
+        failedChecks.push({
+          id: rule.id,
+          hard_fail: hardFail,
+          details: execution.details || {}
+        });
+      }
+
+      if (hardFail && !passed) {
+        hardFailTriggered = true;
+      }
+
+      if (Array.isArray(execution.warnings) && execution.warnings.length > 0) {
+        warnings.push(...execution.warnings.map(message => ({ id: rule.id, message })));
+      }
+
+      weightedScore += ruleScore;
+
+      rules.push({
+        id: rule.id,
+        passed,
+        score: ruleScore,
+        max_score: weight,
+        hard_fail: hardFail,
+        warnings: execution.warnings || [],
+        details: execution.details || {}
+      });
+    }
+
+    const score = totalWeight > 0
+      ? Math.round((weightedScore / totalWeight) * 100)
+      : 0;
+
+    const decision = this._decide({
+      score,
+      hardFailTriggered,
+      warnings
+    });
+
+    const nextActions = this._buildNextActions(decision, failedChecks, warnings);
+    const endedAt = new Date().toISOString();
+
+    return {
+      spec_id: specId,
+      run_id: runId,
+      decision,
+      score,
+      rules,
+      failed_checks: failedChecks,
+      warnings,
+      next_actions: nextActions,
+      policy_snapshot: {
+        thresholds: this.policy.thresholds,
+        strict_mode: this.policy.strict_mode
+      },
+      started_at: startedAt,
+      ended_at: endedAt
+    };
+  }
+
+  _normalizeRatio(value) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+      return 0;
+    }
+
+    if (value < 0) {
+      return 0;
+    }
+
+    if (value > 1) {
+      return 1;
+    }
+
+    return value;
+  }
+
+  _decide(context) {
+    const thresholds = this.policy.thresholds || {};
+    const goThreshold = Number(thresholds.go || 90);
+    const conditionalThreshold = Number(thresholds.conditional_go || 70);
+    const warningAsFailure = !!(this.policy.strict_mode && this.policy.strict_mode.warning_as_failure);
+
+    if (context.hardFailTriggered) {
+      return 'no-go';
+    }
+
+    if (warningAsFailure && context.warnings.length > 0) {
+      return 'no-go';
+    }
+
+    if (context.score >= goThreshold) {
+      return 'go';
+    }
+
+    if (context.score >= conditionalThreshold) {
+      return 'conditional-go';
+    }
+
+    return 'no-go';
+  }
+
+  _buildNextActions(decision, failedChecks, warnings) {
+    if (decision === 'go') {
+      return ['Proceed to implementation and keep evidence attached to Spec artifacts.'];
+    }
+
+    const actions = [];
+
+    if (failedChecks.length > 0) {
+      actions.push(`Fix failed checks: ${failedChecks.map(item => item.id).join(', ')}`);
+    }
+
+    if (warnings.length > 0) {
+      actions.push('Review warnings and decide whether to re-run with relaxed strict mode.');
+    }
+
+    actions.push('Re-run gate after remediation and attach latest gate report.');
+    return actions;
+  }
+}
+
+module.exports = {
+  GateEngine
+};
+

package/lib/spec-gate/policy/default-policy.js

@@ -0,0 +1,22 @@
+const DEFAULT_GATE_POLICY = {
+  version: 1,
+  thresholds: {
+    go: 90,
+    conditional_go: 70
+  },
+  strict_mode: {
+    warning_as_failure: true
+  },
+  rules: {
+    mandatory: { enabled: true, weight: 30, hard_fail: true },
+    tests: { enabled: true, weight: 25, hard_fail: true },
+    docs: { enabled: true, weight: 15, hard_fail: false },
+    config_consistency: { enabled: true, weight: 15, hard_fail: false },
+    traceability: { enabled: true, weight: 15, hard_fail: false }
+  }
+};
+
+module.exports = {
+  DEFAULT_GATE_POLICY
+};
+

package/lib/spec-gate/policy/policy-loader.js

@@ -0,0 +1,103 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { DEFAULT_GATE_POLICY } = require('./default-policy');
+
+class PolicyLoader {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+  }
+
+  async load(options = {}) {
+    const policyPath = this._resolvePolicyPath(options.policy);
+    if (!policyPath) {
+      return this._applyStrictMode(this._clone(DEFAULT_GATE_POLICY), options.strict);
+    }
+
+    const userPolicy = await fs.readJson(policyPath);
+    this._validatePolicy(userPolicy, policyPath);
+
+    const merged = this._deepMerge(this._clone(DEFAULT_GATE_POLICY), userPolicy);
+    return this._applyStrictMode(merged, options.strict);
+  }
+
+  getTemplate() {
+    return this._clone(DEFAULT_GATE_POLICY);
+  }
+
+  _resolvePolicyPath(explicitPath) {
+    if (explicitPath) {
+      return path.isAbsolute(explicitPath)
+        ? explicitPath
+        : path.join(this.projectPath, explicitPath);
+    }
+
+    const projectPolicy = path.join(this.projectPath, '.kiro', 'config', 'spec-gate-policy.json');
+    if (fs.existsSync(projectPolicy)) {
+      return projectPolicy;
+    }
+
+    return null;
+  }
+
+  _applyStrictMode(policy, strict) {
+    if (!strict) {
+      return policy;
+    }
+
+    return {
+      ...policy,
+      strict_mode: {
+        ...policy.strict_mode,
+        warning_as_failure: true
+      }
+    };
+  }
+
+  _validatePolicy(policy, sourcePath) {
+    if (!policy || typeof policy !== 'object') {
+      throw new Error(`Invalid gate policy at ${sourcePath}: expected JSON object`);
+    }
+
+    if (!policy.rules || typeof policy.rules !== 'object') {
+      throw new Error(`Invalid gate policy at ${sourcePath}: missing rules object`);
+    }
+
+    if (policy.thresholds) {
+      const { go, conditional_go: conditionalGo } = policy.thresholds;
+      if ((go !== undefined && typeof go !== 'number') ||
+          (conditionalGo !== undefined && typeof conditionalGo !== 'number')) {
+        throw new Error(`Invalid gate policy at ${sourcePath}: thresholds must be numeric`);
+      }
+    }
+  }
+
+  _clone(value) {
+    return JSON.parse(JSON.stringify(value));
+  }
+
+  _deepMerge(base, override) {
+    const result = { ...base };
+
+    Object.keys(override || {}).forEach(key => {
+      const baseValue = result[key];
+      const overrideValue = override[key];
+
+      if (this._isPlainObject(baseValue) && this._isPlainObject(overrideValue)) {
+        result[key] = this._deepMerge(baseValue, overrideValue);
+      } else {
+        result[key] = overrideValue;
+      }
+    });
+
+    return result;
+  }
+
+  _isPlainObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value);
+  }
+}
+
+module.exports = {
+  PolicyLoader
+};
+

package/lib/spec-gate/result-emitter.js

@@ -0,0 +1,81 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+class ResultEmitter {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+  }
+
+  async emit(result, options = {}) {
+    if (!options.silent) {
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        this._printHumanReadable(result);
+      }
+    }
+
+    const outputPath = options.out
+      ? this._resolvePath(options.out)
+      : null;
+
+    if (outputPath) {
+      await fs.ensureDir(path.dirname(outputPath));
+      await fs.writeJson(outputPath, result, { spaces: 2 });
+    }
+
+    return {
+      outputPath
+    };
+  }
+
+  _printHumanReadable(result) {
+    const decisionColor = result.decision === 'go'
+      ? chalk.green
+      : result.decision === 'conditional-go'
+        ? chalk.yellow
+        : chalk.red;
+
+    console.log(chalk.red('🔥') + ' Spec Gate');
+    console.log();
+    console.log(`${chalk.gray('Spec:')} ${result.spec_id}`);
+    console.log(`${chalk.gray('Run:')} ${result.run_id}`);
+    console.log(`${chalk.gray('Decision:')} ${decisionColor(result.decision)}`);
+    console.log(`${chalk.gray('Score:')} ${result.score}`);
+    console.log();
+
+    console.log(chalk.bold('Rule Results'));
+    result.rules.forEach(rule => {
+      const icon = rule.passed ? chalk.green('✓') : chalk.red('✗');
+      console.log(`  ${icon} ${rule.id} (${rule.score}/${rule.max_score})`);
+    });
+
+    if (result.failed_checks.length > 0) {
+      console.log();
+      console.log(chalk.bold('Failed Checks'));
+      result.failed_checks.forEach(check => {
+        console.log(`  - ${check.id} (hard_fail: ${check.hard_fail})`);
+      });
+    }
+
+    if (result.next_actions.length > 0) {
+      console.log();
+      console.log(chalk.bold('Next Actions'));
+      result.next_actions.forEach(action => console.log(`  - ${action}`));
+    }
+  }
+
+  _resolvePath(filePath) {
+    if (path.isAbsolute(filePath)) {
+      return filePath;
+    }
+
+    return path.join(this.projectPath, filePath);
+  }
+}
+
+module.exports = {
+  ResultEmitter
+};
+