@ultimat3/testing 29.3.2 → 30.0.0

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/testing",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "testing",
+    "test",
+    "fixtures",
+    "harness"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Testing",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -36,20 +46,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "29.3.2",
-    "@ultimat3/cache": "29.3.2",
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/db": "29.3.2",
-    "@ultimat3/entity": "29.3.2",
-    "@ultimat3/http": "29.3.2",
-    "@ultimat3/i18n": "29.3.2",
-    "@ultimat3/jobs": "29.3.2",
-    "@ultimat3/mail": "29.3.2",
-    "@ultimat3/policy": "29.3.2",
-    "@ultimat3/pwa": "29.3.2",
-    "@ultimat3/query": "29.3.2",
-    "@ultimat3/realtime": "29.3.2",
-    "@ultimat3/render": "29.3.2",
-    "@ultimat3/time": "29.3.2"
+    "@ultimat3/action": "30.0.0",
+    "@ultimat3/cache": "30.0.0",
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/db": "30.0.0",
+    "@ultimat3/entity": "30.0.0",
+    "@ultimat3/http": "30.0.0",
+    "@ultimat3/i18n": "30.0.0",
+    "@ultimat3/jobs": "30.0.0",
+    "@ultimat3/mail": "30.0.0",
+    "@ultimat3/policy": "30.0.0",
+    "@ultimat3/pwa": "30.0.0",
+    "@ultimat3/query": "30.0.0",
+    "@ultimat3/realtime": "30.0.0",
+    "@ultimat3/render": "30.0.0",
+    "@ultimat3/schema": "30.0.0",
+    "@ultimat3/time": "30.0.0"
   }
 }

package/src/ax-node.ts

@@ -0,0 +1,96 @@
+// The one reader of the browser's accessibility nodes: what the BROWSER computed for a screen
+// reader, after ARIA, label association and `aria-hidden` pruning. `x shot` reads one selector's
+// node through it (`cli/src/cdp-shot-a11y.ts`), the e2e audit a whole document (`e2e-a11y.ts`).
+// Every answer is somebody else's JSON, read and never cast.
+
+/** What a screen reader is told about one element — the browser's computed role and name. */
+export interface AxNode {
+  readonly role: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly value?: string | undefined;
+  readonly focused?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly ignored: boolean;
+}
+
+/**
+ * One node of a full tree, with the two facts the audit keys on that `AxNode` drops: whether the
+ * role is an ARIA `role` or Chrome's `internalRole` (so the document's `RootWebArea` is never
+ * confused with an author's string), and the DOM node it describes. `html` and `matches` are
+ * filled only for a node the caller asked to have described — one round trip each, never all.
+ */
+export interface AxTreeNode extends AxNode {
+  readonly roleType: string;
+  readonly backendNodeId?: number | undefined;
+  /** The element's `outerHTML`, bounded by the describer. */
+  readonly html?: string | undefined;
+  /** Which of the selectors the describer was handed this element matches. */
+  readonly matches?: readonly string[] | undefined;
+}
+
+export const axRecord = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+
+/** CDP's `AXValue.value` is any scalar; a reader is told text. */
+const textOf = (wrapped: unknown): string | undefined => {
+  const value = axRecord(wrapped)?.['value'];
+  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+    ? String(value)
+    : undefined;
+};
+
+const flagOf = (node: Readonly<Record<string, unknown>>, name: string): boolean | undefined => {
+  const properties = node['properties'];
+  if (!Array.isArray(properties)) return undefined;
+  const found = properties.map(axRecord).find((property) => property?.['name'] === name);
+  return found === undefined ? undefined : axRecord(found['value'])?.['value'] === true;
+};
+
+const readNode = (node: Readonly<Record<string, unknown>>): AxNode => {
+  const description = textOf(node['description']);
+  const value = textOf(node['value']);
+  const focused = flagOf(node, 'focused');
+  const disabled = flagOf(node, 'disabled');
+  return {
+    role: textOf(node['role']) ?? '',
+    name: textOf(node['name']) ?? '',
+    ...(description === undefined ? {} : { description }),
+    ...(value === undefined ? {} : { value }),
+    ...(focused === undefined ? {} : { focused }),
+    ...(disabled === undefined ? {} : { disabled }),
+    ignored: node['ignored'] === true,
+  };
+};
+
+/**
+ * `nodes[0]` is the element's own node when `fetchRelatives` is false. An EMPTY list is a real
+ * answer — an element that never entered the tree — and is kept as ignored, so the count the
+ * caller gets is the count of matches.
+ */
+export const toAxNode = (answer: Readonly<Record<string, unknown>> | undefined): AxNode => {
+  const nodes = answer?.['nodes'];
+  const node = Array.isArray(nodes) ? axRecord(nodes[0]) : undefined;
+  return node === undefined ? { role: '', name: '', ignored: true } : readNode(node);
+};
+
+/** Every node of a full-tree answer, in the browser's order. A non-object entry is skipped. */
+export const toAxTreeNodes = (
+  answer: Readonly<Record<string, unknown>> | undefined,
+): readonly AxTreeNode[] => {
+  const nodes = answer?.['nodes'];
+  if (!Array.isArray(nodes)) return [];
+  const out: AxTreeNode[] = [];
+  for (const raw of nodes) {
+    const node = axRecord(raw);
+    if (node === undefined) continue;
+    const roleType = axRecord(node['role'])?.['type'];
+    const backendNodeId = node['backendDOMNodeId'];
+    out.push({
+      ...readNode(node),
+      roleType: typeof roleType === 'string' ? roleType : '',
+      ...(typeof backendNodeId === 'number' ? { backendNodeId } : {}),
+    });
+  }
+  return out;
+};

package/src/cassette-errors.ts

@@ -0,0 +1,91 @@
+// The four refusals a cassette raises: nothing to replay, a recording the code no longer drives,
+// a secret about to reach disk, and a recording that must not run. Codes and titles are
+// registered in ./errors; the throw sites are ./cassette and ./cassette-record.
+
+import { renderFixLiteral, renderFixShellArg, UltimateError } from '@ultimat3/core';
+
+/** The command that (re)records every cassette under a test directory. */
+const recordCommand = (dir: string): string =>
+  `ULTIMATE_CASSETTE=record bun test ${renderFixShellArg(dir, '<test dir>')}`;
+
+export class CassetteMissingError extends UltimateError {
+  constructor(input: { readonly file: string; readonly dir: string; readonly name: string }) {
+    super({
+      code: 'X_CASSETTE_MISSING',
+      cause: `cassette ${JSON.stringify(input.name)} has no recording at ${input.file}, so there is nothing to replay`,
+      fix: `${recordCommand(input.dir)}   # with cassette(import.meta.dir, ${renderFixLiteral(input.name, "'<name>'")}, { record: { hosts: ['<vendor host>'] } }), CI unset`,
+      meta: { file: input.file },
+    });
+  }
+}
+
+export interface UnusedEntry {
+  readonly method: string;
+  readonly url: string;
+  /** The entry's position among the recording's entries for this method and URL. */
+  readonly index: number;
+}
+
+export class CassetteUnusedError extends UltimateError {
+  constructor(input: {
+    readonly file: string;
+    readonly dir: string;
+    readonly unused: readonly UnusedEntry[];
+  }) {
+    const first = input.unused[0];
+    const named = first === undefined ? '' : `, first ${first.method} ${first.url}`;
+    super({
+      code: 'X_CASSETTE_UNUSED',
+      cause: `${input.unused.length} recorded answer(s) in ${input.file} were never asked for${named}: the recording describes a run the code no longer makes`,
+      fix: `${recordCommand(input.dir)}   # re-record — or delete the entries meta.unused names from ${input.file}`,
+      meta: { file: input.file, unused: input.unused },
+    });
+  }
+}
+
+export class CassetteSecretError extends UltimateError {
+  constructor(input: {
+    readonly file: string;
+    readonly dir: string;
+    /** An env key, or `secrets[<i>]` for a value the cassette was handed. Never the value. */
+    readonly key: string;
+    readonly offset: number;
+    readonly encoding: string;
+  }) {
+    const source = input.key.startsWith('secrets[')
+      ? 'the value you passed in secrets'
+      : `Bun.env[${renderFixLiteral(input.key, "'<KEY>'")}] ?? ''`;
+    super({
+      code: 'X_CASSETTE_SECRET',
+      cause: `the value of ${input.key} (${input.encoding}) is at byte ${input.offset} of what ${input.file} would hold; nothing was written`,
+      fix: `cassette(import.meta.dir, '<name>', { redact: (text) => text.replaceAll(${source}, '[redacted]') })   # covers ${input.key} at byte ${input.offset}; then ${recordCommand(input.dir)}`,
+      meta: { file: input.file, key: input.key, offset: input.offset, encoding: input.encoding },
+    });
+  }
+}
+
+export type RecordRefusal =
+  | { readonly reason: 'ci' }
+  | { readonly reason: 'no-hosts' }
+  | { readonly reason: 'host'; readonly host: string };
+
+export class CassetteRecordRefusedError extends UltimateError {
+  constructor(input: RecordRefusal & { readonly name: string }) {
+    const name = renderFixLiteral(input.name, "'<name>'");
+    const host = input.reason === 'host' ? renderFixLiteral(input.host, "'<host>'") : "'<host>'";
+    const why =
+      input.reason === 'ci'
+        ? 'CI is set: a gate never reaches a vendor, so a recording only runs on a developer machine'
+        : input.reason === 'no-hosts'
+          ? 'ULTIMATE_CASSETTE=record is set but the cassette names no record.hosts to let through'
+          : `the run requested ${input.host}, which record.hosts does not name`;
+    super({
+      code: 'X_CASSETTE_RECORD_REFUSED',
+      cause: `cassette ${JSON.stringify(input.name)} refused to record: ${why}`,
+      fix:
+        input.reason === 'ci'
+          ? 'env -u CI ULTIMATE_CASSETTE=record bun test <test file>   # on a developer machine; CI only replays'
+          : `cassette(import.meta.dir, ${name}, { record: { hosts: [${host}] } })   # add the host`,
+    });
+  }
+}

package/src/cassette-format.ts

@@ -0,0 +1,175 @@
+// What a cassette file holds and how a recorded answer is made safe to hold: response headers on
+// an allow-list, credential-named keys masked in JSON bodies and URL queries, sorted keys, and a
+// non-text body as base64. The request side is never written — a test asserts it via `requestLog`.
+
+import { assert, isRedactedKey, REDACTED, renderFixShellArg } from '@ultimat3/core';
+
+export const CASSETTE_VERSION = 1;
+
+export interface CassetteEntry {
+  readonly method: string;
+  /** The URL as the call spelled it, credential-named query values masked. */
+  readonly url: string;
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  readonly encoding: 'utf8' | 'base64';
+}
+
+export interface CassetteFile {
+  readonly version: number;
+  readonly entries: readonly CassetteEntry[];
+}
+
+/**
+ * An ALLOW-list: a deny-list misses the vendor's next header, and a header is where a session
+ * cookie or a request id tied to an account rides back.
+ */
+const KEPT_HEADERS: readonly RegExp[] = [/^content-type$/, /^retry-after$/, /^ratelimit-/];
+
+export const keptHeaders = (headers: Headers): Record<string, string> => {
+  const kept: Record<string, string> = {};
+  headers.forEach((value, name) => {
+    const lower = name.toLowerCase();
+    if (KEPT_HEADERS.some((rule) => rule.test(lower))) kept[lower] = value;
+  });
+  return kept;
+};
+
+/** The masked value as a query string carries it. */
+const MASKED_QUERY = encodeURIComponent(REDACTED);
+
+/** Each `key=value` whose key names a credential gets the mask; every other byte kept verbatim. */
+export function maskUrl(url: string): string {
+  const queryAt = url.indexOf('?');
+  if (queryAt < 0) return url;
+  const hashAt = url.indexOf('#', queryAt);
+  const end = hashAt < 0 ? url.length : hashAt;
+  const pairs = url.slice(queryAt + 1, end).split('&');
+  const masked = pairs.map((pair) => {
+    const eq = pair.indexOf('=');
+    if (eq < 0) return pair;
+    return isRedactedKey(decodeKey(pair.slice(0, eq)))
+      ? `${pair.slice(0, eq)}=${MASKED_QUERY}`
+      : pair;
+  });
+  return `${url.slice(0, queryAt + 1)}${masked.join('&')}${url.slice(end)}`;
+}
+
+/**
+ * The match for a recorded URL: exact where nothing was masked, else a pattern where each mask —
+ * a query value, or a `[redacted]` an app's `redact` put in a path — stands for one value, so the
+ * replayed request, carrying the real key, still matches.
+ */
+export function urlMatch(recorded: string): string | RegExp {
+  const masks = [MASKED_QUERY, REDACTED];
+  if (!masks.some((mask) => recorded.includes(mask))) return recorded;
+  const pattern = recorded
+    .split(MASKED_QUERY)
+    .map((part) => part.split(REDACTED).map(escapeRegExp).join('[^/?&#]*'))
+    .join('[^&#]*');
+  return new RegExp(`^${pattern}$`);
+}
+
+/** A JSON body with every credential-named key's value masked, at any depth; other text as is. */
+export function redactBody(text: string, contentType: string | undefined): string {
+  if (contentType !== undefined && !/json/i.test(contentType)) return text;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return text; // Not JSON: the app's `redact` and the scan are what stand between it and disk.
+  }
+  return JSON.stringify(masked(parsed));
+}
+
+const masked = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(masked);
+  if (typeof value !== 'object' || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      isRedactedKey(key) ? REDACTED : masked(child),
+    ]),
+  );
+};
+
+const TEXT_TYPE = /^text\/|json|xml|javascript|x-www-form-urlencoded|event-stream/i;
+
+/** A body as the file holds it: text when it is text, base64 otherwise. */
+export function encodeBody(
+  bytes: Uint8Array,
+  contentType: string | undefined,
+): Pick<CassetteEntry, 'body' | 'encoding'> {
+  if (contentType === undefined || TEXT_TYPE.test(contentType)) {
+    try {
+      return { body: new TextDecoder('utf-8', { fatal: true }).decode(bytes), encoding: 'utf8' };
+    } catch {
+      // Labelled text, or unlabelled, that is not UTF-8: keep the bytes, not a lossy decode.
+    }
+  }
+  return { body: Buffer.from(bytes).toString('base64'), encoding: 'base64' };
+}
+
+export const decodeBody = (entry: CassetteEntry): Uint8Array<ArrayBuffer> =>
+  entry.encoding === 'base64'
+    ? Uint8Array.from(Buffer.from(entry.body, 'base64'))
+    : new TextEncoder().encode(entry.body);
+
+/** Sorted keys at every depth and a trailing newline: a re-recording diffs by what changed. */
+export function serializeCassette(file: CassetteFile): string {
+  return `${JSON.stringify(sorted(file), null, 2)}\n`;
+}
+
+const sorted = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (typeof value !== 'object' || value === null) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, sorted((value as Record<string, unknown>)[key])]),
+  );
+};
+
+/** The file read back, its shape checked: a hand-edited cassette that broke is named, not replayed. */
+export function parseCassette(text: string, file: string): CassetteFile {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = undefined;
+  }
+  const fix = `rm ${renderFixShellArg(file, '<cassette file>')} && ULTIMATE_CASSETTE=record bun test <test file>`;
+  const shaped =
+    typeof parsed === 'object' &&
+    parsed !== null &&
+    (parsed as { version?: unknown }).version === CASSETTE_VERSION &&
+    Array.isArray((parsed as { entries?: unknown }).entries) &&
+    (parsed as { entries: unknown[] }).entries.every(isEntry);
+  assert(shaped, `${file} is not a version ${CASSETTE_VERSION} cassette`, fix);
+  return parsed as CassetteFile;
+}
+
+const isEntry = (value: unknown): value is CassetteEntry => {
+  if (typeof value !== 'object' || value === null) return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry['method'] === 'string' &&
+    typeof entry['url'] === 'string' &&
+    typeof entry['status'] === 'number' &&
+    typeof entry['body'] === 'string' &&
+    (entry['encoding'] === 'utf8' || entry['encoding'] === 'base64') &&
+    typeof entry['headers'] === 'object' &&
+    entry['headers'] !== null
+  );
+};
+
+function decodeKey(key: string): string {
+  try {
+    return decodeURIComponent(key.replace(/\+/g, ' '));
+  } catch {
+    return key;
+  }
+}
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/src/cassette-record.ts

@@ -0,0 +1,120 @@
+// The recording half of a cassette: a tap OVER the sealed `fetch` that copies each answer from a
+// host `record.hosts` names, and the dispose that redacts, scans and writes them. Nothing here
+// decides what gets through — the seal still does; `record.hosts` reaches it through `allowHost`.
+
+import { stringField } from '@ultimat3/core';
+import { CassetteRecordRefusedError, CassetteSecretError } from './cassette-errors';
+import type { CassetteEntry } from './cassette-format';
+import {
+  CASSETTE_VERSION,
+  encodeBody,
+  keptHeaders,
+  maskUrl,
+  redactBody,
+  serializeCassette,
+} from './cassette-format';
+import { findSecret, secretSources } from './cassette-secret-scan';
+import type { FetchLike } from './sealed-network';
+
+export interface RecordInput {
+  readonly name: string;
+  readonly dir: string;
+  readonly file: string;
+  readonly hosts: ReadonlySet<string>;
+  readonly redact: ((text: string) => string) | undefined;
+  readonly secrets: readonly string[];
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Writes the checked bytes; ./cassette owns the filesystem. */
+  readonly write: (text: string) => void;
+}
+
+export interface Recording {
+  /** Removes the tap, then writes — or throws, and writes nothing. */
+  finish(): Promise<void>;
+}
+
+const urlOf = (input: RequestInfo | URL): string =>
+  typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+
+const methodOf = (input: RequestInfo | URL, init: RequestInit | undefined): string =>
+  (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+
+const hostOf = (url: string): string | undefined =>
+  URL.canParse(url) ? new URL(url).host : undefined;
+
+export function startRecording(input: RecordInput): Recording {
+  const sealed: FetchLike = globalThis.fetch;
+  // One slot per call, taken BEFORE the await: the file keeps call order, not answer order.
+  const slots: Promise<CassetteEntry>[] = [];
+  const tap = (async (request: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const url = urlOf(request);
+    const method = methodOf(request, init);
+    const host = hostOf(url);
+    const recorded = host !== undefined && input.hosts.has(host);
+    let answer: Promise<Response>;
+    try {
+      answer = sealed(request, init);
+      if (!recorded) return await answer;
+    } catch (error) {
+      // The seal's own refusal names `allowHost`; while recording, the line to edit is the
+      // cassette's own `record.hosts`.
+      if (stringField(error, 'code') === 'X_TEST_NETWORK_SEALED' && host !== undefined) {
+        throw new CassetteRecordRefusedError({ reason: 'host', host, name: input.name });
+      }
+      throw error;
+    }
+    const slot = answer.then(async (response) => {
+      const contentType = response.headers.get('content-type') ?? undefined;
+      const bytes = new Uint8Array(await response.clone().arrayBuffer());
+      return {
+        method,
+        url: maskUrl(url),
+        status: response.status,
+        headers: keptHeaders(response.headers),
+        ...encodeBody(bytes, contentType),
+      } satisfies CassetteEntry;
+    });
+    slots.push(slot);
+    // A failed dial is the test's failure as it would be unrecorded; the slot fails `finish` too.
+    slot.catch(() => undefined);
+    return answer;
+  }) as FetchLike;
+  globalThis.fetch = tap;
+
+  return {
+    async finish() {
+      // Only our own tap is removed: something that replaced it since owns `fetch` now.
+      if (globalThis.fetch === tap) globalThis.fetch = sealed;
+      // A body that failed to read rejects here, so a half run is never a recording.
+      const entries = (await Promise.all(slots)).map((entry) => redacted(entry, input.redact));
+      const text = serializeCassette({ version: CASSETTE_VERSION, entries });
+      // LAST, over the exact bytes about to be written — what `redact` returned included.
+      const sources = secretSources(input.env, input.secrets);
+      // A base64 body hides a value at any of three alignments, so its bytes are scanned too.
+      const hit =
+        findSecret(text, sources) ??
+        entries
+          .filter((entry) => entry.encoding === 'base64')
+          .map((entry) => findSecret(Buffer.from(entry.body, 'base64').toString('latin1'), sources))
+          .find((found) => found !== undefined);
+      if (hit !== undefined) {
+        throw new CassetteSecretError({ file: input.file, dir: input.dir, ...hit });
+      }
+      input.write(text);
+    },
+  };
+}
+
+function redacted(
+  entry: CassetteEntry,
+  redact: ((text: string) => string) | undefined,
+): CassetteEntry {
+  const body =
+    entry.encoding === 'utf8' ? redactBody(entry.body, entry.headers['content-type']) : entry.body;
+  if (redact === undefined) return { ...entry, body };
+  return {
+    ...entry,
+    url: redact(entry.url),
+    body: entry.encoding === 'utf8' ? redact(body) : body,
+  };
+}

package/src/cassette-secret-scan.ts

@@ -0,0 +1,77 @@
+// The last check before a cassette reaches disk: is any secret's value in the exact bytes about
+// to be written, in any of the encodings a vendor echoes one back in? A hit names the KEY and the
+// byte offset — never the value, which would put it in a terminal and a CI log instead.
+
+import { isRedactedKey } from '@ultimat3/core';
+
+/**
+ * Shorter values are skipped, stated rather than hidden: a 4-character "secret" occurs by chance
+ * in any base64 body, and a refusal that fires on noise is one somebody switches off.
+ */
+export const SECRET_MIN_LENGTH = 8;
+
+export interface SecretSource {
+  /** An env key, or `secrets[<i>]` for a value handed to the cassette. */
+  readonly key: string;
+  readonly value: string;
+}
+
+export interface SecretHit {
+  readonly key: string;
+  /** UTF-8 byte offset into the scanned text. */
+  readonly offset: number;
+  readonly encoding: 'raw' | 'json' | 'percent' | 'base64' | 'base64url';
+}
+
+/**
+ * What to look for: every env value whose key `isRedactedKey` answers yes to (which includes every
+ * key `defineEnv({ secret: true })` registered), plus the values the cassette was handed.
+ */
+export function secretSources(
+  env: Readonly<Record<string, string | undefined>>,
+  extra: readonly string[],
+): readonly SecretSource[] {
+  const sources: SecretSource[] = [];
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined && value.length >= SECRET_MIN_LENGTH && isRedactedKey(key)) {
+      sources.push({ key, value });
+    }
+  }
+  extra.forEach((value, index) => {
+    if (value.length >= SECRET_MIN_LENGTH) sources.push({ key: `secrets[${index}]`, value });
+  });
+  return sources;
+}
+
+/** The first secret found in `text`, by position; `undefined` when the bytes are clean. */
+export function findSecret(text: string, sources: readonly SecretSource[]): SecretHit | undefined {
+  let first: { hit: SecretHit; index: number } | undefined;
+  for (const source of sources) {
+    for (const [encoding, needle] of encodings(source.value)) {
+      const index = text.indexOf(needle);
+      if (index >= 0 && (first === undefined || index < first.index)) {
+        first = { index, hit: { key: source.key, offset: byteOffset(text, index), encoding } };
+      }
+    }
+  }
+  return first?.hit;
+}
+
+function encodings(value: string): ReadonlyArray<readonly [SecretHit['encoding'], string]> {
+  const bytes = Buffer.from(value, 'utf8');
+  // Padding is dropped: a value base64-encoded inside a longer string carries none of its own.
+  const base64 = bytes.toString('base64').replace(/=+$/, '');
+  const base64url = bytes.toString('base64url');
+  return [
+    ['raw', value],
+    // As a JSON string literal holds it: a quote or a backslash in the value is escaped there.
+    ['json', JSON.stringify(value).slice(1, -1)],
+    ['percent', encodeURIComponent(value)],
+    ['base64', base64],
+    ['base64url', base64url],
+  ];
+}
+
+function byteOffset(text: string, index: number): number {
+  return Buffer.byteLength(text.slice(0, index), 'utf8');
+}