openspec-sdd-e2e-kit 0.1.0

package/kit/scripts/sdd/lib.mjs

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const allowedValidationTypes = new Set([
+  'mock-e2e',
+  'real-smoke',
+  'component',
+  'unit',
+  'api',
+  'manual',
+]);
+
+export const riskTags = new Set([
+  'race-condition',
+  'degradation',
+  'anti-duplicate',
+  'form-validation',
+  'conditional-render',
+  'cross-view-sync',
+  'state-machine',
+  'feedback',
+  'negative',
+  'data-echo',
+]);
+
+export const automatedValidationTypes = new Set(
+  [...allowedValidationTypes].filter((type) => type !== 'manual'),
+);
+
+export function getChangeName() {
+  const change = process.argv[2];
+  if (!change) {
+    throw new Error('Usage: pnpm <sdd-command> <change> [phase]');
+  }
+  return change;
+}
+
+export function getChangeDir(change) {
+  return path.join(process.cwd(), 'openspec', 'changes', change);
+}
+
+export function assertExists(targetPath, label = targetPath) {
+  if (!fs.existsSync(targetPath)) {
+    throw new Error(`${label} not found: ${targetPath}`);
+  }
+}
+
+export function walkFiles(root, predicate = () => true) {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+
+  const results = [];
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkFiles(fullPath, predicate));
+    } else if (predicate(fullPath)) {
+      results.push(fullPath);
+    }
+  }
+
+  return results.sort();
+}
+
+export function findFeatureFiles(change) {
+  const specsDir = path.join(getChangeDir(change), 'specs');
+  return walkFiles(specsDir, (file) => file.endsWith('.feature'));
+}
+
+export function parseFeatureFile(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const scenarios = [];
+  let pendingTags = [];
+  let featureTags = [];
+
+  lines.forEach((line, index) => {
+    const trimmed = line.trim();
+
+    if (!trimmed) {
+      return;
+    }
+
+    if (trimmed.startsWith('@')) {
+      pendingTags = trimmed.split(/\s+/).filter(Boolean);
+      return;
+    }
+
+    if (trimmed.startsWith('Feature:')) {
+      featureTags = pendingTags;
+      pendingTags = [];
+      return;
+    }
+
+    const scenarioMatch = trimmed.match(/^Scenario(?: Outline)?:\s*(.+)$/);
+    if (scenarioMatch) {
+      scenarios.push({
+        file,
+        line: index + 1,
+        name: scenarioMatch[1].trim(),
+        tags: pendingTags,
+        featureTags,
+      });
+      pendingTags = [];
+      return;
+    }
+
+    if (!trimmed.startsWith('#')) {
+      pendingTags = [];
+    }
+  });
+
+  return scenarios;
+}
+
+export function getFeatureScenarios(change) {
+  return findFeatureFiles(change).flatMap(parseFeatureFile);
+}
+
+export function getTagValue(tags, prefix) {
+  const tag = tags.find((item) => item.startsWith(prefix));
+  return tag ? tag.slice(prefix.length) : null;
+}
+
+export function hasPriority(tags) {
+  return tags.some((tag) => /^@p[0-2]$/.test(tag));
+}
+
+export function getScenarioPhases(change) {
+  return new Set(
+    getFeatureScenarios(change)
+      .map((scenario) => getTagValue(scenario.tags, '@phase:'))
+      .filter(Boolean),
+  );
+}
+
+export function getRequiredPhaseCoverage(change, phase) {
+  const required = getFeatureScenarios(change).filter((scenario) => {
+    const scenarioPhase = getTagValue(scenario.tags, '@phase:');
+    const validation = getTagValue(scenario.tags, '@validation:');
+    const isRequiredPriority = scenario.tags.includes('@p0') || scenario.tags.includes('@p1');
+    return (
+      scenarioPhase === phase &&
+      isRequiredPriority &&
+      !scenario.tags.includes('@gap-pending') &&
+      validation
+    );
+  });
+
+  const automated = required.filter((scenario) =>
+    automatedValidationTypes.has(getTagValue(scenario.tags, '@validation:')),
+  );
+
+  const manual = required.filter((scenario) => getTagValue(scenario.tags, '@validation:') === 'manual');
+
+  return {
+    required,
+    automated,
+    manual,
+  };
+}
+
+export function parseCoverageReport(report) {
+  const values = {};
+  const fields = ['selected', 'automated', 'passed', 'mismatch', 'blocked', 'manual', 'gap-pending'];
+
+  for (const field of fields) {
+    const match = report.match(new RegExp(`\\b${field}\\b\\s*[:|]\\s*(\\d+)`, 'i'));
+    if (match) {
+      values[field] = Number(match[1]);
+    }
+  }
+
+  const gateMatch = report.match(/\bgate\b\s*[:|]\s*(passed|failed)\b/i);
+  if (gateMatch) {
+    values.gate = gateMatch[1].toLowerCase();
+  }
+
+  return values;
+}
+
+export function validatePhaseReport(change, phase, reportPath) {
+  const errors = [];
+
+  if (!fs.existsSync(reportPath)) {
+    return {
+      errors: [`phase report not found: ${reportPath}`],
+      coverage: null,
+      expected: getRequiredPhaseCoverage(change, phase),
+    };
+  }
+
+  const report = fs.readFileSync(reportPath, 'utf8');
+  const coverage = parseCoverageReport(report);
+  const expected = getRequiredPhaseCoverage(change, phase);
+  const requiredFields = ['selected', 'automated', 'passed', 'mismatch', 'blocked', 'manual', 'gap-pending', 'gate'];
+
+  for (const field of requiredFields) {
+    if (coverage[field] === undefined) {
+      errors.push(`phase report missing coverage field: ${field}`);
+    }
+  }
+
+  if (coverage.selected !== undefined && coverage.selected < expected.required.length) {
+    errors.push(
+      `phase report selected=${coverage.selected} but expected at least ${expected.required.length} P0/P1 Scenario results`,
+    );
+  }
+
+  if (coverage.automated !== undefined && coverage.automated < expected.automated.length) {
+    errors.push(
+      `phase report automated=${coverage.automated} but expected ${expected.automated.length} automated P0/P1 Scenario results`,
+    );
+  }
+
+  if (coverage.passed !== undefined && coverage.passed < expected.automated.length) {
+    errors.push(
+      `phase report passed=${coverage.passed} but expected ${expected.automated.length} automated Scenario passed`,
+    );
+  }
+
+  if (coverage.manual !== undefined && coverage.manual < expected.manual.length) {
+    errors.push(
+      `phase report manual=${coverage.manual} but expected ${expected.manual.length} manual Scenario results`,
+    );
+  }
+
+  if (coverage.gate !== 'passed') {
+    errors.push('phase report gate is not passed');
+  }
+
+  for (const field of ['mismatch', 'blocked', 'manual']) {
+    if (
+      coverage[field] > 0 &&
+      !new RegExp(`${field}\\s+accepted exception|${field}.*已接受例外`, 'i').test(report)
+    ) {
+      errors.push(`phase report has ${field}=${coverage[field]} without accepted exception`);
+    }
+  }
+
+  return { errors, coverage, expected };
+}
+
+export function parseTaskPhases(change) {
+  const tasksPath = path.join(getChangeDir(change), 'tasks.md');
+  assertExists(tasksPath, 'tasks.md');
+
+  const text = fs.readFileSync(tasksPath, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const phases = new Map();
+  let current = null;
+
+  lines.forEach((line, index) => {
+    const phaseMatch = line.match(/^## Phase:\s*([a-z0-9-]+)\s*$/);
+    if (phaseMatch) {
+      current = {
+        id: phaseMatch[1],
+        line: index + 1,
+        lines: [],
+      };
+      phases.set(current.id, current);
+      return;
+    }
+
+    if (current) {
+      current.lines.push(line);
+    }
+  });
+
+  return phases;
+}
+
+export function reportResult(title, errors, warnings = []) {
+  if (warnings.length) {
+    console.warn(`\n${title} warnings:`);
+    warnings.forEach((warning) => console.warn(`- ${warning}`));
+  }
+
+  if (errors.length) {
+    console.error(`\n${title} failed:`);
+    errors.forEach((error) => console.error(`- ${error}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`${title} passed`);
+}

package/kit/scripts/sdd/lint-features.mjs

@@ -0,0 +1,60 @@
+import {
+  allowedValidationTypes,
+  findFeatureFiles,
+  getChangeName,
+  getFeatureScenarios,
+  getTagValue,
+  hasPriority,
+  reportResult,
+  riskTags,
+} from './lib.mjs';
+
+const change = getChangeName();
+const featureFiles = findFeatureFiles(change);
+const scenarios = getFeatureScenarios(change);
+const errors = [];
+const warnings = [];
+
+if (!featureFiles.length) {
+  errors.push(`no feature files found for change "${change}"`);
+}
+
+if (!scenarios.length) {
+  errors.push(`no Scenario found for change "${change}"`);
+}
+
+for (const scenario of scenarios) {
+  const label = `${scenario.file}:${scenario.line} ${scenario.name}`;
+  const phase = getTagValue(scenario.tags, '@phase:');
+  const validation = getTagValue(scenario.tags, '@validation:');
+  const req = getTagValue(scenario.tags, '@req:');
+  const hasRiskTag = scenario.tags.some((tag) => riskTags.has(tag.slice(1)));
+
+  if (!phase) {
+    errors.push(`${label} missing @phase:<phase-id>`);
+  }
+
+  if (!validation) {
+    errors.push(`${label} missing @validation:<type>`);
+  } else if (!allowedValidationTypes.has(validation)) {
+    errors.push(`${label} has invalid @validation:${validation}`);
+  }
+
+  if (!req) {
+    errors.push(`${label} missing @req:<requirement-id>`);
+  }
+
+  if (!hasPriority(scenario.tags)) {
+    errors.push(`${label} missing @p0/@p1/@p2`);
+  }
+
+  if (scenario.tags.includes('@p0') && scenario.tags.includes('@gap-pending')) {
+    errors.push(`${label} cannot use @gap-pending on @p0 Scenario`);
+  }
+
+  if ((scenario.tags.includes('@p0') || scenario.tags.includes('@p1')) && !hasRiskTag) {
+    errors.push(`${label} has no risk/boundary tag`);
+  }
+}
+
+reportResult(`sdd:lint-features ${change}`, errors, warnings);

package/kit/scripts/sdd/lint-tasks.mjs

@@ -0,0 +1,41 @@
+import {
+  getChangeName,
+  getScenarioPhases,
+  parseTaskPhases,
+  reportResult,
+} from './lib.mjs';
+
+const change = getChangeName();
+const featurePhases = getScenarioPhases(change);
+const taskPhases = parseTaskPhases(change);
+const errors = [];
+
+if (!featurePhases.size) {
+  errors.push(`no @phase tags found in feature Scenario tags for change "${change}"`);
+}
+
+for (const phase of featurePhases) {
+  const taskPhase = taskPhases.get(phase);
+  if (!taskPhase) {
+    errors.push(`feature phase "${phase}" is missing in tasks.md`);
+    continue;
+  }
+
+  const block = taskPhase.lines.join('\n');
+  if (!block.includes(`Covers: \`@phase:${phase}\``)) {
+    errors.push(`tasks phase "${phase}" missing coverage line: Covers: \`@phase:${phase}\``);
+  }
+
+  const acceptancePattern = new RegExp(`Acceptance 验证 .+@phase:${phase}`);
+  if (!acceptancePattern.test(block)) {
+    errors.push(`tasks phase "${phase}" missing acceptance validation task`);
+  }
+}
+
+for (const phase of taskPhases.keys()) {
+  if (!featurePhases.has(phase)) {
+    errors.push(`tasks phase "${phase}" has no matching feature @phase:${phase}`);
+  }
+}
+
+reportResult(`sdd:lint-tasks ${change}`, errors);

package/kit/scripts/sdd/self-test.mjs

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const repoRoot = process.cwd();
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'sdd-self-test-'));
+const checks = [];
+
+function writeFile(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function createChange(name, featureTags, tasksPhase = 'alpha', includeAcceptance = true) {
+  const changeDir = path.join(tempRoot, 'openspec', 'changes', name);
+  writeFile(
+    path.join(changeDir, 'specs', 'fixture', 'features', 'fixture.feature'),
+    [
+      '@fixture',
+      'Feature: Fixture',
+      '',
+      '  Rule: Fixture rule',
+      '',
+      `    ${featureTags}`,
+      '    Scenario: Fixture scenario',
+      '      Given 存在测试前置条件',
+      '      When 用户执行测试动作',
+      '      Then 系统展示测试结果',
+      '',
+    ].join('\n'),
+  );
+
+  const acceptance = includeAcceptance
+    ? [`- [ ] Acceptance 验证 \`@phase:${tasksPhase}\` 全部自动化 Scenario`]
+    : [];
+
+  writeFile(
+    path.join(changeDir, 'tasks.md'),
+    [
+      '# Tasks',
+      '',
+      `## Phase: ${tasksPhase}`,
+      '',
+      `Covers: \`@phase:${tasksPhase}\``,
+      '',
+      '- [ ] 实现 fixture',
+      ...acceptance,
+      '',
+    ].join('\n'),
+  );
+
+  return changeDir;
+}
+
+function writeReport(change, phase, gate = 'passed', overrides = {}) {
+  const values = {
+    selected: 1,
+    automated: 1,
+    passed: 1,
+    mismatch: 0,
+    blocked: 0,
+    manual: 0,
+    'gap-pending': 0,
+    ...overrides,
+  };
+
+  writeFile(
+    path.join(tempRoot, 'specs', 'e2e', 'bdd', change, `validation-report.${phase}.md`),
+    [
+      '# Validation Report',
+      '',
+      `selected: ${values.selected}`,
+      `automated: ${values.automated}`,
+      `passed: ${values.passed}`,
+      `mismatch: ${values.mismatch}`,
+      `blocked: ${values.blocked}`,
+      `manual: ${values.manual}`,
+      `gap-pending: ${values['gap-pending']}`,
+      `gate: ${gate}`,
+      '',
+    ].join('\n'),
+  );
+}
+
+function runScript(script, args) {
+  return spawnSync(process.execPath, [path.join(repoRoot, script), ...args], {
+    cwd: tempRoot,
+    encoding: 'utf8',
+  });
+}
+
+function expectExit(name, result, expected) {
+  const actual = result.status ?? 0;
+  checks.push({ name, actual, expected, stdout: result.stdout, stderr: result.stderr });
+}
+
+try {
+  createChange('valid', '@phase:alpha @validation:unit @req:fixture @p0 @state-machine');
+  expectExit('valid feature lint passes', runScript('scripts/sdd/lint-features.mjs', ['valid']), 0);
+  expectExit('valid task lint passes', runScript('scripts/sdd/lint-tasks.mjs', ['valid']), 0);
+
+  createChange('missing-phase', '@validation:unit @req:fixture @p0 @state-machine');
+  expectExit('missing phase fails feature lint', runScript('scripts/sdd/lint-features.mjs', ['missing-phase']), 1);
+
+  createChange('invalid-validation', '@phase:alpha @validation:unknown @req:fixture @p0 @state-machine');
+  expectExit('invalid validation fails feature lint', runScript('scripts/sdd/lint-features.mjs', ['invalid-validation']), 1);
+
+  createChange('p0-gap', '@phase:alpha @validation:unit @req:fixture @p0 @gap-pending @state-machine');
+  expectExit('p0 gap-pending fails feature lint', runScript('scripts/sdd/lint-features.mjs', ['p0-gap']), 1);
+
+  createChange('phase-mismatch', '@phase:alpha @validation:unit @req:fixture @p0 @state-machine', 'beta');
+  expectExit('phase mismatch fails task lint', runScript('scripts/sdd/lint-tasks.mjs', ['phase-mismatch']), 1);
+
+  createChange('missing-acceptance', '@phase:alpha @validation:unit @req:fixture @p0 @state-machine', 'alpha', false);
+  expectExit('missing acceptance fails task lint', runScript('scripts/sdd/lint-tasks.mjs', ['missing-acceptance']), 1);
+
+  createChange('report-valid', '@phase:alpha @validation:unit @req:fixture @p0 @state-machine');
+  writeReport('report-valid', 'alpha', 'passed');
+  expectExit('passed report passes phase gate', runScript('scripts/sdd/check-report.mjs', ['report-valid', 'alpha']), 0);
+  expectExit('passed report summarizes final acceptance', runScript('scripts/sdd/summarize-acceptance.mjs', ['report-valid']), 0);
+
+  createChange('report-undercovers', '@phase:alpha @validation:unit @req:fixture @p0 @state-machine');
+  writeFile(
+    path.join(
+      tempRoot,
+      'openspec',
+      'changes',
+      'report-undercovers',
+      'specs',
+      'fixture',
+      'features',
+      'fixture.feature',
+    ),
+    [
+      '@fixture',
+      'Feature: Fixture',
+      '',
+      '  Rule: Fixture rule',
+      '',
+      '    @phase:alpha @validation:unit @req:fixture @p0 @state-machine',
+      '    Scenario: Fixture scenario one',
+      '      Given 存在测试前置条件',
+      '      When 用户执行测试动作',
+      '      Then 系统展示测试结果',
+      '',
+      '    @phase:alpha @validation:unit @req:fixture @p1 @degradation',
+      '    Scenario: Fixture scenario two',
+      '      Given 存在测试前置条件',
+      '      When 用户执行测试动作',
+      '      Then 系统展示测试结果',
+      '',
+    ].join('\n'),
+  );
+  writeReport('report-undercovers', 'alpha', 'passed');
+  expectExit(
+    'undercovered report fails phase gate',
+    runScript('scripts/sdd/check-report.mjs', ['report-undercovers', 'alpha']),
+    1,
+  );
+
+  createChange('report-failed', '@phase:alpha @validation:unit @req:fixture @p0 @state-machine');
+  writeReport('report-failed', 'alpha', 'failed');
+  expectExit('failed report fails phase gate', runScript('scripts/sdd/check-report.mjs', ['report-failed', 'alpha']), 1);
+
+  createChange('report-blocked', '@phase:alpha @validation:unit @req:fixture @p0 @state-machine');
+  writeReport('report-blocked', 'alpha', 'passed', { blocked: 1, passed: 0 });
+  expectExit('blocked report fails phase gate', runScript('scripts/sdd/check-report.mjs', ['report-blocked', 'alpha']), 1);
+
+  const failures = checks.filter((check) => check.actual !== check.expected);
+  if (failures.length) {
+    failures.forEach((failure) => {
+      console.error(`FAILED: ${failure.name}`);
+      console.error(`expected exit ${failure.expected}, got ${failure.actual}`);
+      if (failure.stdout) console.error(failure.stdout);
+      if (failure.stderr) console.error(failure.stderr);
+    });
+    process.exitCode = 1;
+  } else {
+    checks.forEach((check) => console.log(`ok - ${check.name}`));
+    console.log(`sdd:self-test passed (${checks.length} checks)`);
+  }
+} finally {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}

package/kit/scripts/sdd/summarize-acceptance.mjs

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getChangeDir, getChangeName, parseTaskPhases, reportResult, validatePhaseReport } from './lib.mjs';
+
+const change = getChangeName();
+const phases = [...parseTaskPhases(change).keys()];
+const reportDir = path.join(process.cwd(), 'specs', 'e2e', 'bdd', change);
+const errors = [];
+const rows = [];
+
+for (const phase of phases) {
+  const reportPath = path.join(reportDir, `validation-report.${phase}.md`);
+  if (!fs.existsSync(reportPath)) {
+    errors.push(`missing phase report: ${reportPath}`);
+    rows.push(`| \`${phase}\` | missing | - |`);
+    continue;
+  }
+
+  const validation = validatePhaseReport(change, phase, reportPath);
+  const gate = validation.errors.length ? 'failed' : 'passed';
+  errors.push(...validation.errors.map((error) => `phase ${phase}: ${error}`));
+  rows.push(`| \`${phase}\` | ${gate} | \`${path.relative(process.cwd(), reportPath)}\` |`);
+}
+
+const summaryPath = path.join(getChangeDir(change), 'acceptance-coverage.md');
+const summary = [
+  '# Acceptance Coverage',
+  '',
+  `Change: \`${change}\``,
+  '',
+  '| Phase | Gate | Report |',
+  '|---|---|---|',
+  ...rows,
+  '',
+  `Final gate: ${errors.length ? 'failed' : 'passed'}`,
+  '',
+].join('\n');
+
+fs.writeFileSync(summaryPath, summary);
+
+reportResult(`sdd:acceptance ${change}`, errors);

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "openspec-sdd-e2e-kit",
+  "version": "0.1.0",
+  "description": "Project-local OpenSpec SDD + E2E workflow kit",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "sdd-e2e-kit": "bin/sdd-e2e-kit.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "kit",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --check src/lib.mjs && node --check src/check.mjs && node --check src/diff.mjs && node --check src/install.mjs && node --check bin/sdd-e2e-kit.mjs && cd kit && node scripts/sdd/self-test.mjs"
+  }
+}