spectra-cli 4.1.1

package/plugins/spec-driver/scripts/lib/project-profile-schema.mjs

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+
+export const EXCLUDED_EXECUTION_FIELDS = new Set([
+  'phase_focus',
+  'skip_spec',
+  'implementation_only',
+  'task_strategy',
+]);
+
+export const ALLOWED_TOP_LEVEL_FIELDS = new Set([
+  'product',
+  'owner',
+  'references',
+  'architecture_constraints',
+  'verification_policy',
+  'research_policy',
+  'workflow_preferences',
+  'forbidden_changes',
+  'notes',
+]);
+
+export const referenceEntryObjectSchema = z.object({
+  label: z.string().trim().min(1).optional(),
+  path: z.string().trim().min(1).optional(),
+  url: z.string().trim().url().optional(),
+  required: z.boolean().optional(),
+  purpose: z.string().trim().min(1).optional(),
+});
+
+export const referenceEntrySchema = referenceEntryObjectSchema.refine(
+  (value) => Boolean(value.path || value.url),
+  {
+    message: 'reference entry requires either path or url',
+  },
+);
+
+export const resolvedReferenceEntrySchema = referenceEntryObjectSchema.extend({
+  exists: z.boolean().optional(),
+  resolvedPath: z.string().trim().min(1).optional(),
+  source: z.enum(['yaml', 'markdown']).optional(),
+});
+
+export const resolvedProjectProfileSchema = z.object({
+  product: z
+    .object({
+      name: z.string().trim().min(1).optional(),
+      summary: z.string().trim().min(1).optional(),
+    })
+    .nullable(),
+  owner: z
+    .object({
+      name: z.string().trim().min(1).optional(),
+      team: z.string().trim().min(1).optional(),
+      email: z.string().trim().email().optional(),
+    })
+    .nullable(),
+  references: z.array(resolvedReferenceEntrySchema),
+  architectureConstraints: z.array(z.string().trim().min(1)),
+  verificationPolicy: z.object({
+    requireRealExecution: z.boolean(),
+    requiredCommands: z.array(z.string().trim().min(1)),
+    notes: z.array(z.string().trim().min(1)),
+  }),
+  researchPolicy: z.object({
+    onlineRequired: z.boolean(),
+    minPoints: z.number().int().min(0),
+    maxPoints: z.number().int().min(0),
+    preferredTools: z.array(z.string().trim().min(1)),
+    notes: z.array(z.string().trim().min(1)),
+  }),
+  workflowPreferences: z.object({
+    defaultMode: z.string().trim().min(1).nullable(),
+    preferredPreset: z.string().trim().min(1).nullable(),
+    notes: z.array(z.string().trim().min(1)),
+  }),
+  forbiddenChanges: z.array(z.string().trim().min(1)),
+  notes: z.array(z.string().trim().min(1)),
+});

package/plugins/spec-driver/scripts/lib/script-cli-args.mjs

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import process from 'node:process';
+
+export function parseCommonProjectArgs(argv, defaults = {}) {
+  const args = {
+    projectRoot: defaults.projectRoot ?? process.cwd(),
+    json: Boolean(defaults.json),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--json') {
+      args.json = true;
+      continue;
+    }
+
+    if (token === '--project-root') {
+      args.projectRoot = argv[index + 1] ?? args.projectRoot;
+      index += 1;
+    }
+  }
+
+  args.projectRoot = path.resolve(args.projectRoot);
+  return args;
+}

package/plugins/spec-driver/scripts/lib/script-diagnostics.mjs

@@ -0,0 +1,29 @@
+export function dedupeStringValues(items) {
+  return Array.from(new Set(
+    items
+      .filter((item) => typeof item === 'string')
+      .map((item) => item.trim())
+      .filter(Boolean),
+  ));
+}
+
+export function appendWarningsSection(lines, warnings, heading = '## Warnings') {
+  const normalizedWarnings = dedupeStringValues(warnings);
+  if (normalizedWarnings.length === 0) {
+    return lines;
+  }
+
+  if (lines.length > 0 && lines[lines.length - 1] !== '') {
+    lines.push('');
+  }
+  lines.push(heading, '');
+  for (const warning of normalizedWarnings) {
+    lines.push(`- ${warning}`);
+  }
+  lines.push('');
+  return lines;
+}
+
+export function escapeMarkdownTableCell(value) {
+  return String(value).replace(/\|/g, '\\|');
+}

package/plugins/spec-driver/scripts/lib/script-report-io.mjs

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { stringifyYaml } from './simple-yaml.mjs';
+
+export function ensureArtifactDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+export function writeJsonArtifact(filePath, value) {
+  ensureArtifactDir(filePath);
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+
+export function writeMarkdownArtifact(filePath, content) {
+  ensureArtifactDir(filePath);
+  const text = content.endsWith('\n') ? content : `${content}\n`;
+  fs.writeFileSync(filePath, text, 'utf-8');
+}
+
+export function writeYamlArtifact(filePath, value) {
+  ensureArtifactDir(filePath);
+  const serialized = stringifyYaml(value);
+  const text = serialized.endsWith('\n') ? serialized : `${serialized}\n`;
+  fs.writeFileSync(filePath, text, 'utf-8');
+}
+
+export function readJsonArtifact(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}

package/plugins/spec-driver/scripts/lib/simple-yaml.mjs

@@ -0,0 +1,257 @@
+function stripYamlComment(rawLine) {
+  let inSingle = false;
+  let inDouble = false;
+  let result = '';
+  for (let index = 0; index < rawLine.length; index += 1) {
+    const char = rawLine[index];
+    if (char === "'" && !inDouble) {
+      inSingle = !inSingle;
+      result += char;
+      continue;
+    }
+    if (char === '"' && !inSingle) {
+      inDouble = !inDouble;
+      result += char;
+      continue;
+    }
+    if (char === '#' && !inSingle && !inDouble) {
+      break;
+    }
+    result += char;
+  }
+  return result;
+}
+
+function tokenizeYamlLines(content) {
+  const lines = [];
+  for (const rawLine of content.split('\n')) {
+    const withoutComment = stripYamlComment(rawLine);
+    if (withoutComment.trim() === '') {
+      continue;
+    }
+
+    lines.push({
+      indent: rawLine.match(/^\s*/)?.[0].length ?? 0,
+      text: withoutComment.trim(),
+    });
+  }
+  return lines;
+}
+
+function findYamlSeparator(text) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === "'" && !inDouble) {
+      inSingle = !inSingle;
+      continue;
+    }
+    if (char === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+    if (char === ':' && !inSingle && !inDouble) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function parseYamlScalar(rawValue) {
+  const trimmed = rawValue.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (trimmed === 'null') return null;
+  if (trimmed === '[]') return [];
+  if (trimmed === '{}') return {};
+  if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+  return trimmed;
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isScalar(value) {
+  return value === null || ['string', 'number', 'boolean'].includes(typeof value);
+}
+
+function parseYamlSequence(lines, state, indent) {
+  const result = [];
+
+  while (state.index < lines.length) {
+    const line = lines[state.index];
+    if (line.indent < indent) {
+      break;
+    }
+
+    if (line.indent !== indent || !line.text.startsWith('- ')) {
+      break;
+    }
+
+    state.index += 1;
+    const itemText = line.text.slice(2).trim();
+    if (itemText.length === 0) {
+      const next = lines[state.index];
+      if (!next || next.indent <= indent) {
+        result.push(null);
+        continue;
+      }
+      result.push(parseYamlBlock(lines, state, next.indent));
+      continue;
+    }
+
+    const separatorIndex = findYamlSeparator(itemText);
+    if (separatorIndex > 0) {
+      const key = itemText.slice(0, separatorIndex).trim();
+      const rawValue = itemText.slice(separatorIndex + 1).trim();
+      const entry = {};
+      if (rawValue.length > 0) {
+        entry[key] = parseYamlScalar(rawValue);
+      } else {
+        entry[key] = {};
+      }
+
+      const next = lines[state.index];
+      if (next && next.indent > indent) {
+        const nested = parseYamlBlock(lines, state, next.indent);
+        if (isObject(nested)) {
+          Object.assign(entry, nested);
+        } else if (Array.isArray(nested)) {
+          entry[key] = nested;
+        }
+      }
+
+      result.push(entry);
+      continue;
+    }
+
+    result.push(parseYamlScalar(itemText));
+  }
+
+  return result;
+}
+
+function parseYamlMapping(lines, state, indent) {
+  const result = {};
+
+  while (state.index < lines.length) {
+    const line = lines[state.index];
+    if (line.indent < indent) {
+      break;
+    }
+
+    if (line.indent > indent) {
+      state.index += 1;
+      continue;
+    }
+
+    if (line.text.startsWith('- ')) {
+      break;
+    }
+
+    state.index += 1;
+    const separatorIndex = findYamlSeparator(line.text);
+    if (separatorIndex < 0) {
+      continue;
+    }
+
+    const key = line.text.slice(0, separatorIndex).trim();
+    const rawValue = line.text.slice(separatorIndex + 1).trim();
+    if (rawValue.length > 0) {
+      result[key] = parseYamlScalar(rawValue);
+      continue;
+    }
+
+    const next = lines[state.index];
+    if (!next || next.indent <= indent) {
+      result[key] = {};
+      continue;
+    }
+
+    result[key] = parseYamlBlock(lines, state, next.indent);
+  }
+
+  return result;
+}
+
+function parseYamlBlock(lines, state, indent) {
+  if (state.index >= lines.length) {
+    return {};
+  }
+
+  const current = lines[state.index];
+  if (current.text.startsWith('- ')) {
+    return parseYamlSequence(lines, state, indent);
+  }
+
+  return parseYamlMapping(lines, state, indent);
+}
+
+export function parseYamlDocument(content) {
+  const lines = tokenizeYamlLines(content);
+  if (lines.length === 0) {
+    return {};
+  }
+
+  const state = { index: 0 };
+  const parsed = parseYamlBlock(lines, state, lines[0].indent);
+  return isObject(parsed) ? parsed : {};
+}
+
+function formatYamlScalar(value) {
+  if (value === null || value === undefined) {
+    return 'null';
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  return JSON.stringify(String(value));
+}
+
+export function stringifyYaml(value, indent = 0) {
+  if (isScalar(value)) {
+    return `${' '.repeat(indent)}${formatYamlScalar(value)}`;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return `${' '.repeat(indent)}[]`;
+    }
+
+    return value
+      .map((entry) => {
+        if (isScalar(entry)) {
+          return `${' '.repeat(indent)}- ${stringifyYaml(entry).trimStart()}`;
+        }
+
+        const rendered = stringifyYaml(entry, indent + 2).split('\n');
+        return [`${' '.repeat(indent)}- ${rendered[0].trimStart()}`, ...rendered.slice(1)].join('\n');
+      })
+      .join('\n');
+  }
+
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return `${' '.repeat(indent)}{}`;
+  }
+
+  return entries
+    .map(([key, entryValue]) => {
+      if (isScalar(entryValue)) {
+        return `${' '.repeat(indent)}${key}: ${stringifyYaml(entryValue).trimStart()}`;
+      }
+
+      return `${' '.repeat(indent)}${key}:\n${stringifyYaml(entryValue, indent + 2)}`;
+    })
+    .join('\n');
+}

package/plugins/spec-driver/scripts/lib/sync-conflict-resolver.mjs

@@ -0,0 +1,128 @@
+/**
+ * sync-conflict-resolver.mjs — 冲突解决模块
+ *
+ * 检测 MergeSkeleton 中同一 FR ID 的多个 active 版本，
+ * 以编号更大者（sourceSpec 更大）胜出。
+ * 所有导出函数均为纯函数（无副作用），返回新对象。
+ *
+ * @module sync-conflict-resolver
+ */
+
+// ────────────────────────────────────────────────────────────
+// 内部工具
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 深拷贝简单 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;
+}
+
+// ────────────────────────────────────────────────────────────
+// 导出函数
+// ────────────────────────────────────────────────────────────
+
+/**
+ * 解决 MergeSkeleton 中的 FR 冲突。
+ *
+ * 遍历所有章节的 functionalRequirements，检测同一 FR ID 是否存在多个 active 版本。
+ * 冲突解决规则：编号更大者（sourceSpec 数值更大）胜出保持 active，
+ * 编号更小者标记为 superseded。
+ *
+ * 纯函数：不修改输入的 skeleton 对象，返回新对象。
+ *
+ * @param {object} skeleton — MergeSkeleton
+ * @returns {{ skeleton: object, conflicts: Array<{ subject: string, winner: string, loser: string, reason: string }> }}
+ */
+export function resolveConflicts(skeleton) {
+  const result = deepClone(skeleton);
+  const conflicts = [];
+
+  // 遍历所有章节
+  for (const chapter of Object.values(result.chapters)) {
+    const frList = chapter.functionalRequirements;
+    if (frList.length === 0) {
+      continue;
+    }
+
+    // 按 FR ID 分组，找出有多个 active 版本的 FR
+    const activeByFrId = {};
+    for (let i = 0; i < frList.length; i += 1) {
+      const fr = frList[i];
+      if (fr.status !== 'active') {
+        continue;
+      }
+      if (!activeByFrId[fr.id]) {
+        activeByFrId[fr.id] = [];
+      }
+      activeByFrId[fr.id].push({ index: i, fr });
+    }
+
+    // 对有冲突的 FR 执行裁决
+    for (const [frId, entries] of Object.entries(activeByFrId)) {
+      if (entries.length <= 1) {
+        continue;
+      }
+
+      // 按 sourceSpec 编号降序排列，编号最大者胜出
+      entries.sort((a, b) => {
+        const numA = parseInt(a.fr.sourceSpec, 10) || 0;
+        const numB = parseInt(b.fr.sourceSpec, 10) || 0;
+        return numB - numA;
+      });
+
+      const winner = entries[0];
+      // 其余全部标记为 superseded
+      for (let i = 1; i < entries.length; i += 1) {
+        const loser = entries[i];
+        frList[loser.index].status = 'superseded';
+        frList[loser.index].supersededBy = winner.fr.sourceSpec;
+
+        conflicts.push({
+          subject: frId,
+          winner: winner.fr.sourceSpec,
+          loser: loser.fr.sourceSpec,
+          reason: `FR ${frId} 存在多个 active 版本，编号更大者 (${winner.fr.sourceSpec}) 优先`,
+        });
+      }
+    }
+  }
+
+  // 重新计算 mergeStats
+  let activeFRCount = 0;
+  let supersededFRCount = 0;
+  let deprecatedFRCount = 0;
+  let userStoryCount = 0;
+
+  for (const chapter of Object.values(result.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;
+  }
+
+  result.mergeStats = {
+    ...result.mergeStats,
+    activeFRCount,
+    supersededFRCount,
+    deprecatedFRCount,
+    userStoryCount,
+  };
+
+  return { skeleton: result, conflicts };
+}