@nurix/etna 0.19.11 → 0.19.13

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

@@ -1,312 +0,0 @@
-// skills/design/scripts/preship-sweep.mjs — verification-ladder rung 1 (D21/D23): static sweep — per-file catalog + manifest drift via lib/checks.mjs (incl. the budget-stamp vocabulary rules typ-20/col-16/mot-08) + cross-file machine checks + mandatory-procedures checklist + the resolved style row's checklist walk (the corpus's one positive verification) + 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;
-}
-
-// Resolve a --manifest argument or project default to the design.tokens.json file path, or null.
-function tokensFileOf(manifestPath) {
-  if (!manifestPath || !existsSync(manifestPath)) return null;
-  try {
-    if (statSync(manifestPath).isDirectory()) {
-      const candidate = join(manifestPath, 'design.tokens.json');
-      return existsSync(candidate) ? candidate : null;
-    }
-  } catch { return null; }
-  return manifestPath;
-}
-
-// The resolved style row's checklist items, walked at preship — the sweep's one positive verification:
-// the catalog proves nothing is broken; these items assert the resolved style actually landed. The row
-// is read from the artifact root $description's resolution record (a "styles.csv#<id>" reference from
-// seed composition); library/default/project looks carry no style row and print a one-line note.
-function styleChecklist(manifestPath, section) {
-  const tokensFile = tokensFileOf(manifestPath);
-  if (!tokensFile) { section.push('  (no design.tokens.json found — no resolved style row to walk)'); return; }
-  let root;
-  try { root = JSON.parse(readText(tokensFile)); } catch { section.push('  (design.tokens.json does not parse — no resolved style row to walk)'); return; }
-  const record = typeof root?.$description === 'string' ? root.$description : '';
-  const ref = record.match(/styles\.csv#(\d+)/);
-  if (!ref) { section.push('  (the artifact resolution record names no styles.csv row — library/default/project looks carry no style checklist)'); return; }
-  const rows = parseCsv(readText(join(SCRIPT_DIR, '..', 'data', 'combinations', 'styles.csv')));
-  if (rows.length < 2) { section.push(yellow('  data/combinations/styles.csv missing or empty — cannot walk the resolved style row\'s checklist.')); return; }
-  const header = rows[0];
-  const idCol = header.indexOf('id');
-  const checklistCol = header.indexOf('checklist');
-  const row = rows.slice(1).find((r) => (r[idCol] || '').trim() === ref[1]);
-  if (!row || checklistCol < 0) { section.push(yellow(`  resolution record names styles.csv#${ref[1]} but no such row (or no checklist column) exists — reconcile the record.`)); return; }
-  const items = (row[checklistCol] || '').split(';').map((s) => s.trim()).filter(Boolean);
-  if (!items.length) { section.push(`  styles.csv#${ref[1]} carries no checklist items.`); return; }
-  section.push(`  resolved style row: styles.csv#${ref[1]} — walk every box now, on the built surfaces:`);
-  for (const item of items) section.push(`  [ ] ${item}`);
-  section.push('  Handle these before finalizing: an unchecked box means the resolved style did not land — fix the surface, not the checklist.');
-}
-
-// 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('(d) Resolved style row — checklist walk (the positive verification)'));
-    const secD = [];
-    styleChecklist(manifestPath, secD);
-    console.log(secD.join('\n'));
-    console.log('');
-
-    console.log(bold('(e) 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, style-row walk, 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('; ')}. Handle every finding above before finalizing, 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 checklists above before ship.'));
-  console.log('A clean scan means nothing is mechanically broken — it does not mean the design is good; the checklist walks above are where good is decided.');
-  process.exit(0);
-}
-
-main();