spectra-cli 4.1.1

package/plugins/spec-driver/scripts/lib/sync-timeline-builder.mjs

@@ -0,0 +1,114 @@
+/**
+ * sync-timeline-builder.mjs — 时间线构建模块
+ *
+ * 负责将产品下的 SpecEntry 列表排序并标记类型，生成 Timeline 对象。
+ * 所有导出函数均为纯函数（无副作用）。
+ *
+ * @module sync-timeline-builder
+ */
+
+// ────────────────────────────────────────────────────────────
+// SpecType 分类规则
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 根据 spec 目录名判定 SpecType。
+ * 注意：INITIAL 类型由 buildTimeline 在排序后标记（编号最小者），
+ * 此函数不处理 INITIAL 判定。
+ *
+ * 分类规则（按 data-model.md Section 1.1）：
+ * - dirName 含 `fix` → 'FIX'
+ * - dirName 含 `refactor` / `rename` / `split` → 'REFACTOR'
+ * - dirName 含 `enhance` / `batch` / `improve` → 'ENHANCEMENT'
+ * - 其余 → 'FEATURE'
+ *
+ * @param {{ id: string, dirName: string }} specEntry
+ * @returns {'FEATURE' | 'FIX' | 'REFACTOR' | 'ENHANCEMENT'}
+ */
+export function classifySpecType(specEntry) {
+  const name = specEntry.dirName.toLowerCase();
+
+  // fix 类型匹配：需要防止 "fix" 误匹配包含 fix 子串的非修复目录
+  // 使用词边界检测：以 fix 开头的后缀部分，或包含 -fix- 前缀
+  if (/(?:^|\d+-)fix(?:-|$)/.test(name)) {
+    return 'FIX';
+  }
+
+  if (/(?:refactor|rename|split)/.test(name)) {
+    return 'REFACTOR';
+  }
+
+  if (/(?:enhance|batch|improve)/.test(name)) {
+    return 'ENHANCEMENT';
+  }
+
+  return 'FEATURE';
+}
+
+/**
+ * 构建单个产品的 spec 时间线。
+ *
+ * - 按 specId 数值升序排序
+ * - 第一个条目强制标记为 INITIAL
+ * - 其余条目调用 classifySpecType 判定类型
+ * - 编号重复时按 dirName 字母序排列并记录警告
+ *
+ * @param {Array<{ id: string, dirName: string, title: string|null, summary: string|null }>} specEntries
+ * @param {string} productId
+ * @returns {{ productId: string, entries: Array<{ specId: string, dirName: string, type: string, title: string|null, summary: string|null }>, stats: Record<string, number>, warnings: string[] }}
+ */
+export function buildTimeline(specEntries, productId) {
+  const emptyStats = {
+    INITIAL: 0,
+    FEATURE: 0,
+    FIX: 0,
+    REFACTOR: 0,
+    ENHANCEMENT: 0,
+  };
+
+  if (!Array.isArray(specEntries) || specEntries.length === 0) {
+    return { productId, entries: [], stats: { ...emptyStats }, warnings: [] };
+  }
+
+  const warnings = [];
+
+  // 排序：按 specId 数值升序；编号相同时按 dirName 字母序
+  const sorted = [...specEntries].sort((a, b) => {
+    const numA = parseInt(a.id, 10);
+    const numB = parseInt(b.id, 10);
+    if (numA !== numB) {
+      return numA - numB;
+    }
+    // 编号重复——按 dirName 字母序稳定排列
+    return a.dirName.localeCompare(b.dirName);
+  });
+
+  // 检测编号重复
+  const idCounts = {};
+  for (const entry of sorted) {
+    idCounts[entry.id] = (idCounts[entry.id] || 0) + 1;
+  }
+  for (const [id, count] of Object.entries(idCounts)) {
+    if (count > 1) {
+      warnings.push(`编号 ${id} 存在 ${count} 个重复条目，按目录名字母序排列`);
+    }
+  }
+
+  // 构建时间线条目
+  const stats = { ...emptyStats };
+  const entries = sorted.map((entry, index) => {
+    // 第一个条目强制标记为 INITIAL
+    const type = index === 0 ? 'INITIAL' : classifySpecType(entry);
+    stats[type] = (stats[type] || 0) + 1;
+
+    return {
+      specId: entry.id,
+      dirName: entry.dirName,
+      type,
+      title: entry.title ?? null,
+      summary: entry.summary ?? null,
+    };
+  });
+
+  return { productId, entries, stats, warnings };
+}

package/plugins/spec-driver/scripts/lib/sync-validator.mjs

@@ -0,0 +1,174 @@
+/**
+ * sync-validator.mjs — 验证模块
+ *
+ * 对合并结果执行三项验证检查：
+ * 1. fr-count: 合并后 activeFRCount >= INITIAL spec 的 FR 数量
+ * 2. no-contradiction: 同一 FR ID 不存在两个 active 版本
+ * 3. changelog-coverage: 变更历史覆盖所有归属 spec
+ *
+ * 所有导出函数均为纯函数（无副作用）。
+ *
+ * @module sync-validator
+ */
+
+// ────────────────────────────────────────────────────────────
+// 导出函数
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 对合并结果执行三项验证检查。
+ *
+ * @param {object} skeleton — MergeSkeleton（冲突解决后）
+ * @param {{ productId: string, entries: Array<{ specId: string, type: string }> }} timeline
+ * @returns {{ productId: string, passed: boolean, checks: Array<{ name: string, passed: boolean, detail: string, data: Record<string, number|string> }> }}
+ *   ValidationReport
+ */
+export function validateMergeResult(skeleton, timeline) {
+  const checks = [
+    checkFRCount(skeleton, timeline),
+    checkNoContradiction(skeleton),
+    checkChangelogCoverage(skeleton, timeline),
+  ];
+
+  const passed = checks.every((check) => check.passed);
+
+  return {
+    productId: skeleton.productId,
+    passed,
+    checks,
+  };
+}
+
+// ────────────────────────────────────────────────────────────
+// 内部检查函数
+// ────────────────────────────────────────────────────────────
+
+/**
+ * fr-count 检查：合并后活跃 FR 数量 >= INITIAL spec 的 FR 数量
+ *
+ * @param {object} skeleton
+ * @param {object} timeline
+ * @returns {object} ValidationCheck
+ */
+function checkFRCount(skeleton, timeline) {
+  // 找到 INITIAL 条目
+  const initialEntry = timeline.entries.find((e) => e.type === 'INITIAL');
+  const activeFRCount = skeleton.mergeStats.activeFRCount;
+
+  // 计算 INITIAL spec 的 FR 数量
+  // 从骨架的第 5 章中，查找 sourceSpec === INITIAL specId 的 active FR
+  let initialFRCount = 0;
+  if (initialEntry) {
+    const ch5 = skeleton.chapters['5'];
+    if (ch5) {
+      // 统计 sourceSpec 为 INITIAL 的 FR 数量作为基线
+      initialFRCount = ch5.functionalRequirements.filter(
+        (fr) => fr.sourceSpec === initialEntry.specId
+      ).length;
+    }
+  }
+
+  const passed = activeFRCount >= initialFRCount;
+
+  return {
+    name: 'fr-count',
+    passed,
+    detail: passed
+      ? `活跃 FR 数量 (${activeFRCount}) >= INITIAL FR 数量 (${initialFRCount})`
+      : `活跃 FR 数量 (${activeFRCount}) < INITIAL FR 数量 (${initialFRCount})`,
+    data: {
+      activeFRCount,
+      initialFRCount,
+    },
+  };
+}
+
+/**
+ * no-contradiction 检查：同一 FR ID 不存在两个 active 版本
+ * （冲突解决后应不存在，此为二次校验）
+ *
+ * @param {object} skeleton
+ * @returns {object} ValidationCheck
+ */
+function checkNoContradiction(skeleton) {
+  const activeById = {};
+  let contradictions = 0;
+  const contradictionDetails = [];
+
+  for (const chapter of Object.values(skeleton.chapters)) {
+    for (const fr of chapter.functionalRequirements) {
+      if (fr.status !== 'active') {
+        continue;
+      }
+      if (!activeById[fr.id]) {
+        activeById[fr.id] = [];
+      }
+      activeById[fr.id].push(fr.sourceSpec);
+    }
+  }
+
+  for (const [frId, sources] of Object.entries(activeById)) {
+    if (sources.length > 1) {
+      contradictions += 1;
+      contradictionDetails.push(`${frId}: ${sources.join(', ')}`);
+    }
+  }
+
+  const passed = contradictions === 0;
+
+  return {
+    name: 'no-contradiction',
+    passed,
+    detail: passed
+      ? '无矛盾的 FR 描述'
+      : `发现 ${contradictions} 个矛盾: ${contradictionDetails.join('; ')}`,
+    data: {
+      contradictions,
+    },
+  };
+}
+
+/**
+ * changelog-coverage 检查：变更历史覆盖所有归属 spec
+ *
+ * 收集所有 chapter 的 sourceSpecs 去重后的集合 >= timeline.entries 中所有 specId 的集合
+ *
+ * @param {object} skeleton
+ * @param {object} timeline
+ * @returns {object} ValidationCheck
+ */
+function checkChangelogCoverage(skeleton, timeline) {
+  // 收集所有 chapter 中的 sourceSpecs
+  const coveredSpecs = new Set();
+  for (const chapter of Object.values(skeleton.chapters)) {
+    for (const specId of chapter.sourceSpecs) {
+      coveredSpecs.add(specId);
+    }
+  }
+
+  // timeline 中的所有 specId
+  const expectedSpecs = new Set(timeline.entries.map((e) => e.specId));
+
+  // 检查是否所有 expected 都被 covered
+  const missing = [];
+  for (const specId of expectedSpecs) {
+    if (!coveredSpecs.has(specId)) {
+      missing.push(specId);
+    }
+  }
+
+  const passed = missing.length === 0;
+
+  return {
+    name: 'changelog-coverage',
+    passed,
+    detail: passed
+      ? `变更历史覆盖全部 ${expectedSpecs.size} 个 spec`
+      : `缺少 ${missing.length} 个 spec 的变更记录: ${missing.join(', ')}`,
+    data: {
+      expectedCount: expectedSpecs.size,
+      coveredCount: coveredSpecs.size,
+      missingCount: missing.length,
+    },
+  };
+}

package/plugins/spec-driver/scripts/lib/workflow-registry-core.mjs

@@ -0,0 +1,281 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  getProductWorkflowIndexJsonPath,
+  getProductWorkflowIndexMarkdownPath,
+  toRelativePosix,
+} from './product-artifact-paths.mjs';
+import { appendWarningsSection, dedupeStringValues } from './script-diagnostics.mjs';
+import { writeJsonArtifact, writeMarkdownArtifact } from './script-report-io.mjs';
+import { parseYamlDocument } from './simple-yaml.mjs';
+
+export const ALLOWED_OVERRIDE_FIELDS = new Set([
+  'title',
+  'persona',
+  'useCases',
+  'recommendedWhen',
+  'templateVersion',
+]);
+
+export function generateWorkflowRegistry(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+  const libDir = path.dirname(new URL(import.meta.url).pathname);
+  const scriptDir = path.dirname(libDir);
+  const pluginDir = path.dirname(scriptDir);
+  const workflowDir = path.join(pluginDir, 'workflows');
+  const overrideDir = path.join(projectRoot, '.specify', 'workflows');
+  const warnings = [];
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+
+  const workflowDefs = readWorkflowDefinitions(workflowDir);
+  const overrides = readWorkflowOverrides(overrideDir, warnings);
+  const workflows = workflowDefs.map((workflow) => applyWorkflowOverride(workflow, overrides.get(workflow.id), warnings));
+  const goldenPaths = readGoldenPaths(path.join(workflowDir, 'golden-paths.yaml'));
+  const normalizedWarnings = dedupeStringValues(warnings);
+
+  const jsonPath = getProductWorkflowIndexJsonPath(projectRoot, 'spec-driver');
+  const markdownPath = getProductWorkflowIndexMarkdownPath(projectRoot, 'spec-driver');
+
+  const indexJson = {
+    generatedAt,
+    sourceDir: relativePosix(projectRoot, workflowDir),
+    overrideDir: fs.existsSync(overrideDir) ? relativePosix(projectRoot, overrideDir) : null,
+    workflowCount: workflows.length,
+    goldenPathCount: goldenPaths.length,
+    workflows,
+    goldenPaths,
+    warnings: normalizedWarnings,
+  };
+
+  writeJsonArtifact(jsonPath, indexJson);
+  writeMarkdownArtifact(markdownPath, renderWorkflowIndexMarkdown(indexJson));
+
+  return {
+    generatedAt,
+    workflowCount: workflows.length,
+    goldenPathCount: goldenPaths.length,
+    jsonPath: toRelativePosix(projectRoot, jsonPath),
+    markdownPath: toRelativePosix(projectRoot, markdownPath),
+    workflows,
+    goldenPaths,
+    warnings: normalizedWarnings,
+  };
+}
+
+export function readWorkflowDefinitions(workflowDir) {
+  const filePaths = fs.readdirSync(workflowDir)
+    .filter((fileName) => fileName.endsWith('.yaml') && fileName !== 'golden-paths.yaml')
+    .sort((left, right) => left.localeCompare(right))
+    .map((fileName) => path.join(workflowDir, fileName));
+
+  return filePaths.map((filePath) => {
+    const parsed = parseYamlDocument(fs.readFileSync(filePath, 'utf-8'));
+    return normalizeWorkflowDefinition(parsed, filePath);
+  });
+}
+
+export function readWorkflowOverrides(overrideDir, warnings) {
+  const overrides = new Map();
+  if (!fs.existsSync(overrideDir)) {
+    return overrides;
+  }
+
+  const filePaths = fs.readdirSync(overrideDir)
+    .filter((fileName) => fileName.endsWith('.yaml'))
+    .sort((left, right) => left.localeCompare(right))
+    .map((fileName) => path.join(overrideDir, fileName));
+
+  for (const filePath of filePaths) {
+    const parsed = parseYamlDocument(fs.readFileSync(filePath, 'utf-8'));
+    const workflowId = asString(parsed.id) ?? path.basename(filePath, '.yaml');
+    const fields = {};
+
+    for (const [key, value] of Object.entries(parsed)) {
+      if (key === 'id') {
+        continue;
+      }
+
+      if (!ALLOWED_OVERRIDE_FIELDS.has(key)) {
+        warnings.push(`workflow override 忽略非 metadata 字段: ${workflowId}.${key}`);
+        continue;
+      }
+
+      fields[key] = value;
+    }
+
+    overrides.set(workflowId, fields);
+  }
+
+  return overrides;
+}
+
+export function applyWorkflowOverride(base, override, warnings) {
+  if (!override) {
+    return base;
+  }
+
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (!ALLOWED_OVERRIDE_FIELDS.has(key)) {
+      warnings.push(`workflow override 字段未生效: ${base.id}.${key}`);
+      continue;
+    }
+    merged[key] = normalizeOverrideValue(key, value, base);
+  }
+  return merged;
+}
+
+export function normalizeOverrideValue(key, value, base) {
+  if (key === 'useCases' || key === 'recommendedWhen') {
+    return asStringArray(value) ?? base[key];
+  }
+
+  return asString(value) ?? base[key];
+}
+
+export function normalizeWorkflowDefinition(parsed, filePath) {
+  return {
+    id: asString(parsed.id) ?? path.basename(filePath, '.yaml'),
+    title: asString(parsed.title) ?? path.basename(filePath, '.yaml'),
+    persona: asString(parsed.persona) ?? 'unknown',
+    useCases: asStringArray(parsed.useCases) ?? [],
+    entryCommand: normalizeStringMap(parsed.entryCommand),
+    requiredInputs: asStringArray(parsed.requiredInputs) ?? [],
+    keyGates: asStringArray(parsed.keyGates) ?? [],
+    artifacts: asStringArray(parsed.artifacts) ?? [],
+    recommendedWhen: asStringArray(parsed.recommendedWhen) ?? [],
+    templateVersion: asString(parsed.templateVersion) ?? '1.0.0',
+  };
+}
+
+export function readGoldenPaths(filePath) {
+  const parsed = parseYamlDocument(fs.readFileSync(filePath, 'utf-8'));
+  const paths = Array.isArray(parsed.goldenPaths) ? parsed.goldenPaths : [];
+  return paths
+    .map((entry) => (isObject(entry) ? entry : null))
+    .filter(Boolean)
+    .map((entry) => ({
+      id: asString(entry.id) ?? 'unknown',
+      title: asString(entry.title) ?? asString(entry.id) ?? 'Unknown Golden Path',
+      persona: asString(entry.persona) ?? 'unknown',
+      workflows: asStringArray(entry.workflows) ?? [],
+      recommendedWhen: asStringArray(entry.recommendedWhen) ?? [],
+    }));
+}
+
+function normalizeStringMap(value) {
+  if (!isObject(value)) {
+    return {};
+  }
+
+  const result = {};
+  for (const [key, entryValue] of Object.entries(value)) {
+    const parsed = asString(entryValue);
+    if (parsed) {
+      result[key] = parsed;
+    }
+  }
+  return result;
+}
+
+function asString(value) {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value
+    .map((entry) => asString(entry))
+    .filter(Boolean);
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function relativePosix(projectRoot, candidatePath) {
+  return path.relative(projectRoot, candidatePath).split(path.sep).join('/');
+}
+
+export function renderWorkflowIndexMarkdown(index) {
+  const lines = [
+    '# Spec Driver Workflow Registry',
+    '',
+    `- Generated At: ${index.generatedAt}`,
+    `- Source Dir: ${index.sourceDir}`,
+    index.overrideDir ? `- Override Dir: ${index.overrideDir}` : '- Override Dir: 未配置',
+    `- Workflows: ${index.workflowCount}`,
+    `- Golden Paths: ${index.goldenPathCount}`,
+    '',
+    '## 如何选择技能',
+    '',
+    '| Workflow | Persona | Use Cases | Claude | Codex |',
+    '| --- | --- | --- | --- | --- |',
+    ...index.workflows.map((workflow) => (
+      `| \`${workflow.id}\` | ${workflow.persona} | ${workflow.useCases.join(' / ')} | \`${workflow.entryCommand.claude ?? '-'}\` | \`${workflow.entryCommand.codex ?? '-'}\` |`
+    )),
+    '',
+    '## Golden Paths',
+    '',
+  ];
+
+  for (const pathDef of index.goldenPaths) {
+    lines.push(`### ${pathDef.title}`);
+    lines.push('');
+    lines.push(`- ID: \`${pathDef.id}\``);
+    lines.push(`- Persona: ${pathDef.persona}`);
+    lines.push(`- Workflows: ${pathDef.workflows.map((workflow) => `\`${workflow}\``).join(' -> ')}`);
+    if (pathDef.recommendedWhen.length > 0) {
+      lines.push('- Recommended When:');
+      for (const item of pathDef.recommendedWhen) {
+        lines.push(`  - ${item}`);
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push('## Workflow Details');
+  lines.push('');
+
+  for (const workflow of index.workflows) {
+    lines.push(`### ${workflow.title}`);
+    lines.push('');
+    lines.push(`- ID: \`${workflow.id}\``);
+    lines.push(`- Persona: ${workflow.persona}`);
+    lines.push(`- Template Version: ${workflow.templateVersion}`);
+    lines.push(`- Use Cases: ${workflow.useCases.join(' / ') || '未配置'}`);
+    lines.push(`- Required Inputs: ${workflow.requiredInputs.join(' / ') || '未配置'}`);
+    lines.push(`- Key Gates: ${workflow.keyGates.join(' / ') || '无'}`);
+    lines.push(`- Artifacts: ${workflow.artifacts.join(' / ') || '未配置'}`);
+    lines.push(`- Recommended When: ${workflow.recommendedWhen.join(' / ') || '未配置'}`);
+    lines.push(`- Claude Entry: \`${workflow.entryCommand.claude ?? '-'}\``);
+    lines.push(`- Codex Entry: \`${workflow.entryCommand.codex ?? '-'}\``);
+    lines.push('');
+  }
+
+  appendWarningsSection(lines, index.warnings);
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export function printWorkflowRegistryResult(result, asJson) {
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(
+    [
+      'Spec Driver Workflow Registry',
+      `Workflows: ${result.workflowCount}`,
+      `Golden Paths: ${result.goldenPathCount}`,
+      `Markdown: ${result.markdownPath}`,
+      `JSON: ${result.jsonPath}`,
+      ...(result.warnings.length > 0 ? ['Warnings:', ...result.warnings.map((warning) => `  - ${warning}`)] : []),
+    ].join('\n') + '\n',
+  );
+}