lynkeus 0.2.0

package/lib/flow/runner.js

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import { writeJson } from '../files.js';
+import { drainEvents, writeEvents } from '../knowledge/events.js';
+import { runDir, stepFile } from './artifacts.js';
+const interpolate = (value, vars) => {
+    if (typeof value === 'string') {
+        return value.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => {
+            const found = key.split('.').reduce((acc, part) => acc?.[part], vars);
+            if (found === undefined)
+                throw new Error(`Unknown flow variable {{${key}}}`);
+            return String(found);
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v) => interpolate(v, vars));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolate(v, vars)]));
+    }
+    return value;
+};
+export const runFlow = async (flow, options) => {
+    const { device } = options;
+    const vars = { ...options.vars };
+    const missing = (flow.vars ?? []).filter((name) => vars[name] === undefined);
+    if (missing.length)
+        throw new Error(`Flow "${flow.name}" needs vars: ${missing.join(', ')}`);
+    const reports = [];
+    const started = performance.now();
+    const dir = options.artifactsRoot ? runDir(options.artifactsRoot, flow.name) : undefined;
+    const runEvents = [];
+    // What the app recorded before this run is not this run's.
+    if (options.events && device.server.connected)
+        await drainEvents(device);
+    for (const [index, raw] of flow.steps.entries()) {
+        const step = interpolate(raw, vars);
+        const t0 = performance.now();
+        const report = { step, ok: true, ms: 0 };
+        try {
+            await execute(step, flow, device, vars);
+        }
+        catch (error) {
+            report.ok = false;
+            report.error = error instanceof Error ? error.message : String(error);
+        }
+        report.ms = Math.round(performance.now() - t0);
+        if (device.server.connected && !('note' in step)) {
+            try {
+                const screen = await device.screen();
+                report.route = screen.route;
+                report.screen = screen;
+                const events = options.events ? await drainEvents(device) : [];
+                if (events.length) {
+                    report.events = events;
+                    for (const e of events)
+                        runEvents.push({ ...e, step: index + 1, route: screen.route });
+                }
+                if (dir) {
+                    report.artifact = { screen: stepFile(dir, index + 1, 'json') };
+                    writeJson(report.artifact.screen, screen);
+                    if (options.screenshots) {
+                        report.artifact.screenshot = stepFile(dir, index + 1, 'png');
+                        await device.screenshot(report.artifact.screenshot);
+                    }
+                }
+            }
+            catch {
+                // A hung or gone app is reported by the step itself.
+            }
+        }
+        reports.push(report);
+        options.onStep?.(report, index);
+        if (!report.ok)
+            break;
+    }
+    const report = {
+        name: flow.name,
+        ok: reports.every((r) => r.ok),
+        totalMs: Math.round(performance.now() - started),
+        steps: reports,
+        vars,
+        dir,
+    };
+    if (dir) {
+        writeEvents(dir, runEvents);
+        writeJson(path.join(dir, 'report.json'), { ...report, steps: report.steps.map(({ screen: _screen, ...rest }) => rest) });
+    }
+    return report;
+};
+const execute = async (step, flow, device, vars) => {
+    if ('note' in step)
+        return;
+    if ('launch' in step) {
+        await device.server.listen();
+        // A running app dials in within ~1.5 s.
+        const hello = device.server.hello ??
+            (await device.server.waitForApp(2500).then(() => device.server.hello, () => null));
+        if (step.launch.clean && hello)
+            await device.command('reset').catch(() => undefined);
+        // A headless host has no process to relaunch; the reset was the fresh start.
+        if (hello?.app?.runtime === 'headless')
+            return;
+        const appId = step.launch.appId ?? flow.appId ?? device.appId;
+        if (!appId)
+            throw new Error('launch needs an appId (step, flow, or --app)');
+        await device.launchApp(appId, { fresh: step.launch.fresh ?? true });
+        return;
+    }
+    if ('press' in step) {
+        await device.press(step.press);
+        return;
+    }
+    if ('pressIf' in step) {
+        const { timeoutMs, ...target } = step.pressIf;
+        const present = await device.waitFor({ target, timeoutMs: timeoutMs ?? 300 }).then(() => true, () => false);
+        if (present)
+            await device.press(target);
+        return;
+    }
+    if ('keypad' in step) {
+        for (const digit of step.keypad.digits) {
+            await device.press({ testId: step.keypad.pattern.replace('{d}', digit), mode: step.keypad.mode });
+        }
+        return;
+    }
+    if ('type' in step) {
+        await device.type(step.type);
+        return;
+    }
+    if ('swipe' in step) {
+        await device.swipe({ direction: step.swipe.direction });
+        return;
+    }
+    if ('back' in step) {
+        await device.back();
+        return;
+    }
+    if ('dismissKeyboard' in step) {
+        await device.server.call('dismissKeyboard');
+        return;
+    }
+    if ('navigate' in step) {
+        await device.navigate(step.navigate.name, step.navigate.params);
+        return;
+    }
+    if ('deepLink' in step) {
+        await device.openUrl(step.deepLink.url);
+        return;
+    }
+    if ('waitFor' in step) {
+        await device.waitFor(step.waitFor);
+        return;
+    }
+    if ('idle' in step) {
+        await device.idle(step.idle);
+        return;
+    }
+    if ('assert' in step) {
+        // An assertion is a wait with no patience: the state must already hold.
+        await device.waitFor({ ...step.assert, timeoutMs: 0 });
+        return;
+    }
+    if ('call' in step) {
+        const result = await device.command(step.call.method, step.call.params);
+        if (step.call.as)
+            vars[step.call.as] = result;
+        return;
+    }
+    throw new Error(`Unknown step ${JSON.stringify(step)}`);
+};

package/lib/flow/types.d.ts

@@ -0,0 +1,111 @@
+import type { PressOptions, Screen, Target } from 'lynkeus-protocol';
+import type { AppEvent } from '../knowledge/events.js';
+/** A step's values may reference the run's variables (`{{phone}}`) or what an earlier `call` saved (`{{user.pin}}`). */
+export type FlowStep = 
+/** `clean` runs the app's `reset` command first, if it registered one. */
+{
+    launch: {
+        appId?: string;
+        fresh?: boolean;
+        clean?: boolean;
+    };
+} | {
+    press: Target & PressOptions;
+}
+/** Taps the target only if it is on screen. */
+ | {
+    pressIf: Target & {
+        timeoutMs?: number;
+    };
+} | {
+    type: {
+        text: string;
+        target?: Target;
+        clear?: boolean;
+        paste?: boolean;
+    };
+} | {
+    swipe: {
+        direction: 'up' | 'down' | 'left' | 'right';
+    };
+} | {
+    back: true;
+} | {
+    navigate: {
+        name: string;
+        params?: object;
+    };
+} | {
+    deepLink: {
+        url: string;
+    };
+} | {
+    dismissKeyboard: true;
+} | {
+    waitFor: {
+        route?: string;
+        target?: Target;
+        anyOf?: Target[];
+        gone?: boolean;
+        timeoutMs?: number;
+    };
+} | {
+    idle: {
+        quietMs?: number;
+        timeoutMs?: number;
+    };
+} | {
+    assert: {
+        route?: string;
+        target?: Target;
+        gone?: boolean;
+    };
+}
+/** Presses one button per digit, e.g. a code on `digit-{d}-button`. */
+ | {
+    keypad: {
+        digits: string;
+        pattern: string;
+        mode?: 'native' | 'js';
+    };
+}
+/** An app command registered with `qa.register`; the result is saved under `as`. */
+ | {
+    call: {
+        method: string;
+        params?: unknown;
+        as?: string;
+    };
+} | {
+    note: string;
+};
+export type Flow = {
+    name: string;
+    appId?: string;
+    /** The variables the run must supply. */
+    vars?: string[];
+    steps: FlowStep[];
+};
+export type StepReport = {
+    step: FlowStep;
+    ok: boolean;
+    ms: number;
+    error?: string;
+    route?: string;
+    /** The screen after the step, when the step touched the app. */
+    screen?: Screen;
+    artifact?: {
+        screen: string;
+        screenshot?: string;
+    };
+    /** What the app told its analytics while this step ran. */
+    events?: AppEvent[];
+};
+export type FlowReport = {
+    name: string;
+    ok: boolean;
+    totalMs: number;
+    steps: StepReport[];
+    vars: Record<string, unknown>;
+    dir?: string;
+};

package/lib/flow/types.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -0,0 +1,18 @@
+export { Device, describeScreen } from './device/driver.js';
+export { bootedSimulators, pickAgentDevice } from './device/devices.js';
+export type { DeviceInfo, Platform } from './device/devices.js';
+export { runFlow } from './flow/runner.js';
+export type { RunFlowOptions } from './flow/runner.js';
+export type { Flow, FlowReport, FlowStep, StepReport } from './flow/types.js';
+export { diffScreens, describeDiff } from './flow/artifacts.js';
+export { smoke } from './commands/smoke.js';
+export type { SmokeOptions, SmokeResult } from './commands/smoke.js';
+export { crawl } from './commands/crawl.js';
+export type { CrawlOptions, Transition } from './commands/crawl.js';
+export { extractScreenGraph } from './knowledge/extract.js';
+export { pathsTo, screensAffectedBy, vocabularyOf } from './knowledge/query.js';
+export { plan, describePlan } from './knowledge/plan.js';
+export type { PlanStep } from './knowledge/plan.js';
+export { readRouteParams } from './knowledge/route-params.js';
+export * as edges from './knowledge/edges.js';
+export type { ScreenGraph } from './knowledge/types.js';

package/lib/index.js

@@ -0,0 +1,11 @@
+export { Device, describeScreen } from './device/driver.js';
+export { bootedSimulators, pickAgentDevice } from './device/devices.js';
+export { runFlow } from './flow/runner.js';
+export { diffScreens, describeDiff } from './flow/artifacts.js';
+export { smoke } from './commands/smoke.js';
+export { crawl } from './commands/crawl.js';
+export { extractScreenGraph } from './knowledge/extract.js';
+export { pathsTo, screensAffectedBy, vocabularyOf } from './knowledge/query.js';
+export { plan, describePlan } from './knowledge/plan.js';
+export { readRouteParams } from './knowledge/route-params.js';
+export * as edges from './knowledge/edges.js';

package/lib/knowledge/__tests__/edges.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/knowledge/__tests__/edges.test.js

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import * as edges from '../edges.js';
+test('a sighting is one appended line; reading merges them and compaction keeps one per edge', () => {
+    const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-edges-')), 'edges.jsonl');
+    const store = edges.open(file);
+    assert.equal(store.record({ from: 'B.Main', to: 'C.Main', via: 'next' }), true);
+    assert.equal(store.record({ from: 'A.Main', to: 'B.Main', via: 'open' }), true);
+    assert.equal(store.record({ from: 'B.Main', to: 'C.Main', via: 'next' }), false);
+    assert.equal(fs.readFileSync(file, 'utf8').trim().split('\n').length, 3);
+    assert.deepEqual(edges.load(file).map((e) => [e.from, e.seen]), [
+        ['B.Main', 2],
+        ['A.Main', 1],
+    ]);
+    store.compact();
+    assert.deepEqual(fs
+        .readFileSync(file, 'utf8')
+        .trim()
+        .split('\n')
+        .map((l) => JSON.parse(l).from), ['A.Main', 'B.Main']);
+    assert.equal(edges.prune(file, new Set(['A.Main', 'B.Main'])), 1);
+});

package/lib/knowledge/__tests__/events.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/knowledge/__tests__/events.test.js

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { runFlow } from '../../flow/runner.js';
+import { eventsFile, normalizeEvents, readEvents } from '../events.js';
+test('an app buffer that says properties reads as props', () => {
+    assert.deepEqual(normalizeEvents([{ name: 'a', properties: { x: 1 } }, { name: 'b', props: { y: 2 } }, { nope: true }]), [
+        { name: 'a', props: { x: 1 } },
+        { name: 'b', props: { y: 2 } },
+    ]);
+});
+test('a run with events keeps each one with the step and route that caused it', async () => {
+    let buffer = [{ name: 'app_opened' }];
+    const routes = ['Checkout.Main', 'Checkout.Confirm'];
+    let step = 0;
+    const device = {
+        server: { connected: true },
+        press: async () => {
+            buffer.push({ name: step === 0 ? 'checkout_started' : 'checkout_confirmed', properties: { step } });
+            step += 1;
+        },
+        screen: async () => ({ route: routes[step - 1], path: [], elements: [], commit: 0, busy: false, window: { w: 1, h: 1 }, costMs: 0 }),
+        command: async (name, params) => {
+            assert.equal(name, 'events');
+            const out = buffer;
+            if (params?.clear)
+                buffer = [];
+            return out;
+        },
+    };
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-events-'));
+    const report = await runFlow({ name: 'checkout', steps: [{ press: { testId: 'start' } }, { press: { testId: 'confirm' } }] }, { device, artifactsRoot: root, events: true });
+    assert.deepEqual(readEvents(eventsFile(report.dir)), [
+        { name: 'checkout_started', props: { step: 0 }, step: 1, route: 'Checkout.Main' },
+        { name: 'checkout_confirmed', props: { step: 1 }, step: 2, route: 'Checkout.Confirm' },
+    ]);
+});

package/lib/knowledge/__tests__/extract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/knowledge/__tests__/extract.test.js

@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { Project } from 'ts-morph';
+import { collectImports, screenDeclarations } from '../extract.js';
+const file = (code) => new Project({ useInMemoryFileSystem: true }).createSourceFile('Nav.tsx', code);
+test('JSX screens are found', () => {
+    const decls = screenDeclarations(file(`
+    const Nav = () => <Stack.Navigator><Stack.Screen name="A.Main" component={AMain} /></Stack.Navigator>
+  `));
+    assert.deepEqual(decls, [{ route: 'A.Main', component: 'AMain' }]);
+});
+test('static-config screens are found, with quoted and bare keys', () => {
+    const decls = screenDeclarations(file(`
+    const Tabs = createTabs({ screens: {
+      'Settings.Notifications': { screen: SettingsNotifications, options: { lazy: false } },
+      Settings: { screen: SettingsMain },
+    } })
+  `));
+    assert.deepEqual(decls, [
+        { route: 'Settings.Notifications', component: 'SettingsNotifications' },
+        { route: 'Settings', component: 'SettingsMain' },
+    ]);
+});
+test('a static entry whose screen is a nested navigator call is not a screen', () => {
+    const decls = screenDeclarations(file(`
+    const Root = createStack({ screens: { 'Root.Tabs': { screen: buildRootTabs({ hideFirst: false }) } } })
+  `));
+    assert.deepEqual(decls, []);
+});
+test('an object with a screen key inside a spread still counts', () => {
+    const decls = screenDeclarations(file(`
+    const tabs = { ...(hide ? {} : { 'Settings.Main': { screen: SettingsMain } }) }
+  `));
+    assert.deepEqual(decls, [{ route: 'Settings.Main', component: 'SettingsMain' }]);
+});
+test('navigate params that name a screen are not declarations', () => {
+    const decls = screenDeclarations(file(`
+    navigation.navigate('Root.Tabs', { screen: 'Settings.Main', params: { screen: 'Settings.Main' } })
+    const target = { name: 'Root.Tabs', params: { screen: 'Settings.Main' } }
+  `));
+    assert.deepEqual(decls, []);
+});
+const app = (files) => {
+    const project = new Project({ useInMemoryFileSystem: true });
+    for (const [name, code] of Object.entries(files))
+        project.createSourceFile(`/app/${name}`, code);
+    return (name) => collectImports(project.getSourceFileOrThrow(`/app/${name}`), '/app');
+};
+test('a name imported through a barrel points at the file that defines it', () => {
+    const imports = app({
+        'hooks/useThing.ts': 'const useThing = () => 1\nexport { useThing }',
+        'hooks/useOther.ts': 'export const useOther = () => 2',
+        'hooks/index.ts': "export * from './useThing'\nexport { useOther as useRenamed } from './useOther'",
+        'Screen.tsx': "import { useThing } from './hooks'",
+        'Other.tsx': "import { useRenamed } from './hooks'",
+    });
+    assert.deepEqual(imports('Screen.tsx'), { imports: ['hooks/useThing.ts'], barrels: ['hooks/index.ts'] });
+    assert.deepEqual(imports('Other.tsx'), { imports: ['hooks/useOther.ts'], barrels: ['hooks/index.ts'] });
+});
+test('what cannot be traced to one file stays on the module it was imported from', () => {
+    const imports = app({
+        'hooks/useThing.ts': 'export const useThing = () => 1',
+        'hooks/index.ts': "export * from './useThing'\nexport const here = 1",
+        'Whole.tsx': "import * as hooks from './hooks'",
+        'Local.tsx': "import { here, missing } from './hooks'",
+    });
+    assert.deepEqual(imports('Whole.tsx'), { imports: ['hooks/index.ts'], barrels: [] });
+    assert.deepEqual(imports('Local.tsx'), { imports: ['hooks/index.ts'], barrels: [] });
+});

package/lib/knowledge/__tests__/frontier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/knowledge/__tests__/frontier.test.js

@@ -0,0 +1,57 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import * as frontier from '../frontier.js';
+const tmpFile = () => path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-frontier-')), 'frontier.jsonl');
+test('a place owes what it has not tried', () => {
+    const file = tmpFile();
+    const memory = frontier.open(file);
+    memory.record('Settings.Main', { seen: ['share-button', 'account-button', 'profile-button'], visited: true });
+    memory.record('Settings.Main', { tried: ['share-button'] });
+    const [row] = frontier.load(file);
+    assert.deepEqual(row?.tried, ['share-button']);
+    assert.deepEqual(row?.left, ['account-button', 'profile-button']);
+    assert.deepEqual(memory.tried('Settings.Main'), ['share-button']);
+});
+test('a place with nothing left is not offered again', () => {
+    const memory = frontier.open(tmpFile());
+    memory.record('Settings.Main', { seen: ['a'], visited: true });
+    memory.record('Profile.Main', { seen: ['b', 'c'], visited: true });
+    memory.record('Settings.Main', { tried: ['a'] });
+    assert.deepEqual(memory.unfinished(), ['Profile.Main']);
+});
+test('a place only ever seen from outside owes a first visit, before any remainder', () => {
+    const memory = frontier.open(tmpFile());
+    memory.record('Settings.Main', { seen: ['a', 'b', 'c'], visited: true });
+    memory.record('Settings.Main', { tried: ['a'] });
+    memory.record('Profile.Edit', {});
+    assert.deepEqual(memory.unfinished(), ['Profile.Edit', 'Settings.Main']);
+});
+test('a layer is a place of its own', () => {
+    const memory = frontier.open(tmpFile());
+    memory.record('Settings.Main#account-button', { seen: ['nested-button'], visited: true });
+    memory.record('Settings.Main', { seen: ['account-button'], tried: ['account-button'], visited: true });
+    assert.deepEqual(memory.unfinished(), ['Settings.Main#account-button']);
+});
+test('a run appends as it goes and compacts to one sorted line per place', () => {
+    const file = tmpFile();
+    const memory = frontier.open(file);
+    memory.record('Settings.Main', { seen: ['a', 'b'], visited: true });
+    memory.record('Settings.Main', { tried: ['a'] });
+    memory.record('Account.Main', { seen: ['c'] });
+    assert.equal(fs.readFileSync(file, 'utf8').trim().split('\n').length, 3);
+    assert.deepEqual(frontier.open(file).tried('Settings.Main'), ['a']);
+    memory.compact();
+    const lines = fs.readFileSync(file, 'utf8').trim().split('\n');
+    assert.deepEqual(lines.map((l) => JSON.parse(l).node), ['Account.Main', 'Settings.Main']);
+});
+test('a deleted screen takes its unfinished controls with it', () => {
+    const file = tmpFile();
+    const memory = frontier.open(file);
+    memory.record('Settings.Main', { seen: ['a'], visited: true });
+    memory.record('Gone.Screen#sheet', { seen: ['b'], visited: true });
+    assert.equal(frontier.prune(file, new Set(['Settings.Main'])), 1);
+    assert.deepEqual(frontier.load(file).map((r) => r.node), ['Settings.Main']);
+});

package/lib/knowledge/__tests__/funnels.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/knowledge/__tests__/funnels.test.js

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { checkFunnel, diffEvents, funnelCoverage } from '../funnels.js';
+const signup = {
+    name: 'signup',
+    steps: [
+        { event: 'signup_started', props: { source: 'string', step: 'number' } },
+        { event: 'signup_completed', props: { method: 'email' } },
+    ],
+};
+test('a run that produced every step in order, with the right shapes, passes', () => {
+    const result = checkFunnel(signup, [
+        { name: 'app_opened', step: 1 },
+        { name: 'signup_started', props: { source: 'ad', step: 2 }, step: 2 },
+        { name: 'signup_completed', props: { method: 'email' }, step: 4 },
+    ]);
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.steps.map((s) => s.at), [2, 4]);
+});
+test('a missing step, a step out of order and a property of the wrong type each say so', () => {
+    assert.equal(checkFunnel(signup, [{ name: 'signup_started', props: { source: 'ad', step: 2 } }]).steps[1]?.problem, 'never happened');
+    assert.equal(checkFunnel(signup, [
+        { name: 'signup_completed', props: { method: 'email' } },
+        { name: 'signup_started', props: { source: 'ad', step: 2 } },
+    ]).steps[1]?.problem, 'happened, but before the step it should follow');
+    assert.equal(checkFunnel(signup, [
+        { name: 'signup_started', props: { source: 'ad', step: '2' } },
+        { name: 'signup_completed', props: { method: 'phone' } },
+    ])
+        .steps.map((s) => s.problem)
+        .join(' | '), 'step is string, the funnel needs number | method is "phone", the funnel filters on "email"');
+});
+test('between two builds: an event that appeared, one that was lost, one whose properties changed', () => {
+    const diff = diffEvents([{ name: 'a', props: { step: 1 } }, { name: 'gone' }], [{ name: 'a', props: { step: '1', ref: 'x' } }, { name: 'new' }]);
+    assert.deepEqual(diff, { added: ['new'], lost: ['gone'], changed: [{ event: 'a', changes: ['+ref', 'step number→string'] }] });
+});
+test('coverage names the funnel steps no run produces', () => {
+    const coverage = funnelCoverage([signup], [{ run: 'signup/1', events: [{ name: 'signup_started' }] }]);
+    assert.deepEqual(coverage[0]?.steps.map((s) => s.runs.length), [1, 0]);
+});

package/lib/knowledge/__tests__/lint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/knowledge/__tests__/lint.test.js

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { lintScreen } from '../lint.js';
+const screen = (elements) => ({
+    path: ['Root'],
+    commit: 1,
+    busy: false,
+    window: { w: 390, h: 844 },
+    costMs: 1,
+    elements: elements.map((e, i) => ({ i, kind: 'view', frame: { x: 0, y: 0, w: 100, h: 50 }, enabled: true, depth: 0, ...e })),
+});
+test('an unlabeled button is flagged', () => {
+    const f = lintScreen(screen([{ kind: 'button' }]));
+    assert.equal(f.filter((x) => x.rule === 'unlabeled-control').length, 1);
+});
+test('a labeled button is not', () => {
+    const f = lintScreen(screen([{ kind: 'button', testId: 'ok' }]));
+    assert.equal(f.filter((x) => x.rule === 'unlabeled-control').length, 0);
+});
+test('an icon-only small target warns, a labeled one (a tab item) is info', () => {
+    const f = lintScreen(screen([
+        { kind: 'button', testId: 'icon', frame: { x: 0, y: 0, w: 24, h: 24 } },
+        { kind: 'button', testId: 'tab', text: 'HOME', frame: { x: 0, y: 0, w: 26, h: 16 } },
+    ]));
+    const small = f.filter((x) => x.rule === 'small-target');
+    assert.equal(small.find((x) => x.message.includes('icon'))?.severity, 'warn');
+    assert.equal(small.find((x) => x.message.includes('tab'))?.severity, 'info');
+});
+test('an untranslated i18n key is flagged, real copy is not', () => {
+    const f = lintScreen(screen([
+        { kind: 'text', text: 'profile.settings.title' },
+        { kind: 'text', text: 'Settings' },
+    ]));
+    assert.equal(f.filter((x) => x.rule === 'untranslated').length, 1);
+});
+test('the theme-[object Object] duplicate testId is caught', () => {
+    const f = lintScreen(screen([
+        { kind: 'button', testId: 'theme-[object Object]-radio', frame: { x: 0, y: 0, w: 24, h: 24 } },
+        { kind: 'button', testId: 'theme-[object Object]-radio', frame: { x: 0, y: 100, w: 24, h: 24 } },
+    ]));
+    assert.equal(f.filter((x) => x.rule === 'duplicate-testid').length, 1);
+});
+test('a covered interactive element is info, a covered view is nothing', () => {
+    const f = lintScreen(screen([
+        { kind: 'button', testId: 'under', covered: true },
+        { kind: 'view', covered: true },
+    ]));
+    assert.equal(f.filter((x) => x.rule === 'covered-control').length, 1);
+});
+test('an element drawn past the window is flagged', () => {
+    const f = lintScreen(screen([{ kind: 'text', text: 'wide', frame: { x: 300, y: 0, w: 200, h: 20 } }]));
+    assert.equal(f.filter((x) => x.rule === 'offscreen').length, 1);
+});

package/lib/knowledge/__tests__/perf.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/knowledge/__tests__/perf.test.js

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { summarize, visitsFrom } from '../perf.js';
+const ev = (partial, seq) => ({ seq, ...partial });
+const trace = [
+    ev({ kind: 'route', route: 'First.Main', path: ['First.Main'], t: 1000 }, 1),
+    ev({ kind: 'request', method: 'GET', url: 'http://x/api/a', status: 200, ms: 120, t: 1130 }, 2),
+    ev({ kind: 'request', method: 'GET', url: 'http://x/api/b?limit=100', status: 500, ms: 900, t: 1920 }, 3),
+    // Polling long after arrival is not part of what the screen cost to open.
+    ev({ kind: 'request', method: 'GET', url: 'http://x/api/a', status: 200, ms: 50, t: 4000 }, 8),
+    ev({ kind: 'stall', renders: 50, windowMs: 100, t: 1500 }, 4),
+    ev({ kind: 'route', route: 'Second.Main', path: ['Second.Main'], t: 5000 }, 5),
+    ev({ kind: 'request', method: 'GET', url: 'http://x/api/c', status: 200, ms: 40, t: 5045 }, 6),
+    ev({ kind: 'command', method: 'press', ms: 5, t: 5100 }, 7),
+];
+test('a visit counts its requests, errors, stalls and when it went quiet', () => {
+    const [home, pay] = visitsFrom(trace);
+    assert.equal(home.route, 'First.Main');
+    assert.equal(home.requests, 3);
+    assert.equal(home.errors, 1);
+    assert.equal(home.stalls, 1);
+    assert.equal(home.quietAfterMs, 920); // the 900 ms request ended at +920; the poll at +3950 came after a quiet gap
+    assert.deepEqual(home.slowest, { method: 'GET', path: '/api/b?limit=100', ms: 900 });
+    assert.equal(home.ms, 4000);
+    assert.equal(pay.requests, 1);
+});
+test('the summary averages per route and puts the slowest screen first', () => {
+    const s = summarize(visitsFrom(trace));
+    assert.deepEqual(s.map((r) => r.route), ['First.Main', 'Second.Main']);
+    assert.equal(s[0].quietAfterMs, 920);
+});
+test('events before any route are ignored', () => {
+    assert.deepEqual(visitsFrom([ev({ kind: 'request', method: 'GET', url: 'http://x/a', ms: 1, t: 1 }, 1)]), []);
+});

package/lib/knowledge/__tests__/plan.test.d.ts

@@ -0,0 +1 @@
+export {};