lynkeus 0.4.0 → 0.5.0

package/src/cases/coverage.ts

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { Affected } from '../knowledge/query.js';
+import type { Case, Step } from './format.js';
+
+const ROUTE = /^[A-Z][\w.]+$/;
+
+// A step names a route when it goes there, waits for it or checks it is on screen.
+const routeOf = (step: Step): string | undefined => {
+  const v = step.value;
+  const named = (x: unknown) => (typeof x === 'string' && ROUTE.test(x) ? x : undefined);
+  if (step.verb === 'app.nav' || step.verb === 'app.wait')
+    return (
+      named(v) ??
+      (v && typeof v === 'object' && !Array.isArray(v) ? named((v as Record<string, unknown>).route ?? (v as Record<string, unknown>).what) : undefined)
+    );
+  if (step.verb === 'app.see') return v && typeof v === 'object' && !Array.isArray(v) ? named((v as Record<string, unknown>).route) : undefined;
+  return undefined;
+};
+
+/** The routes a case names in its steps. */
+export const routesNamed = (c: Case): string[] => [...new Set([...c.setup, ...c.steps].map(routeOf).filter((r): r is string => !!r))];
+
+/** What `case run --seen <dir>` kept: each passing case's screens, by case id. */
+export const readSeen = (dir: string | undefined): Record<string, string[]> => {
+  if (!dir || !fs.existsSync(dir)) return {};
+  const seen: Record<string, string[]> = {};
+  for (const file of fs.readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8')) as { id?: string; routes?: unknown };
+      if (typeof s.id === 'string' && Array.isArray(s.routes)) seen[s.id] = s.routes.filter((r): r is string => typeof r === 'string');
+    } catch {}
+  }
+  return seen;
+};
+
+export type Coverage = {
+  routes: number;
+  covered: string[];
+  uncovered: string[];
+  /** Routes a case names that the graph does not know: renamed, or a typo. */
+  unknown: string[];
+  byRoute: Record<string, string[]>;
+  files: Record<string, string>;
+};
+
+/** Which cases touch which of the app's routes, by what they name and what they went through last time they passed. */
+export const coverageOf = (cases: Case[], graphRoutes: string[], seen: Record<string, string[]> = {}): Coverage => {
+  const byRoute: Record<string, string[]> = {};
+  const files: Record<string, string> = {};
+  const add = (route: string, id: string) => {
+    byRoute[route] ??= [];
+    if (!byRoute[route].includes(id)) byRoute[route].push(id);
+  };
+  for (const c of cases) {
+    files[c.id] = c.file;
+    for (const r of routesNamed(c)) add(r, c.id);
+    for (const r of seen[c.id] ?? []) add(r, c.id);
+  }
+  const known = new Set(graphRoutes);
+  const covered = graphRoutes.filter((r) => byRoute[r]?.length);
+  return {
+    routes: graphRoutes.length,
+    covered,
+    uncovered: graphRoutes.filter((r) => !byRoute[r]?.length),
+    unknown: Object.keys(byRoute)
+      .filter((r) => !known.has(r))
+      .sort(),
+    byRoute,
+    files,
+  };
+};
+
+export type Impact = {
+  /** Each case to run, with the reached routes it touches, nearest first. */
+  cases: { id: string; file: string; routes: string[]; distance: number; via: string }[];
+  /** Routes the change reaches that no case touches. */
+  untested: string[];
+};
+
+/** The cases a change reaches: the screens it touches or imports, crossed with what each case covers. */
+export const impactOf = (affected: Affected[], coverage: Coverage): Impact => {
+  const nearest = new Map<string, Affected>();
+  for (const a of affected) if (!nearest.has(a.route) || nearest.get(a.route)!.distance > a.distance) nearest.set(a.route, a);
+  const byCase = new Map<string, Impact['cases'][number]>();
+  const untested: string[] = [];
+  for (const [route, hit] of nearest) {
+    const ids = coverage.byRoute[route] ?? [];
+    if (!ids.length) untested.push(route);
+    for (const id of ids) {
+      const c = byCase.get(id) ?? { id, file: coverage.files[id] ?? '', routes: [], distance: hit.distance, via: hit.via };
+      c.routes.push(route);
+      if (hit.distance < c.distance) Object.assign(c, { distance: hit.distance, via: hit.via });
+      byCase.set(id, c);
+    }
+  }
+  return { cases: [...byCase.values()].sort((a, b) => a.distance - b.distance || a.id.localeCompare(b.id)), untested: untested.sort() };
+};

package/src/cases/draft.ts

@@ -0,0 +1,75 @@
+import type { FixtureCommand } from 'lynkeus-protocol';
+
+import type { PlanStep } from '../knowledge/plan.js';
+
+export type DraftInput = {
+  id: string;
+  title?: string;
+  from: string;
+  to: string;
+  /** The way from `from` to `to`, as `map plan` finds it; undefined when no path is known. */
+  path: PlanStep[] | undefined;
+  /** What the project's fixtures server says it can do, offered as the setup to pick from. */
+  fixtures?: FixtureCommand[];
+  /** The project's macros (`app.login`…), offered too. */
+  macros?: string[];
+  /** The project declares a fixtures server that did not describe itself. */
+  fixturesSilent?: boolean;
+};
+
+const quote = (s: string) => JSON.stringify(s);
+
+const paramsHint = (c: FixtureCommand) => {
+  const params = Object.entries(c.params ?? {}).map(([k, p]) => `${k}${p.values ? ` (${p.values.join('|')})` : ''}`);
+  return params.length ? ` — ${params.join(', ')}` : '';
+};
+
+/**
+ * A case to finish: its frontmatter with the questions a reader needs answered, the backend's setup offered (never
+ * chosen: what state the case needs is the author's call), the way to the screen, and the checks left to write.
+ */
+export const draftCase = (d: DraftInput): string => {
+  const lines = [
+    '---',
+    `id: ${d.id}`,
+    `title: ${quote(d.title ?? `[What a person can do on ${d.to}]`)}`,
+    'description: >',
+    '  [What this case proves, in a sentence or two.]',
+    'why: >',
+    '  [What breaks for a person if it fails.]',
+    'given: >',
+    `  [Who the user is and what is true when it starts, on ${d.from}.]`,
+    '---',
+    'setup:',
+  ];
+  if (d.fixtures?.length) {
+    lines.push('  # Pick what the case needs; the backend answers these (lynkeus fixtures describe):');
+    for (const c of d.fixtures) {
+      const example = c.example ? ` ${JSON.stringify(c.example).replace(/"(\w+)":/g, '$1: ')}` : ' {}';
+      lines.push(`  # - ${c.name}:${example}${c.summary ? `    # ${c.summary}` : ''}${paramsHint(c)}`);
+    }
+  } else if (d.fixturesSilent)
+    lines.push('  # The fixtures server did not answer lynkeus.describe (lynkeus fixtures check says why): the setup options are not listed.');
+  else lines.push('  # The state the case needs, through the project’s fixtures (cases.fixtures).');
+  lines.push('', 'steps:');
+  if (d.macros?.length) lines.push(`  # The project's own steps: ${d.macros.join(', ')}`);
+  if (!d.path) {
+    lines.push(`  # No known way from ${d.from} to ${d.to}: \`lynkeus crawl --to ${d.to}\` learns one.`);
+    lines.push(`  - app.nav: ${d.to}`);
+  } else {
+    for (const s of d.path) {
+      if (s.press) lines.push(`  - app.press: ${quote(`#${s.press}`)}${s.source === 'static' ? '    # from the source: confirm it on screen' : ''}`);
+      else lines.push(`  # ${s.from} → ${s.to}: ${s.hint ?? 'find the control that leads here'}`);
+      lines.push(`  - app.wait: { what: ${s.opens ? quote(s.opens) : s.to}, timeoutMs: 10000 }`);
+    }
+  }
+  lines.push(
+    `  - app.see: { route: ${d.to} }`,
+    '  # [What the person does here, and what must be on screen after.]',
+    '',
+    'expected: |',
+    '  [What must be true when it ends, on screen and in the backend.]',
+    '',
+  );
+  return lines.join('\n');
+};

package/src/cases/fixtures.ts

@@ -13,7 +13,8 @@
  *
  *   {"command": "lynkeus.describe", "params": {}, "env": {}}
  *
- * — and a server that knows answers `{"commands": ["create_user", …]}`. With
+ * — and a server that knows answers `{"commands": ["create_user", …]}`, each entry a name or a description
+ * (`FixtureCommand` in lynkeus-protocol: summary, params, example). The contract is docs/FIXTURES.md. With
  * that, a case naming a fixture nobody answers is refused before anything
  * runs. A server that answers `"ok": false`, as one written before this did,
  * is taken to describe nothing, and its cases run unchecked. A server that is
@@ -26,9 +27,12 @@
  * answer anything.
  */
 import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 
+import type { FixtureCommand } from 'lynkeus-protocol';
+
 export type FixturesConfig = { command: string; cwd?: string; env?: Record<string, string>; timeoutMs?: number };
 
 export type Answer = Record<string, unknown>;
@@ -36,7 +40,23 @@ export type Answer = Record<string, unknown>;
 /** The one command that is lynkeus's own and not the project's. */
 export const DESCRIBE = 'lynkeus.describe';
 
-export type Description = { commands: string[]; down?: string };
+/** What the server answers: the names, with each command's description where it gave one. */
+export type Description = { commands: string[]; details: FixtureCommand[]; down?: string; protocol?: number };
+
+/** A description as the server sent it, names and descriptions mixed, made one shape; anything else is no description. */
+export const readDescription = (answer: Record<string, unknown> | undefined): Description | undefined => {
+  const list = answer?.commands;
+  if (!Array.isArray(list)) return undefined;
+  const details: FixtureCommand[] = [];
+  for (const c of list) {
+    if (typeof c === 'string' && c) details.push({ name: c });
+    else if (c && typeof c === 'object' && typeof (c as FixtureCommand).name === 'string' && (c as FixtureCommand).name) details.push(c as FixtureCommand);
+    else return undefined;
+  }
+  const down = typeof answer?.down === 'string' && answer.down ? answer.down : undefined;
+  const protocol = typeof answer?.protocol === 'number' ? answer.protocol : undefined;
+  return { commands: details.map((d) => d.name), details, ...(down ? { down } : {}), ...(protocol !== undefined ? { protocol } : {}) };
+};
 
 /** lynkeus's second own command: this connection works ahead of the cases. */
 export const AHEAD = 'lynkeus.ahead';
@@ -48,6 +68,18 @@ const envOf = (params: Record<string, unknown>): Record<string, string> =>
       .map(([k, v]) => [k.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase(), typeof v === 'object' ? JSON.stringify(v) : String(v)]),
   );
 
+const describedFile = (root: string) => path.join(root, '.lynkeus', 'fixtures-described.json');
+
+/** What the server last said it answers, and how long ago; undefined when it never did for this command. */
+export const lastDescription = (root: string, command: string): { at: number; description: Description } | undefined => {
+  try {
+    const kept = JSON.parse(fs.readFileSync(describedFile(root), 'utf8')) as { at: number; command: string; description: Description };
+    return kept.command === command ? { at: kept.at, description: kept.description } : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
 export class Fixtures {
   #config: FixturesConfig;
   #root: string;
@@ -55,6 +87,10 @@ export class Fixtures {
   #lines: string[] = [];
   #waiting: ((line: string | null) => void) | null = null;
   #stderr = '';
+  // Ends in a row without one answer. A command that cannot start (a wrong path, a backend that is not
+  // there) would otherwise be started again for every case, and each case would wait out its own start.
+  #silentEnds = 0;
+  #broken: string | null = null;
 
   constructor(config: FixturesConfig, root: string) {
     this.#config = config;
@@ -70,12 +106,15 @@ export class Fixtures {
       cwd: path.resolve(this.#root, this.#config.cwd ?? '.'),
       env: { ...process.env, ...this.#config.env },
     });
+    // Writing to a command that already ended fails here; its close says so to whoever waits.
+    child.stdin.on('error', () => undefined);
     child.stderr.on('data', (chunk: Buffer) => {
       this.#stderr = (this.#stderr + chunk.toString()).slice(-4000);
     });
     const reader = readline.createInterface({ input: child.stdout });
     reader.on('line', (line) => {
       if (!line.trim().startsWith('{')) return;
+      this.#silentEnds = 0;
       if (this.#waiting) {
         const resolve = this.#waiting;
         this.#waiting = null;
@@ -83,6 +122,7 @@ export class Fixtures {
       } else this.#lines.push(line);
     });
     child.on('close', () => {
+      if (this.#child === child) this.#silentEnds += 1;
       this.#child = null;
       this.#waiting?.(null);
       this.#waiting = null;
@@ -92,6 +132,7 @@ export class Fixtures {
   }
 
   async call(command: string, params: Record<string, unknown>): Promise<Answer> {
+    if (this.#broken) throw new Error(`${command}: ${this.#broken}`);
     const child = this.#start();
     child.stdin.write(`${JSON.stringify({ command, params, env: envOf(params) })}\n`);
     const timeoutMs = this.#config.timeoutMs ?? 120_000;
@@ -107,8 +148,11 @@ export class Fixtures {
         resolve(answer);
       };
     });
-    if (line === null)
-      throw new Error(`${command}: the fixtures command ended${this.#stderr ? `: ${this.#stderr.trim().split('\n').slice(-3).join(' · ')}` : ''}`);
+    if (line === null) {
+      const ended = `the fixtures command ended${this.#stderr ? `: ${this.#stderr.trim().split('\n').slice(-3).join(' · ')}` : ''}`;
+      if (this.#silentEnds >= 2) this.#broken = `${ended} (it ended twice without answering, so it is not started again in this run)`;
+      throw new Error(`${command}: ${ended}`);
+    }
     const answer = JSON.parse(line) as Answer;
     if (answer.ok === false) throw new Error(`${command}: ${String(answer.error ?? answer.message ?? 'ok=false')}`);
     return answer;
@@ -116,10 +160,15 @@ export class Fixtures {
 
   /** What the server says it answers, or nothing when it does not say. */
   async describe(): Promise<Description | undefined> {
-    const answer = await this.call(DESCRIBE, {}).catch(() => undefined);
-    const commands = answer?.commands;
-    if (!Array.isArray(commands) || !commands.every((c) => typeof c === 'string')) return undefined;
-    return typeof answer?.down === 'string' && answer.down ? { commands, down: answer.down } : { commands };
+    const d = readDescription(await this.call(DESCRIBE, {}).catch(() => undefined));
+    // Kept for `fixtures describe`: a server that boots a backend's framework takes longer to start than an MCP
+    // client waits, and what it answers changes only with its code.
+    if (d && !d.down)
+      try {
+        fs.mkdirSync(path.dirname(describedFile(this.#root)), { recursive: true });
+        fs.writeFileSync(describedFile(this.#root), JSON.stringify({ at: Date.now(), command: this.#config.command, description: d }));
+      } catch {}
+    return d;
   }
 
   /** Says this connection works ahead of the cases being run. Whatever the server answers, it goes on. */

package/src/cases/frames.ts

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+
+type Encoder = (input: string) => { avif: (o: { quality: number; effort: number }) => { toFile: (path: string) => Promise<unknown> } };
+
+let encoder: Promise<Encoder | null> | undefined;
+// sharp is optional: a CLI installed without it keeps the PNG the host took.
+const load = () => {
+  const name = 'sharp';
+  encoder ??= import(name).then((m: { default: Encoder }) => m.default).catch(() => null);
+  return encoder;
+};
+
+/**
+ * A simulator or emulator gives its frames as PNG (`simctl io screenshot` cannot write AVIF or WebP, nor can
+ * `screencap`): a report frame is encoded again as AVIF, about 4% of the PNG's bytes in some 70 ms, and the
+ * PNG removed. Answers the frame's path, the PNG's when it could not be encoded.
+ */
+export const compactFrame = async (png: string): Promise<string> => {
+  const sharp = await load();
+  if (!sharp || !png.endsWith('.png')) return png;
+  const avif = `${png.slice(0, -'.png'.length)}.avif`;
+  try {
+    await sharp(png).avif({ quality: 60, effort: 2 }).toFile(avif);
+    fs.unlinkSync(png);
+    return avif;
+  } catch {
+    fs.rmSync(avif, { force: true });
+    return png;
+  }
+};

package/src/cases/nativeLogs.ts

@@ -0,0 +1,112 @@
+import { type ChildProcess, execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import type { DeviceInfo } from '../device/devices.js';
+import type { LogLine } from './runner.js';
+
+const run = promisify(execFile);
+const KEEP = 5000;
+const LONG = 4000;
+
+/** The app's native log while a run goes on: `take` hands over what came since the last take. */
+export type NativeLogs = { take: () => LogLine[]; stop: () => void };
+
+const cut = (text: string) => (text.length > LONG ? `${text.slice(0, LONG)}…` : text);
+
+// `log stream --style ndjson`: one JSON object a line. React Native's own console lines (category javascript)
+// come from the agent already, with their stacks.
+export const parseOsLog = (line: string): LogLine | undefined => {
+  if (!line.startsWith('{')) return undefined;
+  let e: { timestamp?: string; messageType?: string; eventMessage?: string; subsystem?: string; category?: string };
+  try {
+    e = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (!e.eventMessage || !e.timestamp) return undefined;
+  if (e.subsystem === 'com.facebook.react.log' && e.category === 'javascript') return undefined;
+  // "2026-10-16 14:55:01.123456-0300" → an instant.
+  const at = Date.parse(
+    e.timestamp
+      .replace(' ', 'T')
+      .replace(/(\.\d{3})\d*/, '$1')
+      .replace(/([+-]\d\d)(\d\d)$/, '$1:$2'),
+  );
+  if (Number.isNaN(at)) return undefined;
+  const type = (e.messageType ?? '').toLowerCase();
+  const level = type === 'error' || type === 'fault' ? 'error' : type === 'debug' ? 'debug' : 'info';
+  return { at, level, source: 'native', text: cut(e.eventMessage) };
+};
+
+// `logcat -v epoch,uid`: "  1760637301.123  10123  4521  4533 E Tag: message". ReactNativeJS repeats the console.
+export const parseLogcat = (line: string, uid: string): LogLine | undefined => {
+  const m = /^\s*(\d+\.\d+)\s+(\S+)\s+\d+\s+\d+\s+([VDIWEF])\s+([^:]*?)\s*:\s?(.*)$/.exec(line);
+  if (!m || m[2] !== uid) return undefined;
+  const [, seconds, , priority, tag, message] = m;
+  if (tag === 'ReactNativeJS') return undefined;
+  const level = priority === 'E' || priority === 'F' ? 'error' : priority === 'W' ? 'warn' : priority === 'I' ? 'info' : 'debug';
+  return { at: Math.round(Number(seconds) * 1000), level, source: 'native', text: cut(`${tag}: ${message}`) };
+};
+
+const executable = async (udid: string, bundleId: string): Promise<string | undefined> => {
+  const { stdout } = await run('xcrun', ['simctl', 'appinfo', udid, bundleId]);
+  return /CFBundleExecutable = "?([^";\n]+)"?;/.exec(stdout)?.[1];
+};
+
+const androidUid = async (serial: string, appId: string): Promise<string | undefined> => {
+  const { stdout } = await run('adb', ['-s', serial, 'shell', 'cmd', 'package', 'list', 'packages', '-U', appId]);
+  const line = stdout.split('\n').find((l) => l.startsWith(`package:${appId} `));
+  return line ? /uid:(\d+)/.exec(line)?.[1] : undefined;
+};
+
+/**
+ * Streams the app's native log on a simulator or an emulator. A device lynkeus cannot read a log from, or an app it
+ * cannot find there, gives none: the run goes on without it.
+ */
+export const startNativeLogs = async (device: DeviceInfo, appId: string): Promise<NativeLogs | undefined> => {
+  if (device.type === 'physical' || device.id === 'headless') return undefined;
+  const lines: LogLine[] = [];
+  let child: ChildProcess;
+  let parse: (line: string) => LogLine | undefined;
+  try {
+    if (device.platform === 'ios') {
+      const name = await executable(device.id, appId);
+      if (!name) return undefined;
+      // Inside the app's process every Apple framework logs too, thousands of lines a launch: keep its errors, and
+      // the rest only from the app's own code (NSLog and print have no subsystem) and React Native's native side.
+      const own = `subsystem == "" OR subsystem BEGINSWITH "${appId.replaceAll('"', '')}" OR subsystem BEGINSWITH "com.facebook.react"`;
+      const predicate = `process == "${name.replaceAll('"', '')}" AND (messageType == error OR messageType == fault OR ${own})`;
+      child = spawn('xcrun', ['simctl', 'spawn', device.id, 'log', 'stream', '--style', 'ndjson', '--level', 'default', '--predicate', predicate], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      parse = parseOsLog;
+    } else {
+      const uid = await androidUid(device.id, appId);
+      if (!uid) return undefined;
+      // From now on: `-T 1` starts at the newest line instead of replaying the buffer.
+      child = spawn('adb', ['-s', device.id, 'logcat', '-v', 'epoch,uid', '-T', '1'], { stdio: ['ignore', 'pipe', 'ignore'] });
+      parse = (line) => parseLogcat(line, uid);
+    }
+  } catch {
+    return undefined;
+  }
+  let rest = '';
+  child.stdout?.on('data', (chunk: Buffer) => {
+    const text = rest + chunk.toString('utf8');
+    const parts = text.split('\n');
+    rest = parts.pop() ?? '';
+    for (const part of parts) {
+      const line = parse(part);
+      if (!line) continue;
+      lines.push(line);
+      if (lines.length > KEEP) lines.shift();
+    }
+  });
+  child.on('error', () => undefined);
+  return {
+    take: () => lines.splice(0, lines.length),
+    stop: () => {
+      child.kill();
+    },
+  };
+};

package/src/cases/runDirs.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Bytes under a directory, its files and their subfolders'. */
+export const sizeOf = (dir: string): number => {
+  let total = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const at = path.join(dir, entry.name);
+    if (entry.isDirectory()) total += sizeOf(at);
+    else if (entry.isFile()) total += fs.statSync(at).size;
+  }
+  return total;
+};
+
+export const megabytes = (bytes: number) => `${(bytes / 1024 / 1024).toFixed(bytes < 10 * 1024 * 1024 ? 1 : 0)} MB`;
+
+/** `7d`, `12h`, `30m` as milliseconds; anything else is refused. */
+export const ageOf = (text: string): number | undefined => {
+  const m = /^(\d+)([dhm])$/.exec(text.trim());
+  if (!m) return undefined;
+  return Number(m[1]) * { d: 86_400_000, h: 3_600_000, m: 60_000 }[m[2] as 'd' | 'h' | 'm'];
+};
+
+/** A directory `case run --out` wrote: it holds the run's manifest and its cases. */
+const isRun = (dir: string) => fs.existsSync(path.join(dir, 'run.json')) && fs.existsSync(path.join(dir, 'cases.jsonl'));
+
+/**
+ * The runs `case run --out` left, at `root` itself or one level under it, that ended longer than `olderMs` ago.
+ * Only folders that hold a run are touched; `dry` lists them without removing anything.
+ */
+export const pruneRuns = (root: string, olderMs: number, dry = false, now = Date.now()): { removed: string[]; bytes: number } => {
+  const candidates = isRun(root)
+    ? [root]
+    : fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => path.join(root, e.name))
+        .filter(isRun);
+  const removed: string[] = [];
+  let bytes = 0;
+  for (const dir of candidates) {
+    if (now - fs.statSync(path.join(dir, 'run.json')).mtimeMs < olderMs) continue;
+    bytes += sizeOf(dir);
+    removed.push(dir);
+    if (!dry) fs.rmSync(dir, { recursive: true, force: true });
+  }
+  return { removed, bytes };
+};

package/src/cases/runfile.ts

@@ -22,8 +22,19 @@ export const toRunCase = (c: Case, { report, attempt, startedAt }: Attempt, root
     // The runner numbers an event's step from 1, in the order the steps ran.
     const told = (report.events ?? [])
       .filter((e) => e.step === index + 1)
-      .map((e) => ({ origin: 'app' as const, name: e.name, ...(e.props ? { props: e.props } : {}), ...(e.route ? { route: e.route } : {}) }));
-    const sent = (s.sent ?? []).map((e) => ({ origin: 'app' as const, provider: e.provider, name: e.name, ...(e.props ? { props: e.props } : {}) }));
+      .map((e) => ({
+        origin: 'app' as const,
+        ...(e.provider ? { provider: e.provider } : {}),
+        name: e.name,
+        ...(e.props ? { props: e.props } : {}),
+        ...(e.route ? { route: e.route } : {}),
+      }));
+    const sent = (s.sent ?? []).map((e) => ({
+      origin: e.via === 'server' ? ('server' as const) : ('app' as const),
+      provider: e.provider,
+      name: e.name,
+      ...(e.props ? { props: e.props } : {}),
+    }));
     const events = [...told, ...sent];
     const screenshot = within(dir, s.screenshot);
     return {
@@ -36,6 +47,8 @@ export const toRunCase = (c: Case, { report, attempt, startedAt }: Attempt, root
       ...(screenshot ? { screenshot } : {}),
       ...(s.videoS !== undefined ? { videoS: s.videoS } : {}),
       ...(s.backend?.length ? { backend: s.backend } : {}),
+      ...(s.requests?.length ? { requests: s.requests } : {}),
+      ...(s.logs?.length ? { logs: s.logs } : {}),
     };
   });
   const description = typeof c.meta.description === 'string' ? c.meta.description : undefined;
@@ -44,6 +57,7 @@ export const toRunCase = (c: Case, { report, attempt, startedAt }: Attempt, root
     id: report.id,
     ...(report.title ? { title: report.title } : {}),
     ...(description ? { description } : {}),
+    ...(report.about ? { about: report.about } : {}),
     file: path.relative(root, path.resolve(root, report.file)),
     attempt,
     result: report.result,
@@ -57,7 +71,7 @@ export const toRunCase = (c: Case, { report, attempt, startedAt }: Attempt, root
 };
 
 /** The branch and commit the run was made from, so a report can say which code it tested. */
-const gitOf = (root: string): RunManifest['git'] => {
+export const gitOf = (root: string): RunManifest['git'] => {
   const ask = (...args: string[]) => {
     try {
       return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
@@ -68,7 +82,53 @@ const gitOf = (root: string): RunManifest['git'] => {
   const commit = ask('rev-parse', '--short', 'HEAD');
   if (!commit) return undefined;
   const branch = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || ask('rev-parse', '--abbrev-ref', 'HEAD');
-  return { commit, ...(branch && branch !== 'HEAD' ? { branch } : {}) };
+  const remote = webOf(ask('remote', 'get-url', 'origin'));
+  // What the run had that no commit has: a report says the app was not exactly the commit it names.
+  const changed = (ask('status', '--porcelain', '--untracked-files=no') ?? '')
+    .split('\n')
+    .map((l) => l.slice(3).trim())
+    .filter(Boolean);
+  // A branch that lives only on this machine names nothing a reader can open: the run names the remote branch
+  // that has its commit instead (the one it tracks first, else any), and keeps the local name beside it.
+  const local = branch && branch !== 'HEAD' ? branch : undefined;
+  const onRemote = (name: string) => !!ask('rev-parse', '--verify', '--quiet', `refs/remotes/origin/${name}`);
+  const holding = remote && local && !onRemote(local) ? remoteBranchWith(ask, commit) : undefined;
+  const shown = holding ?? local;
+  const pushed = remote ? { branch: !!shown && (shown === holding || onRemote(shown)), commit: !!ask('branch', '--remotes', '--contains', commit) } : undefined;
+  return {
+    commit,
+    ...(shown ? { branch: shown } : {}),
+    ...(holding && local ? { localBranch: local } : {}),
+    ...(remote ? { remote } : {}),
+    ...(pushed ? { pushed } : {}),
+    ...(changed.length ? { changed: changed.slice(0, 20), changedCount: changed.length } : {}),
+  };
+};
+
+/** The origin branch that holds `commit`: the one the checkout tracks when it does, else the first. */
+const remoteBranchWith = (ask: (...args: string[]) => string | undefined, commit: string): string | undefined => {
+  const strip = (ref: string) => ref.replace(/^origin\//, '');
+  const upstream = ask('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}');
+  const holders = (ask('branch', '--remotes', '--contains', commit, '--format=%(refname:short)') ?? '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith('origin/') && l !== 'origin/HEAD' && l !== 'origin');
+  if (upstream && holders.includes(upstream)) return strip(upstream);
+  return holders[0] ? strip(holders[0]) : undefined;
+};
+
+/** A remote as a web address a report can link commits to, without any credentials it carried. */
+export const webOf = (url: string | undefined): string | undefined => {
+  if (!url) return undefined;
+  const ssh = url.match(/^[\w.-]+@([\w.-]+):(.+?)(\.git)?$/);
+  if (ssh) return `https://${ssh[1]}/${ssh[2]}`;
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:' && u.protocol !== 'http:' && u.protocol !== 'ssh:') return undefined;
+    return `https://${u.hostname}${u.pathname.replace(/\.git$/, '')}`;
+  } catch {
+    return undefined;
+  }
 };
 
 export class RunFile {