lynkeus 0.2.0

package/src/commands/flake.ts

@@ -0,0 +1,48 @@
+import type { FlowReport } from '../flow/types.js';
+
+export type FlakeSummary = {
+  runs: number;
+  passed: number;
+  msMedian: number;
+  failures: { step: number; what: string; error: string; times: number }[];
+};
+
+const stepLabel = (r: FlowReport, i: number): string => {
+  const s = r.steps[i]?.step;
+  if (!s) return '?';
+  const [key] = Object.keys(s);
+  const v = (s as Record<string, unknown>)[key!];
+  return `${key}${typeof v === 'object' && v ? ` ${JSON.stringify(v).slice(0, 60)}` : ''}`;
+};
+
+export const summarizeRuns = (reports: FlowReport[]): FlakeSummary => {
+  const failures = new Map<string, FlakeSummary['failures'][number]>();
+  for (const r of reports) {
+    if (r.ok) continue;
+    const i = r.steps.findIndex((s) => !s.ok);
+    const error = (r.steps[i]?.error ?? 'unknown')
+      .replace(/\(on [^)]*\)/, '')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, 120);
+    const key = `${i}|${error}`;
+    const f = failures.get(key) ?? { step: i + 1, what: stepLabel(r, i), error, times: 0 };
+    f.times += 1;
+    failures.set(key, f);
+  }
+  const ms = reports.map((r) => r.totalMs).sort((a, b) => a - b);
+  return {
+    runs: reports.length,
+    passed: reports.filter((r) => r.ok).length,
+    msMedian: ms[Math.floor(ms.length / 2)] ?? 0,
+    failures: [...failures.values()].sort((a, b) => b.times - a.times),
+  };
+};
+
+export const describeFlake = (name: string, s: FlakeSummary): string => {
+  const lines = [`${name}: passed ${s.passed}/${s.runs} (median ${Math.round(s.msMedian / 1000)}s)`];
+  if (s.passed === s.runs) lines.push('  no failure in this sample; if it fails elsewhere, the difference is the environment (load, data, a parallel runner)');
+  for (const f of s.failures) lines.push(`  ${f.times}× at step ${f.step} (${f.what}): ${f.error}`);
+  if (s.failures.length > 1) lines.push('  more than one failure shape: not one flake but several, or a screen that fails in different ways when slow');
+  return lines.join('\n');
+};

package/src/commands/headless.ts

@@ -0,0 +1,131 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { type LynkeusConfig, lynkeusDir, portFromEnv } from '../config.js';
+import { describeExplanations, explainError } from '../knowledge/errors.js';
+import { type Ctx, define } from '../registry.js';
+import { doctor } from './doctor.js';
+import { init } from './init.js';
+
+const ENTRY_FLAG = { entry: { type: 'string' as const, help: 'the headless entry (or `entry` in lynkeus.config.json)', value: 'file' } };
+const entryOf = (ctx: Ctx) => (ctx.flags.entry as string | undefined) ?? ctx.config.entry ?? 'qa/headless.tsx';
+
+/** The jest test that hosts the app. The port is written in, not read from the environment there: babel would inline the first run's value into jest's transform cache. */
+const hostTest = (entryImport: string, port: number | undefined, config: LynkeusConfig, appName: string) => {
+  const live = config.live?.join('|');
+  const options = [
+    'navigation: entry.navigation',
+    'token: process.env.LYNKEUS_TOKEN',
+    `port: ${port ?? 'undefined'}`,
+    'host: process.env.LYNKEUS_HOST',
+    `live: ${live ? `/${live}/` : 'undefined'}`,
+    `strictMode: ${config.strictMode === true}`,
+    `app: { name: ${JSON.stringify(appName)}, runtime: 'headless' }`,
+  ];
+  return `// Written by \`lynkeus headless start\`; runs the app under jest as a host for the agent.
+import { hostApp } from 'lynkeus-headless';
+import * as entry from '${entryImport}';
+
+hostApp(() => <entry.App />, { ${options.join(', ')} });
+`;
+};
+
+export const headlessCommands = [
+  define({
+    name: 'headless start',
+    group: 'headless',
+    summary: 'Host the app in Node (jest + RNTL) and wait for a driver; same protocol, no simulator',
+    details:
+      'Needs LYNKEUS_TOKEN in the environment (the value the app reads for its token). LYNKEUS_PORT moves the host and its driver together; LYNKEUS_HOST says where the driver is listening, for a host that is not in the same place as its driver (a container dialling out, say). Arguments after `--` go to jest. When the host crashes, the last lines say what the error usually means.',
+    flags: ENTRY_FLAG,
+    aliases: ['headless'],
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const token = process.env.LYNKEUS_TOKEN;
+      if (!token)
+        return {
+          text: 'lynkeus headless needs LYNKEUS_TOKEN in the environment (the same value the app reads for its token): a hosted app talks to a real backend, and without one any local process could drive it.',
+          code: 1,
+        };
+      const entry = entryOf(ctx);
+      if (!fs.existsSync(path.join(ctx.root, entry)))
+        return { text: `No ${entry} in ${ctx.root}. \`lynkeus headless init\` writes one; it must export \`App\` and, optionally, \`navigation\`.`, code: 1 };
+      const testDir = path.join(lynkeusDir(ctx.root), '__tests__');
+      const port = portFromEnv(ctx.config);
+      // One file per port: two hosts of the same app must not read each other's.
+      const testFile = path.join(testDir, port ? `headless-${port}.test.tsx` : 'headless.test.tsx');
+      const rel = path
+        .relative(testDir, path.join(ctx.root, entry))
+        .replace(/\\/g, '/')
+        .replace(/\.tsx?$/, '');
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(testFile, hostTest(rel.startsWith('.') ? rel : `./${rel}`, port, ctx.config, path.basename(ctx.root)));
+      // Node resolves `localhost` to ::1 first; local backends usually listen on IPv4 only.
+      const nodeOptions = [process.env.NODE_OPTIONS, '--dns-result-order=ipv4first'].filter(Boolean).join(' ');
+      const child = spawn('npx', ['jest', testFile, '--runInBand', '--watchAll=false', ...ctx.passthrough], {
+        cwd: ctx.root,
+        stdio: ['inherit', 'inherit', 'pipe'],
+        env: { ...process.env, CI: '1', NODE_OPTIONS: nodeOptions },
+      });
+      let tail = '';
+      child.stderr?.on('data', (chunk: Buffer) => {
+        process.stderr.write(chunk);
+        tail = (tail + chunk.toString()).slice(-20000);
+      });
+      const code = await new Promise<number>((resolve) => child.on('exit', (c) => resolve(c ?? 0)));
+      if (code) {
+        const found = explainError(tail);
+        if (found.length) ctx.err(describeExplanations(found));
+      }
+      return { code };
+    },
+  }),
+  define({
+    name: 'headless init',
+    group: 'headless',
+    summary: 'Write the headless entry: default mocks, a local-backend guard, your App',
+    flags: {
+      ...ENTRY_FLAG,
+      component: { type: 'string', help: 'the App component file (found by itself when standard)', value: 'App.tsx' },
+      'api-env': { type: 'string', help: 'the env var the app reads its API base from', value: 'NAME' },
+      auto: { type: 'boolean', help: 'also mount the agent from index.js with auto()' },
+      force: { type: 'boolean', help: 'overwrite an existing entry' },
+    },
+    needs: 'nothing',
+    run: async (ctx) => {
+      const lines = init(ctx.root, {
+        entry: entryOf(ctx),
+        app: ctx.flags.component as string | undefined,
+        apiEnv: (ctx.flags['api-env'] as string | undefined) ?? ctx.config.apiEnv ?? 'API_URL',
+        auto: !!ctx.flags.auto,
+        force: !!ctx.flags.force,
+        locale: { ...ctx.config.locale, language: ctx.config.language },
+      });
+      return { text: lines.join('\n'), json: lines };
+    },
+  }),
+  define({
+    name: 'headless doctor',
+    group: 'headless',
+    summary: 'What lynkeus mocks, and which native modules still need one',
+    flags: {
+      ...ENTRY_FLAG,
+      fix: { type: 'boolean', help: 'write stubs for the uncovered modules into the entry' },
+      explain: { type: 'string', help: 'turn a jest error into its usual cause and fix', value: 'text' },
+    },
+    needs: 'nothing',
+    run: async (ctx) => {
+      if (ctx.flags.explain) {
+        const found = explainError(ctx.flags.explain as string);
+        return {
+          text: found.length ? describeExplanations(found).trim() : 'nothing in the catalogue matches; paste the first line of the error, not the stack.',
+          json: found,
+        };
+      }
+      return doctor(ctx.root, entryOf(ctx), { fix: !!ctx.flags.fix }).join('\n');
+    },
+  }),
+];

package/src/commands/init.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { packageName } from '../config.js';
+
+const APP_CANDIDATES = ['App.tsx', 'App.jsx', 'App.js', 'app/App.tsx', 'src/App.tsx', 'src/App.jsx', 'src/App.js'];
+const INDEX_CANDIDATES = ['index.js', 'index.tsx', 'index.ts'];
+
+export type InitOptions = {
+  entry: string;
+  app?: string;
+  apiEnv: string;
+  auto: boolean;
+  force: boolean;
+  locale?: { languageTag?: string; country?: string; language?: string };
+};
+
+const findFirst = (root: string, candidates: string[]): string | undefined => candidates.find((c) => fs.existsSync(path.join(root, c)));
+
+const relImport = (fromFile: string, toFile: string): string => {
+  const rel = path
+    .relative(path.dirname(fromFile), toFile)
+    .replace(/\\/g, '/')
+    .replace(/\.(tsx|ts|jsx|js)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+};
+
+const entryTemplate = (appImport: string, apiEnv: string, appName: string, locale?: InitOptions['locale']): string => {
+  const LOCALE =
+    locale?.languageTag || locale?.country || locale?.language
+      ? `\n  // The locale this app is built for, from lynkeus.config.json.\n  locale: ${JSON.stringify({ country: locale.country, languageTag: locale.languageTag, languageCode: locale.language })},`
+      : "\n  // locale: { country: 'DE', languageTag: 'de-DE', languageCode: 'de' },";
+  return `// Entry for \`lynkeus headless start\`: the whole app, hosted under jest so an agent can
+// drive it in Node against a real local backend. Nothing here runs in the app
+// itself. lynkeus mocks the common native modules (storage, keychain,
+// device-info, safe-area, localize, ...); only ${appName}-specific pieces go here.
+import { installDefaultMocks } from 'lynkeus-headless/mocks'
+
+// Real network plus a hosted app is exactly what would let a driver act
+// against production if ${apiEnv} ever pointed there. Refuse anything not local.
+const apiUrl = process.env.${apiEnv} ?? ''
+if (!/^https?:\\/\\/(localhost|127\\.0\\.0\\.1|10\\.0\\.2\\.2)(:\\d+)?(\\/|$)/.test(apiUrl)) {
+  throw new Error(\`lynkeus headless only drives a local backend; ${apiEnv} is "\${apiUrl}"\`)
+}
+
+installDefaultMocks({
+  network: 'real',${LOCALE}
+})
+
+// App-specific mocks go here, before the app is required. \`lynkeus headless doctor\`
+// lists the native modules the app references that nothing covers yet:
+//   jest.mock('some-native-package', () => ({ method: () => undefined }))
+
+// Whatever the app's index runs before rendering (polyfills, i18n, services):
+// require it here too, then the App.
+const { default: App } = require('${appImport}')
+
+export { App }
+`;
+};
+
+export const init = (root: string, opts: InitOptions): string[] => {
+  const notes: string[] = [];
+  const entryPath = path.join(root, opts.entry);
+  const app = opts.app ?? findFirst(root, APP_CANDIDATES);
+  if (!app) throw new Error(`no App component found (${APP_CANDIDATES.join(', ')}); pass --component <path>`);
+  if (fs.existsSync(entryPath) && !opts.force) {
+    notes.push(`${opts.entry} exists; left as is (--force overwrites)`);
+  } else {
+    fs.mkdirSync(path.dirname(entryPath), { recursive: true });
+    fs.writeFileSync(entryPath, entryTemplate(relImport(entryPath, path.join(root, app)), opts.apiEnv, packageName(root), opts.locale));
+    notes.push(`wrote ${opts.entry} (app: ${app})`);
+  }
+  if (opts.auto) {
+    const index = findFirst(root, INDEX_CANDIDATES);
+    if (!index) {
+      notes.push("no index.js to add the auto mount to; add it yourself: import { auto } from 'lynkeus-agent/auto'; auto({ token: ... })");
+    } else {
+      const indexPath = path.join(root, index);
+      const text = fs.readFileSync(indexPath, 'utf8');
+      if (text.includes('lynkeus-agent/auto')) {
+        notes.push(`${index} already mounts the agent`);
+      } else {
+        const line =
+          "import { auto } from 'lynkeus-agent/auto'\n// Dev-only QA agent; a release build never evaluates the client.\nauto({ token: process.env.LYNKEUS_TOKEN })\n";
+        // After the last import, so the app's own polyfills still run first.
+        const imports = [...text.matchAll(/^import .*$/gm)];
+        const at = imports.length ? imports[imports.length - 1]!.index! + imports[imports.length - 1]![0].length + 1 : 0;
+        fs.writeFileSync(indexPath, text.slice(0, at) + line + text.slice(at));
+        notes.push(`added auto() to ${index}`);
+      }
+    }
+  }
+  notes.push("jest: make sure transformIgnorePatterns lets 'lynkeus-[^/]+' through, next to react-native (lynkeus headless doctor checks it)");
+  notes.push(`next: LYNKEUS_TOKEN=<token> ${opts.apiEnv}=http://127.0.0.1:3000/ lynkeus headless start`);
+  notes.push('      then, in another shell: lynkeus screen  (or lynkeus headless doctor to see what still needs a mock)');
+  return notes;
+};

package/src/commands/map.ts

@@ -0,0 +1,298 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { edgesFile, frontierFile, graphFile, lynkeusDir } from '../config.js';
+import { readJson, writeJson } from '../files.js';
+import * as edges from '../knowledge/edges.js';
+import * as frontier from '../knowledge/frontier.js';
+import { describePlan, plan } from '../knowledge/plan.js';
+import { type Affected, pathsTo, screensAffectedBy, vocabularyOf } from '../knowledge/query.js';
+import * as screens from '../knowledge/screens.js';
+import type { ScreenGraph } from '../knowledge/types.js';
+import { define } from '../registry.js';
+import { describeGraphDiff, diffGraphs } from './check.js';
+
+const baseGraphFile = (root: string) => path.join(lynkeusDir(root), 'graph.base.json');
+
+/** Nearest first, under a heading per distance; `chain` names every file in between instead of the last. */
+const describeAffected = (affected: Affected[], chain: boolean): string[] => {
+  const lines: string[] = [];
+  let last = -1;
+  for (const a of affected) {
+    if (a.distance !== last) {
+      last = a.distance;
+      lines.push(a.distance === 0 ? '  changed screens' : a.distance === 1 ? '  screens importing a changed file' : `  ${a.distance} imports away`);
+    }
+    const how = a.distance === 0 ? '' : a.through.length ? `via ${chain ? a.through.join(' > ') : a.through.at(-1)}` : `imports ${a.via}`;
+    lines.push(`    ${a.route.padEnd(32)} ${how}`.trimEnd());
+  }
+  return lines;
+};
+
+export const mapCommands = [
+  define({
+    name: 'map build',
+    group: 'map',
+    summary: 'Read the source once: routes, testIDs, navigations → .lynkeus/graph.json',
+    flags: { 'as-base': { type: 'boolean', help: 'also keep it as graph.base.json, for `map check` to diff against' } },
+    needs: 'nothing',
+    run: async (ctx) => {
+      if (!fs.existsSync(path.join(ctx.root, 'tsconfig.json')))
+        return { text: `No tsconfig.json under ${ctx.root}: run this inside a React Native app (or pass --root).`, code: 1 };
+      const started = Date.now();
+      // The extractor brings a compiler with it; only this command pays for loading it.
+      const { extractScreenGraph } = await import('../knowledge/extract.js');
+      const graph = extractScreenGraph({ root: ctx.root });
+      writeJson(graphFile(ctx.root), graph);
+      if (ctx.flags['as-base']) writeJson(baseGraphFile(ctx.root), graph);
+      const routes = new Set(Object.keys(graph.screens));
+      const dropped = edges.prune(edgesFile(ctx.root), routes) + frontier.prune(frontierFile(ctx.root), routes);
+      const facts = Object.values(graph.files);
+      const summary = {
+        screens: routes.size,
+        files: facts.length,
+        selectors: facts.reduce((n, f) => n + f.selectors.length, 0),
+        edges: facts.reduce((n, f) => n + f.navigates.length, 0),
+        seconds: (Date.now() - started) / 1000,
+        wrote: graphFile(ctx.root),
+      };
+      const text = [
+        `  screens    ${summary.screens}`,
+        `  files      ${summary.files}`,
+        `  selectors  ${summary.selectors}`,
+        `  edges      ${summary.edges}`,
+        `  took       ${summary.seconds.toFixed(1)}s`,
+        `  wrote      ${summary.wrote}`,
+        ...(dropped ? [`  collected  ${dropped} rows for screens that are gone`] : []),
+      ];
+      return { text: text.join('\n'), json: { ...summary, dropped } };
+    },
+  }),
+  define({
+    name: 'map screens',
+    group: 'map',
+    summary: 'Every route in the graph, and every route a run has actually opened',
+    needs: 'graph',
+    run: async (ctx) => {
+      const fromSource = new Set(Object.keys(ctx.graph().screens));
+      const seen = screens.observed(lynkeusDir(ctx.root));
+      const rows = [...new Set([...fromSource, ...seen.keys()])]
+        .sort()
+        .map((route) => ({ route, source: fromSource.has(route), seen: seen.get(route)?.seen ?? 0 }));
+      const text = rows.map((r) => `${r.route}${r.source ? '' : '  (observed only)'}${r.seen ? `  seen ${r.seen}x` : ''}`).join('\n');
+      return { text, json: rows };
+    },
+  }),
+  define({
+    name: 'map show',
+    mcp: 'core',
+    group: 'map',
+    summary: 'testIDs and navigations a screen is likely to have, from source',
+    positionals: [{ name: 'route', help: 'e.g. Settings.Main', required: true }],
+    needs: 'graph',
+    run: async (ctx) => {
+      const route = ctx.args[0]!;
+      const v = vocabularyOf(ctx.graph(), route);
+      const seen = screens.observed(lynkeusDir(ctx.root)).get(route);
+      if (!v && !seen) return { text: `Unknown route ${route}`, code: 1 };
+      // Observed first: a testID read off the running app is a fact; one from source is a guess about which screen renders it.
+      const observedIds = seen?.testIds ?? [];
+      const fromSource = new Set((v?.selectors ?? []).map((s) => s.id));
+      const sourceOnly = (v?.selectors ?? []).filter((s) => !observedIds.includes(s.id));
+      const navigatesTo = v?.navigatesTo ?? [];
+      const lines = [
+        `${route}  (${v?.file ?? 'not in the source graph'})`,
+        seen ? `seen ${seen.seen}x, last ${seen.date}${seen.path.length ? `  [${seen.path.join(' > ')}]` : ''}` : 'never opened by a run',
+        '',
+        'selectors:',
+        ...observedIds.map((id) => `  #${id}${fromSource.has(id) ? '' : '  (observed)'}`),
+        ...sourceOnly.map((s) => `  #${s.id}  (source only, not seen)`),
+        ...(observedIds.length + sourceOnly.length === 0 ? ['  (none)'] : []),
+        '',
+        'navigates to:',
+        ...navigatesTo.map((e) => `  ${e.to}  ${e.via.kind === 'testId' ? `via #${e.via.testId}` : `(${e.via.kind})`}`),
+        ...(navigatesTo.length === 0 ? ['  (none)'] : []),
+      ];
+      return {
+        text: lines.join('\n'),
+        json: {
+          ...(v ?? { route, file: null, selectors: [], navigatesTo: [], filesConsidered: 0 }),
+          observed: seen ?? null,
+          observedOnly: observedIds.filter((id) => !fromSource.has(id)),
+        },
+      };
+    },
+  }),
+  define({
+    name: 'map paths',
+    group: 'map',
+    summary: 'What leads to a route: observed edges first, then static',
+    positionals: [{ name: 'route', help: 'e.g. Checkout.Confirm', required: true }],
+    needs: 'graph',
+    run: async (ctx) => {
+      const list = pathsTo(ctx.graph(), ctx.args[0]!, edges.load(edgesFile(ctx.root)));
+      const text = list.map((a) => `  ${a.source.padEnd(8)} ${a.via.padEnd(40)} from ${a.from}${a.seen ? `  (seen ${a.seen}×)` : ''}`).join('\n');
+      return { text: text || '(nothing known)', json: list };
+    },
+  }),
+  define({
+    name: 'map plan',
+    mcp: 'core',
+    group: 'map',
+    summary: 'Directions from one route to another: which buttons to press, screen by screen',
+    flags: {
+      from: { type: 'string', help: 'starting route', value: 'Route' },
+      to: { type: 'string', help: 'destination route', value: 'Route' },
+    },
+    aliases: ['plan'],
+    needs: 'graph',
+    run: async (ctx) => {
+      const from = ctx.flags.from as string | undefined;
+      const to = ctx.flags.to as string | undefined;
+      if (!from || !to) throw new Error('map plan needs --from <Route> --to <Route>');
+      const steps = plan(ctx.graph(), from, to, edges.load(edgesFile(ctx.root)));
+      if (!steps) return { text: `No known path from ${from} to ${to}. Crawl to learn more edges.`, code: 1 };
+      return { text: steps.length ? describePlan(steps) : 'Already there.', json: steps };
+    },
+  }),
+  define({
+    name: 'map impact',
+    group: 'map',
+    summary: 'Screens a change can reach, nearest first',
+    positionals: [{ name: 'file', help: 'changed source files', required: true, rest: true }],
+    flags: {
+      depth: { type: 'number', help: 'how many imports away to look', default: 4, value: 'n' },
+      direct: { type: 'boolean', help: 'only the screen and its importers' },
+    },
+    needs: 'graph',
+    run: async (ctx) => {
+      const depth = ctx.flags.depth as number;
+      const all = screensAffectedBy(ctx.graph(), ctx.args, depth);
+      const affected = ctx.flags.direct ? all.filter((a) => a.distance <= 1) : all;
+      if (affected.length === 0) {
+        const text =
+          all.length === 0
+            ? `  (no screen imports these files, directly or through ${depth} levels)`
+            : `  (nothing within one import; ${all.length} screens further away, a shared module. Drop --direct to list them.)`;
+        return { text, json: affected };
+      }
+      const lines = describeAffected(affected, false);
+      const far = affected.filter((a) => a.distance > 1).length;
+      if (far > 20) lines.push(`  (${far} screens more than one import away, a shared module; --direct narrows to what to test first)`);
+      return { text: lines.join('\n'), json: affected };
+    },
+  }),
+  define({
+    name: 'map ci',
+    group: 'map',
+    summary: 'Write a GitHub workflow that comments on each pull request which screens its diff reaches',
+    details:
+      'Writes `.github/workflows/lynkeus-map-check.yml` in the app. On every pull request it builds the map from the sources (no app, no device, well under a second of analysis), runs `map check` against the base branch and keeps one comment on the PR up to date. `--force` overwrites an existing file.',
+    flags: {
+      force: { type: 'boolean', help: 'overwrite the workflow if it exists' },
+      depth: { type: 'number', help: 'how many imports away the check looks', default: 2, value: 'n' },
+    },
+    needs: 'nothing',
+    run: async (ctx) => {
+      const file = path.join(ctx.root, '.github', 'workflows', 'lynkeus-map-check.yml');
+      if (fs.existsSync(file) && !ctx.flags.force) return { text: `${path.relative(ctx.root, file)} exists; --force overwrites it`, code: 1 };
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, mapCheckWorkflow(ctx.flags.depth as number));
+      return { text: `wrote ${path.relative(ctx.root, file)}`, json: { file } };
+    },
+  }),
+  define({
+    name: 'map check',
+    group: 'map',
+    summary: "A branch from the app's side: screens its diff reaches, routes/navigations/testIDs that changed",
+    flags: {
+      base: { type: 'string', help: 'git ref to diff against', default: 'main', value: 'ref' },
+      'graph-base': { type: 'string', help: 'graph to diff against (default .lynkeus/graph.base.json)', value: 'file' },
+      depth: { type: 'number', help: 'how many imports away to look', default: 4, value: 'n' },
+    },
+    needs: 'graph',
+    run: async (ctx) => {
+      const graph = ctx.graph();
+      const base = ctx.flags.base as string;
+      const git = (...args: string[]) => execFileSync('git', args, { cwd: ctx.root, encoding: 'utf8' });
+      let changed: string[] = [];
+      try {
+        const names = `${git('diff', '--name-only', `${base}...HEAD`)}\n${git('diff', '--name-only', 'HEAD')}`;
+        changed = [
+          ...new Set(
+            names
+              .split('\n')
+              .map((l) => l.trim())
+              .filter((l) => /\.[cm]?[jt]sx?$/.test(l)),
+          ),
+        ];
+      } catch (error) {
+        ctx.err(`could not diff against ${base}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      const affected = screensAffectedBy(graph, changed, ctx.flags.depth as number);
+      const lines = [`changed against ${base}: ${changed.length} source file(s)`, ...describeAffected(affected, true)];
+      if (!affected.length && changed.length) lines.push('  (no screen imports these files within the depth)');
+      const baseFile = (ctx.flags['graph-base'] as string | undefined) ?? baseGraphFile(ctx.root);
+      const graphDiff = fs.existsSync(baseFile) ? diffGraphs(readJson<ScreenGraph>(baseFile), graph) : undefined;
+      if (graphDiff) lines.push(`graph against ${path.relative(ctx.root, baseFile)}:`, describeGraphDiff(graphDiff));
+      else lines.push(`graph: no baseline (run \`lynkeus map build --as-base\` on ${base} to diff routes, navigations and testIDs)`);
+      if (affected.length) {
+        const first = affected.slice(0, 5).map((a) => a.route);
+        lines.push(
+          `next: run the cases that cover ${first.join(', ')}${affected.length > 5 ? ', …' : ''}; \`lynkeus lint --baseline <file>\` on those screens prints what is new`,
+        );
+      }
+      return { text: lines.join('\n'), json: { base, changed, affected, graphDiff } };
+    },
+  }),
+  define({
+    name: 'map changes',
+    group: 'map',
+    summary: 'testIDs that appeared, disappeared or moved on a recorded screen since it was last read',
+    flags: { last: { type: 'number', help: 'how many changes', default: 30, value: 'n' } },
+    needs: 'nothing',
+    run: async (ctx) => {
+      const list = screens.changes(lynkeusDir(ctx.root), ctx.flags.last as number);
+      if (list.length === 0) return { text: '(no recorded screen changes; record with `lynkeus screen --record` or LYNKEUS_RECORD_SCREENS=1)', json: [] };
+      return { text: list.map(screens.describeChange).join('\n'), json: list };
+    },
+  }),
+];
+
+export const mapCheckWorkflow = (depth: number): string => `name: lynkeus map check
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  map-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+      - name: Build the map and check the diff
+        run: |
+          npx --yes lynkeus map build > /dev/null
+          npx --yes lynkeus map check --base origin/\${{ github.base_ref }} --depth ${depth} > map-check.txt
+      - name: Comment on the pull request
+        env:
+          GH_TOKEN: \${{ github.token }}
+        run: |
+          {
+            echo '<!-- lynkeus map check -->'
+            echo '**Screens this diff reaches** (lynkeus map check)'
+            echo
+            echo '\`\`\`'
+            cat map-check.txt
+            echo '\`\`\`'
+          } > body.md
+          gh pr comment \${{ github.event.pull_request.number }} --edit-last --body-file body.md || gh pr comment \${{ github.event.pull_request.number }} --body-file body.md
+`;