spectra-cli 4.1.1

package/plugins/spec-driver/scripts/validate-config.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * validate-config.mjs -- spec-driver.config.yaml 校验和 effective config 展示的 CLI 入口
+ *
+ * 用法:
+ *   node validate-config.mjs --project-root <path> --validate
+ *   node validate-config.mjs --project-root <path> --show-effective [--preset <name>]
+ *
+ * 退出码:
+ *   0 - 校验通过 / effective config 展示成功
+ *   1 - Schema 校验失败
+ *   2 - YAML 语法错误
+ */
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseYamlDocument } from './lib/simple-yaml.mjs';
+import { validateConfig, resolveEffectiveConfig } from './lib/config-schema.mjs';
+
+// ────────────────────────────────────────
+// 参数解析
+// ────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {
+    projectRoot: process.cwd(),
+    mode: null, // 'validate' | 'show-effective'
+    preset: null,
+  };
+
+  for (let i = 2; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--project-root':
+        args.projectRoot = argv[++i] || process.cwd();
+        break;
+      case '--validate':
+        args.mode = 'validate';
+        break;
+      case '--show-effective':
+        args.mode = 'show-effective';
+        break;
+      case '--preset':
+        args.preset = argv[++i] || null;
+        break;
+      default:
+        break;
+    }
+  }
+  return args;
+}
+
+// ────────────────────────────────────────
+// 配置文件定位
+// ────────────────────────────────────────
+
+function findConfigFile(projectRoot) {
+  const primary = path.resolve(projectRoot, 'spec-driver.config.yaml');
+  if (existsSync(primary)) return primary;
+
+  const alt = path.resolve(projectRoot, '.specify', 'spec-driver.config.yaml');
+  if (existsSync(alt)) return alt;
+
+  return null;
+}
+
+// ────────────────────────────────────────
+// createCheck 输出格式
+// ────────────────────────────────────────
+
+function createCheck(id, label, status, detail) {
+  const check = { id, label, status, ...detail };
+  return check;
+}
+
+function printCheck(check) {
+  const icon = check.status === 'pass' ? '✅' : check.status === 'warn' ? '⚠️' : '❌';
+  console.log(`${icon} [${check.id}] ${check.label}: ${check.status}`);
+  if (check.diagnostics) {
+    for (const d of check.diagnostics) {
+      const prefix = d.level === 'warning' ? '  ⚠️ ' : '  ❌ ';
+      console.log(`${prefix}${d.message}`);
+    }
+  }
+}
+
+// ────────────────────────────────────────
+// --validate 模式
+// ────────────────────────────────────────
+
+function runValidate(projectRoot) {
+  const configPath = findConfigFile(projectRoot);
+
+  if (!configPath) {
+    // 配置文件不存在，视为合法（全用默认值）
+    printCheck(createCheck('config-schema', '配置文件 Schema 校验', 'pass', {
+      configPath: '(不存在，使用默认值)',
+      fieldCount: 0,
+    }));
+    process.exit(0);
+  }
+
+  // 检查空文件
+  const stat = statSync(configPath);
+  if (stat.size === 0) {
+    printCheck(createCheck('config-schema', '配置文件 Schema 校验', 'fail', {
+      configPath: path.relative(projectRoot, configPath),
+      errorCount: 1,
+      diagnostics: [
+        { level: 'error', code: 'config.empty-file', message: '配置文件为空，请参考模板填写' },
+      ],
+    }));
+    process.exit(2);
+  }
+
+  // YAML 解析阶段
+  let parsed;
+  try {
+    const content = readFileSync(configPath, 'utf8');
+    parsed = parseYamlDocument(content);
+  } catch (err) {
+    printCheck(createCheck('config-schema', '配置文件 Schema 校验', 'fail', {
+      configPath: path.relative(projectRoot, configPath),
+      errorCount: 1,
+      diagnostics: [
+        { level: 'error', code: 'config.yaml-syntax-error', message: `YAML 语法错误: ${err.message}` },
+      ],
+    }));
+    process.exit(2);
+  }
+
+  // Schema 校验阶段
+  const { success, diagnostics } = validateConfig(parsed);
+
+  const errors = diagnostics.filter((d) => d.level === 'error');
+  const warnings = diagnostics.filter((d) => d.level === 'warning');
+
+  if (errors.length > 0) {
+    printCheck(createCheck('config-schema', '配置文件 Schema 校验', 'fail', {
+      configPath: path.relative(projectRoot, configPath),
+      errorCount: errors.length,
+      diagnostics: errors,
+    }));
+    process.exit(1);
+  }
+
+  if (warnings.length > 0) {
+    printCheck(createCheck('config-schema', '配置文件 Schema 校验', 'warn', {
+      configPath: path.relative(projectRoot, configPath),
+      warningCount: warnings.length,
+      diagnostics: warnings,
+    }));
+    process.exit(0);
+  }
+
+  printCheck(createCheck('config-schema', '配置文件 Schema 校验', 'pass', {
+    configPath: path.relative(projectRoot, configPath),
+    fieldCount: (parsed && typeof parsed === 'object') ? Object.keys(parsed).length : 0,
+  }));
+  process.exit(0);
+}
+
+// ────────────────────────────────────────
+// --show-effective 模式
+// ────────────────────────────────────────
+
+function padRight(str, len) {
+  const s = String(str);
+  return s + ' '.repeat(Math.max(0, len - s.length));
+}
+
+function runShowEffective(projectRoot, presetOverride) {
+  const configPath = findConfigFile(projectRoot);
+  let configYaml = {};
+
+  if (configPath) {
+    try {
+      const content = readFileSync(configPath, 'utf8');
+      configYaml = parseYamlDocument(content);
+    } catch {
+      // 解析失败时用空对象
+      configYaml = {};
+    }
+  }
+
+  const entries = resolveEffectiveConfig({
+    configYaml,
+    presetOverride: presetOverride || undefined,
+  });
+
+  // 计算列宽
+  const colKey = Math.max(6, ...entries.map((e) => e.key.length)) + 2;
+  const colVal = Math.max(6, ...entries.map((e) => String(e.value).length)) + 2;
+  const colSrc = Math.max(4, ...entries.map((e) => e.source.length)) + 2;
+
+  // 输出 ASCII 表格
+  console.log('');
+  console.log('[Effective Config]');
+  const sep = `+-${'-'.repeat(colKey)}-+-${'-'.repeat(colVal)}-+-${'-'.repeat(colSrc)}-+`;
+  console.log(sep);
+  console.log(`| ${padRight('配置项', colKey)} | ${padRight('生效值', colVal)} | ${padRight('来源', colSrc)} |`);
+  console.log(sep);
+  for (const entry of entries) {
+    const val = Array.isArray(entry.value) ? JSON.stringify(entry.value) : String(entry.value);
+    console.log(`| ${padRight(entry.key, colKey)} | ${padRight(val, colVal)} | ${padRight(entry.source, colSrc)} |`);
+  }
+  console.log(sep);
+  console.log('');
+}
+
+// ────────────────────────────────────────
+// 主入口
+// ────────────────────────────────────────
+
+const args = parseArgs(process.argv);
+
+if (args.mode === 'validate') {
+  runValidate(args.projectRoot);
+} else if (args.mode === 'show-effective') {
+  runShowEffective(args.projectRoot, args.preset);
+} else {
+  console.error('用法: node validate-config.mjs --project-root <path> --validate|--show-effective [--preset <name>]');
+  process.exit(1);
+}

package/plugins/spec-driver/scripts/validate-orchestration-overrides.mjs

@@ -0,0 +1,190 @@
+/**
+ * validate-orchestration-overrides.mjs
+ * Feature 133 — 项目级 orchestration overrides 校验器
+ *
+ * 主导出：validateOrchestrationOverrides({ projectRoot })
+ * 返回值格式与 repo-maintenance-core.mjs 的 aggregateValidation 兼容：
+ *   { status: "ok" | "warning" | "error", checks: [], warnings: [], errors: [] }
+ *
+ * 其中 check 格式：{ id, title, status, evidence }
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveOrchestrationConfig } from '../lib/orchestration-resolver.mjs';
+
+/**
+ * 创建 check 对象（与 repo-maintenance-core.mjs 的 createCheck 格式一致）
+ * @param {string} id
+ * @param {string} title
+ * @param {'pass'|'warn'|'fail'} status
+ * @param {object} [evidence]
+ * @returns {{ id: string, title: string, status: string, evidence: object }}
+ */
+function createCheck(id, title, status, evidence = {}) {
+  return { id, title, status, evidence };
+}
+
+/**
+ * 校验项目级 orchestration overrides 配置。
+ *
+ * 校验内容：
+ *   1. overrides 文件是否存在（不存在则 skip，status=ok）
+ *   2. YAML 解析是否成功（parse-error → warning）
+ *   3. overrides Zod schema 校验（schema-fallback → warning）
+ *   4. version 是否与 base 一致（version-mismatch → warning）
+ *   5. 合并后 mergedConfig 防御性校验（base-invalid → error）
+ *   6. unsupported-field 检测（parallel_groups strip → warning）
+ *
+ * @param {{ projectRoot: string }} params
+ * @returns {Promise<{ status: "ok" | "warning" | "error", checks: object[], warnings: string[], errors: string[] }>}
+ */
+export async function validateOrchestrationOverrides({ projectRoot }) {
+  const checks = [];
+  const warnings = [];
+  const errors = [];
+
+  // 检查 overrides 文件是否存在
+  const overridesPath = path.join(projectRoot, '.specify', 'orchestration-overrides.yaml');
+  const overridesExists = fs.existsSync(overridesPath);
+
+  if (!overridesExists) {
+    // 不存在：skip，状态 ok（无 overrides 是合法状态）
+    checks.push(createCheck(
+      'overrides-file-exists',
+      'orchestration-overrides.yaml 文件存在性检查',
+      'pass',
+      { path: overridesPath, exists: false, note: '无 overrides 文件，使用 base 配置（正常）' },
+    ));
+    return { status: 'ok', checks, warnings, errors };
+  }
+
+  checks.push(createCheck(
+    'overrides-file-exists',
+    'orchestration-overrides.yaml 文件存在性检查',
+    'pass',
+    { path: overridesPath, exists: true },
+  ));
+
+  // 调用 resolver，获取完整校验结果（含所有降级路径）
+  let resolverResult;
+  try {
+    resolverResult = await resolveOrchestrationConfig({ projectRoot });
+  } catch (err) {
+    // resolver 本身抛异常（极罕见）
+    const msg = `resolver 调用异常：${err.message}`;
+    errors.push(msg);
+    checks.push(createCheck(
+      'overrides-resolver',
+      'orchestration overrides resolver 调用',
+      'fail',
+      { error: err.message },
+    ));
+    return { status: 'error', checks, warnings, errors };
+  }
+
+  const { diagnostics, isFallback, isBaseInvalid } = resolverResult;
+
+  // 根据 diagnostics 分类生成 checks / warnings / errors
+  for (const diag of diagnostics) {
+    switch (diag.code) {
+      case 'orchestration-overrides.parse-error': {
+        // YAML 解析失败 → error（文件存在但不可读，repo:check 应拦截；AC-009）
+        errors.push(`orchestration-overrides.yaml YAML 解析失败：${diag.message}`);
+        checks.push(createCheck(
+          'overrides-yaml-parse',
+          'orchestration-overrides.yaml YAML 语法解析',
+          'fail',
+          { code: diag.code, message: diag.message },
+        ));
+        break;
+      }
+      case 'orchestration-overrides.schema-fallback': {
+        // schema 校验失败 → error（无效 overrides 文件应被 repo:check 拦截；AC-009）
+        errors.push(`orchestration-overrides.yaml schema 校验失败：${diag.message}`);
+        checks.push(createCheck(
+          'overrides-schema-validation',
+          'orchestration-overrides.yaml Zod schema 校验',
+          'fail',
+          { code: diag.code, message: diag.message },
+        ));
+        break;
+      }
+      case 'orchestration-overrides.version-mismatch': {
+        // version 不一致 → error（overrides 文件与 base 不兼容，应被 repo:check 拦截）
+        errors.push(`orchestration-overrides.yaml version 不一致：${diag.message}`);
+        checks.push(createCheck(
+          'overrides-version-match',
+          'orchestration-overrides.yaml version 与 base 一致性',
+          'fail',
+          { code: diag.code, message: diag.message, context: diag.context },
+        ));
+        break;
+      }
+      case 'orchestration-overrides.unsupported-field': {
+        // unsupported 字段（parallel_groups strip）→ warning（非阻断性）
+        warnings.push(`orchestration-overrides.yaml 含不支持的字段：${diag.message}`);
+        checks.push(createCheck(
+          'overrides-unsupported-fields',
+          'orchestration-overrides.yaml 不支持字段检测',
+          'warn',
+          { code: diag.code, message: diag.message },
+        ));
+        break;
+      }
+      case 'orchestration.base-invalid': {
+        // base config 不可读或校验失败 → error
+        errors.push(`orchestration base 配置错误：${diag.message}`);
+        checks.push(createCheck(
+          'overrides-base-valid',
+          'orchestration base 配置有效性',
+          'fail',
+          { code: diag.code, message: diag.message },
+        ));
+        break;
+      }
+      case 'orchestration-overrides.mode-overridden': {
+        // 正常 info，不生成 check
+        break;
+      }
+      default: {
+        // 未知 diagnostic → 记录为 warning
+        warnings.push(`[unknown] ${diag.code}: ${diag.message}`);
+        break;
+      }
+    }
+  }
+
+  // 如果没有错误也没有警告来自 diagnostics，补充正常校验 check
+  const hasSchemaCheck = checks.some(c => c.id === 'overrides-schema-validation');
+  if (!hasSchemaCheck && !isBaseInvalid) {
+    checks.push(createCheck(
+      'overrides-schema-validation',
+      'orchestration-overrides.yaml Zod schema 校验',
+      'pass',
+      { isFallback, diagnosticCount: diagnostics.length },
+    ));
+  }
+
+  const hasVersionCheck = checks.some(c => c.id === 'overrides-version-match');
+  if (!hasVersionCheck && !isBaseInvalid) {
+    checks.push(createCheck(
+      'overrides-version-match',
+      'orchestration-overrides.yaml version 与 base 一致性',
+      'pass',
+      { note: '版本一致或无 version 字段' },
+    ));
+  }
+
+  // 判断整体状态
+  let status;
+  if (errors.length > 0) {
+    status = 'error';
+  } else if (warnings.length > 0) {
+    status = 'warning';
+  } else {
+    status = 'ok';
+  }
+
+  return { status, checks, warnings, errors };
+}