lynkeus 0.2.0 → 0.4.0

package/src/commands/report.ts

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { define } from '../registry.js';
+
+type Fetch = typeof fetch;
+
+export type Pushed = { url: string; files: number; refused: string[]; changes?: { newFailures: string[]; fixed: string[] } };
+
+/** What a run changed against the one before, in a line or two for a terminal or a pull request comment. */
+export const describeChanges = (changes: Pushed['changes']): string[] =>
+  changes
+    ? [
+        ...(changes.newFailures.length ? [`newly failing (${changes.newFailures.length}): ${changes.newFailures.join(', ')}`] : []),
+        ...(changes.fixed.length ? [`fixed since the run before (${changes.fixed.length}): ${changes.fixed.join(', ')}`] : []),
+      ]
+    : [];
+
+const answer = async (response: Response, doing: string) => {
+  if (response.ok) return response.json() as Promise<Record<string, unknown>>;
+  const body = (await response.json().catch(() => ({}))) as { error?: string };
+  throw new Error(`${doing}: ${body.error ?? `the service answered ${response.status}`}`);
+};
+
+/**
+ * Uploads a run directory (`case run --out`) to the reports service: the run, its cases, then every frame and
+ * film the cases name. A file the organization's plan does not keep (a film on Free) is left out and listed.
+ */
+export const pushRun = async (dir: string, o: { url: string; key: string; project: string; fetch?: Fetch }): Promise<Pushed> => {
+  const call = o.fetch ?? fetch;
+  const auth = { authorization: `Bearer ${o.key}` };
+  const base = o.url.replace(/\/+$/, '');
+  const run = JSON.parse(fs.readFileSync(path.join(dir, 'run.json'), 'utf8')) as unknown;
+  const cases = fs.readFileSync(path.join(dir, 'cases.jsonl'), 'utf8');
+
+  const created = await answer(
+    await call(`${base}/v1/runs`, {
+      method: 'POST',
+      headers: { ...auth, 'content-type': 'application/json' },
+      body: JSON.stringify({ project: o.project, run }),
+    }),
+    'creating the run',
+  );
+  const id = String(created.id);
+  await answer(await call(`${base}/v1/runs/${id}/cases`, { method: 'PUT', headers: auth, body: cases }), 'sending its cases');
+
+  const named = new Set<string>();
+  for (const line of cases.split('\n')) {
+    if (!line.trim()) continue;
+    const c = JSON.parse(line) as { video?: string; steps?: { screenshot?: string }[] };
+    for (const p of [c.video, ...(c.steps ?? []).map((s) => s.screenshot)]) if (p) named.add(p);
+  }
+  let files = 0;
+  const refused: string[] = [];
+  for (const file of named) {
+    const local = path.join(dir, file);
+    if (!fs.existsSync(local)) continue;
+    const response = await call(`${base}/v1/runs/${id}/files/${file.split('/').map(encodeURIComponent).join('/')}`, {
+      method: 'PUT',
+      headers: auth,
+      body: fs.readFileSync(local),
+    });
+    if (response.status === 402) refused.push(file);
+    else {
+      await answer(response, `sending ${file}`);
+      files += 1;
+    }
+  }
+  const finished = await answer(await call(`${base}/v1/runs/${id}/finish`, { method: 'POST', headers: auth }), 'finishing the run');
+  const changes = finished.changes as Pushed['changes'] | undefined;
+  return { url: String(finished.url), files, refused, ...(changes ? { changes } : {}) };
+};
+
+type Service = { url: string; key: string; fetch?: Fetch };
+
+const ask = async (o: Service, method: string, route: string, doing: string) =>
+  answer(await (o.fetch ?? fetch)(`${o.url.replace(/\/+$/, '')}${route}`, { method, headers: { authorization: `Bearer ${o.key}` } }), doing);
+
+export type ListedRun = { project: string; platform: string | null; totals: Record<string, number>; createdAt: string; url: string };
+
+export const listRuns = async (o: Service & { limit?: number }) =>
+  (await ask(o, 'GET', `/v1/runs?limit=${o.limit ?? 20}`, 'listing the runs')).runs as ListedRun[];
+
+export type Flaky = {
+  id: string;
+  title: string;
+  runs: number;
+  firstTryRate: number;
+  state: 'flaky' | 'broken';
+  recent: ('passed' | 'retried' | 'failed')[];
+  lastFailure: string | null;
+};
+
+export const flakes = async (o: Service & { project: string; runs?: number }) =>
+  (await ask(o, 'GET', `/v1/flakes?project=${encodeURIComponent(o.project)}&runs=${o.runs ?? 30}`, 'reading flake trends')) as {
+    runs: number;
+    cases: Flaky[];
+  };
+
+export type CaseRun = { at: string; outcome: 'passed' | 'retried' | 'failed'; ms: number | null; branch?: string | null; commit?: string | null; url: string };
+
+export const caseHistory = async (o: Service & { project: string; id: string; runs?: number }) =>
+  (await ask(
+    o,
+    'GET',
+    `/v1/cases/history?project=${encodeURIComponent(o.project)}&case=${encodeURIComponent(o.id)}&runs=${o.runs ?? 50}`,
+    'reading the case’s history',
+  )) as { title: string; runs: CaseRun[] };
+
+export type Plan = { name: string; plan: string; days: number; projects: number | null; film: boolean };
+
+/** The organization's plan, and with `upgrade` or `manage` the Stripe page that changes it. */
+export const plan = async (o: Service & { go?: 'upgrade' | 'manage' }) => {
+  const now = (await ask(o, 'GET', '/v1/billing', 'reading the plan')) as Plan;
+  if (!o.go) return { ...now, url: null };
+  const route = o.go === 'upgrade' ? '/v1/billing/checkout' : '/v1/billing/portal';
+  return { ...now, url: String((await ask(o, 'POST', route, o.go === 'upgrade' ? 'opening checkout' : 'opening the billing portal')).url) };
+};
+
+export const service = (): Service | string => {
+  const url = process.env.LYNKEUS_REPORTS_URL || 'https://lynkeus.io';
+  const key = process.env.LYNKEUS_REPORTS_KEY;
+  return key ? { url, key } : 'set LYNKEUS_REPORTS_KEY to an API key of your organization (lynkeus.io, API keys); LYNKEUS_REPORTS_URL names another service';
+};
+
+export const reportCommands = [
+  define({
+    name: 'report push',
+    group: 'runs',
+    summary: 'Upload a run to the reports service and print the report’s address',
+    details:
+      'Uploads what `case run --out <dir>` wrote: the run, its cases, and every frame and film they name. The report shows the film in step with the steps, the events each step sent, and why a case failed. The service and the organization’s key come from LYNKEUS_REPORTS_URL and LYNKEUS_REPORTS_KEY; a film the organization’s plan does not keep is left out and said so.',
+    positionals: [{ name: 'dir', help: 'the run directory `case run --out` wrote', required: true }],
+    flags: {
+      project: { type: 'string', help: 'the project the run is filed under (default: the app’s folder name)', value: 'name' },
+    },
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const dir = path.resolve(ctx.args[0]!);
+      if (!fs.existsSync(path.join(dir, 'cases.jsonl')))
+        return { text: `${ctx.args[0]}: no cases.jsonl; pass the directory \`case run --out\` wrote`, code: 2 };
+      const to = service();
+      if (typeof to === 'string') return { text: to, code: 2 };
+      const project = typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root);
+      try {
+        const pushed = await pushRun(dir, { ...to, project });
+        const notes = [...describeChanges(pushed.changes), ...(pushed.refused.length ? [`not kept on this plan: ${pushed.refused.join(', ')}`] : [])];
+        return { text: [pushed.url, ...notes].join('\n'), json: pushed };
+      } catch (error) {
+        return { text: (error as Error).message, code: 1 };
+      }
+    },
+  }),
+  define({
+    name: 'report list',
+    group: 'runs',
+    summary: 'List the organization’s reports, newest first',
+    details: 'Each line is when the run started, its project and platform, how many cases passed, and the report’s address.',
+    flags: { limit: { type: 'string', help: 'how many runs (default 20, at most 100)', value: 'n' } },
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const to = service();
+      if (typeof to === 'string') return { text: to, code: 2 };
+      try {
+        const runs = await listRuns({ ...to, limit: Number(ctx.flags.limit) || 20 });
+        if (runs.length === 0) return { text: 'no reports yet: `lynkeus report push <dir>` uploads one', json: runs };
+        const lines = runs.map(
+          (r) =>
+            `${r.createdAt.slice(0, 16).replace('T', ' ')}  ${r.project}${r.platform ? ` ${r.platform}` : ''}  ${r.totals.passed ?? 0}/${r.totals.cases ?? 0} passed  ${r.url}`,
+        );
+        return { text: lines.join('\n'), json: runs };
+      } catch (error) {
+        return { text: (error as Error).message, code: 1 };
+      }
+    },
+  }),
+  define({
+    name: 'report plan',
+    group: 'runs',
+    summary: 'Show the organization’s plan, or open the page that changes it',
+    details:
+      'Free keeps frames for 7 days and one project; Team keeps films too, for 90 days, and any number of projects. `--upgrade` prints the Stripe checkout for Team; `--manage` prints Stripe’s portal for the card, the invoices and cancelling.',
+    flags: {
+      upgrade: { type: 'boolean', help: 'print the Stripe checkout address for the Team plan' },
+      manage: { type: 'boolean', help: 'print the Stripe portal address for a paying organization' },
+    },
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const to = service();
+      if (typeof to === 'string') return { text: to, code: 2 };
+      const go = ctx.flags.upgrade ? 'upgrade' : ctx.flags.manage ? 'manage' : undefined;
+      try {
+        const now = await plan({ ...to, go });
+        const keeps = `${now.film ? 'films and frames' : 'frames'} for ${now.days} days, ${now.projects ?? 'any number of'} project${now.projects === 1 ? '' : 's'}`;
+        return { text: `${now.name}: ${now.plan} (${keeps})${now.url ? `\n${now.url}` : ''}`, json: now };
+      } catch (error) {
+        return { text: (error as Error).message, code: 1 };
+      }
+    },
+  }),
+  define({
+    name: 'report flakes',
+    group: 'runs',
+    summary: 'List the cases that do not always pass at the first try, across the project’s last runs',
+    details:
+      'Reads the reports pushed for the project and ranks its cases by how often they passed at the first try, the least reliable first. Each line shows the recent runs newest first (✓ passed, ↻ passed on a retry, ✗ failed) and the last report where it went wrong. A case that failed its last three runs is broken rather than flaky. On the Team plan.',
+    flags: {
+      project: { type: 'string', help: 'the project (default: the app’s folder name)', value: 'name' },
+      runs: { type: 'string', help: 'how many of the latest runs to read (default 30)', value: 'n' },
+    },
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const to = service();
+      if (typeof to === 'string') return { text: to, code: 2 };
+      const project = typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root);
+      try {
+        const found = await flakes({ ...to, project, runs: Number(ctx.flags.runs) || 30 });
+        if (found.cases.length === 0) return { text: `${project}: every case passed at the first try in the last ${found.runs} runs`, json: found };
+        const mark = { passed: '✓', retried: '↻', failed: '✗' } as const;
+        const lines = found.cases.map(
+          (c) =>
+            `${c.state === 'broken' ? 'broken' : 'flaky '}  ${Math.round(c.firstTryRate * 100)
+              .toString()
+              .padStart(3)}%  ${c.recent.map((r) => mark[r]).join('')}  ${c.id}${c.lastFailure ? `  ${c.lastFailure}` : ''}`,
+        );
+        return { text: [`${project}: ${found.runs} runs`, ...lines].join('\n'), json: found };
+      } catch (error) {
+        return { text: (error as Error).message, code: 1 };
+      }
+    },
+  }),
+  define({
+    name: 'report history',
+    group: 'runs',
+    summary: 'Show how one case came out in each of the project’s last runs',
+    details:
+      'Newest first: ✓ passed, ↻ passed on a retry, ✗ failed, with how long it took, the branch and commit the run was made from, and the report to open. What tells a case that fails now and then from one a commit broke.',
+    positionals: [{ name: 'case', help: 'the case id', required: true }],
+    flags: {
+      project: { type: 'string', help: 'the project (default: the app’s folder name)', value: 'name' },
+      runs: { type: 'string', help: 'how many of the latest runs to read (default 50)', value: 'n' },
+    },
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const to = service();
+      if (typeof to === 'string') return { text: to, code: 2 };
+      const project = typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root);
+      try {
+        const found = await caseHistory({ ...to, project, id: ctx.args[0]!, runs: Number(ctx.flags.runs) || 50 });
+        if (found.runs.length === 0) return { text: `${ctx.args[0]} is in none of ${project}'s recent runs`, json: found };
+        const mark = { passed: '✓', retried: '↻', failed: '✗' } as const;
+        const lines = found.runs.map(
+          (r) =>
+            `${mark[r.outcome]}  ${r.at.slice(0, 16).replace('T', ' ')}  ${(r.ms === null ? '—' : `${(r.ms / 1000).toFixed(1)}s`).padStart(6)}  ${[r.branch, r.commit].filter(Boolean).join(' @ ') || '—'}  ${r.url}`,
+        );
+        return { text: [`${found.title} (${project})`, ...lines].join('\n'), json: found };
+      } catch (error) {
+        return { text: (error as Error).message, code: 1 };
+      }
+    },
+  }),
+];

package/src/config.ts

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -10,6 +11,33 @@ export const graphFile = (root?: string) => path.join(lynkeusDir(root), 'graph.j
 export const edgesFile = (root?: string) => path.join(lynkeusDir(root), 'edges.jsonl');
 export const frontierFile = (root?: string) => path.join(lynkeusDir(root), 'frontier.jsonl');
 export const runsDir = (root?: string) => path.join(lynkeusDir(root), 'runs');
+export const tokenFile = (root?: string) => path.join(lynkeusDir(root), 'token');
+
+/**
+ * The secret the app and its driver share. LYNKEUS_TOKEN wins; otherwise it is the one `lynkeus init` wrote to
+ * `.lynkeus/token`, which the app's bundle reads too, so nobody has to set a variable in two terminals.
+ */
+export const readToken = (root?: string): string | undefined => {
+  if (process.env.LYNKEUS_TOKEN) return process.env.LYNKEUS_TOKEN;
+  try {
+    return fs.readFileSync(tokenFile(root), 'utf8').trim() || undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Makes the project's token if it has none, and keeps it out of git: `.lynkeus` also holds what a team commits. */
+export const ensureToken = (root?: string): { token: string; made: boolean } => {
+  const had = readToken(root);
+  if (had) return { token: had, made: false };
+  const token = crypto.randomBytes(24).toString('hex');
+  fs.mkdirSync(lynkeusDir(root), { recursive: true });
+  fs.writeFileSync(tokenFile(root), `${token}\n`, { mode: 0o600 });
+  const ignore = path.join(lynkeusDir(root), '.gitignore');
+  const ignored = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
+  if (!ignored.split('\n').includes('token')) fs.writeFileSync(ignore, `${ignored}${ignored && !ignored.endsWith('\n') ? '\n' : ''}token\n`);
+  return { token, made: true };
+};
 
 export const loadGraph = (root?: string): ScreenGraph | null => {
   const file = graphFile(root);
@@ -27,6 +55,11 @@ export type LynkeusConfig = {
   entry?: string;
   /** The environment variable the app reads its API base from; the headless entry refuses one that is not local. */
   apiEnv?: string;
+  /**
+   * The local backend `headless start` hands the app under `apiEnv` when the environment sets none: an agent
+   * starting the host over MCP cannot export a variable.
+   */
+  apiUrl?: string;
   /** The driver port the app dials. */
   port?: number;
   /** Simulator udid or name. */
@@ -46,8 +79,12 @@ export type LynkeusConfig = {
   lintBaseline?: string;
   /** Regular expressions for the text this app shows when it is broken; `smoke` and `crawl` report a match. */
   errorCopy?: string[];
-  /** The shape of an untranslated key, and the smallest acceptable touch target in points. */
-  lint?: { i18nKeyPatterns?: string[]; minTouchTarget?: number };
+  /**
+   * The shape of an untranslated key, the smallest acceptable touch target in points, and how text contrast is
+   * judged: `false` turns it off; otherwise the least ratio for ordinary and for large text (4.5 and 3, WCAG 2 AA)
+   * and the testIDs to leave out, as regular expressions.
+   */
+  lint?: { i18nKeyPatterns?: string[]; minTouchTarget?: number; contrast?: false | { normal?: number; large?: number; ignore?: string[] } };
   /**
    * Regular expressions for the testIDs of controls whose content changes on
    * its own (a ticking clock, a countdown). Their text stops counting as a

package/src/device/agentVersion.ts

@@ -0,0 +1,15 @@
+import { createRequire } from 'node:module';
+
+import type { HelloEvent } from 'lynkeus-protocol';
+
+export const CLI_VERSION = (createRequire(import.meta.url)('../../package.json') as { version: string }).version;
+
+/**
+ * An agent of another release can answer without an error and still do something else (type into
+ * nothing): what to tell the person running it, or nothing when the two match.
+ */
+export const agentMismatch = (hello: Pick<HelloEvent, 'agentVersion'>, cli = CLI_VERSION): string | undefined => {
+  if (hello.agentVersion === cli) return undefined;
+  const agent = hello.agentVersion ? `lynkeus-agent ${hello.agentVersion}` : 'a lynkeus-agent too old to say its version';
+  return `⚠️  The app runs ${agent}, this CLI is lynkeus ${cli}: they can misread each other without an error. Install lynkeus-agent@${cli} in the app and rebuild it (or run the lynkeus CLI of the agent's version).`;
+};

package/src/device/devices.ts

@@ -29,6 +29,34 @@ export const bootedSimulators = async (): Promise<DeviceInfo[]> => {
     .map((d) => ({ id: d.udid, name: d.name, platform: 'ios', type: 'simulator', connected: true }));
 };
 
+/** The serials `adb devices` lists as ready, in its order; none when there is no adb to ask. */
+export const parseAdbDevices = (stdout: string): DeviceInfo[] =>
+  stdout
+    .split('\n')
+    .slice(1)
+    .map((line) => line.trim().split(/\s+/))
+    .filter(([serial, state]) => serial && state === 'device')
+    .map(([serial]) => ({ id: serial!, name: serial!, platform: 'android', type: serial!.startsWith('emulator-') ? 'emulator' : 'physical', connected: true }));
+
+export const androidDevices = async (): Promise<DeviceInfo[]> => {
+  try {
+    return parseAdbDevices((await run('adb', ['devices'])).stdout);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+};
+
+/** The Android device an app that said it runs on Android is on: the one asked for, or the first that is up. */
+export const pickAndroidDevice = async (wanted?: string): Promise<DeviceInfo> => {
+  const devices = await androidDevices();
+  const id = wanted ?? process.env.LYNKEUS_DEVICE;
+  // A name meant for a simulator (the config's `device` when both platforms are driven) is not a reason to fail here.
+  const device = (id ? devices.find((d) => d.id === id) : undefined) ?? devices[0];
+  if (!device) throw new Error('No Android device or emulator is up (adb devices lists none).');
+  return device;
+};
+
 export const HEADLESS_HOST: DeviceInfo = { id: 'headless', name: 'headless host', platform: 'ios', type: 'simulator', connected: true };
 
 export const pickAgentDevice = async (wanted?: string): Promise<DeviceInfo> => {

package/src/device/driver.ts

@@ -6,7 +6,7 @@
 import { AgentServer } from 'lynkeus-client';
 import type { CoreMethods, Screen, TraceEvent } from 'lynkeus-protocol';
 
-import { portFromEnv } from '../config.js';
+import { portFromEnv, readToken } from '../config.js';
 import { withoutHost } from '../knowledge/problems.js';
 import type { DeviceInfo } from './devices.js';
 import { lifecycleFor, type PlatformLifecycle } from './platform.js';
@@ -23,7 +23,7 @@ export class Device {
     this.info = info;
     this.#resolving = options.resolving;
     // The app serves commands only to a driver that presents its token; without one, anything on the loopback could drive a dev build.
-    this.server = options.server ?? new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: portFromEnv() });
+    this.server = options.server ?? new AgentServer({ token: readToken(), port: portFromEnv() });
     this.#lifecycle = lifecycleFor(info.platform);
     this.#appId = options.appId ?? null;
   }

package/src/flow/runner.ts

@@ -1,5 +1,7 @@
 import path from 'node:path';
 
+import type { Element } from 'lynkeus-protocol';
+
 import type { Device } from '../device/driver.js';
 import { writeJson } from '../files.js';
 import { drainEvents, type RunEvent, writeEvents } from '../knowledge/events.js';
@@ -98,6 +100,34 @@ export const runFlow = async (flow: Flow, options: RunFlowOptions): Promise<Flow
   return report;
 };
 
+/**
+ * A keypad the app raises slides in, and under load its keys are listed a while before they can take a
+ * press: disabled, under the screen it is leaving, or still moving. A press then lands on nothing, and the
+ * code comes up a digit short.
+ */
+const keyReady = async (device: Device, key: { testId: string }, timeoutMs: number): Promise<void> => {
+  const deadline = Date.now() + timeoutMs;
+  let was: string | undefined;
+  for (;;) {
+    const found = (await device.server.call('find', key)) as Element | null;
+    const at = found ? JSON.stringify(found.frame) : undefined;
+    const why =
+      !found || (found.hidden && found.hidden !== 'inert')
+        ? 'not on screen'
+        : !found.enabled
+          ? 'disabled'
+          : found.covered
+            ? 'covered'
+            : at !== was
+              ? 'moving'
+              : undefined;
+    if (!why) return;
+    if (Date.now() > deadline) throw new Error(`keypad key #${key.testId} is ${why} after ${timeoutMs} ms`);
+    was = at;
+    await device.idle({ quietMs: 50, timeoutMs: 200 }).catch(() => undefined);
+  }
+};
+
 const execute = async (step: FlowStep, flow: Flow, device: Device, vars: Record<string, unknown>): Promise<void> => {
   if ('note' in step) return;
   if ('launch' in step) {
@@ -132,7 +162,11 @@ const execute = async (step: FlowStep, flow: Flow, device: Device, vars: Record<
   }
   if ('keypad' in step) {
     for (const digit of step.keypad.digits) {
-      await device.press({ testId: step.keypad.pattern.replace('{d}', digit), mode: step.keypad.mode });
+      const key = { testId: step.keypad.pattern.replace('{d}', digit) };
+      await keyReady(device, key, step.keypad.timeoutMs ?? 5000);
+      await device.press({ ...key, mode: step.keypad.mode });
+      // A code field fed by the app's state drops a digit pressed before the last one rendered.
+      await device.idle({ quietMs: 50, timeoutMs: 400 }).catch(() => undefined);
     }
     return;
   }

package/src/flow/types.ts

@@ -18,8 +18,8 @@ export type FlowStep =
   | { waitFor: { route?: string; target?: Target; anyOf?: Target[]; gone?: boolean; timeoutMs?: number } }
   | { idle: { quietMs?: number; timeoutMs?: number } }
   | { assert: { route?: string; target?: Target; gone?: boolean } }
-  /** Presses one button per digit, e.g. a code on `digit-{d}-button`. */
-  | { keypad: { digits: string; pattern: string; mode?: 'native' | 'js' } }
+  /** Presses one button per digit, e.g. a code on `digit-{d}-button`, each once it is there, enabled, uncovered and still (`timeoutMs` per key, 5000 by default). */
+  | { keypad: { digits: string; pattern: string; mode?: 'native' | 'js'; timeoutMs?: number } }
   /** An app command registered with `qa.register`; the result is saved under `as`. */
   | { call: { method: string; params?: unknown; as?: string } }
   | { note: string };

package/src/knowledge/contrast.ts

@@ -0,0 +1,135 @@
+/**
+ * How well a screen's text stands out from what is behind it, measured on the pixels of a screenshot: the
+ * colors an app declares say nothing of a label over a photo, a gradient or a translucent sheet.
+ */
+import type { Element, Screen } from 'lynkeus-protocol';
+
+import type { Finding } from './lint.js';
+
+export type Pixels = { width: number; height: number; data: Uint8Array | Buffer };
+export type Rgb = [number, number, number];
+export type Contrast = { ratio: number; text: Rgb; background: Rgb; plain: boolean };
+
+export type ContrastOptions = {
+  /** The least ratio for ordinary text (WCAG 2 AA asks 4.5). */
+  normal?: number;
+  /** The least ratio for large text: 18 points, or 14 and bold (WCAG 2 AA asks 3). */
+  large?: number;
+  /** testIDs left out: a watermark, a brand color nobody may change. */
+  ignore?: RegExp[];
+};
+
+const AA_NORMAL = 4.5;
+const AA_LARGE = 3;
+// A text box this uniform has a flat background; under it the text sits on a picture or a gradient.
+const PLAIN_SHARE = 0.5;
+// Enough pixels of one color to be glyphs and not the fringe where a glyph meets its background.
+const LEAST_SHARE = 0.004;
+const LEAST_PIXELS = 6;
+
+const channel = (value: number): number => {
+  const v = value / 255;
+  return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+};
+
+/** WCAG's relative luminance of an sRGB color. */
+export const luminance = ([r, g, b]: Rgb): number => 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+
+/** WCAG's contrast ratio, from 1 (the same color) to 21 (black on white). */
+export const contrastRatio = (a: Rgb, b: Rgb): number => {
+  const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [number, number];
+  return (light + 0.05) / (dark + 0.05);
+};
+
+export const hex = (rgb: Rgb): string => `#${rgb.map((v) => Math.round(v).toString(16).padStart(2, '0')).join('')}`;
+
+/**
+ * The contrast of the text inside a rectangle of the picture, in pixels. The background is the color most
+ * of the rectangle has; the text is the color, among those with enough pixels to be glyphs, that stands
+ * furthest from it. Anything else in the box (an icon beside a label) can only raise the figure, so a low one
+ * is a finding and a high one is not a certificate.
+ */
+export const measureContrast = (picture: Pixels, box: { x: number; y: number; w: number; h: number }): Contrast | undefined => {
+  const left = Math.max(0, Math.floor(box.x));
+  const top = Math.max(0, Math.floor(box.y));
+  const right = Math.min(picture.width, Math.ceil(box.x + box.w));
+  const bottom = Math.min(picture.height, Math.ceil(box.y + box.h));
+  if (right - left < 2 || bottom - top < 2) return undefined;
+
+  // Colors are gathered 8 levels to a bucket: antialiasing and compression never give one flat value.
+  const buckets = new Map<number, { count: number; r: number; g: number; b: number }>();
+  let total = 0;
+  for (let y = top; y < bottom; y++) {
+    for (let x = left; x < right; x++) {
+      const at = (y * picture.width + x) * 4;
+      const r = picture.data[at]!;
+      const g = picture.data[at + 1]!;
+      const b = picture.data[at + 2]!;
+      const key = ((r >> 3) << 10) | ((g >> 3) << 5) | (b >> 3);
+      const bucket = buckets.get(key);
+      if (bucket) {
+        bucket.count++;
+        bucket.r += r;
+        bucket.g += g;
+        bucket.b += b;
+      } else {
+        buckets.set(key, { count: 1, r, g, b });
+      }
+      total++;
+    }
+  }
+  const colors = [...buckets.values()].map((bucket) => ({
+    count: bucket.count,
+    rgb: [bucket.r / bucket.count, bucket.g / bucket.count, bucket.b / bucket.count] as Rgb,
+  }));
+  const background = colors.reduce((most, color) => (color.count > most.count ? color : most));
+  const least = Math.max(LEAST_PIXELS, total * LEAST_SHARE);
+  let best: { ratio: number; rgb: Rgb } | undefined;
+  for (const color of colors) {
+    if (color === background || color.count < least) continue;
+    const ratio = contrastRatio(color.rgb, background.rgb);
+    if (!best || ratio > best.ratio) best = { ratio, rgb: color.rgb };
+  }
+  // Nothing but background: an empty field, or text the same color as what is behind it.
+  if (!best || best.ratio < 1.05) return undefined;
+  return { ratio: best.ratio, text: best.rgb, background: background.rgb, plain: background.count / total >= PLAIN_SHARE };
+};
+
+const isLarge = (font: Element['font']): boolean => !!font && (font.size >= 18 || (font.size >= 14 && font.bold === true));
+
+/** WCAG leaves out what cannot be used (a disabled control) and what is not there to be read. */
+const judged = (e: Element): boolean =>
+  !e.hidden &&
+  !e.covered &&
+  !e.offscreen &&
+  e.enabled !== false &&
+  (e.kind === 'text' || e.kind === 'button' || e.kind === 'input') &&
+  (e.text ?? e.value ?? e.placeholder) !== undefined;
+
+/** A finding for every text on the screen whose contrast falls short, most serious first. */
+export const lintContrast = (screen: Screen, picture: Pixels, options: ContrastOptions = {}): Finding[] => {
+  const window = screen.window;
+  if (!window || window.w <= 0) return [];
+  const scale = picture.width / window.w;
+  const out: Finding[] = [];
+  for (const e of screen.elements ?? []) {
+    if (!judged(e) || !e.frame || e.frame.w <= 0 || e.frame.h <= 0) continue;
+    if (e.testId && options.ignore?.some((pattern) => pattern.test(e.testId!))) continue;
+    const measured = measureContrast(picture, { x: e.frame.x * scale, y: e.frame.y * scale, w: e.frame.w * scale, h: e.frame.h * scale });
+    if (!measured) continue;
+    const large = isLarge(e.font);
+    const needed = large ? (options.large ?? AA_LARGE) : (options.normal ?? AA_NORMAL);
+    if (measured.ratio >= needed) continue;
+    const said = (e.text ?? e.value ?? e.placeholder ?? '').slice(0, 40);
+    out.push({
+      rule: 'low-contrast',
+      // Over a picture the background is a guess, so it is said and left to a person.
+      severity: measured.plain ? 'warn' : 'info',
+      element: e.i,
+      // The text, not the ratio: a baseline knows the finding again when the measurement moves.
+      subject: said,
+      message: `"${said}" ${measured.ratio.toFixed(1)}:1 (${hex(measured.text)} on ${hex(measured.background)}${measured.plain ? '' : ', over a varied background'}), needs ${needed}:1${large ? ' for large text' : ''}`,
+    });
+  }
+  return out;
+};

package/src/knowledge/errors.ts

@@ -35,7 +35,7 @@ const RULES: Rule[] = [
     re: /Cannot read propert(?:y|ies) of undefined \(reading '(\w+)'\)/,
     cause: (m) => `something the app expected to exist is undefined (reading '${m[1]}')`,
     fix: () =>
-      `look one frame up the stack for the module: a mock returning {} instead of the shape the app reads, or a store not initialised because a service failed earlier.`,
+      `look one frame up the stack for the module: a mock returning {} instead of the shape the app reads, or a store not initialized because a service failed earlier.`,
   },
   {
     re: /Jest did not exit one second after the test run has completed/,