@haposoft/cafekit 0.15.1 → 0.16.0-rc.1

package/src/claude/scripts/spec-ground.cjs

@@ -2,40 +2,31 @@
 /**
  * CafeKit spec GROUNDING checker (Specs v2, Layer 2).
  *
- * The deterministic validator (`validate-spec-output.cjs`) checks spec SHAPE
- * (headings, registry sync, coverage). It is blind to whether the file paths a
- * task cites actually EXIST. This script closes that gap: it parses every task's
- * `Related Files` table and verifies, against the real work tree, that each
- * Modify/Delete/Read path exists — unless another task in the same spec Creates
- * it first (intra-spec resolution).
- *
- * Why active-grep instead of opt-in: field tests showed opt-in checks get
- * skipped by the author. Grounding runs unconditionally over whatever paths the
- * tasks already declare, so it cannot be dodged by choosing a different format.
- *
- * Usage:
- *   node spec-ground.cjs <specDir> [--root <work-context>]
- *
- * <specDir>  : path to specs/<feature>  (relative or absolute)
- * --root     : work tree the paths resolve against. Default: two levels up from
- *              specDir (…/<root>/specs/<feature> -> <root>). Override for
- *              monorepos where the spec lives apart from the code.
- *
- * Exit: 0 = GROUNDED, 1 = FAIL (missing path), 2 = usage error.
+ * Verifies every task Related Files declaration against the real work tree.
+ * Paths are relative, actions are explicit, and globs must match at least one
+ * filesystem entry. Create on existing paths is an error. Lifecycle ordering
+ * (Create before Modify/Delete/Read) is enforced within task and via
+ * dependency DAG for cross-task references; cross-task producer/consumer
+ * requires a valid spec.json task_registry (fail-closed).
  */
 
 const fs = require('fs');
 const path = require('path');
 
+const ACTIONS = new Set(['create', 'modify', 'delete', 'read']);
+
 function usage() {
   console.error('Usage: node spec-ground.cjs <specDir> [--root <work-context>]');
 }
 
 function parseArgs(argv) {
   const args = { specDir: null, root: null };
-  for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === '--root') args.root = argv[++i];
-    else if (!args.specDir) args.specDir = argv[i];
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--root') {
+      args.root = argv[++i];
+      if (!args.root) throw new Error('--root requires a value');
+    } else if (!args.specDir) args.specDir = argv[i];
+    else throw new Error(`Unknown argument: ${argv[i]}`);
   }
   return args;
 }
@@ -45,102 +36,217 @@ function listTaskFiles(specDir) {
   if (!fs.existsSync(tasksDir)) return [];
   return fs
     .readdirSync(tasksDir, { withFileTypes: true })
-    .filter((e) => e.isFile() && e.name.endsWith('.md'))
-    .map((e) => path.join(tasksDir, e.name))
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => path.join(tasksDir, entry.name))
     .sort();
 }
 
-/**
- * Pull rows out of a markdown `## Related Files` table. Returns
- * [{ path, action, taskFile }]. Tables look like:
- *   | Path | Action | Description |
- *   | `front/x.vue` | Modify | ... |
- */
 function parseRelatedFiles(content, taskFile) {
-  const rows = [];
   const lines = content.split('\n');
-  let inSection = false;
-  for (const line of lines) {
-    if (/^##+\s+Related Files\s*$/i.test(line)) { inSection = true; continue; }
-    if (inSection && /^##+\s+/.test(line)) break; // next heading ends section
-    if (!inSection) continue;
+  const headingIndex = lines.findIndex((line) => /^##+\s+Related Files\s*$/i.test(line));
+  if (headingIndex < 0) return { present: false, rows: [] };
+
+  const rows = [];
+  for (let index = headingIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^##+\s+/.test(line)) break;
     if (!line.trim().startsWith('|')) continue;
+    const cells = line.split('|').map((cell) => cell.trim());
+    const filePath = (cells[1] || '').replace(/`/g, '').trim();
+    const action = (cells[2] || '').replace(/`/g, '').trim().toLowerCase();
+    if (!filePath || filePath.toLowerCase() === 'path' || /^-+$/.test(filePath)) continue;
+    rows.push({ path: filePath, action, taskFile: path.basename(taskFile) });
+  }
+  return { present: true, rows };
+}
+
+function unsafePath(filePath) {
+  return path.isAbsolute(filePath)
+    || /^[A-Za-z]:[\\/]/.test(filePath)
+    || filePath.split(/[\\/]+/).includes('..');
+}
+
+function expandBraces(pattern) {
+  const match = pattern.match(/\{([^{}]*)\}/);
+  if (!match) return [pattern];
+  return match[1].split(',').flatMap((part) => expandBraces(
+    `${pattern.slice(0, match.index)}${part}${pattern.slice(match.index + match[0].length)}`,
+  ));
+}
 
-    const cells = line.split('|').map((c) => c.trim());
-    // cells[0] is '' (leading pipe). path=cells[1], action=cells[2].
-    const rawPath = (cells[1] || '').replace(/`/g, '').trim();
-    const action = (cells[2] || '').toLowerCase().trim();
-    if (!rawPath || rawPath === 'path') continue;          // header row
-    if (/^-+$/.test(rawPath)) continue;                    // separator row
-    if (!action || !/(create|modify|delete|read)/.test(action)) continue;
-    rows.push({ path: rawPath, action, taskFile: path.basename(taskFile) });
+function globRegExp(pattern) {
+  let source = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === '*') {
+      if (pattern[index + 1] === '*') {
+        index += 1;
+        if (pattern[index + 1] === '/') index += 1;
+        source += '.*';
+      } else source += '[^/]*';
+    } else if (char === '?') source += '[^/]';
+    else source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
   }
-  return rows;
+  return new RegExp(`${source}$`);
 }
 
-/** Lenient existence check with minimal glob handling. */
-function pathExists(root, p) {
-  // Glob-ish path (e.g. `assets/{x,instagram,facebook}.svg` or `dir/*.ts`):
-  // verify the parent directory exists rather than the literal name.
-  if (/[{*]/.test(p)) {
-    const parent = path.dirname(p.replace(/\{.*$/, '').replace(/\*.*$/, ''));
-    return fs.existsSync(path.join(root, parent));
+function relativeEntries(root) {
+  const entries = [];
+  function walk(current, relative) {
+    let children;
+    try { children = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of children) {
+      const nextRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      const next = path.join(current, entry.name);
+      entries.push(nextRelative);
+      if (entry.isDirectory() && !entry.isSymbolicLink()) walk(next, nextRelative);
+    }
   }
-  return fs.existsSync(path.join(root, p));
+  walk(root, '');
+  return entries;
+}
+
+function matchingEntries(root, filePath) {
+  if (!/[{}*?]/.test(filePath)) return fs.existsSync(path.join(root, filePath)) ? [filePath] : [];
+  const candidates = relativeEntries(root);
+  const matches = new Set();
+  for (const expanded of expandBraces(filePath)) {
+    const matcher = globRegExp(expanded.replaceAll('\\', '/'));
+    for (const candidate of candidates) if (matcher.test(candidate)) matches.add(candidate);
+  }
+  return [...matches];
 }
 
 function main() {
-  const { specDir: specInput, root: rootInput } = parseArgs(process.argv);
-  if (!specInput) { usage(); process.exit(2); }
+  let args;
+  try { args = parseArgs(process.argv); } catch (error) {
+    usage();
+    console.error(`- ${error.message}`);
+    process.exit(2);
+  }
+  if (!args.specDir) { usage(); process.exit(2); }
 
-  const specDir = path.resolve(process.cwd(), specInput);
+  const specDir = path.resolve(process.cwd(), args.specDir);
   if (!fs.existsSync(specDir)) {
-    console.error(`FAIL ${specInput}\n- spec directory does not exist`);
+    console.error(`FAIL ${args.specDir}\n- spec directory does not exist`);
     process.exit(1);
   }
-  // Default work-context: two levels up (…/<root>/specs/<feature>).
-  const root = rootInput
-    ? path.resolve(process.cwd(), rootInput)
+  const root = args.root
+    ? path.resolve(process.cwd(), args.root)
     : path.resolve(specDir, '..', '..');
 
   const taskFiles = listTaskFiles(specDir);
   const allRows = [];
-  for (const tf of taskFiles) {
-    allRows.push(...parseRelatedFiles(fs.readFileSync(tf, 'utf8'), tf));
+  const rowsByTask = new Map();
+  const errors = [];
+  const warnings = [];
+  for (const taskFile of taskFiles) {
+    const section = parseRelatedFiles(fs.readFileSync(taskFile, 'utf8'), taskFile);
+    const basename = path.basename(taskFile);
+    if (!rowsByTask.has(basename)) rowsByTask.set(basename, []);
+    if (!section.present) errors.push(`${basename}: missing Related Files section`);
+    else if (section.rows.length === 0) errors.push(`${basename}: Related Files section must not be empty`);
+    for (const row of section.rows) {
+      if (!ACTIONS.has(row.action)) errors.push(`${row.taskFile}: unsupported Related Files action "${row.action}" for ${row.path}`);
+      if (unsafePath(row.path)) errors.push(`${row.taskFile}: Related Files path must be relative and stay within work root: ${row.path}`);
+      allRows.push(row);
+      rowsByTask.get(basename).push(row);
+    }
   }
 
-  // Paths that will exist because a task Creates them (intra-spec resolution).
-  const createdPaths = new Set(
-    allRows.filter((r) => r.action.includes('create')).map((r) => r.path),
-  );
+  // Lifecycle ordering: Create must precede Modify/Delete/Read within same task
+  for (const [taskFile, rows] of rowsByTask.entries()) {
+    const createIndexByPath = new Map();
+    rows.forEach((row, idx) => {
+      if (row.action === 'create' && !createIndexByPath.has(row.path)) createIndexByPath.set(row.path, idx);
+    });
+    rows.forEach((row, idx) => {
+      if (!['modify', 'delete', 'read'].includes(row.action)) return;
+      if (!createIndexByPath.has(row.path)) return;
+      const createIdx = createIndexByPath.get(row.path);
+      if (createIdx > idx) {
+        errors.push(`${taskFile}: Create must precede ${row.action} for ${row.path} within Related Files order`);
+      }
+    });
+  }
 
-  const errors = [];
-  const warnings = [];
-  let checked = 0;
+  // Cross-task lifecycle via spec.json dependency DAG (fail-closed when registry missing)
+  let taskRegistry = null;
+  try {
+    const specJson = JSON.parse(fs.readFileSync(path.join(specDir, 'spec.json'), 'utf8'));
+    if (specJson.task_registry && typeof specJson.task_registry === 'object' && !Array.isArray(specJson.task_registry)) taskRegistry = specJson.task_registry;
+  } catch {}
+  const producers = new Map();
+  for (const [taskFile, rows] of rowsByTask.entries()) {
+    for (const row of rows) {
+      if (row.action !== 'create') continue;
+      if (!producers.has(row.path)) producers.set(row.path, { taskFile });
+    }
+  }
+  const crossTaskConsumers = [];
+  for (const [taskFile, rows] of rowsByTask.entries()) {
+    for (const row of rows) {
+      if (!['modify', 'delete', 'read'].includes(row.action)) continue;
+      const producer = producers.get(row.path);
+      if (!producer) continue;
+      if (producer.taskFile === taskFile) continue;
+      crossTaskConsumers.push({ taskFile, row, producer });
+    }
+  }
+  if (crossTaskConsumers.length > 0 && !taskRegistry) {
+    for (const { taskFile, row, producer } of crossTaskConsumers) {
+      errors.push(`${taskFile}: ${row.action} of ${row.path} has producer ${producer.taskFile} but spec.json task_registry is missing or invalid — cannot verify cross-task dependency (fail-closed)`);
+    }
+  } else if (taskRegistry) {
+    // Build basename-indexed dependencies
+    const dependencies = new Map();
+    for (const [key, entry] of Object.entries(taskRegistry)) {
+      const base = path.basename(key);
+      const deps = new Set((entry.dependencies || []).map((d) => path.basename(d)));
+      dependencies.set(base, deps);
+    }
+    function dependsOn(taskBase, ancestorBase, seen = new Set()) {
+      if (taskBase === ancestorBase) return true;
+      if (seen.has(taskBase)) return false;
+      seen.add(taskBase);
+      const deps = dependencies.get(taskBase) || new Set();
+      for (const dep of deps) if (dependsOn(dep, ancestorBase, seen)) return true;
+      return false;
+    }
+    for (const { taskFile, row, producer } of crossTaskConsumers) {
+      if (!dependsOn(taskFile, producer.taskFile)) {
+        errors.push(`${taskFile}: ${row.action} of ${row.path} must depend on creator ${producer.taskFile}`);
+      }
+    }
+  }
 
+  const createdPaths = new Set(allRows.filter((row) => row.action === 'create').map((row) => row.path));
+  let checked = 0;
   for (const row of allRows) {
-    const onDisk = pathExists(root, row.path);
-    if (row.action.includes('create')) {
-      if (onDisk) warnings.push(`${row.taskFile}: Create path already exists (will overwrite): ${row.path}`);
+    if (!ACTIONS.has(row.action) || unsafePath(row.path)) continue;
+    const matches = matchingEntries(root, row.path);
+    if (/[{}*?]/.test(row.path) && matches.length === 0) {
+      errors.push(`${row.taskFile}: glob matches no paths in work tree: ${row.path}`);
       continue;
     }
-    // modify / delete / read must exist OR be created by another task in-spec.
-    checked++;
-    if (!onDisk && !createdPaths.has(row.path)) {
+    if (row.action === 'create') {
+      if (matches.length > 0) errors.push(`${row.taskFile}: Create path already exists in work tree (would overwrite): ${row.path} — use Modify instead of Create for existing files`);
+      continue;
+    }
+    checked += 1;
+    if (matches.length === 0 && !createdPaths.has(row.path)) {
       errors.push(`${row.taskFile}: ${row.action} path not found in work tree: ${row.path}`);
     }
   }
 
-  for (const w of warnings) console.warn(`[WARN] ${w}`);
-
-  const rel = path.relative(process.cwd(), specDir) || specDir;
+  for (const warning of warnings) console.warn(`[WARN] ${warning}`);
+  const relativeSpec = path.relative(process.cwd(), specDir) || specDir;
   if (errors.length > 0) {
-    console.error(`FAIL ${rel}  (root: ${root})`);
-    for (const e of errors) console.error(`- ${e}`);
-    console.error(`\n${errors.length} missing / ${checked} checked path(s).`);
+    console.error(`FAIL ${relativeSpec}  (root: ${root})`);
+    for (const error of errors) console.error(`- ${error}`);
     process.exit(1);
   }
-  console.log(`GROUNDED ${rel}  (${checked} path(s) verified against ${root})`);
+  console.log(`GROUNDED ${relativeSpec}  (${checked} path(s) verified against ${root})`);
 }
 
 main();