@ultimat3/cli 20.2.1 → 22.0.0

package/src/e2e-locator.ts

@@ -1,86 +0,0 @@
-// `LocatorLike` over a browser page: a handle that holds a SELECTION and resolves nothing until
-// something asks. One round trip per question, and no waiting of its own — `toBeVisible()` owns
-// the only retry budget in the harness and drives this by looking again.
-
-import type { LocatorLike } from '@ultimat3/testing';
-import { E2eLocatorAmbiguousError, E2eLocatorEmptyError } from './e2e-errors';
-import type { E2eResolution, E2eSelection } from './e2e-selection';
-import { markSelector, selectionExpression, unmarkExpression } from './e2e-selection';
-
-/**
- * What a locator needs from the browser. Narrower than `ScrapePage` on purpose: three methods is
- * what a test has to stand up to prove the mapping, and `click` is taken from the page rather than
- * re-derived here so the actionability wait `@ultimat3/scraping` already performs is the one that
- * runs.
- */
-export interface LocatablePage {
-  evaluate(expression: string): Promise<unknown>;
-  click(selector: string): Promise<void>;
-  url(): string;
-}
-
-const readResolution = (raw: unknown): E2eResolution => {
-  const decoded = typeof raw === 'string' ? (JSON.parse(raw) as unknown) : raw;
-  const held = decoded as { count?: unknown; visible?: unknown; marked?: unknown };
-  return {
-    count: typeof held?.count === 'number' ? held.count : 0,
-    visible: held?.visible === true,
-    marked: held?.marked === true,
-  };
-};
-
-/**
- * One mark per click, never a constant: two locators marking the same page at once would each
- * click whichever element the other had just tagged. Seeded from a counter and not from
- * `Math.random()`, which `bun run flight-copies` refuses in shipped source and which would make
- * two runs of one test address two different elements.
- */
-let marks = 0;
-const nextMark = (): string => {
-  marks += 1;
-  return `m${String(marks)}`;
-};
-
-/** Test seam: the counter is process-global, so a test that asserts a mark resets it first. */
-export const resetLocatorMarks = (): void => {
-  marks = 0;
-};
-
-/**
- * Nothing is cached. A locator taken before a navigation must address the page that is there when
- * it is USED — the same rule `ScrapeFrame` states for a frame handle — so every method below
- * re-resolves, and a handle can never go stale behind the caller's back.
- */
-export function e2eLocator(page: LocatablePage, selection: E2eSelection): LocatorLike {
-  const resolve = async (mark?: string): Promise<E2eResolution> =>
-    readResolution(await page.evaluate(selectionExpression(selection, mark)));
-
-  return {
-    count: async () => (await resolve()).count,
-    /**
-     * A point-in-time look, and deliberately not an ambiguity check: an assertion handed a locator
-     * that matched three elements has an ANSWER — was the first one visible — and a refusal there
-     * would turn `expect(...).toBeVisible()` into a crash rather than a verdict. Only `click`
-     * refuses, because only `click` has to pick one.
-     */
-    isVisible: async () => (await resolve()).visible,
-    first: () => e2eLocator(page, { ...selection, first: true }),
-    click: async () => {
-      const mark = nextMark();
-      const resolution = await resolve(mark);
-      if (resolution.count === 0) {
-        throw new E2eLocatorEmptyError({ selection, url: page.url() });
-      }
-      if (resolution.count > 1 && !selection.first) {
-        throw new E2eLocatorAmbiguousError({ selection, count: resolution.count });
-      }
-      try {
-        await page.click(markSelector(mark));
-      } finally {
-        // Best effort, and never allowed to replace the click's own failure: a click that
-        // navigated took the whole document — attribute included — with it.
-        await page.evaluate(unmarkExpression(mark)).catch(() => undefined);
-      }
-    },
-  };
-}

package/src/e2e-page.ts

@@ -1,150 +0,0 @@
-// `PageLike` over a browser page. The adapter itself: `@ultimat3/testing` declares the surface an
-// e2e test drives and `@ultimat3/scraping` owns the only driver that can drive one, and neither
-// may import the other — so the join is here, in the one package allowed to know about both.
-
-import { finiteCount } from '@ultimat3/core';
-import type { LocatorLike, PageLike } from '@ultimat3/testing';
-import { E2eServiceWorkerAbsentError } from './e2e-errors';
-import { evaluateClosure } from './e2e-evaluate';
-import { e2eLocator } from './e2e-locator';
-import type { E2eSelection } from './e2e-selection';
-
-/**
- * What this adapter needs of a browser: four required members, every one of them on `ScrapePage`.
- * Declared structurally rather than as `ScrapePage` so a test can stand one up in six lines — the
- * same bargain `cdp-port.ts` makes about puppeteer, one layer up.
- */
-export interface E2eBrowserPage {
-  url(): string;
-  goto(url: string, options?: { readonly timeout?: number | undefined }): Promise<unknown>;
-  evaluate(expression: string): Promise<unknown>;
-  click(selector: string): Promise<void>;
-  /**
-   * The browser's own network condition, which `E2eFixtures.offline()`/`online()` forward to.
-   * `ScrapePage` has it (`page-over-target.ts`), reaching `CdpPageLike.setOfflineMode` through
-   * `cdp-target.ts`'s guard.
-   *
-   * OPTIONAL for the reason the four above are structural: this port is the shape of somebody
-   * ELSE's object, and requiring it would cost every six-line double a type error for a capability
-   * a test that never goes offline does not need. Absent, `e2e-driver.ts` keeps refusing by name —
-   * a coded refusal, never a silent no-op, because an `offline()` that did nothing would let the
-   * app's ONLINE page pass an offline test.
-   */
-  offline?(enabled: boolean): Promise<void>;
-}
-
-export interface E2ePageOptions {
-  readonly page: E2eBrowserPage;
-  /** Every `goto('/feed')` in an e2e suite is app-relative; this is what makes one absolute. */
-  readonly baseUrl: string;
-  /** Per-navigation deadline, handed to the driver rather than enforced here. */
-  readonly timeoutMs?: number | undefined;
-  /** How long `waitForServiceWorker()` waits before refusing. Bounded IN THE PAGE. */
-  readonly serviceWorkerTimeoutMs?: number | undefined;
-}
-
-/** Named once, so both refusals below name the call an app's test preload actually makes. */
-const SUBJECT = 'installE2eDriver';
-
-export const DEFAULT_E2E_TIMEOUT_MS = 30_000;
-export const DEFAULT_SERVICE_WORKER_TIMEOUT_MS = 10_000;
-
-/** Every in-page expression here answers JSON text, for the reason `cdp-snapshot.ts` states. */
-const readField = (raw: unknown, key: string): unknown => {
-  const decoded = typeof raw === 'string' ? (JSON.parse(raw) as unknown) : raw;
-  return typeof decoded === 'object' && decoded !== null
-    ? (decoded as Record<string, unknown>)[key]
-    : undefined;
-};
-
-const TITLE = '(() => JSON.stringify({ title: document.title }))()';
-
-/**
- * The first flush, read by a `fetch` INSIDE the page after the navigation, because neither
- * `ScrapePage` nor `CdpPageLike` exposes a response body — puppeteer's `page.on('response')` is
- * not on the port and adding it would be an edit to `@ultimat3/scraping`.
- *
- * The cost, stated rather than hidden: this is a SECOND request to the same route, so what it
- * measures is that route's streaming behaviour and not the byte-for-byte first chunk the open
- * document received. It runs in the page, so it carries the page's cookies and its origin — a
- * `fetch` from the test process would carry neither.
- */
-const firstFlushExpression = (url: string): string =>
-  `(() => fetch(${JSON.stringify(url)}, { credentials: 'same-origin' })
-    .then((response) => response.body.getReader().read())
-    .then((chunk) => JSON.stringify({ html: new TextDecoder().decode(chunk.value || new Uint8Array()) })))()`;
-
-/**
- * `ready` alone is not control: a first load activates a worker that is not yet the page's
- * controller, and an offline assertion made in that window tests nothing. So this waits for
- * `controllerchange` too — an EVENT, not a poll, so the harness still has exactly one retry loop.
- */
-const serviceWorkerExpression = (timeoutMs: number): string =>
-  `(() => {
-  if (!navigator.serviceWorker) return JSON.stringify({ controlled: false });
-  const controlled = new Promise((resolve) => {
-    if (navigator.serviceWorker.controller) { resolve(true); return; }
-    navigator.serviceWorker.addEventListener('controllerchange', () => resolve(true), { once: true });
-  });
-  const deadline = new Promise((resolve) => setTimeout(() => resolve(false), ${String(timeoutMs)}));
-  return Promise.race([navigator.serviceWorker.ready.then(() => controlled), deadline])
-    .catch(() => false)
-    .then((ok) => JSON.stringify({ controlled: ok === true }));
-})()`;
-
-/**
- * The adapter. Every member re-reads the live page: a `PageLike` handed to a test outlives every
- * navigation the test makes, so nothing here may capture a URL, a document or an element.
- */
-export function e2ePage(options: E2ePageOptions): PageLike {
-  const page = options.page;
-  // Both are screened HERE, at construction, and not where they land: `timeout` is handed to a
-  // driver that reads it as a deadline, and `swTimeout` is INTERPOLATED into the in-page source,
-  // where `setTimeout(fn, NaN)` is `setTimeout(fn, 0)` — so a NaN budget makes every
-  // `waitForServiceWorker()` refuse a worker that really did take control. A misdiagnosis reported
-  // as a test failure is worse than the failure. Floor 0, because a driver reads `timeout: 0` as
-  // "no deadline" and that is a value an app is entitled to declare.
-  const timeout = finiteCount(SUBJECT, 'timeoutMs', options.timeoutMs ?? DEFAULT_E2E_TIMEOUT_MS);
-  const swTimeout = finiteCount(
-    SUBJECT,
-    'serviceWorkerTimeoutMs',
-    options.serviceWorkerTimeoutMs ?? DEFAULT_SERVICE_WORKER_TIMEOUT_MS,
-  );
-  const absolute = (url: string): string => new URL(url, options.baseUrl).toString();
-  const locate = (selection: E2eSelection): LocatorLike => e2eLocator(page, selection);
-
-  return {
-    url: () => page.url(),
-    goto: (url) => page.goto(absolute(url), { timeout }),
-    // The page's OWN url, re-read at call time: a reload of the url the adapter was built with
-    // would navigate away from wherever the test had got to.
-    reload: () => page.goto(page.url(), { timeout }),
-    title: async () => {
-      const title = readField(await page.evaluate(TITLE), 'title');
-      return typeof title === 'string' ? title : '';
-    },
-    gotoStreamed: async (url) => {
-      const target = absolute(url);
-      await page.goto(target, { timeout });
-      const html = readField(await page.evaluate(firstFlushExpression(target)), 'html');
-      return { html: typeof html === 'string' ? html : '' };
-    },
-    waitForServiceWorker: async () => {
-      const raw = await page.evaluate(serviceWorkerExpression(swTimeout));
-      if (readField(raw, 'controlled') !== true) {
-        throw new E2eServiceWorkerAbsentError({ url: page.url(), timeoutMs: swTimeout });
-      }
-    },
-    evaluate: <T>(fn: () => T): Promise<T> => evaluateClosure(page, fn) as unknown as Promise<T>,
-    locator: (selector) => locate({ kind: 'css', selector, first: false }),
-    getByRole: (role, roleOptions) =>
-      locate({
-        kind: 'role',
-        role,
-        first: false,
-        ...(roleOptions?.name === undefined ? {} : { name: roleOptions.name }),
-        ...(roleOptions?.level === undefined ? {} : { level: roleOptions.level }),
-      }),
-    getByText: (text) => locate({ kind: 'text', text, first: false }),
-  };
-}

package/src/e2e-selection.ts

@@ -1,182 +0,0 @@
-// What an e2e locator SELECTS, as a value, plus the one in-page expression that resolves it.
-// `locator`/`getByRole`/`getByText` are lazy handles, so the selection has to survive as data
-// until something asks a question about it — and only then does it become a string the browser
-// can run.
-
-/** Where the driver parks its click target. Removed again as soon as the click has been made. */
-export const MARK_ATTRIBUTE = 'data-x-e2e';
-
-/** One selection, exactly as the test spelled it. `first` is `.first()`, applied at resolve time. */
-export type E2eSelection =
-  | { readonly kind: 'css'; readonly selector: string; readonly first: boolean }
-  | {
-      readonly kind: 'role';
-      readonly role: string;
-      readonly name?: string | undefined;
-      readonly level?: number | undefined;
-      readonly first: boolean;
-    }
-  | { readonly kind: 'text'; readonly text: string; readonly first: boolean };
-
-/**
- * What the page answers for one selection. `count` is how many elements matched AFTER `first`
- * narrowed it, `visible` is about the first match alone, and `marked` says the click target now
- * carries `MARK_ATTRIBUTE` — three facts in one round trip, because a locator that asked twice
- * could be answered about two different renders.
- */
-export interface E2eResolution {
-  readonly count: number;
-  readonly visible: boolean;
-  readonly marked: boolean;
-}
-
-/**
- * The elements that carry a role IMPLICITLY, so `getByRole('button')` finds a `<button>` that
- * never wrote the attribute. A `Map` and not an object literal: the key is a role a test typed,
- * and a computed read of a `Record` answers `Object.prototype` members — the defect
- * `bun run proto-index` exists for.
- *
- * Deliberately not the whole of WAI-ARIA. A role absent from this table still resolves through
- * its explicit `[role="…"]` attribute, which is why an unknown role is not refused: refusing
- * `role="feed"` because a table in the framework is short would be the framework deciding an app's
- * markup is wrong.
- */
-const IMPLICIT_ROLE_ELEMENTS = new Map<string, readonly string[]>([
-  ['banner', ['header']],
-  ['button', ['button', 'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]']],
-  ['checkbox', ['input[type="checkbox"]']],
-  ['combobox', ['select']],
-  ['contentinfo', ['footer']],
-  ['dialog', ['dialog']],
-  ['form', ['form']],
-  ['heading', ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']],
-  ['img', ['img']],
-  ['link', ['a[href]']],
-  ['list', ['ul', 'ol']],
-  ['listitem', ['li']],
-  ['main', ['main']],
-  ['navigation', ['nav']],
-  ['option', ['option']],
-  ['radio', ['input[type="radio"]']],
-  ['table', ['table']],
-  ['textbox', ['input[type="text"]', 'input[type="email"]', 'input[type="search"]', 'textarea']],
-]);
-
-/** Elements whose text is markup rather than page copy — `getByText` must never land on one. */
-const TEXT_SKIP_TAGS = ['SCRIPT', 'STYLE', 'HEAD', 'TITLE', 'META', 'LINK', 'NOSCRIPT'];
-
-/** A CSS attribute selector takes a double-quoted string, which is what `JSON.stringify` writes. */
-const roleSelector = (role: string): string =>
-  [`[role=${JSON.stringify(role)}]`, ...(IMPLICIT_ROLE_ELEMENTS.get(role) ?? [])].join(',');
-
-/**
- * The call a test wrote, rebuilt from the selection. Every refusal below quotes it, because
- * "an e2e locator matched nothing" names no line of the test file and this does.
- */
-export function selectionCall(selection: E2eSelection): string {
-  const tail = selection.first ? '.first()' : '';
-  if (selection.kind === 'css') return `page.locator(${JSON.stringify(selection.selector)})${tail}`;
-  if (selection.kind === 'text') return `page.getByText(${JSON.stringify(selection.text)})${tail}`;
-  const options = [
-    ...(selection.name === undefined ? [] : [`name: ${JSON.stringify(selection.name)}`]),
-    ...(selection.level === undefined ? [] : [`level: ${String(selection.level)}`]),
-  ];
-  const role = JSON.stringify(selection.role);
-  const suffix = options.length === 0 ? '' : `, { ${options.join(', ')} }`;
-  return `page.getByRole(${role}${suffix})${tail}`;
-}
-
-/**
- * The candidate list, as a JS expression evaluating to an array of elements.
- *
- * `getByRole` and `getByText` are not CSS and cannot be: a role is implicit in a tag name, an
- * accessible name comes off four different attributes before it comes off the text, and
- * `getByText` has to pick the INNERMOST element that contains the string. So the union selector
- * is only the cheap first pass and every rule after it runs in JS, in the page.
- */
-function candidateSource(selection: E2eSelection): string {
-  if (selection.kind === 'css') return `all(${JSON.stringify(selection.selector)})`;
-  if (selection.kind === 'text') {
-    const needle = JSON.stringify(selection.text.replace(/\s+/g, ' ').trim().toLowerCase());
-    // Innermost FIRST and the skip list second, in that order. Reversed, `<html>` becomes the
-    // innermost survivor of a page whose only copy of the string is inside a `<script>` — the
-    // ancestor inherits the match its own excluded child made, which is worse than not filtering
-    // at all: it reports one match, at the document root, for text no reader can see.
-    return `innermost(all('*').filter((el) => norm(el.textContent).toLowerCase().indexOf(${needle}) !== -1)).filter((el) => ${JSON.stringify(TEXT_SKIP_TAGS)}.indexOf(el.tagName) === -1)`;
-  }
-  const byRole = `all(${JSON.stringify(roleSelector(selection.role))}).filter((el) => { const own = el.getAttribute('role'); return own === null || norm(own).toLowerCase() === ${JSON.stringify(selection.role.toLowerCase())}; })`;
-  const byLevel =
-    selection.level === undefined
-      ? byRole
-      : `${byRole}.filter((el) => level(el) === ${String(selection.level)})`;
-  return selection.name === undefined
-    ? byLevel
-    : `${byLevel}.filter((el) => accName(el).toLowerCase() === ${JSON.stringify(selection.name.replace(/\s+/g, ' ').trim().toLowerCase())})`;
-}
-
-/**
- * The helpers the candidate source above calls, defined once inside the IIFE.
- *
- * `visible` is `display`/`visibility`/`opacity`, which is character for character what
- * `@ultimat3/scraping`'s `snapshotExpression` computes for `ElementSnapshot.visible`. That is a
- * COPY and it is the wrong shape: `ScrapeTarget.query()` already answers a snapshot per element
- * and `ScrapeFrame` does not expose it, so this driver cannot reach the framework's one definition
- * of visible without an edit to `packages/scraping/src/page.ts`. Mirrored deliberately rather than
- * invented, so the two cannot disagree about a page until that edit lands.
- */
-const HELPERS = `
-  const norm = (s) => (s || '').replace(/\\s+/g, ' ').trim();
-  const all = (sel) => Array.prototype.slice.call(document.querySelectorAll(sel));
-  const innermost = (found) => found.filter((el) => !found.some((other) => other !== el && el.contains(other)));
-  const level = (el) => {
-    const aria = el.getAttribute('aria-level');
-    if (aria !== null) return Number(aria);
-    const tag = el.tagName.toLowerCase();
-    return /^h[1-6]$/.test(tag) ? Number(tag.slice(1)) : undefined;
-  };
-  const accName = (el) => {
-    const label = el.getAttribute('aria-label');
-    if (label !== null && norm(label) !== '') return norm(label);
-    const by = el.getAttribute('aria-labelledby');
-    if (by !== null) {
-      const parts = norm(by).split(' ').map((id) => document.getElementById(id)).filter((n) => n).map((n) => norm(n.textContent));
-      if (norm(parts.join(' ')) !== '') return norm(parts.join(' '));
-    }
-    const tag = el.tagName.toLowerCase();
-    if (tag === 'input') { const v = el.getAttribute('value'); if (v !== null && norm(v) !== '') return norm(v); }
-    if (tag === 'img') { const a = el.getAttribute('alt'); if (a !== null) return norm(a); }
-    const text = norm(el.textContent);
-    if (text !== '') return text;
-    const title = el.getAttribute('title');
-    return title !== null ? norm(title) : '';
-  };`;
-
-/**
- * Returns JSON TEXT rather than an object, the same bargain `cdp-snapshot.ts` makes: a CDP round
- * trip serialises the answer anyway, and a string has ONE deserialiser — a schema parse — instead
- * of an implicit one inside the browser library plus a cast on this side.
- */
-export function selectionExpression(selection: E2eSelection, mark?: string): string {
-  const marker = mark === undefined ? 'null' : JSON.stringify(mark);
-  return `(() => {${HELPERS}
-  const found = ${candidateSource(selection)};
-  const matches = ${selection.first ? 'found.slice(0, 1)' : 'found'};
-  const el = matches[0];
-  let visible = false;
-  if (el) {
-    const style = getComputedStyle(el);
-    visible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
-  }
-  const mark = ${marker};
-  let marked = false;
-  if (mark !== null && el) { el.setAttribute(${JSON.stringify(MARK_ATTRIBUTE)}, mark); marked = true; }
-  return JSON.stringify({ count: matches.length, visible: visible, marked: marked });
-})()`;
-}
-
-/** The CSS the marked element answers to — what `ScrapePage.click` is handed once one is marked. */
-export const markSelector = (mark: string): string => `[${MARK_ATTRIBUTE}=${JSON.stringify(mark)}]`;
-
-/** Undo. Best effort by design: a click that navigated took the whole document with it. */
-export const unmarkExpression = (mark: string): string =>
-  `(() => { const el = document.querySelector(${JSON.stringify(markSelector(mark))}); if (el) el.removeAttribute(${JSON.stringify(MARK_ATTRIBUTE)}); return JSON.stringify(true); })()`;

package/src/measurement-actor.ts

@@ -1,26 +0,0 @@
-// The actor a route is rendered AS when the render exists only to be weighed. `app/` pages are
-// authed by construction: a `load` that calls a policy-guarded query denies an anonymous actor with
-// `X_UNAUTHENTICATED`, so under the anonymous build context every authed page was reported
-// `X_BUDGET_UNMEASURED` and a real app could not pass the `budgets` step (measured 2026-09-05).
-// Weighing bytes needs no data authority — the rendered document is discarded — so this actor holds
-// every permission. It is handed ONLY to the weigh-and-discard branch of `prerender.ts`, never to
-// `renderStatic`: a `site/` artifact is published to everyone, and a guarded query inside its `load`
-// must keep failing the build rather than rendering another actor's rows into a file.
-
-import type { Actor } from '@ultimat3/core';
-
-/** The id every trace and log line under a measurement render carries, so it is recognisable. */
-export const MEASUREMENT_ACTOR_ID = 'x-build-measure';
-
-/**
- * `kind: 'service'` and not `'user'`: an app's own `requireMember()`-style helper that resolves a
- * user to a row has nothing to resolve here, and the honest kind says so. `'*'` is the grant
- * `actorHas` reads as everything — the same spelling a role map uses for a superuser.
- */
-export const measurementActor = (): Actor => ({
-  kind: 'service',
-  id: MEASUREMENT_ACTOR_ID,
-  roles: [],
-  scopes: [],
-  permissions: ['*'],
-});