rcf-lite 0.0.1 → 0.8.0

package/src/browser-verify/invariants.js

@@ -0,0 +1,336 @@
+// Browser-verification invariants (ui-design-gate-0.7.0-spec §8.3).
+//
+// v1 invariant set is module-encoded (§12 O-6 Decided): the record
+// carries free-string invariant names, and adding an invariant is a
+// build minor bump with no schema-versioning ceremony. v2 can
+// schema-encode once the set stabilises.
+//
+// Every invariant here is deterministic against a DOM string plus a
+// FBS + baseline context. The `agentScreenshotCritique` mode calls
+// these against markup the driven browser returned; the operator-
+// session mode does not invoke them (the operator's ack is the
+// evidence, spec §8.2). Severities are the runtime enforcement:
+// `block` refuses at the finalise gate, `warn` requires operator ack,
+// `advisory` records the finding without gating.
+
+/**
+ * @typedef {'block'|'warn'|'advisory'} InvariantSeverity
+ * @typedef {'pass'|'warn'|'fail'} InvariantVerdict
+ */
+
+/**
+ * @typedef {object} InvariantResult
+ * @property {string} invariant
+ * @property {InvariantVerdict} verdict
+ * @property {string} [detail]
+ * @property {InvariantSeverity} severity
+ */
+
+/**
+ * @typedef {object} InvariantContext
+ * @property {string} routePath                  path of the route being checked
+ * @property {'light'|'dark'} themeApplied       theme active during capture
+ * @property {object} fbs                        the FBS being verified
+ * @property {object} [uiBaseline]               the manifest uiBaseline record (defaults + opt-outs)
+ * @property {string} dom                        the response HTML for the route
+ * @property {boolean} [authenticated]           whether the request carried the auth cookie
+ */
+
+const OPT_OUT_FIELDS = new Set([
+  'themeMode',
+  'sharedLayoutModule',
+  'authFlow.htmlLoginPageRequired',
+]);
+
+const V1_INVARIANTS = [
+  {
+    name: 'sharedNavPresent',
+    severity: 'block',
+    perThemeOnly: false,
+    run: checkSharedNavPresent,
+  },
+  {
+    name: 'activeNavMarked',
+    severity: 'block',
+    perThemeOnly: false,
+    run: checkActiveNavMarked,
+  },
+  {
+    name: 'signedInAsAffordance',
+    severity: 'block',
+    perThemeOnly: false,
+    run: checkSignedInAsAffordance,
+  },
+  {
+    name: 'themeToggleVisible',
+    severity: 'block',
+    perThemeOnly: false,
+    run: checkThemeToggleVisible,
+  },
+  {
+    name: 'themeDefaultsToLight',
+    severity: 'warn',
+    perThemeOnly: true, // only fires on the light-capture without a cookie
+    run: checkThemeDefaultsToLight,
+  },
+  {
+    name: 'focusRingsVisible',
+    severity: 'warn',
+    perThemeOnly: false,
+    run: checkFocusRingsVisible,
+  },
+  {
+    name: 'sharedLayoutModule',
+    severity: 'block',
+    perThemeOnly: false,
+    run: checkSharedLayoutStructural,
+  },
+];
+
+/** Versioned constant, module-encoded per §12 O-6. */
+export const UI_INVARIANTS_V1 = Object.freeze(V1_INVARIANTS.map((i) => Object.freeze({ name: i.name, severity: i.severity })));
+
+/**
+ * Run the v1 invariant set against a single (route × theme × DOM)
+ * capture. Returns one result per invariant.
+ *
+ * @param {InvariantContext} ctx
+ * @returns {InvariantResult[]}
+ */
+export function runInvariantsForCapture(ctx) {
+  /** @type {InvariantResult[]} */
+  const results = [];
+  for (const inv of V1_INVARIANTS) {
+    // `themeDefaultsToLight` only makes sense on the "no cookie, first
+    // load" light capture; other invariants fire per capture.
+    if (inv.perThemeOnly && ctx.themeApplied !== 'light') continue;
+    const raw = inv.run(ctx);
+    const detail = raw?.detail;
+    /** @type {InvariantVerdict} */
+    const verdict = raw?.verdict ?? 'pass';
+    const result = { invariant: inv.name, verdict, severity: inv.severity };
+    if (detail) result.detail = detail;
+    // Baseline opt-outs demote block -> advisory (per spec §6.3: the
+    // operator ruling wins). Only opt-outs registered for fields that
+    // map to invariant enforcement.
+    if (verdict !== 'pass' && isOptedOut(inv.name, ctx.uiBaseline)) {
+      result.severity = 'advisory';
+      result.detail = (detail ? detail + ' ' : '') + '(opt-out recorded on uiBaseline)';
+    }
+    results.push(result);
+  }
+  return results;
+}
+
+/**
+ * Aggregate one route's results into a `browserVerificationInvariantCheck[]`
+ * array as it lands on the record (spec §3.3). One entry per invariant,
+ * with the per-route + per-theme details flattened into the detail
+ * string when the invariant ran per capture.
+ *
+ * @param {Array<{ routePath: string, themeApplied: 'light'|'dark', results: InvariantResult[] }>} perCapture
+ * @returns {Array<{ invariant: string, verdict: InvariantVerdict, detail?: string, severity: InvariantSeverity }>}
+ */
+export function foldInvariantsForRecord(perCapture) {
+  /** @type {Map<string, { invariant: string, verdict: InvariantVerdict, severity: InvariantSeverity, details: string[] }>} */
+  const byName = new Map();
+  for (const cap of perCapture) {
+    for (const r of cap.results) {
+      const cursor = byName.get(r.invariant) ?? { invariant: r.invariant, verdict: 'pass', severity: r.severity, details: [] };
+      cursor.verdict = worstOf(cursor.verdict, r.verdict);
+      cursor.severity = mostSevere(cursor.severity, r.severity);
+      if (r.verdict !== 'pass' && r.detail) {
+        cursor.details.push(`${cap.routePath}[${cap.themeApplied}]: ${r.detail}`);
+      }
+      byName.set(r.invariant, cursor);
+    }
+  }
+  const out = [];
+  for (const cursor of byName.values()) {
+    const entry = { invariant: cursor.invariant, verdict: cursor.verdict, severity: cursor.severity };
+    if (cursor.details.length > 0) entry.detail = cursor.details.join(' | ');
+    out.push(entry);
+  }
+  return out;
+}
+
+function worstOf(a, b) {
+  const order = { pass: 0, warn: 1, fail: 2 };
+  return (order[b] > order[a]) ? b : a;
+}
+function mostSevere(a, b) {
+  const order = { advisory: 0, warn: 1, block: 2 };
+  return (order[b] > order[a]) ? b : a;
+}
+
+function isOptedOut(invariantName, baseline) {
+  const optOuts = Array.isArray(baseline?.operatorOptOuts) ? baseline.operatorOptOuts : [];
+  if (invariantName === 'themeDefaultsToLight' && optOuts.some((o) => OPT_OUT_FIELDS.has(o.field) && o.field === 'themeMode')) return true;
+  if (invariantName === 'sharedNavPresent' && optOuts.some((o) => o.field === 'sharedLayoutModule')) return true;
+  if (invariantName === 'sharedLayoutModule' && optOuts.some((o) => o.field === 'sharedLayoutModule')) return true;
+  return false;
+}
+
+// ---------- individual checks (each returns { verdict, detail? }) ----------
+
+function checkSharedNavPresent(ctx) {
+  const routes = ctx.fbs?.designStage?.navModel?.routes ?? [];
+  const authRoutes = routes.filter((r) => r.authRequired);
+  if (authRoutes.length === 0) return { verdict: 'pass' };
+  if (!/<nav\b/i.test(ctx.dom)) {
+    return { verdict: 'fail', detail: 'no <nav> element in the response HTML for an authenticated route' };
+  }
+  // Every enumerated route must appear as <a href="..."> OR (for the
+  // current route) as a non-anchor stand-in - either the same path in
+  // a <span>/<a> without href, or a labelled non-anchor. v1 heuristic:
+  // pass when path shows up somewhere inside the <nav>.
+  const navMatch = /<nav\b[\s\S]*?<\/nav>/i.exec(ctx.dom);
+  const navMarkup = navMatch ? navMatch[0] : '';
+  const missing = [];
+  for (const r of routes) {
+    const patternPath = escapeForRegExp(r.path);
+    const patternLabel = escapeForRegExp(r.label);
+    const found = new RegExp(`href=["']${patternPath}["']`, 'i').test(navMarkup)
+      || new RegExp(`>${patternLabel}<`, 'i').test(navMarkup);
+    if (!found) missing.push(r.path);
+  }
+  if (missing.length > 0) {
+    return { verdict: 'fail', detail: `<nav> missing enumerated route(s): ${missing.join(', ')}` };
+  }
+  return { verdict: 'pass' };
+}
+
+function checkActiveNavMarked(ctx) {
+  const routes = ctx.fbs?.designStage?.navModel?.routes ?? [];
+  const authRoutes = routes.filter((r) => r.authRequired);
+  if (authRoutes.length === 0) return { verdict: 'pass' };
+  if (!/aria-current=["']page["']/i.test(ctx.dom)) {
+    return { verdict: 'fail', detail: 'no element carries aria-current="page" (active-nav marker missing)' };
+  }
+  // We do NOT verify that the aria-current landed on the CURRENT
+  // route's link (that would require request-to-route mapping in the
+  // driver; v1 keeps this cheap and delegates that mapping to the
+  // agent-critique rubric).
+  return { verdict: 'pass' };
+}
+
+function checkSignedInAsAffordance(ctx) {
+  const affordance = ctx.fbs?.designStage?.navModel?.signedInAsAffordance;
+  if (affordance !== true) return { verdict: 'pass' };
+  if (ctx.authenticated === false) return { verdict: 'pass' };
+  const hasText = /signed[\s-]in as|logged[\s-]in as/i.test(ctx.dom);
+  const hasLogout = /href=["'][^"']*\/logout["']/i.test(ctx.dom);
+  if (hasText || hasLogout) return { verdict: 'pass' };
+  return { verdict: 'fail', detail: 'no signed-in-as text and no /logout link visible on an authenticated route' };
+}
+
+function checkThemeToggleVisible(ctx) {
+  // Widened recognition set per N7 (spec §8.3): any of (a)
+  // [data-theme-toggle], (b) id/class matching /theme-toggle|toggle-theme/i,
+  // (c) accessible name containing "theme" (aria-label / aria-labelledby /
+  // inner text).
+  if (/data-theme-toggle/i.test(ctx.dom)) return { verdict: 'pass' };
+  if (/(?:id|class)=["'][^"']*(?:theme[\s-]?toggle|toggle[\s-]?theme)[^"']*["']/i.test(ctx.dom)) return { verdict: 'pass' };
+  if (/aria-label=["'][^"']*theme[^"']*["']/i.test(ctx.dom)) return { verdict: 'pass' };
+  // Inner-text heuristic: an element whose direct inner text contains
+  // "theme" (case-insensitive). Cheap without a real DOM parser.
+  if (/>[^<]*theme[^<]*</i.test(ctx.dom)) return { verdict: 'pass' };
+  return { verdict: 'fail', detail: 'no theme toggle detectable in the response HTML' };
+}
+
+function checkThemeDefaultsToLight(ctx) {
+  // Only meaningful on the "no cookie" first load. The runner is
+  // expected to fire this against a light capture with no cookie; here
+  // we just check the served theme attribute matches.
+  const match = /<html\b[^>]*data-theme=["']([^"']+)["']/i.exec(ctx.dom);
+  const served = match?.[1] ?? null;
+  const expected = ctx.uiBaseline?.defaults?.themeMode === 'dark-default-with-toggle' ? 'dark'
+    : ctx.uiBaseline?.defaults?.themeMode === 'single-theme-declared' ? null
+      : 'light';
+  if (expected === null) return { verdict: 'pass' };
+  if (served === expected) return { verdict: 'pass' };
+  return { verdict: 'fail', detail: `<html data-theme> served '${served ?? '(unset)'}' but the baseline expects '${expected}' on a first-load without a theme cookie` };
+}
+
+function checkFocusRingsVisible(ctx) {
+  // Cheap chain-shaped heuristic: the response HTML mentions a focus
+  // style (either an inline focus-ring rule or a class that reads as
+  // one). The real check happens agent-side against a tab-focused
+  // screenshot; v1 records `advisory` when the heuristic is
+  // inconclusive so operators know to eyeball. spec §8.3 severity `warn`.
+  if (/focus-visible|focus-ring|outline\s*:/i.test(ctx.dom)) return { verdict: 'pass' };
+  return { verdict: 'warn', detail: 'no focus-ring style detected in the response HTML (visually confirm agent-side)' };
+}
+
+function checkSharedLayoutStructural(ctx) {
+  // The record-shape reduction: pass on the individual capture; the
+  // structural cross-route compare lives at the fold stage
+  // (`compareTopLevelStructure` below) and is called from the runner.
+  return { verdict: 'pass' };
+}
+
+/**
+ * Compare top-level element sequences across multiple captured DOMs.
+ * Returns a `sharedLayoutModule` invariant result to append to the
+ * record when the sequences differ meaningfully (§8.3).
+ *
+ * @param {Array<{ routePath: string, dom: string }>} captures
+ * @param {object} [baseline]
+ * @returns {InvariantResult}
+ */
+export function compareTopLevelStructure(captures, baseline) {
+  const auth = captures.filter((c) => c.dom);
+  if (auth.length < 2) {
+    return { invariant: 'sharedLayoutModule', verdict: 'pass', severity: 'block' };
+  }
+  const structures = auth.map((c) => topLevelChildTagSequence(c.dom));
+  const [reference, ...rest] = structures;
+  const mismatched = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    if (!arraysEqual(rest[i], reference)) mismatched.push(auth[i + 1].routePath);
+  }
+  const severity = isOptedOut('sharedLayoutModule', baseline) ? 'advisory' : 'block';
+  if (mismatched.length === 0) return { invariant: 'sharedLayoutModule', verdict: 'pass', severity };
+  return {
+    invariant: 'sharedLayoutModule',
+    verdict: 'fail',
+    detail: `top-level DOM structure diverges between ${auth[0].routePath} and ${mismatched.join(', ')} (spec §8.3 structural check)`,
+    severity,
+  };
+}
+
+function topLevelChildTagSequence(dom) {
+  // Extract the tag-name sequence of direct children of <body>. Cheap
+  // regex-based; deliberately conservative (misses nested body-siblings
+  // in unusual documents but catches the two-shells watchpost pattern).
+  const bodyMatch = /<body\b[^>]*>([\s\S]*?)<\/body>/i.exec(dom);
+  const source = bodyMatch ? bodyMatch[1] : dom;
+  const tags = [];
+  const re = /<([a-zA-Z][a-zA-Z0-9-]*)\b/g;
+  let m;
+  let depth = 0;
+  let index = 0;
+  while ((m = re.exec(source)) !== null) {
+    if (depth === 0 && index === m.index) tags.push(m[1].toLowerCase());
+    // Depth tracking is imprecise for self-closing tags; the check
+    // exists as a coarse divergence signal, not a formal parser.
+    if (source[m.index + 1] !== '/') depth += 1;
+    // Advance index heuristically to next top-level opening.
+    const closeIdx = source.indexOf(`</${m[1]}>`, m.index);
+    if (closeIdx < 0) break;
+    depth = Math.max(0, depth - 1);
+    index = closeIdx + `</${m[1]}>`.length;
+    re.lastIndex = index;
+  }
+  return tags;
+}
+
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+function escapeForRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/browser-verify/manifest-writer.js

@@ -0,0 +1,189 @@
+// Browser-verification record composer + writer
+// (ui-design-gate-0.7.0-spec §3.3, §8).
+
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '#core/errors';
+import { validateDocument } from '#core/store';
+
+/**
+ * Compute the next `bv-<fbsId>-<n>` id: monotonic per FBS.
+ *
+ * @param {object|null} manifest
+ * @param {string} fbsId
+ * @returns {string}
+ */
+export function nextBrowserVerificationId(manifest, fbsId) {
+  const prefix = `bv-${fbsId}-`;
+  const existing = Array.isArray(manifest?.browserVerification) ? manifest.browserVerification : [];
+  let maxN = 0;
+  for (const rec of existing) {
+    if (typeof rec?.id !== 'string' || !rec.id.startsWith(prefix)) continue;
+    const n = Number.parseInt(rec.id.slice(prefix.length), 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  return `${prefix}${maxN + 1}`;
+}
+
+/**
+ * Aggregate the record verdict per spec §8.5:
+ *   block if any invariant severity=block verdict=fail, OR any auth smoke fail;
+ *   warn if any invariant severity=warn verdict=fail (and no block);
+ *   pass otherwise.
+ *
+ * @param {Array<{ invariant: string, verdict: 'pass'|'warn'|'fail', severity: 'block'|'warn'|'advisory' }>} invariantChecks
+ * @param {Array<{ verdict: 'pass'|'warn'|'fail' }>} authSmokeChecks
+ * @returns {'pass'|'warn'|'block'}
+ */
+export function aggregateVerdict(invariantChecks, authSmokeChecks) {
+  for (const check of invariantChecks) {
+    if (check.severity === 'block' && check.verdict === 'fail') return 'block';
+  }
+  for (const check of authSmokeChecks ?? []) {
+    if (check.verdict === 'fail') return 'block';
+  }
+  for (const check of invariantChecks) {
+    if (check.severity === 'warn' && (check.verdict === 'fail' || check.verdict === 'warn')) return 'warn';
+  }
+  return 'pass';
+}
+
+/**
+ * Compose a `browserVerification` record ready to append.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} args.fbsId
+ * @param {'operatorSession'|'agentScreenshotCritique'} args.mode
+ * @param {'deployed'|'ci'|'local-dev'} args.runtimeProfile
+ * @param {string} args.runtimeUrl
+ * @param {Array<{ path: string, screenshotPath: string, themeApplied: 'light'|'dark' }>} args.routesChecked
+ * @param {Array<{ invariant: string, verdict: 'pass'|'warn'|'fail', detail?: string, severity: 'block'|'warn'|'advisory' }>} args.invariantChecks
+ * @param {Array<{ check: string, status?: number, contentType?: string, verdict: 'pass'|'warn'|'fail', detail?: string }>} [args.authSmokeChecks]
+ * @param {string} [args.notes]
+ * @param {Date} [args.now]
+ * @returns {object}
+ */
+export function composeBrowserVerificationRecord({
+  manifest, fbsId, mode, runtimeProfile, runtimeUrl, routesChecked,
+  invariantChecks, authSmokeChecks = [], notes, now = new Date(),
+}) {
+  const id = nextBrowserVerificationId(manifest, fbsId);
+  const verdict = aggregateVerdict(invariantChecks, authSmokeChecks);
+  const record = {
+    id,
+    fbsId,
+    createdAt: now.toISOString(),
+    mode,
+    runtimeProfile,
+    runtimeUrl,
+    routesChecked: routesChecked.map((r) => ({ path: r.path, screenshotPath: r.screenshotPath, themeApplied: r.themeApplied })),
+    invariantChecks: invariantChecks.map((c) => stripSeverity(c)),
+    verdict,
+  };
+  if (authSmokeChecks && authSmokeChecks.length > 0) record.authSmokeChecks = authSmokeChecks;
+  if (typeof notes === 'string' && notes.length > 0) record.notes = notes;
+  return record;
+}
+
+function stripSeverity(check) {
+  const out = { invariant: check.invariant, verdict: check.verdict };
+  if (typeof check.detail === 'string' && check.detail.length > 0) out.detail = check.detail;
+  return out;
+}
+
+/**
+ * Persist a composed `browserVerification` record on the manifest.
+ * Atomic tmp-and-rename, schema-validated before write.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {object} args.record
+ * @param {object} [args.options]
+ * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
+ */
+export async function writeBrowserVerificationRecord({ projectRoot, tree, record, options = {} }) {
+  const manifest = tree.manifest ?? {};
+  const nextManifest = { ...manifest };
+  const existing = Array.isArray(nextManifest.browserVerification) ? nextManifest.browserVerification : [];
+  nextManifest.browserVerification = [...existing, record];
+
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });
+  if (validation) return validation;
+
+  if (options.dryRun) return { record, dryRun: true };
+
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, absPath);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `browser-verify: manifest write failed: ${err.message}`,
+      filePath: relPath,
+      stack: err.stack,
+    });
+  }
+  return { record };
+}
+
+/**
+ * Append `operatorAckAt` or `operatorShipDespiteBlockReason` to the
+ * latest `browserVerification` record for a FBS.
+ *
+ * @param {object} args
+ * @returns {Promise<{ record: object } | import('#core/errors').RcfError>}
+ */
+export async function writeBrowserVerificationAck({
+  projectRoot, tree, fbsId, operatorAckAt, operatorShipDespiteBlockReason, now = new Date(),
+}) {
+  const manifest = tree.manifest ?? {};
+  const records = Array.isArray(manifest.browserVerification) ? manifest.browserVerification : [];
+  const latestIdx = findLatestRecordIndex(records, fbsId);
+  if (latestIdx < 0) {
+    return rcfError({
+      kind: 'usage',
+      message: `browser-verify --ack: no browserVerification record exists for ${fbsId} yet.`,
+    });
+  }
+  const isoNow = now.toISOString();
+  const nextManifest = { ...manifest };
+  const next = [...records];
+  const target = { ...next[latestIdx] };
+  if (operatorAckAt) target.operatorAckAt = operatorAckAt === true ? isoNow : String(operatorAckAt);
+  if (operatorShipDespiteBlockReason) target.operatorShipDespiteBlockReason = operatorShipDespiteBlockReason;
+  next[latestIdx] = target;
+  nextManifest.browserVerification = next;
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });
+  if (validation) return validation;
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try { await rename(tmp, absPath); } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `browser-verify --ack: manifest write failed: ${err.message}`, filePath: relPath, stack: err.stack });
+  }
+  return { record: target };
+}
+
+function findLatestRecordIndex(records, fbsId) {
+  for (let i = records.length - 1; i >= 0; i -= 1) if (records[i]?.fbsId === fbsId) return i;
+  return -1;
+}