kiro-spec-engine 1.45.13 → 1.46.0

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
+};
+

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

@@ -0,0 +1,156 @@
+const fs = require('fs-extra');
+const path = require('path');
+const docsCommand = require('../../commands/docs');
+
+function createDefaultRules(projectPath = process.cwd()) {
+  return [
+    {
+      id: 'mandatory',
+      description: 'Verify mandatory Spec files exist',
+      async execute(context) {
+        const specPath = path.join(projectPath, '.kiro', 'specs', context.specId);
+        const requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
+        const checks = await Promise.all(requiredFiles.map(async fileName => {
+          const filePath = path.join(specPath, fileName);
+          const exists = await fs.pathExists(filePath);
+          return { fileName, exists };
+        }));
+
+        const missing = checks.filter(item => !item.exists).map(item => item.fileName);
+        const passRatio = checks.filter(item => item.exists).length / requiredFiles.length;
+
+        return {
+          passed: missing.length === 0,
+          ratio: passRatio,
+          details: {
+            requiredFiles,
+            missing
+          },
+          warnings: missing.length > 0 ? [`Missing files: ${missing.join(', ')}`] : []
+        };
+      }
+    },
+    {
+      id: 'tests',
+      description: 'Verify tasks include explicit validation intent',
+      async execute(context) {
+        const tasksPath = path.join(projectPath, '.kiro', 'specs', context.specId, 'tasks.md');
+        if (!await fs.pathExists(tasksPath)) {
+          return {
+            passed: false,
+            ratio: 0,
+            details: { reason: 'tasks.md missing' },
+            warnings: ['tasks.md missing']
+          };
+        }
+
+        const content = await fs.readFile(tasksPath, 'utf8');
+        const hasValidationHints = /验证|Validation|Acceptance/i.test(content);
+
+        return {
+          passed: hasValidationHints,
+          ratio: hasValidationHints ? 1 : 0,
+          details: {
+            hasValidationHints
+          },
+          warnings: hasValidationHints ? [] : ['No validation markers found in tasks.md']
+        };
+      }
+    },
+    {
+      id: 'docs',
+      description: 'Validate document structure compatibility',
+      async execute(context) {
+        const exitCode = await docsCommand('validate', {
+          spec: context.specId
+        });
+
+        return {
+          passed: exitCode === 0,
+          ratio: exitCode === 0 ? 1 : 0,
+          details: {
+            exitCode
+          },
+          warnings: exitCode === 0 ? [] : [`docs validate returned exit code ${exitCode}`]
+        };
+      }
+    },
+    {
+      id: 'config_consistency',
+      description: 'Verify project-level KSE config baseline exists',
+      async execute() {
+        const kiroDir = path.join(projectPath, '.kiro');
+        const configDir = path.join(kiroDir, 'config');
+        const hasKiro = await fs.pathExists(kiroDir);
+        const hasConfig = await fs.pathExists(configDir);
+
+        const ratio = hasKiro && hasConfig ? 1 : hasKiro ? 0.5 : 0;
+        const warnings = [];
+        if (!hasKiro) {
+          warnings.push('.kiro directory missing');
+        }
+        if (hasKiro && !hasConfig) {
+          warnings.push('.kiro/config directory missing');
+        }
+
+        return {
+          passed: hasKiro,
+          ratio,
+          details: {
+            hasKiro,
+            hasConfig
+          },
+          warnings
+        };
+      }
+    },
+    {
+      id: 'traceability',
+      description: 'Verify requirement-design-task traceability hints',
+      async execute(context) {
+        const specPath = path.join(projectPath, '.kiro', 'specs', context.specId);
+        const designPath = path.join(specPath, 'design.md');
+        const tasksPath = path.join(specPath, 'tasks.md');
+
+        const hasDesign = await fs.pathExists(designPath);
+        const hasTasks = await fs.pathExists(tasksPath);
+
+        if (!hasDesign || !hasTasks) {
+          return {
+            passed: false,
+            ratio: 0,
+            details: {
+              hasDesign,
+              hasTasks
+            },
+            warnings: ['design.md or tasks.md missing']
+          };
+        }
+
+        const [designContent, tasksContent] = await Promise.all([
+          fs.readFile(designPath, 'utf8'),
+          fs.readFile(tasksPath, 'utf8')
+        ]);
+
+        const hasMapping = /Mapping|映射|Requirement/i.test(designContent);
+        const hasTaskReferences = /Requirement|Design|需求|设计/i.test(tasksContent);
+        const scoreParts = [hasMapping, hasTaskReferences].filter(Boolean).length;
+
+        return {
+          passed: hasMapping && hasTaskReferences,
+          ratio: scoreParts / 2,
+          details: {
+            hasMapping,
+            hasTaskReferences
+          },
+          warnings: hasMapping && hasTaskReferences ? [] : ['Traceability links are incomplete']
+        };
+      }
+    }
+  ];
+}
+
+module.exports = {
+  createDefaultRules
+};
+

package/lib/spec-gate/rules/rule-registry.js

@@ -0,0 +1,51 @@
+class RuleRegistry {
+  constructor(initialRules = []) {
+    this.rules = new Map();
+    initialRules.forEach(rule => this.register(rule));
+  }
+
+  register(rule) {
+    if (!rule || !rule.id || typeof rule.execute !== 'function') {
+      throw new Error('Invalid gate rule: expected id and execute()');
+    }
+
+    this.rules.set(rule.id, rule);
+  }
+
+  setEnabled(ruleId, enabled) {
+    const rule = this.rules.get(ruleId);
+    if (!rule) {
+      throw new Error(`Rule not found: ${ruleId}`);
+    }
+
+    rule.enabled = !!enabled;
+  }
+
+  get(ruleId) {
+    return this.rules.get(ruleId);
+  }
+
+  list() {
+    return Array.from(this.rules.values());
+  }
+
+  listEnabled(policyRules = {}) {
+    return this.list().filter(rule => {
+      const policy = policyRules[rule.id];
+      if (!policy) {
+        return false;
+      }
+
+      if (typeof rule.enabled === 'boolean') {
+        return rule.enabled;
+      }
+
+      return policy.enabled !== false;
+    });
+  }
+}
+
+module.exports = {
+  RuleRegistry
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.45.13",
+  "version": "1.46.0",
   "description": "kiro-spec-engine (kse) - A CLI tool and npm package for spec-driven development with AI coding assistants. NOT the Kiro IDE desktop application.",
   "main": "index.js",
   "bin": {
@@ -84,3 +84,4 @@
     "jest": "^27.5.1"
   }
 }
+