lynkeus 0.2.0

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

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { describePlan, plan } from '../plan.js';
+const graph = (routes) => ({
+    app: 'test',
+    root: '/tmp',
+    extractedAt: '2026-01-01',
+    screens: Object.fromEntries(routes.map((route) => [route, { route, component: route, file: null, declaredIn: 'nav.tsx' }])),
+    files: {},
+    warnings: [],
+});
+const edge = (e) => ({ seen: 1, last: '2026-01-01', ...e });
+test('a sheet is a place the directions can reach', () => {
+    const steps = plan(graph(['Settings.Main', 'Account.Delete']), 'Settings.Main', 'Account.Delete', [
+        edge({ from: 'Settings.Main', to: 'Settings.Main', via: 'account-button', toLayer: 'account-button' }),
+        edge({ from: 'Settings.Main', to: 'Account.Delete', via: 'delete-account-button', fromLayer: 'account-button' }),
+    ]);
+    assert.deepEqual(steps?.map((s) => [s.from, s.press, s.to]), [
+        ['Settings.Main', 'account-button', 'Settings.Main#account-button'],
+        ['Settings.Main#account-button', 'delete-account-button', 'Account.Delete'],
+    ]);
+    assert.match(describePlan(steps), /opens a layer/);
+});
+test('what a screen offers does not apply while a sheet covers it', () => {
+    const steps = plan(graph(['Settings.Main', 'Profile.Edit']), 'Settings.Main#account-button', 'Profile.Edit', [
+        edge({ from: 'Settings.Main', to: 'Profile.Edit', via: 'profile-button' }),
+    ]);
+    assert.equal(steps, null);
+});
+test('asking for a route accepts arriving with something open over it', () => {
+    const steps = plan(graph(['Settings.Main', 'Checkout.Main']), 'Settings.Main', 'Checkout.Main', [
+        edge({ from: 'Settings.Main', to: 'Checkout.Main', via: 'send-button', toLayer: 'send-button' }),
+    ]);
+    assert.deepEqual(steps?.map((s) => s.to), ['Checkout.Main#send-button']);
+});

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

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

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

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { screensAffectedBy } from '../query.js';
+const graph = {
+    app: 'test',
+    root: 'Root',
+    extractedAt: '',
+    warnings: [],
+    screens: {
+        'A.Main': { route: 'A.Main', component: 'A', file: 'app/a.tsx', declaredIn: 'nav.tsx' },
+        'B.Main': { route: 'B.Main', component: 'B', file: 'app/b.tsx', declaredIn: 'nav.tsx' },
+    },
+    files: {
+        'app/a.tsx': { imports: ['app/shared.tsx'] },
+        'app/b.tsx': { imports: [] },
+        'app/shared.tsx': { imports: [] },
+    },
+};
+test('a changed screen file is affected at distance 0', () => {
+    const r = screensAffectedBy(graph, ['app/a.tsx']);
+    assert.deepEqual(r.map((x) => [x.route, x.distance]), [['A.Main', 0]]);
+});
+test('a shared file reaches its importer at distance 1, naming the changed file', () => {
+    const r = screensAffectedBy(graph, ['app/shared.tsx']);
+    assert.deepEqual(r.map((x) => [x.route, x.distance, x.via]), [['A.Main', 1, 'app/shared.tsx']]);
+});
+test('results are nearest first', () => {
+    const g = {
+        ...graph,
+        screens: { ...graph.screens, 'C.Main': { route: 'C.Main', component: 'C', file: 'app/c.tsx', declaredIn: 'nav.tsx' } },
+        files: { ...graph.files, 'app/c.tsx': { imports: ['app/a.tsx'] } },
+    };
+    const r = screensAffectedBy(g, ['app/shared.tsx']);
+    assert.deepEqual(r.map((x) => [x.route, x.distance]), [
+        ['A.Main', 1],
+        ['C.Main', 2],
+    ]);
+});
+test('an unrelated change affects nothing', () => {
+    assert.deepEqual(screensAffectedBy(graph, ['app/unrelated.tsx']), []);
+});
+test('a barrel reaches who imports through it only when the barrel itself changed', () => {
+    const g = {
+        ...graph,
+        files: {
+            'app/a.tsx': { imports: ['app/hooks/useThing.ts'], barrels: ['app/hooks/index.ts'] },
+            'app/b.tsx': { imports: ['app/hooks/useOther.ts'], barrels: ['app/hooks/index.ts'] },
+            'app/hooks/index.ts': { imports: ['app/hooks/useThing.ts', 'app/hooks/useOther.ts'] },
+            'app/hooks/useThing.ts': { imports: [] },
+            'app/hooks/useOther.ts': { imports: [] },
+        },
+    };
+    assert.deepEqual(screensAffectedBy(g, ['app/hooks/useThing.ts']).map((x) => x.route), ['A.Main']);
+    assert.deepEqual(screensAffectedBy(g, ['app/hooks/index.ts']).map((x) => x.route), ['A.Main', 'B.Main']);
+});

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

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

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

@@ -0,0 +1,30 @@
+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 { diffGeometry, record } from '../screens.js';
+const f = (x, y, w, h) => ({ x, y, w, h });
+test('drift within the tolerance is not a change', () => {
+    assert.deepEqual(diffGeometry({ a: f(10, 10, 100, 40) }, { a: f(12, 8, 102, 41) }), []);
+});
+test('a move past the tolerance is reported with both positions', () => {
+    assert.deepEqual(diffGeometry({ a: f(10, 10, 100, 40) }, { a: f(10, 60, 100, 40) }), ['#a moved (10,10)→(10,60)']);
+});
+test('a resize is reported', () => {
+    assert.deepEqual(diffGeometry({ a: f(0, 0, 100, 40) }, { a: f(0, 0, 100, 80) }), ['#a resized 100×40→100×80']);
+});
+test('an element that collapsed to zero is named as such', () => {
+    assert.deepEqual(diffGeometry({ a: f(0, 0, 100, 40) }, { a: f(0, 0, 100, 0) }), ['#a collapsed to 100×0 (was 100×40)']);
+});
+test('elements only on one side are not geometry changes', () => {
+    assert.deepEqual(diffGeometry({ a: f(0, 0, 1, 1) }, { b: f(0, 0, 1, 1) }), []);
+});
+test('a recorded screen keeps what is presented, not what another tab or a covered screen holds', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-screens-'));
+    const el = (i, testId, hidden) => ({ i, kind: 'button', frame: f(0, i * 50, 100, 40), enabled: true, depth: 0, testId, hidden });
+    const screen = (elements) => ({ route: 'Settings.Main', path: ['Settings.Main'], commit: 1, busy: false, window: { w: 390, h: 844 }, costMs: 1, elements });
+    record(dir, screen([el(0, 'save'), el(1, 'other-tab', 'a11y'), el(2, 'slide', 'inert')]));
+    const change = record(dir, screen([el(0, 'save'), el(2, 'slide', 'inert')]));
+    assert.equal(change, null);
+});

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

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

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

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { explain } from '../why.js';
+const el = (p, i) => ({ i, kind: 'button', frame: { x: 0, y: 0, w: 10, h: 10 }, enabled: true, depth: 1, tag: i + 1, ...p });
+const screen = (elements, route) => ({ route, path: route ? [route] : [], elements, commit: 5, costMs: 1 });
+const req = (status, url, error) => ({ id: 1, method: 'GET', url, status, startedAt: 0, ms: 10, error });
+const rules = (f) => f.map((x) => x.rule);
+test('a dead navigator and a gone session are named', () => {
+    assert.deepEqual(rules(explain({ screen: screen([]), requests: [], inFlight: 0 })), ['dead-navigator']);
+    assert.ok(rules(explain({ screen: screen([el({}, 0)], 'Home'), requests: [req(401, 'http://x/a'), req(401, 'http://x/b')], inFlight: 0 })).includes('session-gone'));
+});
+test('a covered target, a near text and a capped list', () => {
+    const s = screen([el({ testId: 'submit', covered: true }, 0), el({ kind: 'text', text: 'Café Ünïcode wörks here' }, 1)], 'Home');
+    assert.ok(rules(explain({ screen: s, requests: [], inFlight: 0, target: { testId: 'submit' } })).includes('covered'));
+    assert.ok(rules(explain({ screen: s, requests: [], inFlight: 0, target: { text: 'Cafe Unicode works here' } })).includes('near-match'));
+    assert.ok(rules(explain({ screen: s, requests: [], inFlight: 0, target: { text: 'cafe unicode works here' } })).includes('near-match'));
+    assert.ok(!rules(explain({ screen: s, requests: [], inFlight: 0, target: { text: 'A completely different sentence' } })).includes('near-match'));
+    const list = screen(Array.from({ length: 12 }, (_, i) => el({ testId: `row-${i}-item`, text: `Item${i}` }, i)), 'Search');
+    assert.ok(rules(explain({ screen: list, requests: [req(200, 'http://x/search')], inFlight: 0, target: { text: 'itemabc' } })).includes('capped-list'));
+});
+test('backend and loading conditions', () => {
+    const s = screen([el({}, 0)], 'Home');
+    assert.ok(rules(explain({ screen: s, requests: [req(500, 'http://x/api/a')], inFlight: 0 })).includes('backend-error'));
+    assert.ok(rules(explain({ screen: s, requests: [req(200, 'http://x/a')], inFlight: 2, target: { testId: 'x' } })).includes('in-flight'));
+    const stall = { seq: 1, t: 1, kind: 'stall', renders: 2000, windowMs: 3000, component: 'Feed' };
+    assert.ok(rules(explain({ screen: s, requests: [], inFlight: 0, trace: [stall] })).includes('render-loop'));
+    assert.deepEqual(rules(explain({ screen: s, requests: [req(200, 'http://x/a')], inFlight: 0 })), []);
+});

package/lib/knowledge/edges.d.ts

@@ -0,0 +1,30 @@
+export type ObservedEdge = {
+    from: string;
+    to: string;
+    /** A testID, or `text:<label>` when the control had none. */
+    via: string;
+    /** The layer open over `from` when the press happened, named after the control that opened it. */
+    fromLayer?: string;
+    /** The layer left open over `to`, named the same way. */
+    toLayer?: string;
+    seen: number;
+    /** A date, not a timestamp, so a run does not churn every line. */
+    last: string;
+};
+export type EdgeObservation = Pick<ObservedEdge, 'from' | 'to' | 'via' | 'fromLayer' | 'toLayer'>;
+export declare const splitNode: (node: string) => {
+    route: string;
+    layer?: string;
+};
+export declare const edgeFrom: (edge: EdgeObservation) => string;
+export declare const edgeTo: (edge: EdgeObservation) => string;
+export declare const load: (file: string) => ObservedEdge[];
+/** The edges in a file, kept in memory while a run adds to them. */
+export declare const open: (file: string) => {
+    all: () => ObservedEdge[];
+    /** True when the edge is new. */
+    record: (observation: EdgeObservation) => boolean;
+    compact: () => void;
+};
+/** Drops the edges of routes that no longer exist, so the store is collected against the app rather than a clock. */
+export declare const prune: (file: string, routes: Set<string>) => number;

package/lib/knowledge/edges.js

@@ -0,0 +1,68 @@
+/**
+ * Navigations a run has actually walked, as `edges.jsonl`: one sorted line per
+ * distinct edge so concurrent edits merge in git, and a counter instead of a
+ * row per sighting so the file converges instead of growing.
+ *
+ * A run appends one line per sighting and compacts once at the end; reading
+ * merges duplicate lines, so a run that is killed halfway loses nothing.
+ */
+import { appendJsonl, readJsonl, today, writeJsonl } from '../files.js';
+const nodeId = (route, layer) => (layer ? `${route}#${layer}` : route);
+export const splitNode = (node) => {
+    const at = node.indexOf('#');
+    return at === -1 ? { route: node } : { route: node.slice(0, at), layer: node.slice(at + 1) };
+};
+export const edgeFrom = (edge) => nodeId(edge.from, edge.fromLayer);
+export const edgeTo = (edge) => nodeId(edge.to, edge.toLayer);
+const key = (edge) => `${edgeFrom(edge)} ${edge.via} ${edgeTo(edge)}`;
+const merge = (into, row) => {
+    into.seen += row.seen;
+    if (row.last > into.last)
+        into.last = row.last;
+};
+const merged = (rows) => {
+    const byKey = new Map();
+    for (const row of rows) {
+        const found = byKey.get(key(row));
+        if (found)
+            merge(found, row);
+        else
+            byKey.set(key(row), { ...row });
+    }
+    return byKey;
+};
+const save = (file, edges) => writeJsonl(file, [...edges].sort((a, b) => key(a).localeCompare(key(b))));
+export const load = (file) => [...merged(readJsonl(file)).values()];
+/** The edges in a file, kept in memory while a run adds to them. */
+export const open = (file) => {
+    const known = merged(readJsonl(file));
+    let appended = false;
+    return {
+        all: () => [...known.values()],
+        /** True when the edge is new. */
+        record: (observation) => {
+            const row = { ...observation, seen: 1, last: today() };
+            appendJsonl(file, row);
+            appended = true;
+            const found = known.get(key(row));
+            if (found)
+                merge(found, row);
+            else
+                known.set(key(row), { ...row });
+            return !found;
+        },
+        compact: () => {
+            if (appended)
+                save(file, load(file));
+        },
+    };
+};
+/** Drops the edges of routes that no longer exist, so the store is collected against the app rather than a clock. */
+export const prune = (file, routes) => {
+    const before = load(file);
+    if (before.length === 0)
+        return 0;
+    const after = before.filter((e) => routes.has(e.from) && routes.has(e.to));
+    save(file, after);
+    return before.length - after.length;
+};

package/lib/knowledge/errors.d.ts

@@ -0,0 +1,8 @@
+/** The usual cause and fix of a headless failure, found in jest's output so nobody reads a 300-line stack for it. */
+export type Explanation = {
+    cause: string;
+    fix: string;
+    match: string;
+};
+export declare const explainError: (text: string) => Explanation[];
+export declare const describeExplanations: (list: Explanation[]) => string;

package/lib/knowledge/errors.js

@@ -0,0 +1,62 @@
+const RULES = [
+    {
+        re: /TurboModuleRegistry\.getEnforcing\(\.\.\.\): '([^']+)' could not be found/,
+        cause: (m) => `the native module ${m[1]} does not exist under jest`,
+        fix: (m) => `mock the package that owns ${m[1]} in the headless entry: jest.mock('<package>', () => ({ ... })). \`lynkeus headless doctor\` lists where it is referenced.`,
+    },
+    {
+        re: /Invariant Violation: (?:requireNativeComponent: )?"?([\w.]+)"? was not found in the UIManager/,
+        cause: (m) => `the native view ${m[1]} has no jest counterpart`,
+        fix: (m) => `mock the library that renders ${m[1]} with a plain View (see the vision-camera and webview stubs lynkeus ships for the shape).`,
+    },
+    {
+        re: /Cannot find module '([^']+)' from '([^']+)'/,
+        cause: (m) => `${m[2]} imports ${m[1]}, which jest cannot resolve`,
+        fix: (m) => `if ${m[1]} is a path alias, add it to jest moduleNameMapper; if it is an optional native package, jest.mock it in the headless entry.`,
+    },
+    {
+        re: /lynkeus headless only drives a local backend; API_URL is "([^"]*)"/,
+        cause: (m) => `API_URL is "${m[1] || '(empty)'}", not a local backend`,
+        fix: () => `export API_URL=http://127.0.0.1:<port>/ before \`lynkeus headless start\`; if the app inlines env at build time, clear its jest transform cache too.`,
+    },
+    {
+        re: /(\w+)\.(\w+) is not a function/,
+        cause: (m) => `${m[1]}.${m[2]} is missing — usually a mock that does not implement a method the app calls`,
+        fix: (m) => `extend the mock for ${m[1]} with ${m[2]}; the lynkeus defaults can be overridden per key in installDefaultMocks({ overrides }).`,
+    },
+    {
+        re: /Cannot read propert(?:y|ies) of undefined \(reading '(\w+)'\)/,
+        cause: (m) => `something the app expected to exist is undefined (reading '${m[1]}')`,
+        fix: () => `look one frame up the stack for the module: a mock returning {} instead of the shape the app reads, or a store not initialised because a service failed earlier.`,
+    },
+    {
+        re: /Jest did not exit one second after the test run has completed/,
+        cause: () => `the host finished but something kept the event loop alive`,
+        fix: () => `harmless for a host that is meant to stay up; when it is not, an open socket or timer from a mock is the usual culprit.`,
+    },
+    {
+        re: /ECONNREFUSED (\d+\.\d+\.\d+\.\d+):(\d+)/,
+        cause: (m) => `nothing is listening on ${m[1]}:${m[2]}`,
+        fix: () => `start the backend (or the lynkeus driver, if this is the agent's socket) and check the port the entry dials.`,
+    },
+    {
+        re: /Test environment jest-environment-\w+ cannot be found|Unexpected token 'export'|SyntaxError: Cannot use import statement/,
+        cause: () => `jest is not transforming a dependency (ESM in node_modules)`,
+        fix: () => `add the package to transformIgnorePatterns' allow-list in the app's jest config, the same way react-native itself is listed (lynkeus-agent and lynkeus-headless need 'lynkeus-[^/]+' there).`,
+    },
+    {
+        re: /ReferenceError: (\w+) is not defined/,
+        cause: (m) => `${m[1]} is a global the runtime does not provide under jest`,
+        fix: (m) => `define ${m[1]} in the headless entry before requiring the app (globalThis.${m[1]} = ...), or mock the module that expects it.`,
+    },
+];
+export const explainError = (text) => {
+    const out = [];
+    for (const rule of RULES) {
+        const m = text.match(rule.re);
+        if (m)
+            out.push({ match: m[0], cause: rule.cause(m), fix: rule.fix(m) });
+    }
+    return out;
+};
+export const describeExplanations = (list) => list.length === 0 ? '' : ['', 'lynkeus: what this looks like', ...list.map((e) => `  ${e.match}\n    cause  ${e.cause}\n    fix    ${e.fix}`)].join('\n');

package/lib/knowledge/events.d.ts

@@ -0,0 +1,23 @@
+export type AppEvent = {
+    name: string;
+    props?: Record<string, unknown>;
+};
+export type RunEvent = AppEvent & {
+    step: number;
+    route?: string;
+};
+type Drainable = {
+    command<T = unknown>(name: string, params?: unknown): Promise<T>;
+};
+/** An app's own buffer may say `properties`; lynkeus says `props`. */
+export declare const normalizeEvents: (raw: unknown) => AppEvent[];
+export declare const drainEvents: (device: Drainable) => Promise<AppEvent[]>;
+export declare const eventsFile: (runDir: string) => string;
+export declare const writeEvents: (runDir: string, events: RunEvent[]) => void;
+export declare const readEvents: (file: string) => RunEvent[];
+/** Every run under `runs/` that recorded events, newest first. */
+export declare const eventsFiles: (runsRoot: string) => string[];
+/** A run folder, `last`, or an events.jsonl itself. */
+export declare const resolveEventsFile: (runsRoot: string, ref: string) => string | undefined;
+export declare const describeEvents: (events: RunEvent[]) => string;
+export {};

package/lib/knowledge/events.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonl } from '../files.js';
+/** An app's own buffer may say `properties`; lynkeus says `props`. */
+export const normalizeEvents = (raw) => (Array.isArray(raw) ? raw : []).flatMap((e) => {
+    const r = e;
+    if (typeof r?.name !== 'string')
+        return [];
+    const props = (r.props ?? r.properties);
+    return [{ name: r.name, ...(props && typeof props === 'object' ? { props } : {}) }];
+});
+export const drainEvents = async (device) => {
+    try {
+        return normalizeEvents(await device.command('events', { clear: true }));
+    }
+    catch {
+        return [];
+    }
+};
+export const eventsFile = (runDir) => path.join(runDir, 'events.jsonl');
+export const writeEvents = (runDir, events) => {
+    if (events.length === 0)
+        return;
+    fs.writeFileSync(eventsFile(runDir), `${events.map((e) => JSON.stringify(e)).join('\n')}\n`);
+};
+export const readEvents = (file) => readJsonl(file);
+/** Every run under `runs/` that recorded events, newest first. */
+export const eventsFiles = (runsRoot) => {
+    const found = [];
+    const visit = (dir, depth) => {
+        if (depth > 3 || !fs.existsSync(dir))
+            return;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                visit(full, depth + 1);
+            else if (entry.name === 'events.jsonl')
+                found.push({ file: full, mtime: fs.statSync(full).mtimeMs });
+        }
+    };
+    visit(runsRoot, 0);
+    return found.sort((a, b) => b.mtime - a.mtime).map((f) => f.file);
+};
+/** A run folder, `last`, or an events.jsonl itself. */
+export const resolveEventsFile = (runsRoot, ref) => {
+    if (ref === 'last')
+        return eventsFiles(runsRoot)[0];
+    const full = path.resolve(ref);
+    return full.endsWith('.jsonl') ? full : eventsFile(full);
+};
+export const describeEvents = (events) => events.map((e) => `${String(e.step).padStart(2)} ${e.route ?? '?'}  ${e.name}${e.props ? ` ${JSON.stringify(e.props)}` : ''}`).join('\n');

package/lib/knowledge/extract.d.ts

@@ -0,0 +1,26 @@
+import { type SourceFile } from 'ts-morph';
+import type { ScreenGraph, SourcePath } from './types.js';
+type ExtractOptions = {
+    root: string;
+    navigatorGlobs?: string[];
+    /** First-party source, relative to the root. */
+    sourceDir?: string;
+};
+export declare const extractScreenGraph: ({ root, navigatorGlobs, sourceDir }: ExtractOptions) => ScreenGraph;
+export type ScreenDeclaration = {
+    route: string;
+    component: string | null;
+};
+/** Routes in either of React Navigation's shapes: `<Stack.Screen name component />`, or `screens: { 'A.B': { screen: AB } }`. */
+export declare const screenDeclarations: (source: SourceFile) => ScreenDeclaration[];
+/**
+ * Import edges. A named import through a barrel (`import { useThing } from
+ * '~hooks'`) points at the file that defines the name, not at the barrel:
+ * otherwise a change to one hook reaches every screen that imports any hook.
+ * The barrels passed through are kept apart, for when the barrel itself changes.
+ */
+export declare const collectImports: (source: SourceFile, root: string) => {
+    imports: SourcePath[];
+    barrels: SourcePath[];
+};
+export {};