lynkeus 0.3.0 → 0.5.0

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 {