@g9tm/app-pilot 0.0.0-stage → 0.1.0

package/src/oracles.ts

@@ -0,0 +1,384 @@
+// The always-awake oracles: while an agent or a runner drives the app, things that are wrong without anyone asking are
+// noticed and kept — a JS error, a promise nobody caught, `console.error`, a busy token that never ended, a control a
+// finger cannot reach, a button with no name, a translation key on screen instead of its text. A flow does not need a
+// step for each; the controller reads them (`oracle.list`, or the `oracle.violation` events) and turns each into a
+// finding with its evidence.
+//
+//   installOracles({ rules: { 'i18n.latinDigits': 'warn' } });   // the built-in rules, the commands below
+//   reportViolation('sync.silentRejection', key, 'A refused change has no message on screen', { table, row });
+//   registerScreenCheck('layout.underBar', (nodes) => …);         // an adapter's own screen rule
+//
+//   oracle.list {since?, rule?, severity?}   what was seen (one entry per rule + key, with a count), newest last
+//   oracle.check                            run the screen rules on the current screen now (also after each command)
+//   oracle.rules · oracle.set {rule, severity: finding|warn|off} · oracle.clear
+//
+// Platform-free: the screen rules read the `ui.snapshot` the adapter registered. Debug builds only, like every pilot module.
+import { optionalString, requireString } from './args.ts';
+import { onLogRecorded } from './blackbox.ts';
+import { onAnswer } from './dispatch.ts';
+import { emit } from './events.ts';
+import { PilotError } from './errors.ts';
+import { busySnapshot } from './idle.ts';
+import { commandHandler, registerCommand } from './registry.ts';
+
+export type OracleSeverity = 'finding' | 'warn' | 'off';
+
+export interface OracleViolation {
+  /** Order of first sight (1, 2, …); `oracle.list {since}` pages by it. */
+  readonly seq: number;
+  readonly rule: string;
+  readonly severity: Exclude<OracleSeverity, 'off'>;
+  /** What makes two sightings the same (a control id, an error's first line). */
+  readonly key: string;
+  readonly message: string;
+  readonly data: unknown;
+  readonly firstAt: number;
+  lastAt: number;
+  count: number;
+}
+
+/** A control as `ui.snapshot` lists it (the fields the screen rules read). */
+export interface ScreenNode {
+  readonly automationId: string;
+  readonly type: string;
+  readonly name?: string | null;
+  readonly layer?: string;
+  readonly visible?: boolean;
+  readonly enabled?: boolean;
+  readonly bounds?: { readonly x: number; readonly y: number; readonly width: number; readonly height: number; readonly screenWidth?: number; readonly screenHeight?: number; readonly onScreen?: boolean } | null;
+}
+
+export interface ScreenFinding {
+  readonly key: string;
+  readonly message: string;
+  readonly data?: unknown;
+}
+
+export type ScreenCheck = (nodes: readonly ScreenNode[], context: ScreenContext) => readonly ScreenFinding[] | Promise<readonly ScreenFinding[]>;
+
+export interface ScreenContext {
+  /** The page's language when the adapter knows it ('fa', 'en', …). */
+  readonly language: string | null;
+}
+
+/** The built-in rules and their default severity. */
+export const DEFAULT_ORACLE_RULES: Readonly<Record<string, OracleSeverity>> = {
+  'js.error': 'finding',
+  'js.unhandledRejection': 'finding',
+  'console.error': 'warn',
+  'log.error': 'warn',
+  'busy.leak': 'finding',
+  'a11y.unlabeled': 'finding',
+  'i18n.rawKey': 'finding',
+  'i18n.latinDigits': 'warn',
+  'layout.offScreen': 'warn',
+  // vitals.ts: warn, not finding — a Debug build is slower than the release a person runs (a stall here may not be one there).
+  'perf.longFrame': 'warn',
+  'perf.memoryGrowth': 'warn',
+};
+
+/** A busy token held this long is a leak (the page will never be idle for a waiting runner). */
+export const BUSY_LEAK_MS = 30_000;
+const KEEP = 300;
+
+/** Types a finger acts on: what must stay reachable. */
+const TAPPABLE = new Set(['Button', 'IconButton', 'Tile', 'TabItem', 'Card', 'Switch', 'CheckBox', 'Entry', 'Picker', 'Link', 'MenuItem']);
+/**
+ * Types whose name is a LABEL (what a screen reader says). A field's or a picker's snapshot name is its current value —
+ * empty until something is typed or chosen, which is no missing label (found on the first real run, 2026-11-04).
+ */
+const LABELLED = new Set(['Button', 'IconButton', 'Tile', 'TabItem', 'Card', 'Switch', 'CheckBox', 'Link', 'MenuItem']);
+
+let rules: Record<string, OracleSeverity> = { ...DEFAULT_ORACLE_RULES };
+const seen = new Map<string, OracleViolation>();
+const screenChecks = new Map<string, ScreenCheck>();
+let seq = 0;
+let languageOf: () => string | null = () => null;
+let rawKeyTest: (text: string) => boolean = looksLikeKey;
+
+let oraclesEnabled = true;
+/** The configuration's `oracles.enabled` (config.ts): off, every rule reports nothing. */
+export function setOraclesEnabled(on: boolean): void {
+  oraclesEnabled = on;
+}
+const severityOf = (rule: string): OracleSeverity => (oraclesEnabled ? (rules[rule] ?? 'finding') : 'off');
+
+/**
+ * Reports what a rule saw. The same rule + key again only counts (the first sighting is the evidence); a rule set to
+ * 'off' is dropped. Each NEW violation is an `oracle.violation` event. Returns the violation, or null when off.
+ */
+export function reportViolation(rule: string, key: string, message: string, data: unknown = null): OracleViolation | null {
+  const severity = severityOf(rule);
+  if (severity === 'off') return null;
+  const id = `${rule}\u0000${key}`;
+  const now = Date.now();
+  const known = seen.get(id);
+  if (known) {
+    known.count++;
+    known.lastAt = now;
+    return known;
+  }
+  const v: OracleViolation = { seq: ++seq, rule, severity, key, message: message.slice(0, 400), data, firstAt: now, lastAt: now, count: 1 };
+  seen.set(id, v);
+  if (seen.size > KEEP) seen.delete(seen.keys().next().value as string);
+  emit('oracle.violation', { seq: v.seq, rule, severity, key, message: v.message });
+  return v;
+}
+
+/** An adapter's or an app's own screen rule (it runs with the built-in ones). Returns the remover. */
+export function registerScreenCheck(rule: string, check: ScreenCheck): () => void {
+  screenChecks.set(rule, check);
+  return () => {
+    if (screenChecks.get(rule) === check) screenChecks.delete(rule);
+  };
+}
+
+// ---- the built-in screen rules (pure; exported for tests) ------------------------------------------------------------
+
+/** A translation key on screen instead of its text: «MapFarmSelectorTitle» (PascalCase, two humps or more, no spaces). */
+export function looksLikeKey(text: string): boolean {
+  const t = text.trim();
+  return t.length >= 8 && !/\s/.test(t) && /^[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*){2,}$/.test(t);
+}
+
+// The Arabic-script block U+0600–U+06FF (written as its two characters: the range's ends).
+const PERSIAN = /[؀-ۿ]/;
+// Latin digits standing as a NUMBER in Persian text — a version («6.2.13»), an id («C2»), a unit after a number and
+// anything in an LTR isolate are a different matter, so only a bare run of digits between Persian words counts.
+const LATIN_NUMBER = /(^|[\s؀-ۿ،:])([0-9]{1,6})(?=$|[\s؀-ۿ،:)])/;
+
+export function unlabeledControls(nodes: readonly ScreenNode[]): ScreenFinding[] {
+  return nodes
+    .filter((n) => n.visible !== false && LABELLED.has(n.type) && !(n.name ?? '').trim())
+    .map((n) => ({ key: n.automationId, message: `«${n.automationId}» (${n.type}) has no name: a screen reader says nothing and an agent cannot find it by text.`, data: { automationId: n.automationId, type: n.type } }));
+}
+
+export function rawKeysOnScreen(nodes: readonly ScreenNode[], isKey: (text: string) => boolean = looksLikeKey): ScreenFinding[] {
+  return nodes
+    .filter((n) => n.visible !== false && !!n.name && isKey(n.name))
+    .map((n) => ({ key: `${n.automationId}:${n.name}`, message: `«${n.automationId}» shows the key «${n.name}», not its text (a missing translation).`, data: { automationId: n.automationId, text: n.name } }));
+}
+
+export function latinDigitsInPersian(nodes: readonly ScreenNode[], language: string | null): ScreenFinding[] {
+  if (language !== 'fa') return [];
+  return nodes
+    .filter((n) => n.visible !== false && !!n.name && PERSIAN.test(n.name) && LATIN_NUMBER.test(n.name))
+    .map((n) => ({ key: `${n.automationId}:${n.name}`, message: `«${n.automationId}» shows a Latin number in Persian text: «${(n.name ?? '').slice(0, 80)}».`, data: { automationId: n.automationId, text: n.name } }));
+}
+
+export function offScreenControls(nodes: readonly ScreenNode[]): ScreenFinding[] {
+  const out: ScreenFinding[] = [];
+  for (const n of nodes) {
+    const b = n.bounds;
+    if (n.visible === false || !b || !TAPPABLE.has(n.type) || !b.screenWidth) continue;
+    const cut = b.x < -1 || b.x + b.width > b.screenWidth + 1;
+    if (cut && b.x + b.width > 0 && b.x < b.screenWidth) {
+      out.push({ key: n.automationId, message: `«${n.automationId}» is cut by the screen's side edge (x ${Math.round(b.x)}, width ${Math.round(b.width)} of ${Math.round(b.screenWidth)}).`, data: { automationId: n.automationId, bounds: b } });
+    }
+  }
+  return out;
+}
+
+const BUILT_IN: ReadonlyArray<readonly [string, ScreenCheck]> = [
+  ['a11y.unlabeled', (nodes) => unlabeledControls(nodes)],
+  ['i18n.rawKey', (nodes) => rawKeysOnScreen(nodes, rawKeyTest)],
+  ['i18n.latinDigits', (nodes, ctx) => latinDigitsInPersian(nodes, ctx.language)],
+  ['layout.offScreen', (nodes) => offScreenControls(nodes)],
+];
+
+/** Runs every screen rule on the current screen now; returns how many violations were new. */
+export async function checkScreen(): Promise<number> {
+  const snapshot = commandHandler('ui.snapshot');
+  if (!snapshot) return 0;
+  let nodes: readonly ScreenNode[];
+  try {
+    const result = (await snapshot({ maxNodes: 400 }, { timeoutMs: 5_000, leaseId: null, kid: null, scopes: ['observe'] })) as { nodes?: ScreenNode[] };
+    nodes = result?.nodes ?? [];
+  } catch {
+    return 0;
+  }
+  const context: ScreenContext = { language: languageOf() };
+  const before = seq;
+  for (const [rule, check] of [...BUILT_IN, ...screenChecks]) {
+    if (severityOf(rule) === 'off') continue;
+    try {
+      for (const f of await check(nodes, context)) reportViolation(rule, f.key, f.message, f.data ?? null);
+    } catch {
+      // one rule failing never stops the others
+    }
+  }
+  return seq - before;
+}
+
+// ---- install ---------------------------------------------------------------------------------------------------------
+
+export interface OracleOptions {
+  /** Severity per rule (merged over DEFAULT_ORACLE_RULES); 'off' switches one off. */
+  readonly rules?: Readonly<Record<string, OracleSeverity>>;
+  /** The page's language for the language rules. */
+  readonly language?: () => string | null;
+  /** What a translation key looks like in this app (default `looksLikeKey`). */
+  readonly isRawKey?: (text: string) => boolean;
+  /** Listen to the JS runtime's uncaught errors and rejections and to console.error (default true). */
+  readonly runtime?: boolean;
+  /** Check the screen after every command a controller sends (throttled; default true). */
+  readonly afterCommands?: boolean;
+  /**
+   * The console the page's code calls (default globalThis.console). A bundle whose runtime injects `console` into the
+   * module scope (Lynx) passes its own: wrapping the global one would miss every call the app makes.
+   */
+  readonly consoleTarget?: { error?: (...args: unknown[]) => void };
+  /**
+   * Which rule an error line of the app's log belongs to (default `log.error`): a host that hands uncaught errors to the
+   * app's logger says which lines are `js.error` / `js.unhandledRejection` — and the key that tells them apart.
+   */
+  readonly logRule?: (text: string) => { readonly rule: string; readonly key?: string; readonly message?: string } | null;
+}
+
+/** The built-in rules and the oracle commands. Returns the uninstaller. */
+export function installOracles(options: OracleOptions = {}): () => void {
+  rules = { ...DEFAULT_ORACLE_RULES, ...(options.rules ?? {}) };
+  if (options.language) languageOf = options.language;
+  if (options.isRawKey) rawKeyTest = options.isRawKey;
+  const undo: Array<() => void> = [];
+  if (options.runtime !== false) undo.push(installRuntimeHooks(options.consoleTarget));
+  // What the app's own logger says is an error (the black box's log): the one path every host has — a Lynx bundle's
+  // console is a host object a wrapper cannot replace, its uncaught errors go to the native host.
+  undo.push(
+    onLogRecorded((entry) => {
+      if (entry.level !== 'error') return;
+      const line = entry.text.split('\n')[0]?.slice(0, 200) ?? '';
+      const mapped = options.logRule?.(entry.text) ?? null;
+      if (mapped) reportViolation(mapped.rule, mapped.key ?? line, mapped.message ?? line, { seq: entry.seq, text: entry.text.slice(0, 600) });
+      else reportViolation('log.error', line, `The app logged an error: ${line}`, { seq: entry.seq });
+    }),
+  );
+  // A busy token that never ends: sampled, so a long but honest wait is not reported before BUSY_LEAK_MS.
+  const busyTimer = setInterval(() => {
+    const busy = busySnapshot();
+    if (busy.idle || busy.oldestMs < BUSY_LEAK_MS) return;
+    // reasons[0] is the oldest open one: `name (12.3s)` or `name ×2 (40.1s) — suspected leak`.
+    const name = (busy.reasons[0] ?? 'unknown').replace(/\s*(?:×\d+\s*)?\(.*$/, '').trim() || 'unknown';
+    reportViolation('busy.leak', name, `The busy reason «${name}» has been open ${Math.round(busy.oldestMs / 1000)} s: a runner waiting for idle waits for ever.`, { reasons: busy.reasons, oldestMs: busy.oldestMs });
+  }, 5_000);
+  undo.push(() => clearInterval(busyTimer));
+  if (options.afterCommands !== false) {
+    let last = 0;
+    let pending = false;
+    undo.push(
+      onAnswer((request) => {
+        if (request.command.startsWith('oracle.') || pending || Date.now() - last < 1_500) return;
+        pending = true;
+        setTimeout(() => {
+          last = Date.now();
+          void checkScreen().finally(() => {
+            pending = false;
+          });
+        }, 400);
+      }),
+    );
+  }
+  undo.push(
+    registerCommand(
+      'oracle.list',
+      (args) => {
+        const since = typeof args.since === 'number' ? args.since : 0;
+        const rule = optionalString(args, 'rule');
+        const severity = optionalString(args, 'severity');
+        const list = [...seen.values()].filter((v) => v.seq > since && (!rule || v.rule === rule) && (!severity || v.severity === severity)).sort((a, b) => a.seq - b.seq);
+        return { violations: list, last: seq, findings: list.filter((v) => v.severity === 'finding').length };
+      },
+      { scope: 'observe', description: 'What the oracles saw: one entry per rule + key with a count, newest last. Page with `since` (the returned `last`).', example: { since: 0, severity: 'finding' } },
+    ),
+    registerCommand('oracle.check', async () => ({ fresh: await checkScreen(), last: seq }), { scope: 'observe', description: 'Runs the screen rules on the current screen now.' }),
+    registerCommand('oracle.rules', () => ({ rules: { ...rules }, screenRules: [...BUILT_IN.map(([r]) => r), ...screenChecks.keys()] }), { scope: 'observe', description: 'Every rule and its severity.' }),
+    registerCommand(
+      'oracle.set',
+      (args) => {
+        const rule = requireString(args, 'rule');
+        const severity = requireString(args, 'severity');
+        if (severity !== 'finding' && severity !== 'warn' && severity !== 'off') throw new PilotError('oracle.set needs severity finding, warn or off.', { code: 'BAD_ARGS', fixExample: { command: 'oracle.set', args: { rule, severity: 'off' } } });
+        rules[rule] = severity;
+        return { rule, severity };
+      },
+      { scope: 'stage', description: 'One rule’s severity until the app restarts (finding, warn or off).', example: { rule: 'i18n.latinDigits', severity: 'off' } },
+    ),
+    registerCommand(
+      'oracle.clear',
+      () => {
+        const n = seen.size;
+        seen.clear();
+        return { cleared: n, last: seq };
+      },
+      { scope: 'stage', description: 'Forgets what was seen (a flow’s start); the numbering goes on.' },
+    ),
+  );
+  return () => {
+    for (const u of undo.reverse()) u();
+  };
+}
+
+/** The runtime's own reports: uncaught errors, promises nobody caught, console.error. */
+function installRuntimeHooks(consoleTarget?: { error?: (...a: unknown[]) => void }): () => void {
+  const g = globalThis as unknown as {
+    console?: { error?: (...a: unknown[]) => void };
+    addEventListener?: (type: string, fn: (e: unknown) => void) => void;
+    removeEventListener?: (type: string, fn: (e: unknown) => void) => void;
+  };
+  const undo: Array<() => void> = [];
+  const firstLine = (v: unknown): string => {
+    const s = v instanceof Error ? `${v.name}: ${v.message}` : typeof v === 'string' ? v : (() => {
+      try {
+        return JSON.stringify(v);
+      } catch {
+        return String(v);
+      }
+    })();
+    return (s ?? '').split('\n')[0]?.slice(0, 200) ?? '';
+  };
+  const stackOf = (v: unknown): string | null => (v instanceof Error && v.stack ? v.stack.split('\n').slice(0, 6).join('\n') : null);
+  const target = consoleTarget ?? g.console;
+  const original = target?.error;
+  if (target && original) {
+    target.error = (...args: unknown[]) => {
+      try {
+        const line = args.map(firstLine).join(' ').slice(0, 200);
+        reportViolation('console.error', line, `console.error: ${line}`, { stack: stackOf(args.find((a) => a instanceof Error)) });
+      } catch {
+        // the oracle never breaks the console
+      }
+      original.apply(target, args);
+    };
+    undo.push(() => {
+      target.error = original;
+    });
+  }
+  if (typeof g.addEventListener === 'function') {
+    const onError = (e: unknown) => {
+      const err = (e as { error?: unknown; message?: string })?.error ?? (e as { message?: string })?.message ?? e;
+      reportViolation('js.error', firstLine(err), `Uncaught: ${firstLine(err)}`, { stack: stackOf(err) });
+    };
+    const onRejection = (e: unknown) => {
+      const reason = (e as { reason?: unknown })?.reason ?? e;
+      reportViolation('js.unhandledRejection', firstLine(reason), `A promise nobody caught: ${firstLine(reason)}`, { stack: stackOf(reason) });
+    };
+    g.addEventListener('error', onError);
+    g.addEventListener('unhandledrejection', onRejection);
+    undo.push(() => {
+      g.removeEventListener?.('error', onError);
+      g.removeEventListener?.('unhandledrejection', onRejection);
+    });
+  }
+  return () => {
+    for (const u of undo) u();
+  };
+}
+
+export function resetOraclesForTests(): void {
+  seen.clear();
+  screenChecks.clear();
+  seq = 0;
+  rules = { ...DEFAULT_ORACLE_RULES };
+  languageOf = () => null;
+  rawKeyTest = looksLikeKey;
+}