@event4u/agent-config 16.4.0 → 16.5.0

package/dist/cli/commands/uiRender.js

@@ -23,14 +23,17 @@
  * `b-page-capture-primitive` closed as a recorded null. This supplies the
  * primitive, so that null's own reopening condition fires.
  *
- * Playwright is a devDependency (`package.json:97`) and is therefore NOT
+ * Playwright is a devDependency (`package.json:111`) and is therefore NOT
  * guaranteed present in a consumer install. The import is dynamic and the
  * absence path is a clean, explained exit rather than a stack trace — and it
  * reports `verification: unverified` instead of writing an empty manifest that
  * would read as a successful capture of nothing.
  */
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { runAssetRender } from './uiRenderAsset.js';
+import { scanHostHtml, scanSvg } from '../../scripts/lint_svg_asset.js';
 /** The three viewports E3.1 names. Widths are the contract, not a preference. */
 export const VIEWPORTS = [
     { name: 'desktop', width: 1440, height: 900 },
@@ -49,6 +52,82 @@ export const CAPTURED_PROPERTIES = [
     'overflow-y',
 ];
 export const RENDER_REL = path.join('agents', 'runtime', 'state', 'render');
+/**
+ * `--profile asset` with no renderer. Distinct from 1, which this command
+ * already uses for an internal error (a missing path, a URL handed to the
+ * asset profile), because a caller has to tell "nothing rendered" from
+ * "you called it wrong" — the first is a consumer's ordinary state.
+ */
+export const EXIT_RENDERER_ABSENT = 3;
+/**
+ * The families whose ERROR means the file is broken, as opposed to improvable.
+ *
+ * Finding 4 of the third completion review, reproduced by running `scanSvg`:
+ * an ordinary stroke icon with no `<title>` yields exactly one error —
+ * `svg-a11y-no-accessible-name` — so `errors` was never 0, the static-only
+ * discharge never fired, and a consumer with no Playwright was refused by a
+ * BLOCKING turn-end gate on every `.svg` they wrote, with no way out. That is
+ * the opposite of the path's stated purpose, which the obligation module's own
+ * header spells out: it exists so a Playwright-less install is not refused
+ * forever.
+ *
+ * `structure` is "this file does not parse or does not resolve" and `safety`
+ * is "this file does something it should not". Both are brokenness, and both
+ * SHOULD stop a discharge taken without a render. Accessibility, motion and
+ * geometry are readings about a file that works — they are reported by the
+ * design pass in their own right, and a missing title is not a reason to
+ * refuse a turn on a machine that could not render.
+ */
+const BLOCKING_FAMILIES = ['svg-structure-', 'svg-safety-'];
+/**
+ * The static witness, bound to the bytes it read.
+ *
+ * `errors` counts `severity: 'error'` findings in the blocking families only —
+ * see `BLOCKING_FAMILIES` for which, and for the refusal that made the
+ * distinction necessary. A warning is a reading, not a refusal, and the
+ * static-only discharge in the turn-end gate is about whether the file is
+ * BROKEN. The digest is of the SAME bytes, so a later reader can tell whether
+ * this reading describes the file in front of it.
+ */
+export function staticWitness(absFile, delivery) {
+    // THE DIGEST IS OF THE BYTES, the scan is of the decoded text.
+    //
+    // Finding 2 of the sixth completion review: three places hash "the file"
+    // and two of them hashed the UTF-8 DECODED string while the render hashed
+    // the raw buffer. For any file the decode is not byte-exact over — a BOM,
+    // a lone surrogate, an invalid sequence replaced by U+FFFD — the two
+    // digests differ forever, so the gate never matches a render to the file
+    // it rendered and the obligation can never be discharged. One definition,
+    // and it is the one a digest normally means.
+    let bytes;
+    try {
+        bytes = fs.readFileSync(absFile);
+    }
+    catch {
+        return null;
+    }
+    const content = bytes.toString('utf8');
+    const digest = crypto.createHash('sha256').update(bytes).digest('hex');
+    // The DELIVERY MODE is threaded through. Finding 6 of this change's second
+    // completion review: `scanSvg` grades an undeclared mode as `inline`, the
+    // strictest, because that is the safe default for a file whose embedding
+    // nobody stated. Here the embedding WAS stated — `--delivery img` is on the
+    // same command line — so defaulting raised the safety family to `error` for
+    // an asset that cannot execute anything, and a correct `img`-delivered file
+    // was refused the static-only discharge it qualifies for.
+    // AN HTML HOST IS SCANNED AS A HOST, NOT AS A GRAPHIC.
+    //
+    // Finding 1 of the fourth completion review, reproduced on this repo's own
+    // `hosts/img-delivery-static.html` fixture: `scanSvg` over a host document
+    // reports `svg-structure-not-well-formed` for every HTML void element —
+    // `<meta>` and `<img>` never close, which is correct HTML and malformed
+    // XML — so the witness read 2 errors where `scanHostHtml` over the same
+    // bytes reports none. Under the blocking-family count those are structure
+    // errors, so a correct host document could not discharge its obligation.
+    const scan = /\.html?$/i.test(absFile) ? scanHostHtml : scanSvg;
+    const errors = scan(content, path.basename(absFile), { delivery }).filter((f) => f.severity === 'error' && BLOCKING_FAMILIES.some((fam) => f.rule.startsWith(fam))).length;
+    return { errors, digest };
+}
 export function slugify(target) {
     return (target
         .replace(/^https?:\/\//, '')
@@ -90,11 +169,20 @@ export async function runUiRender(opts) {
     }
     const slug = opts.slug ?? slugify(opts.target);
     const outDir = path.join(projectRoot, RENDER_REL, slug);
+    const isAsset = opts.profile === 'asset';
     let chromium;
     try {
         ({ chromium } = await import('@playwright/test'));
     }
     catch {
+        // Step 2.3, and the reason the absence path sits ABOVE the profile
+        // branch rather than inside either one: both profiles reach it by
+        // construction, so there is no second absence path to keep honest.
+        // Step 2.1(i): on the ASSET profile the renderer-absent path runs the
+        // static witness itself and binds it to the same digest, so the gate's
+        // static-only discharge reads ONE file and never depends on how a
+        // separate lint run was named or stored.
+        const staticReading = isAsset && !isUrl ? staticWitness(abs, opts.delivery) : null;
         const manifest = {
             schema: 1,
             generated_at: new Date().toISOString(),
@@ -104,6 +192,8 @@ export async function runUiRender(opts) {
             palette: [],
             type_families: [],
             verification: 'unverified',
+            ...(isAsset ? { profile: 'asset', reason: 'renderer-absent', goal: 'unassessed' } : {}),
+            ...(staticReading ? { static: staticReading } : {}),
             degradation_reason: '@playwright/test is not installed — it is a devDependency, so a consumer install has no browser. ' +
                 'Install it, or scope any verdict to the static checks that actually ran.',
         };
@@ -111,11 +201,27 @@ export async function runUiRender(opts) {
         process.stderr.write(`[ui:render] ${manifest.degradation_reason}\n`);
         if (opts.json)
             process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
-        // Exit 0, deliberately: an absent devDependency is a capability fact,
-        // not a failure of this command. The manifest carries the honest state.
-        return 0;
+        // The PAGE profile keeps exit 0: an absent devDependency is a
+        // capability fact, not a failure of that command, and the manifest
+        // carries the honest state.
+        //
+        // The ASSET profile exits NON-ZERO (step 2.1(a), review claim C2). The
+        // turn-end gate's transcript path never sees an exit code, so a
+        // non-zero exit alone does not close the hole — but the record path
+        // reads one, and a bare `ui:render --profile asset` that rendered
+        // nothing must not look like a check that passed. The code is distinct
+        // from 1, which this command already uses for an internal error such as
+        // a missing path or a URL handed to the asset profile.
+        return isAsset ? EXIT_RENDERER_ABSENT : 0;
     }
     fs.mkdirSync(outDir, { recursive: true });
+    if (isAsset) {
+        if (isUrl) {
+            process.stderr.write('[ui:render] --profile asset reads a file on disk, not a URL\n');
+            return 1;
+        }
+        return runAssetProfile({ ...opts, projectRoot, abs, slug, outDir }, chromium);
+    }
     const captures = [];
     const allStyles = [];
     let browser = null;
@@ -199,6 +305,97 @@ export async function runUiRender(opts) {
     }
     return 0;
 }
+/**
+ * The asset profile. Same manifest, same output directory, same Class-A
+ * boundary — the browser is closed in a `finally` on every path including a
+ * throw, exactly as the page profile closes its own.
+ */
+async function runAssetProfile(opts, chromium) {
+    let browser = null;
+    try {
+        browser = await chromium.launch({ headless: true });
+        const result = await runAssetRender(browser, {
+            file: opts.abs,
+            projectRoot: opts.projectRoot,
+            outDir: opts.outDir,
+            assetClass: opts.assetClass,
+            delivery: opts.delivery,
+            thresholdsFile: opts.thresholds,
+            iconSet: opts.iconSet,
+            compareTo: opts.compareTo,
+            registration: opts.registration,
+        });
+        // Finding 8 of this change's completion review: ONE evaluation. The
+        // spread below used to call this twice — once as the truthiness guard,
+        // once for the value — so the verified path re-read the file, re-hashed
+        // it and re-ran the whole rule suite, and the two reads could disagree
+        // if the file moved between them.
+        const staticReading = staticWitness(opts.abs, opts.delivery);
+        const manifest = {
+            schema: 1,
+            generated_at: new Date().toISOString(),
+            target: opts.target,
+            slug: opts.slug,
+            captures: [],
+            palette: [],
+            type_families: [],
+            verification: result.verification,
+            profile: 'asset',
+            // Step 2.3. Written on EVERY asset render, by the only layer that
+            // could plausibly be mistaken for the one deciding it. A reader who
+            // sees `verification: verified` and no goal field has to supply the
+            // missing half themselves, which is exactly how `verified` came to
+            // be read as "the graphic is right".
+            goal: 'unassessed',
+            asset: result.reading,
+            // The static witness on the same digest, on the verified path too —
+            // the gate's digest-match discharge reads the ASSET reading, but a
+            // human comparing two manifests should not have to tell whether the
+            // static layer ran from which path produced the file.
+            ...(staticReading ? { static: staticReading } : {}),
+            ...(result.degradationReason ? { degradation_reason: result.degradationReason } : {}),
+            ...(result.verification === 'verified' ? {} : { reason: 'render-failed' }),
+        };
+        writeManifest(opts.outDir, manifest);
+        if (opts.json)
+            process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+        else {
+            const r = result.reading;
+            process.stdout.write(`✅  ui:render --profile asset — ${r.asset_class}` +
+                `${r.asset_class_inferred ? ' (inferred)' : ''}, ${r.sizes.length} capture(s), ` +
+                `${r.findings.length} finding(s), ${r.network.aborted} request(s) aborted\n` +
+                `    ${path.relative(opts.projectRoot, opts.outDir)}\n` +
+                r.findings.map((f) => `    ⚠️  ${f.rule} — ${f.detail}\n`).join(''));
+        }
+        return 0;
+    }
+    catch (err) {
+        const manifest = {
+            schema: 1,
+            generated_at: new Date().toISOString(),
+            target: opts.target,
+            slug: opts.slug,
+            captures: [],
+            palette: [],
+            type_families: [],
+            verification: 'degraded',
+            profile: 'asset',
+            // A renderer that RAN and failed, which is not the same fact as a
+            // renderer that is absent — the turn-end gate discharges an SVG
+            // obligation on the second and never on the first.
+            reason: 'render-failed',
+            goal: 'unassessed',
+            degradation_reason: `asset capture failed: ${String(err)}`,
+        };
+        writeManifest(opts.outDir, manifest);
+        process.stderr.write(`[ui:render] ${manifest.degradation_reason}\n`);
+        return 1;
+    }
+    finally {
+        // The Class-A boundary, same clause as the page profile's.
+        await browser?.close();
+    }
+}
 function writeManifest(outDir, manifest) {
     fs.mkdirSync(outDir, { recursive: true });
     fs.writeFileSync(path.join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);