lynkeus 0.2.0

package/src/knowledge/__tests__/plan.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import type { ObservedEdge } from '../edges.js';
+import { describePlan, plan } from '../plan.js';
+import type { ScreenGraph } from '../types.js';
+
+const graph = (routes: string[]): ScreenGraph => ({
+  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: Partial<ObservedEdge> & Pick<ObservedEdge, 'from' | 'to' | 'via'>): ObservedEdge => ({ 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/src/knowledge/__tests__/query.test.ts

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { screensAffectedBy } from '../query.js';
+import type { ScreenGraph } from '../types.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: [] },
+  },
+} as unknown as ScreenGraph;
+
+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'] } },
+  } as unknown as ScreenGraph;
+  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: [] },
+    },
+  } as unknown as ScreenGraph;
+  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/src/knowledge/__tests__/screens.test.ts

@@ -0,0 +1,37 @@
+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 type { Screen } from 'lynkeus-protocol';
+
+import { diffGeometry, record } from '../screens.js';
+
+const f = (x: number, y: number, w: number, h: number) => ({ 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: number, testId: string, hidden?: string) => ({ i, kind: 'button', frame: f(0, i * 50, 100, 40), enabled: true, depth: 0, testId, hidden });
+  const screen = (elements: object[]) =>
+    ({ route: 'Settings.Main', path: ['Settings.Main'], commit: 1, busy: false, window: { w: 390, h: 844 }, costMs: 1, elements }) as unknown as Screen;
+  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/src/knowledge/__tests__/why.test.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { explain } from '../why.js';
+import type { Element, RequestRecord, Screen, TraceEvent } from 'lynkeus-protocol';
+
+const el = (p: Partial<Element>, i: number): Element =>
+  ({ i, kind: 'button', frame: { x: 0, y: 0, w: 10, h: 10 }, enabled: true, depth: 1, tag: i + 1, ...p }) as Element;
+const screen = (elements: Element[], route?: string): Screen => ({ route, path: route ? [route] : [], elements, commit: 5, costMs: 1 }) as unknown as Screen;
+const req = (status: number | undefined, url: string, error?: string): RequestRecord => ({ id: 1, method: 'GET', url, status, startedAt: 0, ms: 10, error });
+const rules = (f: ReturnType<typeof explain>) => 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: TraceEvent = { 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/src/knowledge/edges.ts

@@ -0,0 +1,91 @@
+/**
+ * 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';
+
+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'>;
+
+const nodeId = (route: string, layer?: string) => (layer ? `${route}#${layer}` : route);
+
+export const splitNode = (node: string): { route: string; layer?: string } => {
+  const at = node.indexOf('#');
+  return at === -1 ? { route: node } : { route: node.slice(0, at), layer: node.slice(at + 1) };
+};
+
+export const edgeFrom = (edge: EdgeObservation) => nodeId(edge.from, edge.fromLayer);
+export const edgeTo = (edge: EdgeObservation) => nodeId(edge.to, edge.toLayer);
+
+const key = (edge: EdgeObservation) => `${edgeFrom(edge)} ${edge.via} ${edgeTo(edge)}`;
+
+const merge = (into: ObservedEdge, row: ObservedEdge) => {
+  into.seen += row.seen;
+  if (row.last > into.last) into.last = row.last;
+};
+
+const merged = (rows: ObservedEdge[]): Map<string, ObservedEdge> => {
+  const byKey = new Map<string, ObservedEdge>();
+  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: string, edges: ObservedEdge[]) =>
+  writeJsonl(
+    file,
+    [...edges].sort((a, b) => key(a).localeCompare(key(b))),
+  );
+
+export const load = (file: string): ObservedEdge[] => [...merged(readJsonl<ObservedEdge>(file)).values()];
+
+/** The edges in a file, kept in memory while a run adds to them. */
+export const open = (file: string) => {
+  const known = merged(readJsonl<ObservedEdge>(file));
+  let appended = false;
+  return {
+    all: (): ObservedEdge[] => [...known.values()],
+    /** True when the edge is new. */
+    record: (observation: EdgeObservation): boolean => {
+      const row: ObservedEdge = { ...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: string, routes: Set<string>): number => {
+  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/src/knowledge/errors.ts

@@ -0,0 +1,73 @@
+/** 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 };
+
+type Rule = { re: RegExp; cause: (m: RegExpMatchArray) => string; fix: (m: RegExpMatchArray) => string };
+
+const RULES: Rule[] = [
+  {
+    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: string): Explanation[] => {
+  const out: Explanation[] = [];
+  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: Explanation[]): string =>
+  list.length === 0 ? '' : ['', 'lynkeus: what this looks like', ...list.map((e) => `  ${e.match}\n    cause  ${e.cause}\n    fix    ${e.fix}`)].join('\n');

package/src/knowledge/events.ts

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readJsonl } from '../files.js';
+
+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 const normalizeEvents = (raw: unknown): AppEvent[] =>
+  (Array.isArray(raw) ? raw : []).flatMap((e) => {
+    const r = e as { name?: unknown; props?: unknown; properties?: unknown };
+    if (typeof r?.name !== 'string') return [];
+    const props = (r.props ?? r.properties) as Record<string, unknown> | undefined;
+    return [{ name: r.name, ...(props && typeof props === 'object' ? { props } : {}) }];
+  });
+
+export const drainEvents = async (device: Drainable): Promise<AppEvent[]> => {
+  try {
+    return normalizeEvents(await device.command('events', { clear: true }));
+  } catch {
+    return [];
+  }
+};
+
+export const eventsFile = (runDir: string) => path.join(runDir, 'events.jsonl');
+
+export const writeEvents = (runDir: string, events: RunEvent[]): void => {
+  if (events.length === 0) return;
+  fs.writeFileSync(eventsFile(runDir), `${events.map((e) => JSON.stringify(e)).join('\n')}\n`);
+};
+
+export const readEvents = (file: string): RunEvent[] => readJsonl<RunEvent>(file);
+
+/** Every run under `runs/` that recorded events, newest first. */
+export const eventsFiles = (runsRoot: string): string[] => {
+  const found: { file: string; mtime: number }[] = [];
+  const visit = (dir: string, depth: number) => {
+    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: string, ref: string): string | undefined => {
+  if (ref === 'last') return eventsFiles(runsRoot)[0];
+  const full = path.resolve(ref);
+  return full.endsWith('.jsonl') ? full : eventsFile(full);
+};
+
+export const describeEvents = (events: RunEvent[]): string =>
+  events.map((e) => `${String(e.step).padStart(2)} ${e.route ?? '?'}  ${e.name}${e.props ? ` ${JSON.stringify(e.props)}` : ''}`).join('\n');