lynkeus 0.2.0 → 0.4.0

package/lib/commands/drive.js

@@ -1,15 +1,18 @@
 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 { newFindings } from './check.js';
 const SCOPE_FLAGS = {
     in: { type: 'string', help: 'the match nearest this target', value: 'target' },
@@ -165,7 +168,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 +184,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,
@@ -206,7 +209,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 +220,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),
                 });
@@ -341,9 +344,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,13 +357,33 @@ 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 = [];
+            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 = [];
             const save = ctx.flags.save;
             const baselineFile = ctx.flags.baseline ?? lintBaseline;
             if (save) {
                 const baseline = fs.existsSync(save) ? readJson(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}`);
             }
@@ -367,7 +391,7 @@ export const driveCommands = [
                 findings = newFindings(readJson(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/lib/commands/headless.js

@@ -1,11 +1,11 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { lynkeusDir, portFromEnv } from '../config.js';
+import { lynkeusDir, portFromEnv, readToken } from '../config.js';
 import { describeExplanations, explainError } from '../knowledge/errors.js';
 import { 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', help: 'the headless entry (or `entry` in lynkeus.config.json)', value: 'file' } };
 const entryOf = (ctx) => ctx.flags.entry ?? 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. */
@@ -27,24 +27,139 @@ import * as entry from '${entryImport}';
 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) => (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) => {
+    let options;
+    try {
+        const text = fs.readFileSync(path.join(root, 'tsconfig.json'), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+        options = JSON.parse(text).compilerOptions;
+    }
+    catch {
+        return {};
+    }
+    const base = path.join(root, options?.baseUrl ?? '.');
+    const literal = (text) => 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) => {
+    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'));
+            config = manifest.jest ? JSON.stringify(manifest.jest) : '';
+        }
+        catch { }
+    }
+    const flags = [];
+    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.',
+        details: "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 };
@@ -60,10 +175,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) => {
@@ -89,8 +204,12 @@ 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),
@@ -100,6 +219,8 @@ 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 };
         },
     }),
@@ -113,11 +234,14 @@ 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);
                 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,
                 };
             }

package/lib/commands/init.d.ts

@@ -10,4 +10,33 @@ export type InitOptions = {
         language?: string;
     };
 };
+/**
+ * Mounts the agent from the app's entry, before anything registers the root component. An Expo Router app
+ * has no entry of its own (`"main": "expo-router/entry"`), so it gets one that mounts the agent and then
+ * loads the router.
+ */
+export declare const mountAgent: (root: string) => string[];
 export declare const init: (root: string, opts: InitOptions) => string[];
+/**
+ * What a failed install said, short enough for one line. npm ends its errors with where its logs are, so
+ * the last lines alone told nothing; the reason (a peer range that does not match, say) comes before them.
+ */
+export declare const installFailure: (ran: {
+    stderr?: string | null;
+    error?: Error;
+}) => string;
+/** Adds lynkeus-agent to the app when it is not a dependency yet. It has native code, so the app is built again after. */
+export declare const installAgent: (root: string) => string;
+export type SetupCheck = {
+    what: string;
+    ok: boolean;
+    fix?: string;
+};
+/** What a project has of lynkeus and what it still lacks, each with the one thing that fixes it. Reads files only. */
+export declare const setupChecks: (root: string) => SetupCheck[];
+/** The packages the headless host needs that this project cannot load yet. */
+export declare const headlessMissing: (root: string) => string[];
+/** The preset \`headless start\` gives jest when the app's own configuration names none. */
+export declare const jestPreset: (root: string) => string;
+/** Adds what the headless host needs as development dependencies; a line saying what happened. */
+export declare const installHeadless: (root: string) => string;