lynkeus 0.2.0 → 0.4.0

package/src/commands/drive.ts

@@ -1,16 +1,20 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
+import { PNG } from 'pngjs';
+
 import { lynkeusDir } from '../config.js';
 import { describeScreen, describeTrace } from '../device/driver.js';
 import { readJson, writeJson } from '../files.js';
+import { lintContrast } from '../knowledge/contrast.js';
 import { describeFindings, lintScreen } from '../knowledge/lint.js';
 import { describePerf, summarize, visitsFrom } from '../knowledge/perf.js';
 import * as screens from '../knowledge/screens.js';
 import { screenTree } from '../knowledge/tree.js';
 import { define } from '../registry.js';
 import { whyFor } from '../runtime.js';
-import { expectedOf, isRoute, parseTarget, scopedTarget, TARGET_HELP } from '../targets.js';
+import { expectedOf, isRoute, parseTarget, routeOf, scopedTarget, TARGET_HELP } from '../targets.js';
 import { type LintBaseline, newFindings } from './check.js';
 
 const SCOPE_FLAGS = {
@@ -165,7 +169,7 @@ export const driveCommands = [
     mcpOmit: ['nth'],
     group: 'drive',
     summary: 'Until a route or element appears (or leaves), or a number of ms',
-    positionals: [{ name: 'what', help: `Route | ${TARGET_HELP} | 800 (ms)`, required: true }],
+    positionals: [{ name: 'what', help: `Route | route:index | ${TARGET_HELP} | 800 (ms)`, required: true }],
     flags: {
       ...SCOPE_FLAGS,
       gone: { type: 'boolean', help: 'until it leaves the screen' },
@@ -181,7 +185,7 @@ export const driveCommands = [
       }
       return {
         json: await (await ctx.device()).waitFor({
-          ...(isRoute(raw) ? { route: raw } : { target: scopedTarget(raw, ctx.flags) }),
+          ...(isRoute(raw) ? { route: routeOf(raw) } : { target: scopedTarget(raw, ctx.flags) }),
           gone: ctx.flags.gone ? true : undefined,
           scroll: ctx.flags.scroll ? true : undefined,
           timeoutMs: ctx.flags.timeout as number,
@@ -206,7 +210,7 @@ export const driveCommands = [
     name: 'see',
     group: 'drive',
     summary: 'Assert a route or element is on screen now (exit 1 if not)',
-    positionals: [{ name: 'what', help: `Route | ${TARGET_HELP}`, required: true }],
+    positionals: [{ name: 'what', help: `Route | route:index | ${TARGET_HELP}`, required: true }],
     flags: {
       absent: { type: 'boolean', help: 'assert it is not there' },
       within: { type: 'number', help: 'allow it this long to appear', default: 0, value: 'ms' },
@@ -217,7 +221,7 @@ export const driveCommands = [
       const device = await ctx.device();
       try {
         const result = await device.waitFor({
-          ...(isRoute(raw) ? { route: raw } : { target: parseTarget(raw) }),
+          ...(isRoute(raw) ? { route: routeOf(raw) } : { target: parseTarget(raw) }),
           gone: ctx.flags.absent ? true : undefined,
           timeoutMs: Math.max(1, ctx.flags.within as number),
         });
@@ -341,9 +345,10 @@ export const driveCommands = [
   define({
     name: 'lint',
     group: 'drive',
-    summary: 'Unlabeled controls, small targets, untranslated keys, covered or clipped elements',
+    summary: 'Unlabeled controls, small targets, low-contrast text, untranslated keys, covered or clipped elements',
     flags: {
       strict: { type: 'boolean', help: 'exit 1 on any warning' },
+      'no-contrast': { type: 'boolean', help: 'skip the contrast of text against its background (it takes a screenshot)' },
       save: { type: 'string', help: "keep this screen's findings in a baseline file", value: 'file' },
       baseline: { type: 'string', help: 'print only what is new against a baseline file', value: 'file' },
     },
@@ -353,20 +358,38 @@ export const driveCommands = [
       const { lint, lintBaseline } = ctx.config;
       let findings = lintScreen(screen, { i18nKeyPatterns: lint?.i18nKeyPatterns?.map((p) => new RegExp(p, 'i')), minTouchTarget: lint?.minTouchTarget });
       const route = screen.route ?? '?';
+      const notes: string[] = [];
+      if (lint?.contrast !== false && !ctx.flags['no-contrast']) {
+        // Contrast is read off the pixels, so it needs a host that can take a picture of the screen.
+        const file = path.join(os.tmpdir(), `lynkeus-lint-${process.pid}-${Date.now()}.png`);
+        try {
+          await (await ctx.device()).screenshot(file);
+          const picture = PNG.sync.read(fs.readFileSync(file));
+          const contrast = lint?.contrast;
+          findings = [
+            ...findings,
+            ...lintContrast(screen, picture, { normal: contrast?.normal, large: contrast?.large, ignore: contrast?.ignore?.map((p) => new RegExp(p)) }),
+          ];
+        } catch {
+          notes.push('contrast not measured: this host takes no screenshots');
+        } finally {
+          fs.rmSync(file, { force: true });
+        }
+      }
       const withIds = findings.map((finding) => ({ finding, testId: screen.elements[finding.element]?.testId }));
       const lines: string[] = [];
       const save = ctx.flags.save as string | undefined;
       const baselineFile = (ctx.flags.baseline as string | undefined) ?? lintBaseline;
       if (save) {
         const baseline = fs.existsSync(save) ? readJson<LintBaseline>(save) : {};
-        baseline[route] = withIds.map((f) => ({ rule: f.finding.rule, testId: f.testId, message: f.finding.message }));
+        baseline[route] = withIds.map((f) => ({ rule: f.finding.rule, testId: f.testId, subject: f.finding.subject, message: f.finding.message }));
         writeJson(save, baseline);
         lines.push(`saved ${findings.length} finding(s) for ${route} → ${save}`);
       } else if (baselineFile && fs.existsSync(baselineFile)) {
         findings = newFindings(readJson<LintBaseline>(baselineFile), route, withIds).map((f) => f.finding);
         lines.push(findings.length ? `${findings.length} new against ${baselineFile}:` : `nothing new on ${route} against ${baselineFile}`);
       }
-      lines.push(describeFindings(findings, screen.route));
+      lines.push(describeFindings(findings, screen.route), ...notes);
       return { text: lines.join('\n'), json: findings, code: ctx.flags.strict && findings.some((f) => f.severity === 'warn') ? 1 : 0 };
     },
   }),

package/src/commands/headless.ts

@@ -2,11 +2,11 @@ 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 { type LynkeusConfig, lynkeusDir, portFromEnv, readToken } 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';
+import { headlessMissing, init, installAgent, installHeadless, jestPreset, mountAgent, setupChecks } 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';
@@ -31,25 +31,150 @@ hostApp(() => <entry.App />, { ${options.join(', ')} });
 `;
 };
 
+const JEST_CONFIGS = ['jest.config.js', 'jest.config.cjs', 'jest.config.mjs', 'jest.config.ts', 'jest.config.json'];
+
+// React Native and most of what an app adds to it ship untranspiled ES modules, which jest leaves alone unless told.
+const apiFromConfig = (config: LynkeusConfig): Record<string, string> => (config.apiUrl ? { [config.apiEnv ?? 'API_URL']: config.apiUrl } : {});
+
+const TRANSFORM_PACKAGES =
+  '((jest-)?react-native[^/]*|@react-native[^/]*|@react-navigation|react-navigation|expo(nent)?|@expo(nent)?/.*|expo-.*|@unimodules|unimodules|@shopify|@gorhom|@sentry/react-native|lynkeus-[^/]+|yoga-layout|@testing-library|immer|@reduxjs/toolkit|react-redux|redux|reselect|@expo-google-fonts|native-base|standard-navigation)';
+
+/**
+ * The import aliases in tsconfig.json's `paths`, as jest mappings, the longest first: \`@/assets/*\` has to be
+ * tried before \`@/*\`, which jest-expo does not do. The bundler reads them; jest knows nothing of them.
+ */
+const aliasesOf = (root: string): Record<string, string> => {
+  let options: { baseUrl?: string; paths?: Record<string, string[]> } | undefined;
+  try {
+    const text = fs.readFileSync(path.join(root, 'tsconfig.json'), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+    options = (JSON.parse(text) as { compilerOptions?: typeof options }).compilerOptions;
+  } catch {
+    return {};
+  }
+  const base = path.join(root, options?.baseUrl ?? '.');
+  const literal = (text: string) => text.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  return Object.fromEntries(
+    Object.entries(options?.paths ?? {})
+      .filter(([alias, [target]]) => alias.endsWith('/*') && target?.endsWith('/*'))
+      .sort(([a], [b]) => b.length - a.length)
+      .map(([alias, [target]]) => [`^${literal(alias.slice(0, -1))}(.*)$`, `${path.join(base, target!.slice(0, -1))}$1`]),
+  );
+};
+
+/**
+ * What jest is told when the app has not said it itself, so an app with no jest set up runs headless as it is:
+ * the preset its framework needs (jest-expo for Expo, React Native's otherwise), and which packages under node_modules to transpile.
+ */
+const jestDefaults = (root: string): string[] => {
+  const file = JEST_CONFIGS.find((f) => fs.existsSync(path.join(root, f)));
+  let config = file ? fs.readFileSync(path.join(root, file), 'utf8') : '';
+  if (!file) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) as { jest?: unknown };
+      config = manifest.jest ? JSON.stringify(manifest.jest) : '';
+    } catch {}
+  }
+  const flags: string[] = [];
+  if (!config) {
+    // A style sheet imported from native code (Expo's templates import global.css) means nothing to jest, even
+    // behind an alias, so it is mapped first. Jest merges these with the preset's own mappings.
+    const stub = path.join(lynkeusDir(root), 'style-stub.js');
+    fs.mkdirSync(path.dirname(stub), { recursive: true });
+    fs.writeFileSync(stub, 'module.exports = {};\n');
+    flags.push('--preset', jestPreset(root), `--moduleNameMapper=${JSON.stringify({ '\\.(css|less|sass|scss)$': stub, ...aliasesOf(root) })}`);
+  }
+  // Two that must stay as they are, as jest-expo leaves them: babel running itself, or Reanimated's plugin, fails.
+  if (!config.includes('transformIgnorePatterns'))
+    flags.push(
+      `--transformIgnorePatterns=node_modules/(?!${TRANSFORM_PACKAGES}/)`,
+      '--transformIgnorePatterns=/node_modules/react-native-reanimated/plugin/',
+      '--transformIgnorePatterns=/node_modules/@react-native/babel-preset/',
+    );
+  return flags;
+};
+
 export const headlessCommands = [
+  define({
+    name: 'init',
+    group: 'drive',
+    summary: "Set lynkeus up in this app: install the agent, mount it from the app's entry, make the project's token",
+    details:
+      'React Native or Expo (an Expo Router app gets an entry of its own). Safe to run again: it changes only what is missing. The agent has native code, so the app is built again afterwards (`npx react-native run-ios`, `npx expo run:ios`) and Metro restarted with `--reset-cache`; `lynkeus status` says what is left.',
+    flags: { 'no-install': { type: 'boolean', help: 'do not add lynkeus-agent to the app; mount it only' } },
+    needs: 'nothing',
+    mcp: 'core',
+    run: async (ctx) => {
+      const lines = [...(ctx.flags['no-install'] ? [] : [installAgent(ctx.root)]), ...mountAgent(ctx.root)];
+      lines.push('next: build the app again and open it, then `lynkeus status` (over MCP: the status tool) to see that it attaches');
+      return { text: lines.join('\n'), json: lines };
+    },
+  }),
+  define({
+    name: 'status',
+    group: 'drive',
+    summary: 'What this project has of lynkeus and what is missing: the agent, the token, a running app, cases, the reports key',
+    details: 'The first thing to call in a project you do not know: each line that fails says what fixes it. `--offline` skips waiting for the app.',
+    flags: { offline: { type: 'boolean', help: 'check the files only; do not wait for a running app' } },
+    needs: 'nothing',
+    mcp: 'core',
+    run: async (ctx) => {
+      const checks = setupChecks(ctx.root);
+      const ready = checks.every((c) => c.ok);
+      if (ready && !ctx.flags.offline) {
+        try {
+          const device = await ctx.device();
+          checks.push({ what: `an app is attached (${device.info.name})`, ok: true });
+        } catch {
+          checks.push({
+            what: 'an app is attached',
+            ok: false,
+            fix: 'open a development build made after `lynkeus init`, with Metro restarted (`--reset-cache`); or `lynkeus headless start` for no simulator',
+          });
+        }
+      }
+      const unloadable = headlessMissing(ctx.root);
+      checks.push({
+        what: unloadable.length ? 'the app can run headless, in Node with no simulator' : 'the app can run headless (jest, Testing Library, lynkeus-headless)',
+        ok: !unloadable.length && fs.existsSync(path.join(ctx.root, entryOf(ctx))),
+        fix: '`lynkeus headless init` installs what it needs and writes its entry; optional',
+      });
+      const dir = path.resolve(ctx.config.cases?.base ?? ctx.root, ctx.config.cases?.dir ?? 'cases');
+      const cases = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !/^(README|FORMAT|CATALOG)\.md$/i.test(f)).length : 0;
+      checks.push({
+        what: cases ? `${cases} case${cases === 1 ? '' : 's'} in ${path.relative(ctx.root, dir) || '.'}` : 'cases to run',
+        ok: cases > 0,
+        fix: '`lynkeus case init` writes an example and the format',
+      });
+      checks.push({
+        what: 'runs can be pushed to the reports service',
+        ok: !!process.env.LYNKEUS_REPORTS_KEY,
+        fix: 'set LYNKEUS_REPORTS_KEY to an API key of your organization (lynkeus.io, API keys); optional',
+      });
+      const text = checks.map((c) => `${c.ok ? '✓' : '✗'} ${c.what}${c.ok || !c.fix ? '' : ` — ${c.fix}`}`).join('\n');
+      return { text, json: checks };
+    },
+  }),
   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.',
+      "Needs the project's token: the one `lynkeus init` wrote to .lynkeus/token, or LYNKEUS_TOKEN in the environment. The app's API base comes from the environment variable `apiEnv` names, or else from `apiUrl` in lynkeus.config.json. 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;
+      const token = readToken(ctx.root);
       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.',
+          text: 'lynkeus headless needs a token (`lynkeus init` makes one in .lynkeus/token, or set LYNKEUS_TOKEN): a hosted app talks to a real backend, and without one any local process could drive it.',
           code: 1,
         };
+      const missing = headlessMissing(ctx.root);
+      if (missing.length)
+        return { text: `lynkeus headless runs the app under jest and needs ${missing.join(', ')}; \`lynkeus headless init\` installs them.`, 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 };
@@ -65,10 +190,10 @@ export const headlessCommands = [
       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], {
+      const child = spawn('npx', ['jest', testFile, '--runInBand', '--watchAll=false', ...jestDefaults(ctx.root), ...ctx.passthrough], {
         cwd: ctx.root,
         stdio: ['inherit', 'inherit', 'pipe'],
-        env: { ...process.env, CI: '1', NODE_OPTIONS: nodeOptions },
+        env: { ...apiFromConfig(ctx.config), ...process.env, LYNKEUS_TOKEN: token, CI: '1', NODE_OPTIONS: nodeOptions },
       });
       let tail = '';
       child.stderr?.on('data', (chunk: Buffer) => {
@@ -93,8 +218,13 @@ export const headlessCommands = [
       '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' },
+      'no-install': { type: 'boolean', help: 'do not add jest, Testing Library and lynkeus-headless to the project' },
     },
     needs: 'nothing',
+    mcp: 'core',
+    mcpOmit: ['entry', 'auto', 'force'],
+    mcpDetails:
+      'Prepares the app to run in Node, no simulator: installs jest, Testing Library and lynkeus-headless, writes the entry. Then `case_run` with `host`.',
     run: async (ctx) => {
       const lines = init(ctx.root, {
         entry: entryOf(ctx),
@@ -104,6 +234,7 @@ export const headlessCommands = [
         force: !!ctx.flags.force,
         locale: { ...ctx.config.locale, language: ctx.config.language },
       });
+      if (!ctx.flags['no-install']) lines.unshift(installHeadless(ctx.root));
       return { text: lines.join('\n'), json: lines };
     },
   }),
@@ -117,11 +248,15 @@ export const headlessCommands = [
       explain: { type: 'string', help: 'turn a jest error into its usual cause and fix', value: 'text' },
     },
     needs: 'nothing',
+    mcp: 'core',
+    mcpOmit: ['entry'],
+    mcpDetails:
+      'Which native modules the app uses that nothing mocks yet, so the headless host would fail on them; `fix` writes stubs for them into the entry. `explain` turns the first line of a jest error into its cause.',
     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.',
+          text: found.length ? describeExplanations(found).trim() : 'nothing in the catalog matches; paste the first line of the error, not the stack.',
           json: found,
         };
       }