spectra-cli 4.1.1

package/plugins/spec-driver/scripts/lib/sync-merge-strategy.mjs

@@ -0,0 +1,388 @@
+/**
+ * sync-merge-strategy.mjs — 增量合并策略模块
+ *
+ * 负责按 Timeline 的类型规则执行增量合并，生成 MergeSkeleton（14 章结构）。
+ * 所有导出函数均为纯函数（无副作用）。
+ *
+ * @module sync-merge-strategy
+ */
+
+// ────────────────────────────────────────────────────────────
+// 14 章标题常量（与 merge-engine-output.md Section 6 一致）
+// ────────────────────────────────────────────────────────────
+
+/** @type {Record<string, string>} */
+export const CHAPTER_TITLES = {
+  '1': '产品概述',
+  '2': '目标与成功指标',
+  '3': '用户画像与场景',
+  '4': '范围与边界',
+  '5': '当前功能全集',
+  '6': '非功能需求',
+  '7': '当前技术架构',
+  '8': '设计原则与决策记录',
+  '9': '已知限制与技术债',
+  '10': '假设与风险',
+  '11': '被废弃的功能',
+  '12': '变更历史',
+  '13': '术语表',
+  '14': '附录：增量 spec 索引',
+};
+
+// ────────────────────────────────────────────────────────────
+// 内部工具
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 创建空的 MergeSkeleton
+ * @param {string} productId
+ * @returns {object} MergeSkeleton
+ */
+function createEmptySkeleton(productId) {
+  const chapters = {};
+  for (const [num, title] of Object.entries(CHAPTER_TITLES)) {
+    chapters[num] = {
+      title,
+      number: parseInt(num, 10),
+      functionalRequirements: [],
+      userStories: [],
+      sourceSpecs: [],
+      changeSummary: '',
+    };
+  }
+
+  return {
+    productId,
+    chapters,
+    mergeStats: {
+      activeFRCount: 0,
+      supersededFRCount: 0,
+      deprecatedFRCount: 0,
+      userStoryCount: 0,
+      totalSpecCount: 0,
+    },
+  };
+}
+
+/**
+ * 在 FR 列表中查找同 ID 的条目
+ * @param {Array<object>} frList
+ * @param {string} frId
+ * @returns {object|null}
+ */
+function findFRById(frList, frId) {
+  return frList.find((fr) => fr.id === frId) ?? null;
+}
+
+/**
+ * 向章节的 sourceSpecs 添加 specId（去重）
+ * @param {object} chapter
+ * @param {string} specId
+ */
+function addSourceSpec(chapter, specId) {
+  if (!chapter.sourceSpecs.includes(specId)) {
+    chapter.sourceSpecs.push(specId);
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+// 合并处理器（按 SpecType）
+// ────────────────────────────────────────────────────────────
+
+/**
+ * INITIAL 类型：将其 FR 和 UserStory 作为基础写入骨架
+ */
+function mergeInitial(skeleton, specId, parsedContent) {
+  const ch5 = skeleton.chapters['5'];
+  const ch3 = skeleton.chapters['3'];
+
+  // 写入 FR
+  if (Array.isArray(parsedContent.requirements)) {
+    for (const fr of parsedContent.requirements) {
+      ch5.functionalRequirements.push({
+        id: fr.id,
+        description: fr.description,
+        sourceSpec: specId,
+        status: 'active',
+        supersededBy: null,
+      });
+    }
+  }
+
+  // 写入 User Stories
+  if (Array.isArray(parsedContent.userStories)) {
+    for (const us of parsedContent.userStories) {
+      ch3.userStories.push({
+        title: us.title,
+        description: us.rawText || us.title,
+        sourceSpec: specId,
+        priority: us.priority ?? null,
+      });
+      ch5.userStories.push({
+        title: us.title,
+        description: us.rawText || us.title,
+        sourceSpec: specId,
+        priority: us.priority ?? null,
+      });
+    }
+  }
+
+  // 标记所有章节的来源
+  for (const chapter of Object.values(skeleton.chapters)) {
+    addSourceSpec(chapter, specId);
+  }
+}
+
+/**
+ * FEATURE 类型：追加新的 FR 和 UserStory（id 不重复则 append）
+ */
+function mergeFeature(skeleton, specId, parsedContent) {
+  const ch5 = skeleton.chapters['5'];
+  const ch3 = skeleton.chapters['3'];
+
+  if (Array.isArray(parsedContent.requirements)) {
+    for (const fr of parsedContent.requirements) {
+      const existing = findFRById(ch5.functionalRequirements, fr.id);
+      if (!existing) {
+        ch5.functionalRequirements.push({
+          id: fr.id,
+          description: fr.description,
+          sourceSpec: specId,
+          status: 'active',
+          supersededBy: null,
+        });
+      }
+      // 如果已存在同 ID 的 FR，不追加（保持现有版本）
+    }
+  }
+
+  if (Array.isArray(parsedContent.userStories)) {
+    for (const us of parsedContent.userStories) {
+      ch3.userStories.push({
+        title: us.title,
+        description: us.rawText || us.title,
+        sourceSpec: specId,
+        priority: us.priority ?? null,
+      });
+      ch5.userStories.push({
+        title: us.title,
+        description: us.rawText || us.title,
+        sourceSpec: specId,
+        priority: us.priority ?? null,
+      });
+    }
+  }
+
+  // 标记相关章节来源
+  addSourceSpec(ch5, specId);
+  addSourceSpec(ch3, specId);
+  addSourceSpec(skeleton.chapters['12'], specId);
+  addSourceSpec(skeleton.chapters['14'], specId);
+}
+
+/**
+ * FIX 类型：查找同 FR ID，更新 description，标记 sourceSpec
+ */
+function mergeFix(skeleton, specId, parsedContent) {
+  const ch5 = skeleton.chapters['5'];
+
+  if (Array.isArray(parsedContent.requirements)) {
+    for (const fr of parsedContent.requirements) {
+      const existing = findFRById(ch5.functionalRequirements, fr.id);
+      if (existing && existing.status === 'active') {
+        existing.description = fr.description;
+        existing.sourceSpec = specId;
+      } else if (!existing) {
+        // FIX 中的新 FR（防御性：理论上 fix 不新增，但容错处理）
+        ch5.functionalRequirements.push({
+          id: fr.id,
+          description: fr.description,
+          sourceSpec: specId,
+          status: 'active',
+          supersededBy: null,
+        });
+      }
+    }
+  }
+
+  addSourceSpec(ch5, specId);
+  addSourceSpec(skeleton.chapters['12'], specId);
+  addSourceSpec(skeleton.chapters['14'], specId);
+}
+
+/**
+ * REFACTOR 类型：查找同 FR ID，替换 description，记录 supersededBy
+ */
+function mergeRefactor(skeleton, specId, parsedContent) {
+  const ch5 = skeleton.chapters['5'];
+  const ch11 = skeleton.chapters['11'];
+
+  if (Array.isArray(parsedContent.requirements)) {
+    for (const fr of parsedContent.requirements) {
+      const existing = findFRById(ch5.functionalRequirements, fr.id);
+      if (existing && existing.status === 'active') {
+        // 标记旧版本被取代
+        existing.status = 'superseded';
+        existing.supersededBy = specId;
+
+        // 追加新版本
+        ch5.functionalRequirements.push({
+          id: fr.id,
+          description: fr.description,
+          sourceSpec: specId,
+          status: 'active',
+          supersededBy: null,
+        });
+      } else if (!existing) {
+        ch5.functionalRequirements.push({
+          id: fr.id,
+          description: fr.description,
+          sourceSpec: specId,
+          status: 'active',
+          supersededBy: null,
+        });
+      }
+    }
+  }
+
+  if (Array.isArray(parsedContent.userStories)) {
+    for (const us of parsedContent.userStories) {
+      skeleton.chapters['3'].userStories.push({
+        title: us.title,
+        description: us.rawText || us.title,
+        sourceSpec: specId,
+        priority: us.priority ?? null,
+      });
+    }
+  }
+
+  addSourceSpec(ch5, specId);
+  addSourceSpec(ch11, specId);
+  addSourceSpec(skeleton.chapters['12'], specId);
+  addSourceSpec(skeleton.chapters['14'], specId);
+}
+
+/**
+ * ENHANCEMENT 类型：查找同 FR ID，增强 description（追加而非替换）
+ */
+function mergeEnhancement(skeleton, specId, parsedContent) {
+  const ch5 = skeleton.chapters['5'];
+
+  if (Array.isArray(parsedContent.requirements)) {
+    for (const fr of parsedContent.requirements) {
+      const existing = findFRById(ch5.functionalRequirements, fr.id);
+      if (existing && existing.status === 'active') {
+        // 增强：追加描述
+        existing.description = `${existing.description}\n[增强 by ${specId}] ${fr.description}`;
+        existing.sourceSpec = specId;
+      } else if (!existing) {
+        ch5.functionalRequirements.push({
+          id: fr.id,
+          description: fr.description,
+          sourceSpec: specId,
+          status: 'active',
+          supersededBy: null,
+        });
+      }
+    }
+  }
+
+  if (Array.isArray(parsedContent.userStories)) {
+    for (const us of parsedContent.userStories) {
+      skeleton.chapters['3'].userStories.push({
+        title: us.title,
+        description: us.rawText || us.title,
+        sourceSpec: specId,
+        priority: us.priority ?? null,
+      });
+      ch5.userStories.push({
+        title: us.title,
+        description: us.rawText || us.title,
+        sourceSpec: specId,
+        priority: us.priority ?? null,
+      });
+    }
+  }
+
+  addSourceSpec(ch5, specId);
+  addSourceSpec(skeleton.chapters['12'], specId);
+  addSourceSpec(skeleton.chapters['14'], specId);
+}
+
+// ────────────────────────────────────────────────────────────
+// 导出函数
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 按 Timeline 顺序执行增量合并，生成 MergeSkeleton。
+ *
+ * 同一 timeline + parsedSpecs 输入多次调用结果完全一致（确定性）。
+ *
+ * @param {{ productId: string, entries: Array<{ specId: string, dirName: string, type: string }> }} timeline
+ * @param {Record<string, object>} parsedSpecs — 键为 specId，值为 ParsedSpecContent
+ * @returns {object} MergeSkeleton
+ */
+export function executeMerge(timeline, parsedSpecs) {
+  const skeleton = createEmptySkeleton(timeline.productId);
+
+  // 合并策略分发表
+  const mergeHandlers = {
+    INITIAL: mergeInitial,
+    FEATURE: mergeFeature,
+    FIX: mergeFix,
+    REFACTOR: mergeRefactor,
+    ENHANCEMENT: mergeEnhancement,
+  };
+
+  // 按 timeline 顺序遍历
+  for (const entry of timeline.entries) {
+    const parsedContent = parsedSpecs[entry.specId] || {
+      requirements: [],
+      userStories: [],
+    };
+
+    const handler = mergeHandlers[entry.type];
+    if (handler) {
+      handler(skeleton, entry.specId, parsedContent);
+    }
+  }
+
+  // 计算 mergeStats
+  let activeFRCount = 0;
+  let supersededFRCount = 0;
+  let deprecatedFRCount = 0;
+  let userStoryCount = 0;
+
+  for (const chapter of Object.values(skeleton.chapters)) {
+    for (const fr of chapter.functionalRequirements) {
+      if (fr.status === 'active') activeFRCount += 1;
+      if (fr.status === 'superseded') supersededFRCount += 1;
+      if (fr.status === 'deprecated') deprecatedFRCount += 1;
+    }
+    userStoryCount += chapter.userStories.length;
+  }
+
+  skeleton.mergeStats = {
+    activeFRCount,
+    supersededFRCount,
+    deprecatedFRCount,
+    userStoryCount,
+    totalSpecCount: timeline.entries.length,
+  };
+
+  // 填充各章节 changeSummary
+  for (const chapter of Object.values(skeleton.chapters)) {
+    const sources = chapter.sourceSpecs;
+    const frCount = chapter.functionalRequirements.filter((fr) => fr.status === 'active').length;
+    const usCount = chapter.userStories.length;
+
+    const parts = [];
+    if (frCount > 0) parts.push(`${frCount} FR`);
+    if (usCount > 0) parts.push(`${usCount} User Stories`);
+    if (sources.length > 0) parts.push(`来自 ${sources.join(', ')}`);
+
+    chapter.changeSummary = parts.length > 0 ? parts.join('，') : '无变更';
+  }
+
+  return skeleton;
+}

package/plugins/spec-driver/scripts/lib/sync-product-mapping.mjs

@@ -0,0 +1,228 @@
+/**
+ * sync-product-mapping.mjs — 产品映射模块
+ *
+ * 负责 product-mapping.yaml 的解析、修正、差集检测和序列化。
+ * 所有导出函数均为纯函数（无副作用），文件 I/O 仅在入口脚本中完成。
+ *
+ * @module sync-product-mapping
+ */
+
+import { parseYamlDocument, stringifyYaml } from './simple-yaml.mjs';
+
+// ────────────────────────────────────────────────────────────
+// 常量
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 已知的产品名自动修正规则。
+ * key 为旧名，value 为新名。
+ * @type {Record<string, string>}
+ */
+export const NAME_CORRECTION_RULES = {
+  'spec-driverdriver': 'spec-driver',
+  'spec-driver-driver-pro': 'spec-driver',
+};
+
+// ────────────────────────────────────────────────────────────
+// 内部工具
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 判断值是否为非数组对象
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * 深拷贝简单 JSON 兼容对象（无函数、无循环引用）
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function deepClone(value) {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(deepClone);
+  }
+  const result = {};
+  for (const key of Object.keys(value)) {
+    result[key] = deepClone(value[key]);
+  }
+  return result;
+}
+
+// ────────────────────────────────────────────────────────────
+// 导出函数
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 解析 product-mapping.yaml 内容为 ProductMapping 对象。
+ *
+ * @param {string} yamlContent — YAML 字符串
+ * @returns {{ products: Record<string, { description: string, specs: string[] }> }}
+ *   ProductMapping 对象；输入为空或解析失败时返回 { products: {} }
+ */
+export function parseProductMapping(yamlContent) {
+  if (!yamlContent || typeof yamlContent !== 'string') {
+    return { products: {} };
+  }
+
+  let document;
+  try {
+    document = parseYamlDocument(yamlContent);
+  } catch {
+    return { products: {} };
+  }
+
+  if (!isObject(document) || !isObject(document.products)) {
+    return { products: {} };
+  }
+
+  const products = {};
+
+  for (const [productId, rawProduct] of Object.entries(document.products)) {
+    const product = isObject(rawProduct) ? rawProduct : {};
+    const description = typeof product.description === 'string' ? product.description : '';
+
+    // specs 列表：支持两种格式
+    // 格式 A（当前）：[{ id: "001-reverse-spec-v2", type: "INITIAL", summary: "..." }, ...]
+    // 格式 B（简化）：["001", "002", ...] 或 ["001-reverse-spec-v2", ...]
+    // 统一提取为纯数字编号（如 "001"）
+    let specs = [];
+    if (Array.isArray(product.specs)) {
+      specs = product.specs
+        .map((entry) => {
+          let rawId = null;
+          if (typeof entry === 'string') {
+            rawId = entry;
+          } else if (isObject(entry) && typeof entry.id === 'string') {
+            rawId = entry.id;
+          }
+          if (!rawId) return null;
+          // 从 "001-reverse-spec-v2" 提取纯数字编号 "001"
+          const numMatch = /^(\d{3})/.exec(rawId);
+          return numMatch ? numMatch[1] : rawId;
+        })
+        .filter(Boolean);
+    }
+
+    products[productId] = { description, specs };
+  }
+
+  return { products };
+}
+
+/**
+ * 执行产品名自动修正。
+ * 若 mapping 中存在旧名 key，将其 specs 合并到新名 key 下（去重），删除旧名条目。
+ *
+ * 纯函数：不修改输入对象，返回新的 ProductMapping。
+ *
+ * @param {{ products: Record<string, { description: string, specs: string[] }> }} mapping
+ * @param {Record<string, string>} [rules=NAME_CORRECTION_RULES] — 修正规则
+ * @returns {{ products: Record<string, { description: string, specs: string[] }> }}
+ */
+export function correctProductNames(mapping, rules = NAME_CORRECTION_RULES) {
+  const result = deepClone(mapping);
+
+  for (const [oldName, newName] of Object.entries(rules)) {
+    if (!result.products[oldName]) {
+      continue;
+    }
+
+    const oldEntry = result.products[oldName];
+
+    // 如果新名已存在，合并 specs（去重）
+    if (result.products[newName]) {
+      const existingSpecs = new Set(result.products[newName].specs);
+      for (const specId of oldEntry.specs) {
+        existingSpecs.add(specId);
+      }
+      result.products[newName].specs = [...existingSpecs].sort();
+    } else {
+      // 新名不存在，直接改名
+      result.products[newName] = { ...oldEntry };
+    }
+
+    // 删除旧名条目
+    delete result.products[oldName];
+  }
+
+  return result;
+}
+
+/**
+ * 检测未映射的 spec。
+ * 计算差集：scannedSpecs 中的 specId 不在任何产品的 specs 列表中。
+ *
+ * @param {{ products: Record<string, { description: string, specs: string[] }> }} mapping
+ * @param {Array<{ id: string, dirName: string, title: string|null, summary: string|null }>} scannedSpecs
+ * @returns {Array<{ specId: string, dirName: string, title: string|null, summary: string|null }>}
+ *   UnmappedSpec[]
+ */
+export function detectUnmappedSpecs(mapping, scannedSpecs) {
+  // 收集所有已映射的 spec 编号
+  const mappedIds = new Set();
+  for (const productDef of Object.values(mapping.products)) {
+    for (const specId of productDef.specs) {
+      mappedIds.add(specId);
+    }
+  }
+
+  // 筛选未映射的 spec
+  return scannedSpecs
+    .filter((entry) => !mappedIds.has(entry.id))
+    .map((entry) => ({
+      specId: entry.id,
+      dirName: entry.dirName,
+      title: entry.title ?? null,
+      summary: entry.summary ?? null,
+    }));
+}
+
+/**
+ * 将 Agent 归属决策的未映射 spec 合并到 mapping 中。
+ *
+ * 纯函数：不修改输入对象，返回新的 ProductMapping。
+ *
+ * @param {{ products: Record<string, { description: string, specs: string[] }> }} mapping
+ * @param {Array<{ specId: string, dirName: string }>} unmappedSpecs
+ * @param {Record<string, string>} agentDecisions — 键为 specId，值为 productId
+ * @returns {{ products: Record<string, { description: string, specs: string[] }> }}
+ */
+export function mergeUnmappedSpecs(mapping, unmappedSpecs, agentDecisions) {
+  const result = deepClone(mapping);
+
+  for (const spec of unmappedSpecs) {
+    const targetProduct = agentDecisions[spec.specId];
+    if (!targetProduct) {
+      continue;
+    }
+
+    // 确保产品存在
+    if (!result.products[targetProduct]) {
+      result.products[targetProduct] = { description: '', specs: [] };
+    }
+
+    // 追加 spec（去重）
+    if (!result.products[targetProduct].specs.includes(spec.specId)) {
+      result.products[targetProduct].specs.push(spec.specId);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 将 ProductMapping 序列化为 YAML 字符串。
+ *
+ * @param {{ products: Record<string, { description: string, specs: string[] }> }} mapping
+ * @returns {string} YAML 字符串
+ */
+export function serializeProductMapping(mapping) {
+  return stringifyYaml(mapping);
+}