spectra-cli 4.1.1

package/plugins/spec-driver/scripts/generate-product-entity-catalog.mjs

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  getCatalogIndexPath,
+  getLegacyProductQualityReportJsonPath,
+  getProductCurrentSpecPath,
+  getProductEntityPath,
+  getProductQualityReportJsonPath,
+  getProductsRoot,
+  toRelativePosix,
+} from './lib/product-artifact-paths.mjs';
+import { readJsonArtifact, writeYamlArtifact } from './lib/script-report-io.mjs';
+import { parseYamlDocument } from './lib/simple-yaml.mjs';
+
+const DEFAULT_KIND = 'product';
+const DEFAULT_OWNER = 'unknown';
+const DEFAULT_LIFECYCLE = 'unknown';
+const ENTITY_SCHEMA_VERSION = 1;
+
+const WORKFLOW_REFS_BY_PRODUCT = {
+  'spectra': [
+    'spectra.init',
+    'spectra.generate',
+    'spectra.batch',
+    'spectra.diff',
+    'spectra.mcp-server',
+    'spectra.auth-status',
+  ],
+  'spec-driver': [
+    'spec-driver-feature',
+    'spec-driver-implement',
+    'spec-driver-story',
+    'spec-driver-fix',
+    'spec-driver-resume',
+    'spec-driver-sync',
+    'spec-driver-doc',
+  ],
+};
+
+function parseArgs(argv) {
+  const args = {
+    projectRoot: process.cwd(),
+    json: false,
+  };
+
+  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;
+}
+
+export function generateProductEntityCatalog(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+  const generatedAt = new Date().toISOString();
+  const productsRoot = getProductsRoot(projectRoot);
+  const mappingPath = path.join(productsRoot, 'product-mapping.yaml');
+
+  if (!fs.existsSync(mappingPath)) {
+    throw new Error(`未找到 product mapping: ${mappingPath}`);
+  }
+
+  const mapping = parseProductMapping(fs.readFileSync(mappingPath, 'utf-8'));
+  const repoMeta = detectRepoMetadata(projectRoot);
+  const entities = [];
+  const warnings = [];
+
+  for (const [productId, productDef] of Object.entries(mapping.products)) {
+    const currentSpecPath = getProductCurrentSpecPath(projectRoot, productId);
+    const currentSpecRelPath = toRelativePosix(projectRoot, currentSpecPath);
+    const entityPath = getProductEntityPath(projectRoot, productId);
+    const entityRelPath = toRelativePosix(projectRoot, entityPath);
+
+    const currentSpecMeta = fs.existsSync(currentSpecPath)
+      ? parseCurrentSpec(fs.readFileSync(currentSpecPath, 'utf-8'))
+      : null;
+
+    if (!currentSpecMeta) {
+      warnings.push(`缺少 current-spec.md: ${currentSpecRelPath}`);
+    }
+
+    const qualityReportInfo = detectQualityReport(projectRoot, productId);
+    const lifecycle = inferLifecycle(currentSpecMeta?.statusRaw);
+    const kind = inferKind(productId, productDef.description, currentSpecMeta);
+    const name = inferProductName(productId, currentSpecMeta);
+    const readmeRelPath = fs.existsSync(path.join(projectRoot, 'README.md')) ? 'README.md' : null;
+
+    const entityDoc = {
+      schemaVersion: ENTITY_SCHEMA_VERSION,
+      generatedAt,
+      id: productId,
+      name,
+      kind,
+      description: productDef.description ?? '[待补充]',
+      owner: {
+        value: DEFAULT_OWNER,
+        source: 'unknown',
+      },
+      lifecycle: {
+        value: lifecycle.value,
+        source: lifecycle.source,
+      },
+      repo: {
+        path: '.',
+        remote: repoMeta.remote ?? null,
+        defaultBranch: repoMeta.defaultBranch ?? null,
+        packageName: repoMeta.packageName ?? null,
+      },
+      docs: compactArray([
+        {
+          id: 'current-spec',
+          kind: 'fact',
+          path: currentSpecRelPath,
+          available: Boolean(currentSpecMeta),
+        },
+        readmeRelPath
+          ? {
+              id: 'readme',
+              kind: 'readme',
+              path: readmeRelPath,
+              available: true,
+            }
+          : null,
+      ]),
+      quality: {
+        currentSpec: {
+          version: currentSpecMeta?.version ?? null,
+          lastAggregated: currentSpecMeta?.lastAggregated ?? null,
+          status: currentSpecMeta?.statusRaw ?? DEFAULT_LIFECYCLE,
+        },
+        report: {
+          path: qualityReportInfo.path,
+          status: qualityReportInfo.status,
+        },
+      },
+      workflowRefs: inferWorkflowRefs(productId),
+      sourceRefs: compactArray([
+        {
+          kind: 'product-mapping',
+          path: toPosix(path.relative(projectRoot, mappingPath)),
+        },
+        {
+          kind: 'current-spec',
+          path: currentSpecRelPath,
+          available: Boolean(currentSpecMeta),
+        },
+        readmeRelPath
+          ? {
+              kind: 'readme',
+              path: readmeRelPath,
+            }
+          : null,
+        qualityReportInfo.path
+          ? {
+              kind: 'quality-report',
+              path: qualityReportInfo.path,
+            }
+          : null,
+      ]),
+    };
+
+    writeYamlArtifact(entityPath, entityDoc);
+
+    entities.push({
+      id: productId,
+      name,
+      kind,
+      lifecycle: lifecycle.value,
+      owner: DEFAULT_OWNER,
+      entityPath: entityRelPath,
+      currentSpecPath: currentSpecRelPath,
+      workflowRefCount: entityDoc.workflowRefs.length,
+      qualityStatus: qualityReportInfo.status,
+      specCount: productDef.specs.length,
+    });
+  }
+
+  const catalogIndex = {
+    schemaVersion: ENTITY_SCHEMA_VERSION,
+    generatedAt,
+    productCount: entities.length,
+    products: entities,
+  };
+
+  const catalogIndexPath = getCatalogIndexPath(projectRoot);
+  writeYamlArtifact(catalogIndexPath, catalogIndex);
+
+  return {
+    projectRoot,
+    generatedAt,
+    catalogIndexPath: toRelativePosix(projectRoot, catalogIndexPath),
+    entities,
+    warnings,
+  };
+}
+
+function compactArray(items) {
+  return items.filter(Boolean);
+}
+
+function parseProductMapping(content) {
+  const document = parseYamlDocument(content);
+  const rawProducts = isObject(document.products) ? document.products : {};
+  const products = {};
+
+  for (const [productId, rawProduct] of Object.entries(rawProducts)) {
+    const product = isObject(rawProduct) ? rawProduct : {};
+    products[productId] = {
+      description: typeof product.description === 'string' ? product.description : '',
+      specs: Array.isArray(product.specs)
+        ? product.specs
+            .filter((entry) => isObject(entry) && typeof entry.id === 'string')
+            .map((entry) => ({
+              id: entry.id,
+              type: typeof entry.type === 'string' ? entry.type : '',
+              summary: typeof entry.summary === 'string' ? entry.summary : '',
+            }))
+        : [],
+    };
+  }
+
+  return { products };
+}
+
+function parseCurrentSpec(content) {
+  return {
+    title: matchMarkdownHeading(content),
+    product: matchMeta(content, '产品'),
+    version: matchMeta(content, '版本'),
+    lastAggregated: matchMeta(content, '最后聚合'),
+    statusRaw: matchMeta(content, '状态'),
+    overview: extractSectionParagraph(content, '1. 产品概述'),
+  };
+}
+
+function matchMarkdownHeading(content) {
+  const match = /^#\s+(.+?)\s*$/m.exec(content);
+  return match ? match[1].trim() : null;
+}
+
+function matchMeta(content, label) {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`^> \\*\\*${escaped}\\*\\*: (.+)$`, 'm').exec(content);
+  return match ? match[1].trim() : null;
+}
+
+function extractSectionParagraph(content, headingTitle) {
+  const escaped = headingTitle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`^## ${escaped}\\s*$([\\s\\S]*?)(?=^##\\s|\\Z)`, 'm').exec(content);
+  if (!match) {
+    return null;
+  }
+
+  const lines = match[1]
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  if (lines.length === 0) {
+    return null;
+  }
+
+  const paragraph = [];
+  for (const line of lines) {
+    if (line.startsWith('|') || /^\d+\./.test(line) || line.startsWith('- ')) {
+      break;
+    }
+    paragraph.push(line);
+  }
+
+  return paragraph.length > 0 ? paragraph.join(' ') : lines[0];
+}
+
+function inferProductName(productId, currentSpecMeta) {
+  if (currentSpecMeta?.title) {
+    return currentSpecMeta.title.replace(/\s+—\s+产品规范活文档$/, '').trim();
+  }
+
+  if (currentSpecMeta?.product) {
+    return slugToTitle(currentSpecMeta.product);
+  }
+
+  return slugToTitle(productId);
+}
+
+function inferKind(productId, description, currentSpecMeta) {
+  const corpus = `${productId} ${description ?? ''} ${currentSpecMeta?.overview ?? ''}`.toLowerCase();
+
+  if (productId === 'spec-driver' || corpus.includes('编排器 plugin')) {
+    return 'plugin';
+  }
+
+  if (productId === 'spectra' || corpus.includes('mcp') || corpus.includes('cli') || corpus.includes('tool')) {
+    return 'library-tooling';
+  }
+
+  return DEFAULT_KIND;
+}
+
+function inferLifecycle(rawStatus) {
+  if (!rawStatus) {
+    return {
+      value: DEFAULT_LIFECYCLE,
+      source: 'unknown',
+    };
+  }
+
+  const normalized = rawStatus.toLowerCase();
+  if (normalized.includes('活跃') || normalized.includes('active')) {
+    return {
+      value: 'active',
+      source: 'inferred:current-spec.status',
+    };
+  }
+
+  if (normalized.includes('草稿') || normalized.includes('draft')) {
+    return {
+      value: 'draft',
+      source: 'inferred:current-spec.status',
+    };
+  }
+
+  if (normalized.includes('废弃') || normalized.includes('deprecated') || normalized.includes('archive')) {
+    return {
+      value: 'deprecated',
+      source: 'inferred:current-spec.status',
+    };
+  }
+
+  return {
+    value: DEFAULT_LIFECYCLE,
+    source: 'unknown',
+  };
+}
+
+function inferWorkflowRefs(productId) {
+  if (productId !== 'spec-driver') {
+    return WORKFLOW_REFS_BY_PRODUCT[productId] ? [...WORKFLOW_REFS_BY_PRODUCT[productId]] : [];
+  }
+
+  const workflowDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'workflows');
+  if (!fs.existsSync(workflowDir)) {
+    return [...WORKFLOW_REFS_BY_PRODUCT['spec-driver']];
+  }
+
+  const refs = fs.readdirSync(workflowDir)
+    .filter((fileName) => fileName.endsWith('.yaml') && fileName !== 'golden-paths.yaml')
+    .map((fileName) => path.basename(fileName, '.yaml'))
+    .sort((left, right) => left.localeCompare(right));
+
+  return refs.length > 0 ? refs : [...WORKFLOW_REFS_BY_PRODUCT['spec-driver']];
+}
+
+function detectRepoMetadata(projectRoot) {
+  let remote = null;
+  let defaultBranch = null;
+
+  try {
+    remote = execFileSync('git', ['config', '--get', 'remote.origin.url'], {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    remote = null;
+  }
+
+  try {
+    defaultBranch = execFileSync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim().split('/').pop() || null;
+  } catch {
+    defaultBranch = null;
+  }
+
+  let packageName = null;
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      packageName = typeof packageJson.name === 'string' ? packageJson.name : null;
+    } catch {
+      packageName = null;
+    }
+  }
+
+  return {
+    remote,
+    defaultBranch,
+    packageName,
+  };
+}
+
+function detectQualityReport(projectRoot, productId) {
+  const candidates = [
+    getProductQualityReportJsonPath(projectRoot, productId),
+    getLegacyProductQualityReportJsonPath(projectRoot, productId),
+    path.join(projectRoot, 'specs', 'quality-report.json'),
+  ];
+
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+
+    const payload = readJsonArtifact(candidate);
+    return {
+      path: toRelativePosix(projectRoot, candidate),
+      status: typeof payload?.status === 'string' ? payload.status : 'available',
+    };
+  }
+
+  return {
+    path: null,
+    status: 'unavailable',
+  };
+}
+
+function slugToTitle(value) {
+  return value
+    .split('-')
+    .map((segment) => segment ? segment[0].toUpperCase() + segment.slice(1) : segment)
+    .join(' ');
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toPosix(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function printResult(result, asJson) {
+  if (asJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(
+    [
+      'Spec Driver Product Entity Catalog',
+      `项目根目录: ${result.projectRoot}`,
+      `Catalog 索引: ${result.catalogIndexPath}`,
+      `产品数: ${result.entities.length}`,
+      ...result.entities.map((entity) => `- ${entity.id}: ${entity.entityPath} (${entity.kind}, workflows=${entity.workflowRefCount})`),
+      ...(result.warnings.length > 0 ? ['Warnings:', ...result.warnings.map((warning) => `  - ${warning}`)] : []),
+    ].join('\n') + '\n',
+  );
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = parseArgs(process.argv.slice(2));
+  const result = generateProductEntityCatalog(args);
+  printResult(result, args.json);
+}

package/plugins/spec-driver/scripts/generate-product-quality-reports.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { parseCommonProjectArgs } from './lib/script-cli-args.mjs';
+import { generateProductQualityReports } from './lib/product-quality-core.mjs';
+
+export { generateProductQualityReports } from './lib/product-quality-core.mjs';
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = parseCommonProjectArgs(process.argv.slice(2));
+  const result = generateProductQualityReports(args);
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`已生成 ${result.products.length} 份产品 quality report\n`);
+  }
+}

package/plugins/spec-driver/scripts/generate-product-scorecards.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { parseCommonProjectArgs } from './lib/script-cli-args.mjs';
+import { generateProductScorecards } from './lib/product-scorecard-core.mjs';
+
+export { generateProductScorecards } from './lib/product-scorecard-core.mjs';
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = parseCommonProjectArgs(process.argv.slice(2));
+  const result = generateProductScorecards({
+    projectRoot: args.projectRoot,
+  });
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      [
+        `✓ 生成 scorecard index: ${result.scorecardIndexPath}`,
+        ...result.products.map((product) => `  - ${product.id}: ${product.markdownPath} (${product.status}, ${product.score}/100)`),
+      ].join('\n') + '\n',
+    );
+  }
+}