@nurix/etna 0.19.2 → 0.19.4

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

@@ -1,4 +1,4 @@
-// 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).
+// 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';
@@ -194,6 +194,44 @@ function procChecklist(catalog) {
   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);
@@ -237,7 +275,13 @@ function main() {
     console.log(procChecklist(catalog).join('\n'));
     console.log('');
 
-    console.log(bold('(c) Scope cross-check (proc-14)'));
+    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) {
@@ -248,7 +292,7 @@ function main() {
     }
     console.log('');
   } else {
-    console.log('(scoped run — the mandatory-procedures checklist and scope cross-check run on the whole-app sweep)');
+    console.log('(scoped run — the mandatory-procedures checklist, style-row walk, and scope cross-check run on the whole-app sweep)');
     console.log('');
   }
 
@@ -257,10 +301,11 @@ function main() {
     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.`));
+    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 checklist above before ship.'));
+  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);
 }
 

package/data/harnesses/code/skills/design/scripts/render-rung.mjs

@@ -1,9 +1,10 @@
-// skills/design/scripts/render-rung.mjs — verification-ladder rung 2: deterministic render checks + pixel instruments (D32)
+// skills/design/scripts/render-rung.mjs — verification-ladder rung 2: deterministic render checks + pixel instruments (D32). --require makes the rung a gate (create's ladder: fail-closed when no headless browser is importable — emission contract 4); without it a skip degrades gracefully but always lands as a named finding, never a one-line notice. --screenshot <outdir> saves one PNG per viewport.
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { inflateSync } from 'node:zlib';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { MOTION_STAGGER_CLASS, STAGGER_CHILD_CAP } from './lib/vocabulary.mjs';
 
 // The four viewports the ladder sweeps; width is the breakpoint, height is a fixed tall canvas.
 const VIEWPORTS = [375, 768, 1024, 1440];
@@ -19,7 +20,11 @@ const DEV_PORTS = [5173, 4173, 3000, 8080];
 // Severity rank for the delivered (severity-ranked) list; auto-critical is never minted by machine render rules.
 const SEVERITY_RANK = { 'auto-critical': 0, critical: 1, major: 2, minor: 3 };
 
-const NO_BROWSER_LINE = 'render rung: no headless browser available in this project; rung skipped (rungs 0-1 still hold)';
+// The exact install command --require prints when no headless browser is importable (contract 4).
+const BROWSER_INSTALL_CMD = 'npm install -D playwright && npx playwright install chromium';
+
+// The token trio cod-15 measures per declared theme context.
+const THEME_DRIFT_PROPS = ['--background', '--foreground', '--primary'];
 
 // ----------------------------------------------------------------------------
 // Pure helpers (exported for unit testing — no browser required)
@@ -205,19 +210,77 @@ function rgbKey(rgb) {
 // CLI plumbing
 // ----------------------------------------------------------------------------
 
-// Parse argv into { project, url }.
+// Parse argv into { project, url, require, screenshot }.
 function parseArgs(argv) {
-  const out = { project: process.cwd(), url: null };
+  const out = { project: process.cwd(), url: null, require: false, screenshot: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--project') out.project = resolve(argv[++i] ?? '.');
     else if (a.startsWith('--project=')) out.project = resolve(a.slice('--project='.length));
     else if (a === '--url') out.url = argv[++i] ?? null;
     else if (a.startsWith('--url=')) out.url = a.slice('--url='.length);
+    else if (a === '--require') out.require = true;
+    else if (a === '--screenshot') out.screenshot = resolve(argv[++i] ?? '.');
+    else if (a.startsWith('--screenshot=')) out.screenshot = resolve(a.slice('--screenshot='.length));
   }
   return out;
 }
 
+// Report a skipped rung and return the process exit code. Never a one-line notice: without
+// --require the skip lands as a named finding in the fix-or-classify register (exit 0 — improve
+// keeps graceful degradation); with --require (create's ladder) the rung is a gate and fails closed
+// with the exact remedy (emission contract 4 — a create run cannot complete without having rendered).
+function reportSkip(requireMode, reason, remedy) {
+  console.log(`[${requireMode ? 'critical' : 'major'}] render-rung  Verification — render rung skipped: ${reason}`);
+  console.log(`  fix  ·  ${remedy}`);
+  console.log('  consequence  ·  the render-only rules (cod-15, spc-16, mot-08 DOM, spc-10, typ-01, int-17/18, cod-12) did not run; the surface ships unrendered.');
+  if (requireMode) {
+    console.log('  --require: this rung is a gate on create runs — fix the remedy above and re-run.');
+    return 1;
+  }
+  console.log('  classify this skip in the ship report or fix it — never ignore silently.');
+  console.log('');
+  return 0;
+}
+
+// cod-15 ground truth: the authored --background/--foreground/--primary byte forms per theme
+// context the resolver declares, read from the project-root design-tokens artifact. Returns
+// { light: { '--background': css, … }, dark?: … } or null when no artifact is readable.
+export function loadAuthoredThemeColors(projectDir) {
+  const readJson = (name) => {
+    try { return JSON.parse(readFileSync(join(resolve(projectDir), name), 'utf8')); } catch { return null; }
+  };
+  const base = readJson('design.tokens.json');
+  const resolver = readJson('design.resolver.json');
+  if (!base || !base.color || !resolver) return null;
+  const themeModifier = (resolver.modifiers || []).find((m) => m && m.name === 'theme');
+  const contexts = Object.keys((themeModifier && themeModifier.contexts) || { light: [] });
+  const dark = readJson('design.tokens.dark.json');
+  const out = {};
+  for (const context of contexts) {
+    // The dark overlay carries the full color group (rule 10), so a token-level merge is the overlay.
+    const colorGroup = context === 'dark' && dark && dark.color ? { ...base.color, ...dark.color } : base.color;
+    const cssOf = (role) => {
+      let token = colorGroup[role];
+      for (let hops = 0; token && hops < 10; hops++) {
+        const ext = token.$extensions && token.$extensions['com.nurix.design'];
+        if (ext && typeof ext.css === 'string') return ext.css;
+        const v = token.$value;
+        if (typeof v === 'string' && /^\{color\.[^}]+\}$/.test(v)) token = colorGroup[v.slice(7, -1)];
+        else return null;
+      }
+      return null;
+    };
+    const values = {};
+    for (const prop of THEME_DRIFT_PROPS) {
+      const css = cssOf(prop.slice(2));
+      if (css) values[prop] = css;
+    }
+    if (Object.keys(values).length) out[context] = values;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
 // Try to import playwright, playwright-core, then puppeteer from the target project; return a driver adapter or null.
 async function loadBrowserDriver(projectDir) {
   const require = createRequire(join(resolve(projectDir), 'package.json'));
@@ -415,6 +478,77 @@ function inPagePerfRead() {
   return window.__perf || { cls: 0, lcp: 0 };
 }
 
+// cod-15: flip data-theme through each declared context and read the rendered token trio off the
+// root element, restoring the boot attribute afterwards.
+function inPageThemeTokens(payload) {
+  const html = document.documentElement;
+  const previous = html.getAttribute('data-theme');
+  const out = {};
+  for (const context of payload.contexts) {
+    html.setAttribute('data-theme', context);
+    const cs = getComputedStyle(html);
+    const read = {};
+    for (const prop of payload.props) read[prop] = cs.getPropertyValue(prop).trim();
+    out[context] = read;
+  }
+  if (previous === null) html.removeAttribute('data-theme');
+  else html.setAttribute('data-theme', previous);
+  return out;
+}
+
+// spc-16: fixed-width table/grid cells whose rendered text exceeds the cell (scrollWidth >
+// clientWidth) with no truncate or scroll affordance on the cell or a descendant wrapper.
+function inPageCellTextFit(cap) {
+  const path = (el) => {
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += '#' + el.id;
+    else if (el.classList.length) s += '.' + el.classList[0];
+    return s;
+  };
+  const offenders = [];
+  const cells = document.querySelectorAll('td, th, [role="cell"], [role="gridcell"], [role="columnheader"]');
+  for (const cell of cells) {
+    const cs = getComputedStyle(cell);
+    if (cs.display === 'none' || cs.visibility === 'hidden') continue;
+    if (cell.scrollWidth <= cell.clientWidth + 1) continue; // content fits — an auto-layout cell grows instead of overflowing
+    let excused = false;
+    for (const node of [cell, ...cell.querySelectorAll('*')]) {
+      const ns = getComputedStyle(node);
+      if (/(auto|scroll)/.test(ns.overflowX)) { excused = true; break; }
+      if (ns.textOverflow === 'ellipsis' && /(hidden|clip)/.test(ns.overflowX)) { excused = true; break; }
+      if (ns.webkitLineClamp && ns.webkitLineClamp !== 'none') { excused = true; break; }
+    }
+    if (excused) continue;
+    offenders.push({ selector: path(cell), scrollWidth: Math.round(cell.scrollWidth), clientWidth: Math.round(cell.clientWidth) });
+    if (offenders.length >= cap) break;
+  }
+  return offenders;
+}
+
+// mot-08 (DOM half): every rendered stagger container's child count and its total sequence length,
+// the latter as the largest resolved child animation-delay.
+function inPageStaggerAudit(payload) {
+  const path = (el) => {
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += '#' + el.id;
+    else if (el.classList.length) s += '.' + el.classList[0];
+    return s;
+  };
+  const out = [];
+  for (const container of document.querySelectorAll('.' + payload.className)) {
+    let maxDelayMs = 0;
+    for (const child of container.children) {
+      for (const raw of getComputedStyle(child).animationDelay.split(',')) {
+        const t = raw.trim();
+        const ms = t.endsWith('ms') ? parseFloat(t) : parseFloat(t) * 1000;
+        if (!Number.isNaN(ms)) maxDelayMs = Math.max(maxDelayMs, ms);
+      }
+    }
+    out.push({ selector: path(container), childCount: container.children.length, maxDelayMs: Math.round(maxDelayMs) });
+  }
+  return out;
+}
+
 // Read the page's effective background colour for the white-space instrument.
 function inPageBackground() {
   const parse = (s) => {
@@ -457,12 +591,11 @@ function printFinding(f) {
 
 // Run the render rung: load a browser, sweep viewports for machine findings, compute pixel instruments.
 async function main() {
-  const { project, url: urlArg } = parseArgs(process.argv.slice(2));
+  const { project, url: urlArg, require: requireMode, screenshot: screenshotDir } = parseArgs(process.argv.slice(2));
 
   const driver = await loadBrowserDriver(project);
   if (!driver) {
-    console.log(NO_BROWSER_LINE);
-    return 0;
+    return reportSkip(requireMode, 'no headless browser importable from this project (tried playwright, playwright-core, puppeteer)', `install one: ${BROWSER_INSTALL_CMD}`);
   }
 
   let url = urlArg;
@@ -471,8 +604,7 @@ async function main() {
     if (url) console.log(`render rung: no --url given; using detected dev server ${url}`);
   }
   if (!url) {
-    console.log('render rung: no --url given and no dev server detected on common ports; pass --url <dev-server-url>. rung skipped.');
-    return 0;
+    return reportSkip(requireMode, 'no --url given and no dev server detected on common ports', 'start the dev server (npm run dev) or pass --url <dev-server-url>');
   }
 
   // Resolve axe-core from the project if present; gate only the accessible-name + ARIA-validity families.
@@ -493,6 +625,13 @@ async function main() {
     console.log('render rung: no src/styles/personality.css found; the rendered token-drift check (cod-02) is skipped.');
   }
 
+  // Load the authored per-theme trio for cod-15 from the project-root design-tokens artifact.
+  const authoredThemes = loadAuthoredThemeColors(project);
+  if (!authoredThemes) {
+    console.log('render rung: no readable design-tokens artifact at the project root; the per-theme rendered token drift check (cod-15) is skipped.');
+  }
+  let themeDriftChecked = false;
+
   const findings = new Map();
   const instruments = {};
   const axeRules = [...(axeSource ? AXE_ACCESSIBLE_NAME.concat(AXE_ARIA_VALIDITY) : [])];
@@ -508,9 +647,8 @@ async function main() {
       try {
         await page.goto(url, { waitUntil: 'load', timeout: 30000 });
       } catch (err) {
-        console.log(`render rung: could not load ${url} at ${width}px (${err.message}); is the dev server running? rung skipped.`);
         await browser.close();
-        return 0;
+        return reportSkip(requireMode, `could not load ${url} at ${width}px (${err.message})`, 'start the dev server (npm run dev) or pass --url <dev-server-url>');
       }
       await new Promise((r) => setTimeout(r, 150));
 
@@ -570,7 +708,65 @@ async function main() {
         }
       }
 
-      // (5) int-17 / int-18 — axe accessible-name + ARIA-validity families.
+      // (5) cod-15 — per-theme rendered token drift (viewport-independent; measured once, with
+      // data-theme flipped through each context the resolver declares).
+      if (authoredThemes && !themeDriftChecked) {
+        themeDriftChecked = true;
+        try {
+          const rendered = await page.evaluate(inPageThemeTokens, { contexts: Object.keys(authoredThemes), props: THEME_DRIFT_PROPS });
+          const normalize = (s) => String(s || '').replace(/\s+/g, ' ').trim().toLowerCase();
+          for (const [context, roles] of Object.entries(authoredThemes)) {
+            for (const [prop, authored] of Object.entries(roles)) {
+              const got = (rendered[context] && rendered[context][prop]) || '';
+              if (normalize(got) === normalize(authored)) continue;
+              addFinding(findings, width, {
+                anchor: 'cod-15', dimension: 'S3 Design Tokens', statement: 'rendered token drifts from the authored value in this theme context',
+                evidenceKey: `${context}|${prop}`, where: `data-theme="${context}" · ${prop} renders ${JSON.stringify(got || '(empty)')}`,
+                before: got || '(empty)', after: `${authored} (the ${context} context's authored value)`,
+                consequence: "the theme context is cascade-dead — the library's later :root block wins and the surface silently reverts to shadcn gray", severity: 'critical',
+              });
+            }
+          }
+        } catch (err) {
+          console.log(`render rung: the per-theme token drift check (cod-15) failed to run (${err.message}); continuing.`);
+        }
+      }
+
+      // (6) spc-16 — fixed-width cell text fit: rendered text exceeds the cell with no truncate or
+      // scroll affordance (document-level overflow cannot see intra-row column paint-over).
+      const cellOffenders = await page.evaluate(inPageCellTextFit, 40);
+      for (const cell of cellOffenders) {
+        addFinding(findings, width, {
+          anchor: 'spc-16', dimension: 'P3 Spatial', statement: 'rendered text exceeds its fixed-width cell with no truncate or scroll affordance',
+          evidenceKey: cell.selector, where: `${cell.selector} · content ${cell.scrollWidth}px > cell ${cell.clientWidth}px`,
+          before: `${cell.scrollWidth}px of content in a ${cell.clientWidth}px cell`, after: 'text fits, truncates (truncate), or scrolls (overflow-x-auto)',
+          consequence: 'cell text paints over or clips against the neighbouring column; the row reads as broken data', severity: 'major',
+        });
+      }
+
+      // (7) mot-08 (DOM half) — rendered stagger containers stay within the child cap and the
+      // 1s total-sequence budget (the source shell owns the per-item band and the budget stamp).
+      const staggerContainers = await page.evaluate(inPageStaggerAudit, { className: MOTION_STAGGER_CLASS });
+      for (const s of staggerContainers) {
+        if (s.childCount > STAGGER_CHILD_CAP) {
+          addFinding(findings, width, {
+            anchor: 'mot-08', dimension: 'B2 Motion', statement: `arrival cascade exceeds the ${STAGGER_CHILD_CAP}-child cap`,
+            evidenceKey: `count|${s.selector}`, where: `${s.selector} · ${s.childCount} children in a ${MOTION_STAGGER_CLASS} container`,
+            before: `${s.childCount} staggered children`, after: `<= ${STAGGER_CHILD_CAP} (children past the cap arrive with the last delayed one)`,
+            consequence: 'a long cascade turns arrival feedback into a wait; the operator reads it as slowness', severity: 'major',
+          });
+        }
+        if (s.maxDelayMs >= 1000) {
+          addFinding(findings, width, {
+            anchor: 'mot-08', dimension: 'B2 Motion', statement: 'total stagger sequence at or over the 1s budget',
+            evidenceKey: `sequence|${s.selector}`, where: `${s.selector} · last child arrives at ${s.maxDelayMs}ms`,
+            before: `${s.maxDelayMs}ms total sequence`, after: '< 1000ms (per-item delay x child count under the budget)',
+            consequence: 'content the operator came for is still arriving after a second; the cascade reads as lag, not polish', severity: 'major',
+          });
+        }
+      }
+
+      // (8) int-17 / int-18 — axe accessible-name + ARIA-validity families.
       if (axeSource) {
         try {
           await page.addScriptTag({ content: axeSource });
@@ -596,7 +792,7 @@ async function main() {
         }
       }
 
-      // (6) cod-12 — runtime perf budgets measurable in a passive headless load: LCP and CLS.
+      // (9) cod-12 — runtime perf budgets measurable in a passive headless load: LCP and CLS.
       // INP and frame time require real interaction and belong to the interactive rung (3), not this one.
       try {
         const perf = await page.evaluate(inPagePerfRead);
@@ -621,6 +817,10 @@ async function main() {
       // Instruments — pixel evidence, never a verdict.
       try {
         const shot = Buffer.from(await page.screenshot({ type: 'png' }));
+        if (screenshotDir) {
+          mkdirSync(screenshotDir, { recursive: true });
+          writeFileSync(join(screenshotDir, `${width}.png`), shot);
+        }
         const bg = await page.evaluate(inPageBackground);
         const img = decodePng(shot);
         instruments[width] = {