lynkeus 0.2.0

package/src/knowledge/perf.ts

@@ -0,0 +1,114 @@
+import type { TraceEvent } from 'lynkeus-protocol';
+
+export type Visit = {
+  route: string;
+  at: number;
+  /** How long the screen stayed on top. */
+  ms: number;
+  requests: number;
+  requestMs: number;
+  errors: number;
+  slowest?: { method: string; path: string; ms: number };
+  /** From arriving to the end of the opening burst of requests. */
+  quietAfterMs: number;
+  stalls: number;
+};
+
+const pathOf = (url: string) => {
+  try {
+    const u = new URL(url);
+    return u.pathname + u.search;
+  } catch {
+    return url;
+  }
+};
+
+// This long with no request ends the opening burst: later polling does not count against arriving.
+const QUIET_GAP_MS = 1500;
+
+export const visitsFrom = (events: TraceEvent[]): Visit[] => {
+  const visits: Visit[] = [];
+  let current: Visit | null = null;
+  let burstEnd = 0;
+  let burstOver = false;
+  const close = (endT: number) => {
+    if (current) current.ms = Math.max(0, endT - current.at);
+  };
+  for (const e of events) {
+    if (e.kind === 'route') {
+      close(e.t);
+      current = { route: e.route ?? e.path.join('/') ?? '?', at: e.t, ms: 0, requests: 0, requestMs: 0, errors: 0, quietAfterMs: 0, stalls: 0 };
+      visits.push(current);
+      burstEnd = e.t;
+      burstOver = false;
+      continue;
+    }
+    if (!current) continue;
+    if (e.kind === 'request') {
+      current.requests += 1;
+      const ms = e.ms ?? 0;
+      current.requestMs += ms;
+      if ((e.status ?? 0) >= 400 || e.error) current.errors += 1;
+      if (!current.slowest || ms > current.slowest.ms) current.slowest = { method: e.method, path: pathOf(e.url), ms };
+      // A request event is stamped when it ends.
+      const start = e.t - ms;
+      if (!burstOver && start - burstEnd > QUIET_GAP_MS) burstOver = true;
+      if (!burstOver) {
+        burstEnd = Math.max(burstEnd, e.t);
+        current.quietAfterMs = Math.max(current.quietAfterMs, burstEnd - current.at);
+      }
+    } else if (e.kind === 'stall') {
+      current.stalls += 1;
+    }
+  }
+  const last = events[events.length - 1];
+  if (last) close(last.t);
+  return visits;
+};
+
+export type RouteSummary = {
+  route: string;
+  visits: number;
+  requests: number;
+  requestMs: number;
+  quietAfterMs: number;
+  errors: number;
+  stalls: number;
+  slowest?: Visit['slowest'];
+};
+
+/** Per route, averaged over its visits, the costliest arrival first. */
+export const summarize = (visits: Visit[]): RouteSummary[] => {
+  const by = new Map<string, RouteSummary>();
+  for (const v of visits) {
+    const s = by.get(v.route) ?? { route: v.route, visits: 0, requests: 0, requestMs: 0, quietAfterMs: 0, errors: 0, stalls: 0 };
+    s.visits += 1;
+    s.requests += v.requests;
+    s.requestMs += v.requestMs;
+    s.quietAfterMs += v.quietAfterMs;
+    s.errors += v.errors;
+    s.stalls += v.stalls;
+    if (v.slowest && (!s.slowest || v.slowest.ms > s.slowest.ms)) s.slowest = v.slowest;
+    by.set(v.route, s);
+  }
+  return [...by.values()]
+    .map((s) => ({
+      ...s,
+      requests: Math.round(s.requests / s.visits),
+      requestMs: Math.round(s.requestMs / s.visits),
+      quietAfterMs: Math.round(s.quietAfterMs / s.visits),
+    }))
+    .sort((a, b) => b.quietAfterMs - a.quietAfterMs || b.requests - a.requests);
+};
+
+export const describePerf = (summary: RouteSummary[]): string => {
+  if (summary.length === 0) return '(no screen visits in the trace yet)';
+  const lines = ['route                              visits  req/visit  req ms   quiet after  errors  stalls  slowest'];
+  for (const s of summary) {
+    const slow = s.slowest ? `${s.slowest.method} ${s.slowest.path.split('?')[0]} ${s.slowest.ms}ms` : '';
+    lines.push(
+      `${s.route.padEnd(34)} ${String(s.visits).padStart(6)}  ${String(s.requests).padStart(9)}  ${String(s.requestMs).padStart(6)}   ${String(s.quietAfterMs).padStart(9)}ms  ${String(s.errors).padStart(6)}  ${String(s.stalls).padStart(6)}  ${slow}`,
+    );
+  }
+  return lines.join('\n');
+};

package/src/knowledge/plan.ts

@@ -0,0 +1,95 @@
+/**
+ * Directions: the shortest known way from one place to another, as the
+ * controls to press. A place is a route, or a layer open over one
+ * (`Settings.Main#account-button`), named after the control that opened it
+ * because pressing that control is the only way back in. Observed edges are
+ * tried before static ones.
+ */
+import { edgeFrom, edgeTo, type ObservedEdge, splitNode } from './edges.js';
+import { vocabularyOf } from './query.js';
+import type { ScreenGraph } from './types.js';
+
+export type PlanStep = {
+  from: string;
+  to: string;
+  /** The testID to press; without one, a hint for whoever looks at the screen. */
+  press?: string;
+  hint?: string;
+  /** The step leaves a sheet or dialog open rather than changing route. */
+  opens?: string;
+  source: 'observed' | 'static';
+};
+
+type Move = { to: string; press?: string; hint?: string; opens?: string; source: 'observed' | 'static' };
+
+const movesFrom = (graph: ScreenGraph, node: string, observed: ObservedEdge[]): Move[] => {
+  const moves: Move[] = observed.map((e) => ({
+    to: edgeTo(e),
+    press: e.via.startsWith('text:') ? undefined : e.via,
+    hint: e.via.startsWith('text:') ? e.via : undefined,
+    opens: e.toLayer !== e.fromLayer ? e.toLayer : undefined,
+    source: 'observed',
+  }));
+  // Source knows routes, not what a route has open: a static edge only applies where nothing covers the screen.
+  const { route, layer } = splitNode(node);
+  if (layer !== undefined) return moves;
+  const vocabulary = vocabularyOf(graph, route, 1);
+  for (const edge of vocabulary?.navigatesTo ?? []) {
+    if (edge.confidence !== 'static' || !graph.screens[edge.to]) continue;
+    if (moves.some((m) => m.to === edge.to)) continue;
+    moves.push({
+      to: edge.to,
+      press: edge.via.kind === 'testId' ? edge.via.testId : undefined,
+      hint:
+        edge.via.kind === 'dynamicTestId'
+          ? `testId built at runtime: ${edge.via.expression}`
+          : edge.via.kind === 'unknown'
+            ? `navigated from ${edge.from}:${edge.line} without a visible trigger`
+            : undefined,
+      source: 'static',
+    });
+  }
+  return moves;
+};
+
+/** Breadth-first over places. A bare route as the destination accepts arriving with something open over it. */
+export const plan = (graph: ScreenGraph, from: string, to: string, observed: ObservedEdge[] = [], maxDepth = 6): PlanStep[] | null => {
+  const byNode = new Map<string, ObservedEdge[]>();
+  for (const e of observed) {
+    const list = byNode.get(edgeFrom(e));
+    if (list) list.push(e);
+    else byNode.set(edgeFrom(e), [e]);
+  }
+  const arrived = (node: string) => node === to || splitNode(node).route === to;
+  if (arrived(from)) return [];
+  const previous = new Map<string, PlanStep>();
+  const queue: string[] = [from];
+  const depth = new Map<string, number>([[from, 0]]);
+  while (queue.length) {
+    const node = queue.shift()!;
+    const d = depth.get(node) ?? 0;
+    if (d >= maxDepth) continue;
+    for (const move of movesFrom(graph, node, byNode.get(node) ?? [])) {
+      if (previous.has(move.to) || move.to === from) continue;
+      previous.set(move.to, { from: node, to: move.to, press: move.press, hint: move.hint, opens: move.opens, source: move.source });
+      depth.set(move.to, d + 1);
+      if (arrived(move.to)) {
+        const steps: PlanStep[] = [];
+        for (let at: string | undefined = move.to; at && at !== from; at = previous.get(at)?.from) {
+          steps.unshift(previous.get(at)!);
+        }
+        return steps;
+      }
+      queue.push(move.to);
+    }
+  }
+  return null;
+};
+
+export const describePlan = (steps: PlanStep[]): string =>
+  steps
+    .map(
+      (s, i) =>
+        `${i + 1}. ${s.from} → ${s.to}   ${s.press ? `press #${s.press}` : `(${s.hint ?? 'look at the screen'})`}${s.opens ? '  (opens a layer)' : ''}   [${s.source}]`,
+    )
+    .join('\n');

package/src/knowledge/problems.ts

@@ -0,0 +1,12 @@
+import type { RequestRecord, Screen } from 'lynkeus-protocol';
+
+export const withoutHost = (url: string) => url.replace(/^https?:\/\/[^/]+/, '');
+
+export const pathOf = (url: string) => withoutHost(url).split('?')[0]!;
+
+/** What a person would call broken on a screen: nothing on it, the app's own error copy, a request that failed. */
+export const problemsOf = (screen: Screen, requests: RequestRecord[], errorCopy?: RegExp): string[] => [
+  ...(screen.elements.length === 0 ? ['blank screen'] : []),
+  ...screen.elements.flatMap((e) => (errorCopy && e.kind === 'text' && e.text && errorCopy.test(e.text) ? [`copy: ${e.text.slice(0, 80)}`] : [])),
+  ...requests.filter((r) => (r.status ?? 0) >= 500 || r.error).map((r) => `${r.status ?? 'ERR'} ${r.method} ${withoutHost(r.url)}`),
+];

package/src/knowledge/query.ts

@@ -0,0 +1,146 @@
+import { edgeFrom, type ObservedEdge } from './edges.js';
+import type { NavigationEdge, RouteName, ScreenGraph, Selector, SourcePath } from './types.js';
+
+// Bounded: through barrels an unbounded closure reaches most of the app and makes every screen look the same.
+const closureOf = (graph: ScreenGraph, entry: SourcePath, maxDepth = 2): Set<SourcePath> => {
+  const seen = new Set<SourcePath>([entry]);
+  let frontier: SourcePath[] = [entry];
+
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const next: SourcePath[] = [];
+    for (const file of frontier) {
+      for (const imported of graph.files[file]?.imports ?? []) {
+        if (seen.has(imported)) continue;
+        seen.add(imported);
+        next.push(imported);
+      }
+    }
+    if (next.length === 0) break;
+    frontier = next;
+  }
+
+  return seen;
+};
+
+export type Vocabulary = {
+  route: RouteName;
+  file: SourcePath | null;
+  selectors: (Selector & { from: SourcePath })[];
+  navigatesTo: (NavigationEdge & { from: SourcePath })[];
+  filesConsidered: number;
+};
+
+/**
+ * A weak guess at what a screen offers, from its file and what it imports
+ * directly. One hop only: through barrels the whole component library is two
+ * hops from every screen. The running app is the ground truth.
+ */
+export const vocabularyOf = (graph: ScreenGraph, route: RouteName, maxDepth = 1): Vocabulary | null => {
+  const screen = graph.screens[route];
+  if (!screen) return null;
+  if (!screen.file) {
+    return { route, file: null, selectors: [], navigatesTo: [], filesConsidered: 0 };
+  }
+
+  const closure = closureOf(graph, screen.file, maxDepth);
+  const selectors: (Selector & { from: SourcePath })[] = [];
+  const navigatesTo: (NavigationEdge & { from: SourcePath })[] = [];
+
+  for (const file of closure) {
+    const facts = graph.files[file];
+    if (!facts) continue;
+    for (const selector of facts.selectors) selectors.push({ ...selector, from: file });
+    for (const edge of facts.navigates) navigatesTo.push({ ...edge, from: file });
+  }
+
+  return { route, file: screen.file, selectors, navigatesTo, filesConsidered: closure.size };
+};
+
+export type Approach = {
+  via: string;
+  source: 'static' | 'observed';
+  /** The file that declares it, or the place it was walked from. */
+  from: string;
+  seen?: number;
+};
+
+/** The controls that lead to a route, the walked ones first: they beat an inference from source. */
+export const pathsTo = (graph: ScreenGraph, destination: RouteName, observed: ObservedEdge[] = []): Approach[] => {
+  const approaches: Approach[] = observed
+    .filter((edge) => edge.to === destination)
+    .map((edge) => ({
+      via: edge.via,
+      source: 'observed',
+      from: edgeFrom(edge),
+      seen: edge.seen,
+    }));
+
+  for (const [file, facts] of Object.entries(graph.files)) {
+    for (const edge of facts.navigates) {
+      if (edge.to !== destination || edge.confidence !== 'static') continue;
+      if (edge.via.kind === 'unknown') continue;
+
+      const via = edge.via.kind === 'testId' ? edge.via.testId : `<runtime: ${edge.via.expression}>`;
+      if (approaches.some((a) => a.via === via)) continue;
+      approaches.push({ via, source: 'static', from: file });
+    }
+  }
+
+  return approaches;
+};
+
+export type Affected = { route: RouteName; distance: number; via: SourcePath; through: SourcePath[] };
+
+/** Screens a change can reach, nearest first; `distance` is how many imports separate the screen's file from a changed one. */
+export const screensAffectedBy = (graph: ScreenGraph, changedFiles: SourcePath[], maxDepth = 4): Affected[] => {
+  const importedBy = new Map<SourcePath, SourcePath[]>();
+  for (const [file, facts] of Object.entries(graph.files)) {
+    for (const target of facts.imports) {
+      const list = importedBy.get(target);
+      if (list) list.push(file);
+      else importedBy.set(target, [file]);
+    }
+  }
+
+  const throughBarrel = new Map<SourcePath, SourcePath[]>();
+  for (const [file, facts] of Object.entries(graph.files)) {
+    for (const barrel of facts.barrels ?? []) {
+      const list = throughBarrel.get(barrel);
+      if (list) list.push(file);
+      else throughBarrel.set(barrel, [file]);
+    }
+  }
+
+  type Hop = { distance: number; via: SourcePath; through: SourcePath[] };
+  const reached = new Map<SourcePath, Hop>();
+  let frontier: SourcePath[] = [];
+  for (const f of changedFiles) {
+    if (!reached.has(f)) {
+      reached.set(f, { distance: 0, via: f, through: [] });
+      frontier.push(f);
+    }
+  }
+  for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+    const next: SourcePath[] = [];
+    for (const file of frontier) {
+      const hop = reached.get(file)!;
+      // Taking a name through a barrel depends on the barrel only when the barrel itself changed.
+      const dependents = hop.distance === 0 ? [...(importedBy.get(file) ?? []), ...(throughBarrel.get(file) ?? [])] : (importedBy.get(file) ?? []);
+      for (const dependent of dependents) {
+        if (reached.has(dependent)) continue;
+        reached.set(dependent, { distance: depth, via: hop.via, through: [...hop.through, file] });
+        next.push(dependent);
+      }
+    }
+    frontier = next;
+  }
+
+  const affected: Affected[] = [];
+  for (const screen of Object.values(graph.screens)) {
+    if (!screen.file) continue;
+    const hop = reached.get(screen.file);
+    if (!hop) continue;
+    affected.push({ route: screen.route, distance: hop.distance, via: hop.via, through: hop.through.slice(1) });
+  }
+  return affected.sort((a, b) => a.distance - b.distance || a.route.localeCompare(b.route));
+};

package/src/knowledge/route-params.ts

@@ -0,0 +1,39 @@
+/**
+ * Which routes open without parameters, read from the app's React Navigation
+ * `ParamList` type: `undefined`, or an object whose keys are all optional.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export type RouteParamsInfo = { route: string; free: boolean; shape: string };
+
+export const readRouteParams = (root: string, paramsFile = 'app/navigation/types.d.ts'): RouteParamsInfo[] => {
+  const file = path.join(root, paramsFile);
+  if (!fs.existsSync(file)) return [];
+  const text = fs.readFileSync(file, 'utf8');
+  const start = Math.max(0, text.search(/\b\w*ParamList\b|ScreenRouteParams/));
+  const out = new Map<string, RouteParamsInfo>();
+  const entry = /'([A-Z][\w.]+)':\s*/g;
+  entry.lastIndex = start;
+  for (const match of text.matchAll(entry)) {
+    const route = match[1]!;
+    let i = match.index + match[0].length;
+    let shape = '';
+    if (text.startsWith('undefined', i)) {
+      shape = 'undefined';
+    } else if (text[i] === '{') {
+      let depth = 0;
+      const from = i;
+      for (; i < text.length; i++) {
+        if (text[i] === '{') depth++;
+        else if (text[i] === '}' && --depth === 0) break;
+      }
+      shape = text.slice(from, i + 1);
+    } else {
+      shape = text.slice(i, text.indexOf('\n', i)).trim();
+    }
+    const free = shape === 'undefined' || (shape.startsWith('{') && !/^\s*\w+\s*:/m.test(shape.slice(1, -1).replace(/\{[^}]*\}/g, '')));
+    if (!out.has(route)) out.set(route, { route, free, shape: shape.replace(/\s+/g, ' ').slice(0, 120) });
+  }
+  return [...out.values()];
+};

package/src/knowledge/screens.ts

@@ -0,0 +1,139 @@
+/**
+ * The structure of each route the last time it was read, under
+ * .lynkeus/screens/, and in changes.jsonl every testID that appeared,
+ * disappeared or moved since: a suite that never asserts on an element still
+ * tells you the day it vanished.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { Screen } from 'lynkeus-protocol';
+
+import { diffScreens } from '../flow/artifacts.js';
+import { appendJsonl, readJsonl, today } from '../files.js';
+
+type Frame = { x: number; y: number; w: number; h: number };
+type Stored = { route: string; path: string[]; seen: number; date: string; elements: Screen['elements']; frames?: Record<string, Frame> };
+
+export type ScreenChange = { route: string; date: string; added: string[]; removed: string[]; changedText: string[]; moved?: string[] };
+
+// Sub-pixel rounding and font hinting move an element a point or two without any layout change.
+const GEOMETRY_TOLERANCE = 4;
+
+const presented = (e: Screen['elements'][number]) => !e.hidden || e.hidden === 'inert';
+
+const framesOf = (screen: Screen): Record<string, Frame> => {
+  const out: Record<string, Frame> = {};
+  for (const e of screen.elements.filter(presented)) {
+    if (!e.testId || !e.frame || out[e.testId]) continue;
+    out[e.testId] = { x: Math.round(e.frame.x), y: Math.round(e.frame.y), w: Math.round(e.frame.w), h: Math.round(e.frame.h) };
+  }
+  return out;
+};
+
+export const diffGeometry = (before: Record<string, Frame>, after: Record<string, Frame>, tolerance = GEOMETRY_TOLERANCE): string[] => {
+  const lines: string[] = [];
+  for (const [id, a] of Object.entries(after)) {
+    const b = before[id];
+    if (!b) continue;
+    const moved = Math.abs(a.x - b.x) > tolerance || Math.abs(a.y - b.y) > tolerance;
+    const resized = Math.abs(a.w - b.w) > tolerance || Math.abs(a.h - b.h) > tolerance;
+    const collapsed = (a.w === 0 || a.h === 0) && b.w > 0 && b.h > 0;
+    if (collapsed) lines.push(`#${id} collapsed to ${a.w}×${a.h} (was ${b.w}×${b.h})`);
+    else if (moved && resized) lines.push(`#${id} moved (${b.x},${b.y})→(${a.x},${a.y}) and resized ${b.w}×${b.h}→${a.w}×${a.h}`);
+    else if (moved) lines.push(`#${id} moved (${b.x},${b.y})→(${a.x},${a.y})`);
+    else if (resized) lines.push(`#${id} resized ${b.w}×${b.h}→${a.w}×${a.h}`);
+  }
+  return lines;
+};
+
+const dirOf = (lynkeusDir: string) => path.join(lynkeusDir, 'screens');
+const fileOf = (lynkeusDir: string, route: string) => path.join(dirOf(lynkeusDir), `${route.replace(/[^\w.-]/g, '_')}.json`);
+const changesFile = (lynkeusDir: string) => path.join(dirOf(lynkeusDir), 'changes.jsonl');
+
+const strip = (screen: Screen): Screen['elements'] =>
+  screen.elements.filter(presented).map((e) => {
+    const { frame: _frame, ...rest } = e as Screen['elements'][number] & { frame?: unknown };
+    return rest as Screen['elements'][number];
+  });
+
+const label = (e: Screen['elements'][number]) => `${e.kind}${e.testId ? ` #${e.testId}` : ''}${e.text ? ` ${JSON.stringify(e.text.slice(0, 60))}` : ''}`;
+
+/** Stores the screen under its route and returns what changed since the previous read. */
+export const record = (lynkeusDir: string, screen: Screen): ScreenChange | null => {
+  if (!screen.route) return null;
+  fs.mkdirSync(dirOf(lynkeusDir), { recursive: true });
+  const file = fileOf(lynkeusDir, screen.route);
+  const date = today();
+  const elements = strip(screen);
+  let previous: Stored | null = null;
+  try {
+    previous = JSON.parse(fs.readFileSync(file, 'utf8')) as Stored;
+  } catch {}
+  const frames = framesOf(screen);
+  const next: Stored = { route: screen.route, path: screen.path, seen: (previous?.seen ?? 0) + 1, date, elements, frames };
+  fs.writeFileSync(file, JSON.stringify(next, null, 1));
+  if (!previous) return null;
+  const diff = diffScreens({ ...screen, elements: previous.elements }, { ...screen, elements });
+  // Texts carry values that change every run; only a testID appearing or disappearing is worth a line.
+  const added = diff.added.filter((e) => e.testId).map(label);
+  const removed = diff.removed.filter((e) => e.testId).map(label);
+  const moved = previous.frames ? diffGeometry(previous.frames, frames) : [];
+  if (added.length === 0 && removed.length === 0 && moved.length === 0) return null;
+  const change: ScreenChange = {
+    route: screen.route,
+    date,
+    added,
+    removed,
+    moved,
+    changedText: diff.changedText.map((c) => `#${c.after.testId}: ${JSON.stringify(c.before.text ?? '')} → ${JSON.stringify(c.after.text ?? '')}`).slice(0, 10),
+  };
+  appendJsonl(changesFile(lynkeusDir), change);
+  return change;
+};
+
+export type Observed = {
+  route: string;
+  path: string[];
+  seen: number;
+  date: string;
+  testIds: string[];
+};
+
+/** What runs have seen, by route: the routes and interpolated testIDs a static parser cannot find. */
+export const observed = (lynkeusDir: string): Map<string, Observed> => {
+  const out = new Map<string, Observed>();
+  let files: string[] = [];
+  try {
+    files = fs.readdirSync(dirOf(lynkeusDir)).filter((f) => f.endsWith('.json'));
+  } catch {
+    return out;
+  }
+  for (const file of files) {
+    let stored: Stored;
+    try {
+      stored = JSON.parse(fs.readFileSync(path.join(dirOf(lynkeusDir), file), 'utf8')) as Stored;
+    } catch {
+      continue;
+    }
+    if (!stored.route) continue;
+    const testIds: string[] = [];
+    for (const e of stored.elements ?? []) {
+      if (!e.testId || e.hidden) continue;
+      if (!testIds.includes(e.testId)) testIds.push(e.testId);
+    }
+    out.set(stored.route, { route: stored.route, path: stored.path ?? [], seen: stored.seen ?? 1, date: stored.date, testIds });
+  }
+  return out;
+};
+
+export const changes = (lynkeusDir: string, last = 50): ScreenChange[] => readJsonl<ScreenChange>(changesFile(lynkeusDir)).slice(-last);
+
+export const describeChange = (c: ScreenChange): string =>
+  [
+    `${c.date}  ${c.route}`,
+    ...c.added.map((a) => `    + ${a}`),
+    ...c.removed.map((r) => `    - ${r}`),
+    ...(c.moved ?? []).map((m) => `    ⇢ ${m}`),
+    ...c.changedText.map((t) => `    ~ ${t}`),
+  ].join('\n');

package/src/knowledge/tree.ts

@@ -0,0 +1,66 @@
+/**
+ * The screen as nested lines of meaning (kinds, labels, testIDs, values,
+ * states) and no geometry: a spacing tweak changes nothing, a renamed heading
+ * or a lost button is a changed line. Diffed like code.
+ */
+import type { Element, Screen } from 'lynkeus-protocol';
+
+const quote = (s: string) => JSON.stringify(s);
+
+const node = (e: Element): string => {
+  const parts: string[] = [e.kind];
+  const label = e.text ?? e.accessibilityLabel;
+  if (label) parts.push(quote(label.length > 80 ? `${label.slice(0, 77)}…` : label));
+  if (e.testId) parts.push(`#${e.testId}`);
+  if (e.value !== undefined && e.value !== '') parts.push(`value=${quote(e.value)}`);
+  if (e.placeholder) parts.push(`placeholder=${quote(e.placeholder)}`);
+  const state = [!e.enabled ? 'disabled' : '', e.covered ? 'covered' : '', e.hidden ?? '', e.focused ? 'focused' : ''].filter(Boolean);
+  if (state.length) parts.push(`[${state.join(' ')}]`);
+  return parts.join(' ');
+};
+
+const meaningful = (e: Element): boolean => e.kind !== 'view' || e.accessibilityLabel !== undefined || e.testId !== undefined;
+
+export const screenTree = (screen: Screen): string => {
+  const lines = [`- screen ${screen.route ?? '?'}${screen.path.length > 1 ? ` (${screen.path.join(' > ')})` : ''}`];
+  // Relative to the nearest listed ancestor, so the layout views left out leave no gaps.
+  const level = new Map<number, number>();
+  for (const e of screen.elements) {
+    const parentLevel = e.parent !== undefined && e.parent >= 0 ? (level.get(e.parent) ?? 0) : 0;
+    if (!meaningful(e)) {
+      level.set(e.i, parentLevel);
+      continue;
+    }
+    const mine = parentLevel + 1;
+    level.set(e.i, mine);
+    lines.push(`${'  '.repeat(mine)}- ${node(e)}`);
+  }
+  return `${lines.join('\n')}\n`;
+};
+
+export type TreeDiff = { added: string[]; removed: string[]; same: number };
+
+/** The lines only one side has. */
+export const diffTrees = (before: string, after: string): TreeDiff => {
+  const a = before.split('\n').filter(Boolean);
+  const b = after.split('\n').filter(Boolean);
+  const countA = new Map<string, number>();
+  for (const l of a) countA.set(l, (countA.get(l) ?? 0) + 1);
+  const added: string[] = [];
+  let same = 0;
+  for (const l of b) {
+    const n = countA.get(l) ?? 0;
+    if (n > 0) {
+      countA.set(l, n - 1);
+      same += 1;
+    } else added.push(l);
+  }
+  const removed: string[] = [];
+  for (const [l, n] of countA) for (let i = 0; i < n; i++) removed.push(l);
+  return { added, removed, same };
+};
+
+export const describeTreeDiff = (d: TreeDiff): string => {
+  if (!d.added.length && !d.removed.length) return '  (the tree did not change)';
+  return [...d.removed.map((l) => `- ${l.trim()}`), ...d.added.map((l) => `+ ${l.trim()}`)].map((l) => `  ${l}`).join('\n');
+};

package/src/knowledge/types.ts

@@ -0,0 +1,60 @@
+/**
+ * What lynkeus reads from an app's source. Facts are kept per file and
+ * attributed to screens by traversal: most testIDs and navigations live in
+ * shared components, so attributing them at extraction would always miss some.
+ */
+
+/** As declared to the navigator, e.g. `Settings.Profile`. */
+export type RouteName = string;
+
+/** Relative to the app's root. */
+export type SourcePath = string;
+
+/** A testID written as a literal; one built at runtime is only found on the device. */
+export type Selector = { id: string; line: number };
+
+/** What the user touches to cause a navigation. */
+export type NavigationTrigger =
+  | { kind: 'testId'; testId: string }
+  /** The element has a testID built at runtime. */
+  | { kind: 'dynamicTestId'; expression: string }
+  /** Nothing to attribute it to: conditional routing, effects, deep links. */
+  | { kind: 'unknown' };
+
+export type NavigationEdge = {
+  /** The route when it is a literal, otherwise the source expression. */
+  to: string;
+  line: number;
+  confidence: 'static' | 'dynamic';
+  via: NavigationTrigger;
+  /** `element` when the call sits in the element's own handler, `handler` when it was reached through a named function. */
+  linkage?: 'element' | 'handler';
+};
+
+export type FileFacts = {
+  selectors: Selector[];
+  navigates: NavigationEdge[];
+  /** First-party imports; a name imported through a barrel points at the file that defines it. */
+  imports: SourcePath[];
+  /** The barrels those names came through: a dependency only when the barrel itself changes. */
+  barrels?: SourcePath[];
+};
+
+export type ScreenNode = {
+  route: RouteName;
+  /** The component bound in the navigator. */
+  component: string;
+  /** Null when the component could not be resolved to a file. */
+  file: SourcePath | null;
+  declaredIn: SourcePath;
+};
+
+export type ScreenGraph = {
+  app: string;
+  root: string;
+  extractedAt: string;
+  screens: Record<RouteName, ScreenNode>;
+  files: Record<SourcePath, FileFacts>;
+  /** What could not be read, so the graph is never silently wrong. */
+  warnings: string[];
+};