@nurix/etna 0.18.19 → 0.18.21

package/data/harnesses/code/skills/design/scripts/preship-sweep.mjs

@@ -0,0 +1,267 @@
+// skills/design/scripts/preship-sweep.mjs — verification-ladder rung 1 (D21/D23): static sweep — per-file catalog + manifest drift via lib/checks.mjs + cross-file machine checks + mandatory-procedures checklist + scope cross-check. --files <a> <b> … scopes the sweep (improve's end-of-run verify); no args = whole-app. --manifest <design.tokens.json | artifact dir> overrides the drift vocabulary source (default: <project>/design.tokens.json).
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runChecks } from './lib/checks.mjs';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const CATALOG = join(SCRIPT_DIR, '..', 'data', 'catalog', 'rules.csv');
+const HARD_RULES = join(SCRIPT_DIR, '..', 'references', 'hard-rules.md');
+
+const useColor = process.stdout.isTTY;
+// Wrap a string in red/yellow/green when writing to a TTY, plain otherwise.
+const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
+const yellow = (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s);
+const green = (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s);
+const bold = (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s);
+
+// Read a UTF-8 file, returning '' when it is absent.
+function readText(path) {
+  try { return readFileSync(path, 'utf8'); } catch { return ''; }
+}
+
+// Recursively collect files under a dir whose name ends with one of the given extensions.
+function walk(dir, exts, acc = []) {
+  if (!existsSync(dir)) return acc;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
+  for (const ent of entries) {
+    if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) walk(full, exts, acc);
+    else if (exts.some((e) => ent.name.endsWith(e))) acc.push(full);
+  }
+  return acc;
+}
+
+// Parse RFC-4180-ish CSV (quoted fields, "" escapes) into an array of row arrays.
+function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQ = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQ) {
+      if (c === '"') { if (text[i + 1] === '"') { field += '"'; i++; } else inQ = false; }
+      else field += c;
+    } else if (c === '"') inQ = true;
+    else if (c === ',') { row.push(field); field = ''; }
+    else if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
+    else if (c === '\r') { /* ignore */ }
+    else field += c;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+// Load rules.csv into an array of header-keyed row objects.
+function loadCatalog() {
+  const rows = parseCsv(readText(CATALOG));
+  if (!rows.length) return [];
+  const header = rows[0];
+  return rows.slice(1).filter((r) => r.length > 1).map((r) => Object.fromEntries(header.map((h, i) => [h, r[i] ?? ''])));
+}
+
+// Extract the sequence of heading levels (1-6) appearing in a source blob.
+function headingLevels(text) {
+  const levels = [];
+  const re = /<h([1-6])[\s/>]/g;
+  let m;
+  while ((m = re.exec(text))) levels.push(Number(m[1]));
+  return levels;
+}
+
+// Return the forward heading-level skips (prev -> level jump greater than one) in order.
+function headingSkips(levels) {
+  const skips = [];
+  let prev = 0;
+  for (const l of levels) {
+    if (prev && l > prev + 1) skips.push(`h${prev}->h${l}`);
+    prev = l;
+  }
+  return skips;
+}
+
+// Count the route directories under src/routes that hold at least one view file.
+function countDeliverables(project) {
+  const rd = join(project, 'src/routes');
+  if (!existsSync(rd)) return 0;
+  let n = 0;
+  for (const ent of readdirSync(rd, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    if (walk(join(rd, ent.name), ['.tsx']).length) n++;
+  }
+  return n;
+}
+
+// Count surfaces declared in the structure map by its per-surface archetype lines.
+function countSurfaces(project) {
+  const p = join(project, 'docs/design/structure.md');
+  if (!existsSync(p)) return null;
+  const m = readText(p).match(/```yaml structure\r?\n([\s\S]*?)```/);
+  if (!m) return null;
+  return (m[1].match(/^\s*archetype\s*:/gm) || []).length;
+}
+
+// Read the spc-14 nav bound (nav 5-9) from the catalog.
+function navBounds(catalog) {
+  const row = catalog.find((r) => r.id === 'spc-14');
+  const m = row && row.numbers && row.numbers.match(/nav\s*(\d+)\s*[-–]\s*(\d+)/);
+  return m ? { min: Number(m[1]), max: Number(m[2]) } : null;
+}
+
+// Count nav items in src/App.tsx, preferring an explicit <nav> region, else route entries.
+function countNav(project) {
+  const text = readText(join(project, 'src/App.tsx'));
+  const nav = text.match(/<nav[\s\S]*?<\/nav>/i);
+  if (nav) {
+    const items = (nav[0].match(/<(a|NavLink|Link|NavItem|button)\b/gi) || []).length;
+    if (items) return items;
+  }
+  return (text.match(/\bpath\s*=/g) || []).length;
+}
+
+// Render one catalog finding as a single fix-or-classify line.
+function formatFinding(f, project) {
+  const anchor = f.rule || '?';
+  const file = f.file ? relative(project, f.file) || f.file : '';
+  const loc = f.line != null ? `${file}:${f.line}` : file;
+  const ev = f.excerpt ? `  [${f.excerpt}]` : '';
+  return `  ${red(anchor)}  ${loc}${ev}  ${f.fix || ''}`.trimEnd();
+}
+
+// Run the per-file catalog + manifest drift (lib/checks.mjs) over the file set; returns the violation count.
+function runCatalog(project, files, manifestPath, section) {
+  if (!files.length) { section.push('  (no src/**/*.{tsx,ts,css,html} files to scan)'); return 0; }
+  const findings = runChecks(files, { manifestPath });
+  if (!findings.length) { section.push(green('  catalog checks: no per-file violations.')); return 0; }
+  section.push(`  catalog checks reported ${findings.length} violation(s) — fix each now, or classify why it does not apply in docs/memory/design-decay.md; never ignore silently:`);
+  for (const f of findings) section.push(formatFinding(f, project));
+  return findings.length;
+}
+
+// Run the cross-file machine checks (dep-02 one-h1 + heading skips) and, on whole-app runs, the route-shell aggregate and advisory nav-count.
+function crossFileChecks(project, files, catalog, section, scoped) {
+  const violations = [];
+  for (const file of files) {
+    if (!/\.(tsx|html)$/.test(file)) continue;
+    const text = readText(file);
+    const rel = relative(project, file) || file;
+    const h1 = (text.match(/<h1[\s/>]/g) || []).length;
+    if (h1 >= 2) violations.push(`  ${red('dep-02')}  ${rel}  ${h1} <h1> elements in one view; exactly one h1 per view.`);
+    const skips = headingSkips(headingLevels(text));
+    if (skips.length) violations.push(`  ${red('dep-02')}  ${rel}  heading level skips (${skips.join(', ')}); heading levels never skip.`);
+  }
+  const routesDir = join(project, 'src/routes');
+  if (!scoped && existsSync(routesDir)) {
+    for (const ent of readdirSync(routesDir, { withFileTypes: true })) {
+      if (!ent.isDirectory()) continue;
+      const dir = join(routesDir, ent.name);
+      const total = walk(dir, ['.tsx']).reduce((n, f) => n + (readText(f).match(/<h1[\s/>]/g) || []).length, 0);
+      if (total > 1) violations.push(`  ${red('dep-02')}  src/routes/${ent.name}/  ${total} <h1> across the route shell; one h1 per route view.`);
+    }
+  }
+  if (violations.length) { section.push(...violations); }
+  else section.push(green('  cross-file machine checks (dep-02 one-h1, heading-skip): clean.'));
+
+  if (!scoped) {
+    const bounds = navBounds(catalog);
+    const nav = countNav(project);
+    if (bounds) {
+      const within = nav >= bounds.min && nav <= bounds.max;
+      const note = `  ${within ? '' : yellow('[advisory] ')}nav items: ${nav} (spc-14 advisory band ${bounds.min}-${bounds.max}${within ? ', within' : ', outside — judged, not gated'}).`;
+      section.push(note);
+    }
+  }
+  return violations.length;
+}
+
+// Print the proc-* mandatory-procedures checklist, each row's imperative sourced from hard-rules.md.
+function procChecklist(catalog) {
+  const hard = readText(HARD_RULES);
+  const imperatives = new Map();
+  for (const line of hard.split(/\r?\n/)) {
+    const m = line.match(/^- `(proc-\d+)`\s*(.*)$/);
+    if (m) imperatives.set(m[1], m[2].trim());
+  }
+  const procs = catalog.filter((r) => /^proc-\d+$/.test(r.id)).sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+  const lines = [];
+  for (const r of procs) {
+    const text = imperatives.get(r.id) || r.statement || '';
+    lines.push(`  [ ] ${r.id} — ${text}`);
+  }
+  return lines;
+}
+
+// Assemble and print the whole sweep, then exit non-zero when catalog or cross-file checks found violations.
+function main() {
+  const args = process.argv.slice(2);
+  let project = process.cwd();
+  let scopedFiles = null;
+  let manifestArg = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project') project = resolve(args[++i] || '.');
+    else if (args[i].startsWith('--project=')) project = resolve(args[i].slice('--project='.length));
+    else if (args[i] === '--manifest') manifestArg = resolve(args[++i] || '.');
+    else if (args[i].startsWith('--manifest=')) manifestArg = resolve(args[i].slice('--manifest='.length));
+    else if (args[i] === '--files') {
+      scopedFiles = [];
+      while (i + 1 < args.length && !args[i + 1].startsWith('--')) scopedFiles.push(resolve(args[++i]));
+    }
+  }
+
+  const catalog = loadCatalog();
+  const scoped = scopedFiles !== null;
+  const files = scoped ? scopedFiles : walk(join(project, 'src'), ['.tsx', '.ts', '.css', '.html']);
+  const defaultManifest = join(project, 'design.tokens.json');
+  const manifestPath = manifestArg || (existsSync(defaultManifest) ? defaultManifest : null);
+
+  console.log(bold(`preship-sweep — verification ladder rung 1  (project: ${project}${scoped ? `, scoped to ${files.length} file(s) via --files` : ''})`));
+  console.log('');
+
+  console.log(bold('(a) Per-file catalog + manifest drift — lib/checks.mjs'));
+  const secA = [];
+  const catalogCount = runCatalog(project, files, manifestPath, secA);
+  console.log(secA.join('\n'));
+  console.log('');
+
+  console.log(bold('(b) Cross-file machine checks'));
+  const secB = [];
+  const crossCount = crossFileChecks(project, files, catalog, secB, scoped);
+  console.log(secB.join('\n'));
+  console.log('');
+
+  if (!scoped) {
+    console.log(bold('(c) Mandatory procedures — self-audit checklist (proc-*)'));
+    console.log(procChecklist(catalog).join('\n'));
+    console.log('');
+
+    console.log(bold('(c) Scope cross-check (proc-14)'));
+    const surfaces = countSurfaces(project);
+    const deliverables = countDeliverables(project);
+    if (surfaces == null) {
+      console.log(`  ${yellow('no docs/design/structure.md map found — cannot cross-check scope.')}`);
+    } else {
+      console.log(`  structure map declares ${surfaces} surface(s); found ${deliverables} route deliverable(s) under src/routes/.`);
+      if (surfaces !== deliverables) console.log(`  ${yellow(`[advisory] scope mismatch (${surfaces} vs ${deliverables}) — add or reconcile before responding (proc-14).`)}`);
+    }
+    console.log('');
+  } else {
+    console.log('(scoped run — the mandatory-procedures checklist and scope cross-check run on the whole-app sweep)');
+    console.log('');
+  }
+
+  const failed = catalogCount > 0 || crossCount > 0;
+  if (failed) {
+    const reasons = [];
+    if (catalogCount > 0) reasons.push(`${catalogCount} per-file violation(s)`);
+    if (crossCount > 0) reasons.push(`${crossCount} cross-file violation(s)`);
+    console.log(red(`FAIL  preship-sweep — ${reasons.join('; ')}. Resolve, then re-run.`));
+    process.exit(1);
+  }
+  console.log(green(scoped ? 'PASS  preship-sweep (scoped) — no static violations in the given files.' : 'PASS  preship-sweep — no static violations; work the checklist above before ship.'));
+  process.exit(0);
+}
+
+main();