lynkeus 0.3.0 → 0.5.0

package/lib/commands/coverage.js

@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { coverageOf, impactOf, readSeen } from '../cases/coverage.js';
+import { draftCase } from '../cases/draft.js';
+import { Fixtures } from '../cases/fixtures.js';
+import { readCases } from '../cases/format.js';
+import { edgesFile } from '../config.js';
+import * as edges from '../knowledge/edges.js';
+import { plan } from '../knowledge/plan.js';
+import { screensAffectedBy } from '../knowledge/query.js';
+import { define } from '../registry.js';
+import { caseFiles } from './cases.js';
+import { changedSources } from './map.js';
+// The project's cases and what they cover, read the way `case run` reads them.
+const coverageFor = (ctx, seenFlag) => {
+    const config = ctx.config.cases ?? {};
+    const home = config.base ?? ctx.root;
+    const files = caseFiles([], home, config.dir);
+    if (typeof files === 'string')
+        return files;
+    const cases = files.flatMap(readCases);
+    const seenDir = path.resolve(ctx.root, typeof seenFlag === 'string' ? seenFlag : '.lynkeus/seen');
+    return { cases, coverage: coverageOf(cases, Object.keys(ctx.graph().screens).sort(), readSeen(seenDir)) };
+};
+export const coverageCommands = [
+    define({
+        name: 'case coverage',
+        group: 'runs',
+        summary: 'Which of the app’s screens the cases touch, which none does, and which a case names that the app no longer has',
+        details: 'A screen counts as touched when a case goes to it (`app.nav`), waits for it (`app.wait`), checks it (`app.see: { route }`), or went through it on its last passing run (`case run --seen <dir>`, read from .lynkeus/seen unless --seen says where). The screens come from the route graph (`lynkeus map build`).',
+        flags: {
+            route: { type: 'string', help: 'only this screen: the cases that touch it', value: 'Route' },
+            seen: { type: 'string', help: 'where `case run --seen` kept the screens of passing cases (default .lynkeus/seen)', value: 'dir' },
+        },
+        needs: 'graph',
+        session: false,
+        mcp: 'core',
+        run: async (ctx) => {
+            const read = coverageFor(ctx, ctx.flags.seen);
+            if (typeof read === 'string')
+                return { text: read, code: 1 };
+            const { cases, coverage } = read;
+            if (typeof ctx.flags.route === 'string') {
+                const ids = coverage.byRoute[ctx.flags.route] ?? [];
+                return { text: `${ctx.flags.route}: ${ids.length ? ids.join(', ') : 'no case'}`, json: { route: ctx.flags.route, cases: ids } };
+            }
+            const pct = coverage.routes ? Math.round((100 * coverage.covered.length) / coverage.routes) : 0;
+            const top = Object.entries(coverage.byRoute)
+                .filter(([r]) => !coverage.unknown.includes(r))
+                .sort((a, b) => b[1].length - a[1].length)
+                .slice(0, 8);
+            const lines = [
+                `${coverage.covered.length} of ${coverage.routes} screens touched by a case (${pct}%), from ${cases.length} case${cases.length === 1 ? '' : 's'}`,
+                ...(top.length ? ['most covered:', ...top.map(([r, ids]) => `  ${r.padEnd(34)} ${ids.length}`)] : []),
+                ...(coverage.unknown.length
+                    ? ['named by a case, unknown to the app (renamed? a typo?):', ...coverage.unknown.map((r) => `  ${r} ← ${coverage.byRoute[r].join(', ')}`)]
+                    : []),
+                `${coverage.uncovered.length} screen${coverage.uncovered.length === 1 ? '' : 's'} no case touches${coverage.uncovered.length ? ':' : ''}`,
+                ...coverage.uncovered.slice(0, 30).map((r) => `  ${r}`),
+                ...(coverage.uncovered.length > 30 ? [`  … ${coverage.uncovered.length - 30} more (--json)`] : []),
+            ];
+            return { text: lines.join('\n'), json: coverage };
+        },
+    }),
+    define({
+        name: 'case impact',
+        group: 'runs',
+        summary: 'The cases a branch’s changes reach, to run only those, and the reached screens no case covers',
+        details: 'The screens the diff against --base touches or imports (as `map check` finds them), crossed with what each case covers (as `case coverage` finds it). --files prints one case file per line: `lynkeus case run $(lynkeus case impact --files)`.',
+        flags: {
+            base: { type: 'string', help: 'git ref to diff against', default: 'main', value: 'ref' },
+            depth: { type: 'number', help: 'how many imports away a change still reaches a screen', default: 4, value: 'n' },
+            seen: { type: 'string', help: 'where `case run --seen` kept the screens of passing cases (default .lynkeus/seen)', value: 'dir' },
+            files: { type: 'boolean', help: 'print only the case files, one per line' },
+        },
+        needs: 'graph',
+        session: false,
+        mcp: 'core',
+        run: async (ctx) => {
+            const read = coverageFor(ctx, ctx.flags.seen);
+            if (typeof read === 'string')
+                return { text: read, code: 1 };
+            const base = ctx.flags.base;
+            const changed = changedSources(ctx.root, base, ctx.err);
+            const affected = screensAffectedBy(ctx.graph(), changed, ctx.flags.depth);
+            const impact = impactOf(affected, read.coverage);
+            if (ctx.flags.files)
+                return { text: [...new Set(impact.cases.map((c) => c.file))].join('\n'), json: impact };
+            const lines = [
+                `${changed.length} source file${changed.length === 1 ? '' : 's'} changed against ${base}; they reach ${new Set(affected.map((a) => a.route)).size} screen(s)`,
+                ...(impact.cases.length
+                    ? [`cases to run (${impact.cases.length}):`, ...impact.cases.map((c) => `  ${c.id.padEnd(46)} ${c.routes.join(', ')} (via ${c.via})`)]
+                    : ['no case touches them']),
+                ...(impact.untested.length ? [`reached, and touched by no case (${impact.untested.length}):`, ...impact.untested.map((r) => `  ${r}`)] : []),
+            ];
+            return { text: lines.join('\n'), json: { base, changed, ...impact } };
+        },
+    }),
+    define({
+        name: 'case new',
+        group: 'runs',
+        summary: 'Draft a case for a screen: the way there, the backend setup to pick from, and the checks left to write',
+        details: 'Prints a case to finish: the frontmatter with the questions a reader needs answered, the setup the project’s fixtures server offers (from `lynkeus.describe`, commented out: what state the case needs is the author’s call), the presses from --from (default `cases.start`) to the screen as `map plan` knows them, and the checks to write. --write saves it as <cases dir>/<id>.md, never over a file that is there.',
+        positionals: [{ name: 'id', help: 'the case id, which is also its file name', required: true }],
+        flags: {
+            to: { type: 'string', help: 'the screen the case is about', value: 'Route' },
+            from: { type: 'string', help: 'where it begins (default: cases.start in lynkeus.config.json)', value: 'Route' },
+            title: { type: 'string', help: 'what a person can do there, as the report will title it', value: 'text' },
+            write: { type: 'boolean', help: 'save it in the cases folder instead of printing it' },
+        },
+        needs: 'graph',
+        session: false,
+        mcp: 'core',
+        run: async (ctx) => {
+            const config = ctx.config.cases ?? {};
+            const id = ctx.args[0];
+            if (!/^[a-z0-9][a-z0-9._-]*$/.test(id))
+                return { text: `${id}: an id is lower case letters, digits, dots, dashes and underscores`, code: 2 };
+            const to = ctx.flags.to;
+            const from = ctx.flags.from ?? config.start;
+            if (!to)
+                return { text: 'case new needs --to <Route>, the screen the case is about', code: 2 };
+            if (!from)
+                return { text: 'case new needs --from <Route>, or cases.start in lynkeus.config.json', code: 2 };
+            const graph = ctx.graph();
+            if (!graph.screens[to])
+                return { text: `${to}: the app has no such screen (lynkeus map routes lists them)`, code: 1 };
+            const server = config.fixtures ? new Fixtures(config.fixtures, config.base ?? ctx.root) : undefined;
+            const described = server ? await server.describe().finally(() => server.close()) : undefined;
+            const text = draftCase({
+                id,
+                title: ctx.flags.title,
+                from,
+                to,
+                path: plan(graph, from, to, edges.load(edgesFile(ctx.root))) ?? undefined,
+                fixtures: described?.details,
+                fixturesSilent: !!server && !described,
+                macros: Object.keys(config.macros ?? {}),
+            });
+            if (!ctx.flags.write)
+                return { text, json: { id, text } };
+            const dir = path.resolve(config.base ?? ctx.root, config.dir ?? 'cases');
+            const file = path.join(dir, `${id}.md`);
+            if (fs.existsSync(file))
+                return { text: `${path.relative(ctx.root, file)} is there already; pick another id or edit it`, code: 1 };
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, text);
+            return { text: `wrote ${path.relative(ctx.root, file)}`, json: { id, file } };
+        },
+    }),
+];

package/lib/commands/device.js

@@ -76,8 +76,29 @@ export const simulatorArgv = (platform, deviceId, sub, args, appId) => {
                     { bin: 'xcrun', args: ['simctl', 'launch', deviceId, app, '-AppleLanguages', `(${tag})`, '-AppleLocale', locale] },
                 ];
             }
+            case 'biometrics': {
+                // The simulator's Face ID / Touch ID enrollment, as Features ▸ Face ID ▸ Enrolled toggles it; which of the two
+                // the device has is its model's.
+                const [available] = args;
+                if (!available)
+                    throw new Error('lynkeus os biometrics --available FaceID|TouchID|none on a simulator');
+                const enrolled = available === 'none' ? '0' : '1';
+                return [
+                    { bin: 'xcrun', args: ['simctl', 'spawn', deviceId, 'notifyutil', '-s', 'com.apple.BiometricKit.enrollmentChanged', enrolled] },
+                    { bin: 'xcrun', args: ['simctl', 'spawn', deviceId, 'notifyutil', '-p', 'com.apple.BiometricKit.enrollmentChanged'] },
+                ];
+            }
+            case 'appstate': {
+                // Another app in front puts this one in the background; launching it again brings it back as it was.
+                const [state] = args;
+                if (state === 'background')
+                    return [{ bin: 'xcrun', args: ['simctl', 'launch', deviceId, 'com.apple.Preferences'] }];
+                if (state === 'active')
+                    return [{ bin: 'xcrun', args: ['simctl', 'launch', deviceId, needApp()] }];
+                throw new Error('lynkeus os appstate background|active on a simulator');
+            }
             default:
-                throw new Error(`unknown os subcommand "${sub}"; one of permissions, push, appearance, location, language`);
+                throw new Error(`unknown os subcommand "${sub}"; one of permissions, push, appearance, location, language, appstate`);
         }
     }
     const adb = (a) => ({ bin: 'adb', args: ['-s', deviceId, ...a] });
@@ -101,8 +122,17 @@ export const simulatorArgv = (platform, deviceId, sub, args, appId) => {
             const [lat, lon] = where.split(',');
             return [adb(['emu', 'geo', 'fix', lon, lat])];
         }
+        case 'appstate': {
+            // Home sends the app to the background; its launcher intent brings the same task back, not a new one.
+            const [state] = args;
+            if (state === 'background')
+                return [adb(['shell', 'input', 'keyevent', 'KEYCODE_HOME'])];
+            if (state === 'active')
+                return [adb(['shell', 'monkey', '--pct-syskeys', '0', '-p', needApp(), '-c', 'android.intent.category.LAUNCHER', '1'])];
+            throw new Error('lynkeus os appstate background|active on an emulator or a phone');
+        }
         default:
-            throw new Error(`"${sub}" is not available on Android through lynkeus; permissions, appearance and location are`);
+            throw new Error(`"${sub}" is not available on Android through lynkeus; permissions, appearance, location and appstate are`);
     }
 };
 export const simulatorCommand = async (platform, deviceId, sub, args, appId) => {

package/lib/commands/doctor.js

@@ -73,6 +73,12 @@ const PATTERNS = [
     { re: /requireNativeComponent\s*(?:<[^>]*>)?\(\s*['"]([^'"]+)['"]/g, how: 'requireNativeComponent' },
     { re: /codegenNativeComponent\s*<[^>]*>\(\s*['"]([^'"]+)['"]/g, how: 'codegenNativeComponent' },
 ];
+/**
+ * The text with its comments blanked, lines kept where they were: a mock or a native module named in a comment
+ * (the generated entry shows `jest.mock('some-native-package', …)` as an example) is neither. Only comments that
+ * own their line are taken, so a `//` inside a string (a URL) stays.
+ */
+const withoutComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, ' ')).replace(/^[ \t]*\/\/.*$/gm, '');
 const scanNativeRefs = (root) => {
     const files = [];
     for (const d of SCAN_DIRS)
@@ -81,7 +87,7 @@ const scanNativeRefs = (root) => {
     for (const file of files) {
         let text;
         try {
-            text = fs.readFileSync(file, 'utf8');
+            text = withoutComments(fs.readFileSync(file, 'utf8'));
         }
         catch {
             continue;
@@ -104,7 +110,7 @@ const entryMocks = (root, entry) => {
     const entryPath = path.join(root, entry);
     let text = '';
     try {
-        text = fs.readFileSync(entryPath, 'utf8');
+        text = withoutComments(fs.readFileSync(entryPath, 'utf8'));
     }
     catch {
         return { specs, files };

package/lib/commands/drive.js

@@ -165,7 +165,7 @@ export const driveCommands = [
     define({
         name: 'wait',
         mcp: 'core',
-        mcpOmit: ['nth'],
+        mcpOmit: ['nth', 'since'],
         group: 'drive',
         summary: 'Until a route or element appears (or leaves), or a number of ms',
         positionals: [{ name: 'what', help: `Route | route:index | ${TARGET_HELP} | 800 (ms)`, required: true }],
@@ -174,6 +174,7 @@ export const driveCommands = [
             gone: { type: 'boolean', help: 'until it leaves the screen' },
             scroll: { type: 'boolean', help: 'scroll until it is in the window' },
             timeout: { type: 'number', help: 'give up after', default: 10000, value: 'ms' },
+            since: { type: 'number', help: 'a trace mark: a route reached after it counts, even if already left', value: 'seq' },
         },
         needs: 'app',
         run: async (ctx) => {
@@ -188,6 +189,7 @@ export const driveCommands = [
                     gone: ctx.flags.gone ? true : undefined,
                     scroll: ctx.flags.scroll ? true : undefined,
                     timeoutMs: ctx.flags.timeout,
+                    since: ctx.flags.since,
                 }),
             };
         },

package/lib/commands/fixtures.d.ts

@@ -0,0 +1,7 @@
+import { type Description } from '../cases/fixtures.js';
+/** What a server keeps of the contract and what it leaves out, as lines a person can act on. */
+export declare const checkDescription: (d: Description | undefined) => {
+    ok: boolean;
+    lines: string[];
+};
+export declare const fixturesCommands: import("../registry.js").Command[];

package/lib/commands/fixtures.js

@@ -0,0 +1,94 @@
+import { FIXTURES_PROTOCOL } from 'lynkeus-protocol';
+import { DESCRIBE, Fixtures, lastDescription, readDescription } from '../cases/fixtures.js';
+import { define } from '../registry.js';
+const paramsOf = (c) => Object.entries(c.params ?? {})
+    .map(([k, p]) => `${k}${p.required ? '' : '?'}${p.values ? `=${p.values.join('|')}` : p.type ? `:${p.type}` : ''}`)
+    .join(' ');
+/** What a server keeps of the contract and what it leaves out, as lines a person can act on. */
+export const checkDescription = (d) => {
+    if (!d)
+        return { ok: false, lines: ['✗ `lynkeus.describe` got no list of commands: answer {"commands": [...]} (docs/FIXTURES.md)'] };
+    const lines = [];
+    let ok = true;
+    if (d.down) {
+        ok = false;
+        lines.push(`✗ the server runs but cannot serve: ${d.down}`);
+    }
+    if (d.protocol !== undefined && d.protocol > FIXTURES_PROTOCOL) {
+        ok = false;
+        lines.push(`✗ it speaks fixtures protocol ${d.protocol}; this lynkeus knows ${FIXTURES_PROTOCOL}`);
+    }
+    const names = new Set();
+    for (const c of d.details) {
+        if (names.has(c.name)) {
+            ok = false;
+            lines.push(`✗ ${c.name} is listed twice`);
+        }
+        names.add(c.name);
+    }
+    const bare = d.details.filter((c) => !c.summary);
+    lines.push(`✓ ${d.commands.length} command${d.commands.length === 1 ? '' : 's'}`);
+    if (bare.length)
+        lines.push(`· ${bare.length} without a summary (${bare
+            .slice(0, 6)
+            .map((c) => c.name)
+            .join(', ')}${bare.length > 6 ? ', …' : ''}): a summary and params let authors and models pick a setup`);
+    return { ok, lines };
+};
+export const fixturesCommands = [
+    define({
+        name: 'fixtures describe',
+        group: 'runs',
+        summary: 'List what the project’s fixtures server can do: each command, what it makes or reads, its parameters',
+        details: 'Starts the command `cases.fixtures` names, asks `lynkeus.describe`, and prints each command with its summary and parameters, for whoever writes a case. A server that answers names only shows names. What it answered last (here or before a run) is kept in .lynkeus and shown for a day without starting it; --fresh asks again.',
+        flags: { fresh: { type: 'boolean', help: 'ask the server even when it described itself in the last day' } },
+        needs: 'nothing',
+        session: false,
+        mcp: 'core',
+        run: async (ctx) => {
+            const config = ctx.config.cases ?? {};
+            if (!config.fixtures)
+                return { text: 'the project declares no fixtures (cases.fixtures in lynkeus.config.json)', code: 1 };
+            const root = config.base ?? ctx.root;
+            const kept = ctx.flags.fresh ? undefined : lastDescription(root, config.fixtures.command);
+            const recent = kept && Date.now() - kept.at < 24 * 3600_000 ? kept : undefined;
+            let d = recent?.description;
+            if (!d) {
+                const server = new Fixtures(config.fixtures, root);
+                d = await server.describe().finally(() => server.close());
+            }
+            if (!d)
+                return { text: 'the fixtures server did not describe itself (it answers `lynkeus.describe` with {"commands": [...]})', code: 1 };
+            const text = d.details.map((c) => `${c.name}${c.params ? ` ${paramsOf(c)}` : ''}${c.summary ? `\n    ${c.summary}` : ''}`).join('\n');
+            const age = recent ? `\n(as the server described itself ${Math.round((Date.now() - recent.at) / 60_000)} min ago; --fresh asks it again)` : '';
+            return { text: d.down ? `${text}\n(the server cannot serve now: ${d.down})` : `${text}${age}`, json: d };
+        },
+    }),
+    define({
+        name: 'fixtures check',
+        group: 'runs',
+        summary: 'Tell whether the project’s fixtures server keeps the fixtures protocol',
+        details: 'Starts the server, asks `lynkeus.describe`, and checks the answer against the contract in docs/FIXTURES.md: a list of commands, no name twice, a protocol version this lynkeus knows, and whether it is up. It changes nothing in the backend.',
+        needs: 'nothing',
+        session: false,
+        mcp: 'core',
+        run: async (ctx) => {
+            const config = ctx.config.cases ?? {};
+            if (!config.fixtures)
+                return { text: 'the project declares no fixtures (cases.fixtures in lynkeus.config.json)', code: 1 };
+            const server = new Fixtures(config.fixtures, config.base ?? ctx.root);
+            // Its own call, not describe(): a server that never answers is told apart from one that answers wrong.
+            const answered = await server.call(DESCRIBE, {}).then((answer) => ({ answer }), (error) => ({ error: error.message }));
+            server.close();
+            if ('error' in answered)
+                return {
+                    text: `✗ the fixtures server gave no answer to lynkeus.describe: ${answered.error}\n  (is its backend up? the command is \`${config.fixtures.command}\`)`,
+                    json: { ok: false, error: answered.error },
+                    code: 1,
+                };
+            const d = readDescription(answered.answer);
+            const { ok, lines } = checkDescription(d);
+            return { text: lines.join('\n'), json: { ok, description: d }, code: ok ? 0 : 1 };
+        },
+    }),
+];

package/lib/commands/headless.d.ts

@@ -1 +1,12 @@
+/**
+ * A jest cache of its own for each API base. Babel inlines `process.env` into the code it transforms and jest
+ * keeps that output, so a host started with another API address kept calling the first one it was started with.
+ */
+export declare const cacheFor: (root: string, env: Record<string, string | undefined>, apiEnv?: string) => string;
+/**
+ * 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.
+ */
+/** The app's react folder, when lynkeus-headless would load another copy; undefined when they are one. */
+export declare const duplicateReact: (root: string) => string | undefined;
 export declare const headlessCommands: import("../registry.js").Command[];