ccgx-workflow 2.3.1 → 2.4.1

package/templates/scripts/spec-suggestion.cjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// CCG Spec Suggestion CLI — RFC-9 F2 follow-up.
+//
+// Standalone Node CJS reimplementation of src/utils/spec-suggestion.ts. The
+// TS version lives in CCG's own dist and is great for the `ccgx-workflow`
+// package consumers; but `/ccg:spec-impl` runs in the USER's project, which
+// generally has no dependency on ccgx-workflow. The model can't `import` a
+// helper that isn't installed.
+//
+// installer.ts copies this file to ~/.claude/.ccg/scripts/spec-suggestion.cjs
+// (alongside check-plugins.cjs and friends). The spec-impl.md step calls:
+//
+//   node ~/.claude/.ccg/scripts/spec-suggestion.cjs \
+//     --diff <path-to-diff>   \
+//     --review <path-to-review-md> \
+//     --change-id <id>
+//
+// stdout = JSON array of candidates (same shape as TS SpecCandidate[]).
+// exit 0 = ran (including empty result).
+// exit 1 = bad args / read failure / internal error.
+//
+// Logic must stay in lockstep with src/utils/spec-suggestion.ts. The shared
+// test cases in __tests__/specSuggestionCjs.test.ts pin both implementations
+// against the same fixtures.
+
+'use strict';
+
+const fs = require('node:fs');
+
+// ─────────────────────────────────────────────────────────────────
+// Constants (must mirror spec-suggestion.ts)
+// ─────────────────────────────────────────────────────────────────
+const MIN_RATIONALE_CHARS = 40;
+const MAX_STATEMENT_CHARS = 200;
+
+const FILLER_PHRASES = [
+  '写好的代码',
+  '注意安全',
+  '小心',
+  '保持代码整洁',
+  '遵循最佳实践',
+  '请仔细审查',
+  'best practice',
+  'be careful',
+  'write good code',
+  'clean code',
+  'follow best practices',
+];
+
+const SPECIFIC_REFERENCE_PATTERN = /(?:[a-zA-Z0-9_-]+\.[a-zA-Z]{1,8}\b|\w+\/\w+|\b[A-Z][a-zA-Z0-9]{2,}\b|`[^`]+`)/;
+
+const CATEGORY_HINTS = [
+  { kw: /\b(api|endpoint|route|router|middleware|jwt|oauth|session|cookie|sql|schema|migration|database|orm|prisma|drizzle|knex|graphql|grpc|kafka|redis)\b/i, category: 'backend' },
+  { kw: /\b(component|hook|jsx|tsx|css|tailwind|store|reducer|redux|zustand|pinia|router\.(get|push)|route|svelte|vue|react)\b/i, category: 'frontend' },
+  { kw: /(?:认证|授权|加密|后端|接口|数据库|迁移)/, category: 'backend' },
+  { kw: /(?:前端|组件|页面|样式|交互|路由跳转)/, category: 'frontend' },
+];
+
+// ─────────────────────────────────────────────────────────────────
+// Pure helpers
+// ─────────────────────────────────────────────────────────────────
+
+function categorizeStatement(statement, rationale) {
+  const haystack = `${statement} ${rationale}`;
+  for (const hint of CATEGORY_HINTS) {
+    if (hint.kw.test(haystack)) return hint.category;
+  }
+  return 'cross-cutting';
+}
+
+function checkQuality(statement, rationale) {
+  if (!statement || statement.length < 10) return 'statement too short (< 10 chars)';
+  if (statement.length > MAX_STATEMENT_CHARS) return `statement too long (> ${MAX_STATEMENT_CHARS} chars) — break it down`;
+  if (rationale.length < MIN_RATIONALE_CHARS) return `rationale too thin (< ${MIN_RATIONALE_CHARS} chars) — explain *why*`;
+  const lower = `${statement} ${rationale}`.toLowerCase();
+  for (const filler of FILLER_PHRASES) {
+    if (lower.includes(filler.toLowerCase())) return `filler phrase detected: "${filler}"`;
+  }
+  if (!SPECIFIC_REFERENCE_PATTERN.test(`${statement} ${rationale}`)) {
+    return 'no specific file / API / command reference — add a concrete anchor';
+  }
+  return undefined;
+}
+
+function extractFromReview(reviewMd) {
+  const out = [];
+  const findingRe = /^[#\-*\s]*(?:Finding\s+)?[CW]-?\d+\b[^\n]*(?:Critical|Warning|critical|warning)[^\n]*$/gm;
+  let match;
+  while ((match = findingRe.exec(reviewMd)) !== null) {
+    const start = match.index;
+    const tail = reviewMd.slice(start, start + 1200);
+    const lines = tail.split('\n').slice(0, 12);
+    const header = lines[0].trim();
+    const body = lines.slice(1).join(' ').replace(/\s+/g, ' ').trim();
+    const sugMatch = body.match(/(?:建议[：:]|Suggested(?:\s+fix)?[：:]|应当?[：:]|Must[：:]|Should[：:])\s*([^\.。;；]+)/i);
+    const statement = (sugMatch && sugMatch[1] ? sugMatch[1] : header).slice(0, MAX_STATEMENT_CHARS).trim();
+    const rationale = body.slice(0, 400).trim();
+    const category = categorizeStatement(statement, rationale);
+    out.push({
+      statement,
+      rationale,
+      source: { kind: 'review', excerpt: header },
+      category,
+      rejectionReason: checkQuality(statement, rationale),
+    });
+  }
+  return out;
+}
+
+function extractFromDiff(gitDiff) {
+  const out = [];
+  const lines = gitDiff.split('\n');
+  let currentFile = '';
+  const fileRe = /^\+\+\+ b\/(.+)$/;
+  const constraintRe = /^\+\s*(?:\/\/|#|--|\*)\s*(?:MUST|必须|invariant|约束|不变量|注意[:：])\s*(.+)/i;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fm = line.match(fileRe);
+    if (fm) {
+      currentFile = fm[1];
+      continue;
+    }
+    const cm = line.match(constraintRe);
+    if (!cm) continue;
+    const statement = cm[1].trim().slice(0, MAX_STATEMENT_CHARS);
+    const context = lines.slice(Math.max(0, i - 3), Math.min(lines.length, i + 4))
+      .map(l => l.replace(/^[+\-]\s?/, ''))
+      .join('\n').slice(0, 400);
+    const rationale = `In ${currentFile}: ${context}`.slice(0, 400);
+    const category = categorizeStatement(statement, rationale);
+    out.push({
+      statement,
+      rationale,
+      source: { kind: 'diff', excerpt: `${currentFile} (${cm[0].slice(0, 80)}...)` },
+      category,
+      rejectionReason: checkQuality(statement, rationale),
+    });
+  }
+  return out;
+}
+
+function dedupeByStatement(candidates) {
+  const seen = new Set();
+  const out = [];
+  for (const c of candidates) {
+    const key = c.statement.toLowerCase().replace(/\s+/g, ' ').trim();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(c);
+  }
+  return out;
+}
+
+function extractCandidates(input) {
+  const out = [];
+  if (input.reviewMd) out.push(...extractFromReview(input.reviewMd));
+  if (input.gitDiff) out.push(...extractFromDiff(input.gitDiff));
+  return dedupeByStatement(out);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────────────────────────────
+
+const MAX_INPUT_BYTES = 5 * 1024 * 1024; // 5MB cap per input file
+
+function readBoundedFile(path) {
+  // Defensive: a 1GB diff file would otherwise blow process memory. Real diffs
+  // for a single change rarely exceed 200KB; 5MB is generous.
+  try {
+    const stat = fs.statSync(path);
+    if (!stat.isFile()) return null;
+    if (stat.size > MAX_INPUT_BYTES) {
+      process.stderr.write(`spec-suggestion: ${path} exceeds ${MAX_INPUT_BYTES} bytes (${stat.size}) — refusing\n`);
+      return null;
+    }
+    return fs.readFileSync(path, 'utf-8');
+  }
+  catch (err) {
+    process.stderr.write(`spec-suggestion: cannot read ${path}: ${err.message}\n`);
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  // Minimal flag parser — keep deps zero. Recognized:
+  //   --diff <path>        path to git diff file
+  //   --review <path>      path to REVIEW.md
+  //   --change-id <id>     optional change identifier (passed through, not used)
+  //   --help               print usage
+  const out = { diff: null, review: null, changeId: null, help: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+    }
+    else if (a === '--diff' && i + 1 < argv.length) {
+      out.diff = argv[++i];
+    }
+    else if (a === '--review' && i + 1 < argv.length) {
+      out.review = argv[++i];
+    }
+    else if (a === '--change-id' && i + 1 < argv.length) {
+      out.changeId = argv[++i];
+    }
+    else {
+      process.stderr.write(`spec-suggestion: unknown arg: ${a}\n`);
+      out.help = true;
+    }
+  }
+  return out;
+}
+
+function printUsage() {
+  process.stderr.write([
+    'Usage: node spec-suggestion.cjs --diff <path> --review <path> [--change-id <id>]',
+    '',
+    'Extracts spec-evolution candidates from a git diff + REVIEW.md and prints',
+    'a JSON array to stdout. Used by /ccg:spec-impl Step 10 (RFC-9).',
+    '',
+    'At least one of --diff or --review must be provided.',
+  ].join('\n') + '\n');
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help || (!args.diff && !args.review)) {
+    printUsage();
+    return 1;
+  }
+
+  const gitDiff = args.diff ? readBoundedFile(args.diff) : '';
+  const reviewMd = args.review ? readBoundedFile(args.review) : '';
+
+  // If both paths were given but neither readable, fail loud. If only one was
+  // given and unreadable, also fail (the user expected it to be there).
+  if (args.diff && gitDiff === null) return 1;
+  if (args.review && reviewMd === null) return 1;
+
+  const candidates = extractCandidates({
+    gitDiff: gitDiff || undefined,
+    reviewMd: reviewMd || undefined,
+    changeId: args.changeId || undefined,
+  });
+
+  process.stdout.write(JSON.stringify(candidates, null, 2) + '\n');
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = {
+  extractCandidates,
+  extractFromReview,
+  extractFromDiff,
+  categorizeStatement,
+  checkQuality,
+  dedupeByStatement,
+  parseArgs,
+  main,
+  MIN_RATIONALE_CHARS,
+  MAX_STATEMENT_CHARS,
+  MAX_INPUT_BYTES,
+};