lynkeus 0.2.0

package/src/knowledge/extract.ts

@@ -0,0 +1,379 @@
+/**
+ * The screen graph of a React Navigation app, read from its source. Routes are
+ * declared on the navigator and implemented elsewhere, so a component is
+ * resolved through the type checker, not by file name. Most navigations live in
+ * shared components rather than screen files, so facts are recorded per file
+ * and attributed to screens later through the import graph.
+ */
+import path from 'node:path';
+import { Node, Project, SyntaxKind, type JsxAttribute, type SourceFile } from 'ts-morph';
+
+import { packageName } from '../config.js';
+
+import type { FileFacts, NavigationEdge, NavigationTrigger, ScreenGraph, ScreenNode, Selector, SourcePath } from './types.js';
+
+// Only on a receiver that looks like the navigation object: `push` and `replace` are also Array and String methods.
+const NAVIGATION_METHODS = new Set(['navigate', 'push', 'replace', 'reset']);
+
+const isNavigationReceiver = (text: string): boolean => /(^|\.)nav(igation)?$/i.test(text.trim());
+
+type ExtractOptions = {
+  root: string;
+  navigatorGlobs?: string[];
+  /** First-party source, relative to the root. */
+  sourceDir?: string;
+};
+
+export const extractScreenGraph = ({ root, navigatorGlobs = ['app/navigation/**/*.tsx'], sourceDir = 'app' }: ExtractOptions): ScreenGraph => {
+  const warnings: string[] = [];
+  const project = new Project({
+    tsConfigFilePath: path.join(root, 'tsconfig.json'),
+    skipAddingFilesFromTsConfig: false,
+  });
+
+  const rel = (file: SourceFile | string): SourcePath => path.relative(root, typeof file === 'string' ? file : file.getFilePath());
+
+  const sourceRoot = path.join(root, sourceDir);
+  const firstParty = project
+    .getSourceFiles()
+    .filter((f) => !f.getFilePath().includes('/node_modules/'))
+    .filter((f) => f.getFilePath().startsWith(sourceRoot));
+
+  const navigators = project.getSourceFiles(navigatorGlobs.map((g) => path.join(root, g))).filter((f) => !f.getFilePath().includes('/node_modules/'));
+
+  if (navigators.length === 0) {
+    warnings.push(`No navigator files matched ${navigatorGlobs.join(', ')}`);
+  }
+
+  const screens: Record<string, ScreenNode> = {};
+  for (const navigator of navigators) {
+    for (const { route, component } of screenDeclarations(navigator)) {
+      if (!component) {
+        warnings.push(`${rel(navigator)}: route "${route}" has no resolvable component`);
+        continue;
+      }
+
+      if (screens[route]) {
+        warnings.push(`Route "${route}" declared more than once; keeping the first`);
+        continue;
+      }
+
+      const file = resolveComponentFile(navigator, component);
+      if (!file) {
+        warnings.push(`${rel(navigator)}: "${route}" -> <${component}> unresolved to a file`);
+      }
+
+      screens[route] = {
+        route,
+        component,
+        file: file ? rel(file) : null,
+        declaredIn: rel(navigator),
+      };
+    }
+  }
+
+  const files: Record<SourcePath, FileFacts> = {};
+  for (const source of firstParty) {
+    files[rel(source)] = {
+      selectors: collectSelectors(source),
+      navigates: collectNavigationEdges(source),
+      ...collectImports(source, root),
+    };
+  }
+
+  return {
+    app: packageName(root),
+    root,
+    extractedAt: new Date().toISOString(),
+    screens,
+    files,
+    warnings,
+  };
+};
+
+type ScreenElement = { attr: (name: string) => JsxAttribute | undefined };
+
+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 const screenDeclarations = (source: SourceFile): ScreenDeclaration[] => {
+  const out: ScreenDeclaration[] = [];
+  for (const element of findScreenElements(source)) {
+    const route = stringAttribute(element.attr('name'));
+    if (route) out.push({ route, component: identifierAttribute(element.attr('component')) });
+  }
+  for (const prop of source.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
+    const value = prop.getInitializer();
+    if (!value || !Node.isObjectLiteralExpression(value)) continue;
+    const screen = value.getProperty('screen');
+    if (!screen || !Node.isPropertyAssignment(screen)) continue;
+    const nameNode = prop.getNameNode();
+    const route = Node.isStringLiteral(nameNode) ? nameNode.getLiteralValue() : Node.isIdentifier(nameNode) ? nameNode.getText() : null;
+    if (!route) continue;
+    // `params: { screen, params }` is React Navigation's nested-navigate payload, never a route.
+    if (route === 'params' || route === 'initialParams') continue;
+    const target = screen.getInitializer();
+    if (!target) continue;
+    if (Node.isCallExpression(target)) continue; // a nested navigator, not a screen
+    // `params: { screen: 'X' }` is a navigate() payload naming a route, not a declaration.
+    if (Node.isStringLiteral(target) || Node.isNoSubstitutionTemplateLiteral(target)) continue;
+    out.push({ route, component: Node.isIdentifier(target) ? target.getText() : null });
+  }
+  return out;
+};
+
+/** `<Stack.Screen …>` / `<Tab.Screen …>`, self-closing or not. */
+const findScreenElements = (source: SourceFile): ScreenElement[] => {
+  const elements: ScreenElement[] = [];
+
+  const consider = (tagName: string, attributes: JsxAttribute[]) => {
+    if (!tagName.endsWith('.Screen') && tagName !== 'Screen') return;
+    elements.push({ attr: (name) => attributes.find((a) => a.getNameNode().getText() === name) });
+  };
+
+  for (const node of source.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement)) {
+    consider(node.getTagNameNode().getText(), node.getAttributes().filter(Node.isJsxAttribute));
+  }
+  for (const node of source.getDescendantsOfKind(SyntaxKind.JsxOpeningElement)) {
+    consider(node.getTagNameNode().getText(), node.getAttributes().filter(Node.isJsxAttribute));
+  }
+
+  return elements;
+};
+
+const stringAttribute = (attr: JsxAttribute | undefined): string | null => {
+  const initializer = attr?.getInitializer();
+  if (!initializer) return null;
+  if (Node.isStringLiteral(initializer)) return initializer.getLiteralValue();
+  if (Node.isJsxExpression(initializer)) {
+    const expression = initializer.getExpression();
+    if (expression && Node.isStringLiteral(expression)) return expression.getLiteralValue();
+  }
+  return null;
+};
+
+const identifierAttribute = (attr: JsxAttribute | undefined): string | null => {
+  const initializer = attr?.getInitializer();
+  if (!initializer || !Node.isJsxExpression(initializer)) return null;
+  const expression = initializer.getExpression();
+  return expression && Node.isIdentifier(expression) ? expression.getText() : null;
+};
+
+const resolveComponentFile = (navigator: SourceFile, componentName: string): SourceFile | null => {
+  const identifier = navigator.getDescendantsOfKind(SyntaxKind.Identifier).find((id) => id.getText() === componentName);
+  if (!identifier) return null;
+
+  for (const definition of identifier.getDefinitionNodes()) {
+    const file = definition.getSourceFile();
+    if (file.getFilePath().includes('/node_modules/')) continue;
+    // A barrel re-export resolves to the export declaration itself; keep walking.
+    if (Node.isExportSpecifier(definition) || Node.isExportDeclaration(definition)) continue;
+    return file;
+  }
+  return null;
+};
+
+const collectSelectors = (source: SourceFile): Selector[] => {
+  const selectors: Selector[] = [];
+  for (const attr of source.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+    if (attr.getNameNode().getText() !== 'testID') continue;
+    const id = stringAttribute(attr);
+    if (!id) continue; // dynamic testID: the agent discovers it at runtime instead
+    selectors.push({ id, line: attr.getStartLineNumber() });
+  }
+  return selectors;
+};
+
+const collectNavigationEdges = (source: SourceFile): NavigationEdge[] => {
+  const handlerTriggers = mapHandlersToTriggers(source);
+  const edges: NavigationEdge[] = [];
+
+  for (const call of source.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    if (!Node.isPropertyAccessExpression(callee)) continue;
+    if (!NAVIGATION_METHODS.has(callee.getNameNode().getText())) continue;
+    if (!isNavigationReceiver(callee.getExpression().getText())) continue;
+
+    const target = call.getArguments()[0];
+    if (!target) continue;
+
+    const trigger = triggerFor(call, handlerTriggers);
+    edges.push({
+      ...(Node.isStringLiteral(target)
+        ? { to: target.getLiteralValue(), confidence: 'static' as const }
+        : {
+            to: target.getText().replace(/\s+/g, ' ').slice(0, 120),
+            confidence: 'dynamic' as const,
+          }),
+      line: call.getStartLineNumber(),
+      via: trigger.via,
+      ...(trigger.linkage ? { linkage: trigger.linkage } : {}),
+    });
+  }
+  return edges;
+};
+
+const testIdOfElementOwning = (attribute: Node): NavigationTrigger | null => {
+  const element = attribute.getFirstAncestor((a) => Node.isJsxSelfClosingElement(a) || Node.isJsxOpeningElement(a));
+  if (!element) return null;
+
+  const attributes = (Node.isJsxSelfClosingElement(element) || Node.isJsxOpeningElement(element) ? element.getAttributes() : []).filter(Node.isJsxAttribute);
+
+  const testId = attributes.find((a) => a.getNameNode().getText() === 'testID');
+  if (!testId) return null;
+
+  const literal = stringAttribute(testId);
+  if (literal) return { kind: 'testId', testId: literal };
+
+  // Assembled at runtime (a list row keyed by item, a prop passed down): the device resolves it.
+  const initializer = testId.getInitializer();
+  return {
+    kind: 'dynamicTestId',
+    expression: (initializer?.getText() ?? '').replace(/\s+/g, ' ').slice(0, 80),
+  };
+};
+
+// Separate from the one above: `getFirstAncestorByKind` does not match the node itself, so given an attribute it would look past it.
+const owningElementTestId = (node: Node): NavigationTrigger | null => {
+  const attribute = node.getFirstAncestorByKind(SyntaxKind.JsxAttribute);
+  return attribute ? testIdOfElementOwning(attribute) : null;
+};
+
+/** `onPress={goToProfile}` on an element with `testID="profile-button"`: the handler's name to that testID, once per file. */
+const mapHandlersToTriggers = (source: SourceFile): Map<string, NavigationTrigger> => {
+  const handlers = new Map<string, NavigationTrigger>();
+
+  for (const attribute of source.getDescendantsOfKind(SyntaxKind.JsxAttribute)) {
+    const initializer = attribute.getInitializer();
+    if (!initializer || !Node.isJsxExpression(initializer)) continue;
+
+    const expression = initializer.getExpression();
+    if (!expression || !Node.isIdentifier(expression)) continue;
+
+    const trigger = testIdOfElementOwning(attribute);
+    if (trigger) handlers.set(expression.getText(), trigger);
+  }
+
+  return handlers;
+};
+
+const triggerFor = (call: Node, handlers: Map<string, NavigationTrigger>): { via: NavigationTrigger; linkage?: 'element' | 'handler' } => {
+  const direct = owningElementTestId(call);
+  if (direct) return { via: direct, linkage: 'element' };
+
+  const declaration = call.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
+  const viaHandler = declaration && handlers.get(declaration.getName());
+  if (viaHandler) return { via: viaHandler, linkage: 'handler' };
+
+  return { via: { kind: 'unknown' } };
+};
+
+const localExports = new WeakMap<SourceFile, Set<string>>();
+
+// The names a file defines itself, read from its syntax: no type checker, so a
+// whole app resolves in the time it takes to parse it.
+const exportedHere = (source: SourceFile): Set<string> => {
+  const known = localExports.get(source);
+  if (known) return known;
+  const names = new Set<string>();
+  for (const statement of source.getStatements()) {
+    if (Node.isExportAssignment(statement)) names.add('default');
+    if (Node.isExportDeclaration(statement)) {
+      if (!statement.getModuleSpecifier()) for (const spec of statement.getNamedExports()) names.add(spec.getAliasNode()?.getText() ?? spec.getName());
+      continue;
+    }
+    if (!Node.isExportable(statement) || !statement.isExported()) continue;
+    if (statement.isDefaultExport()) names.add('default');
+    if (Node.isVariableStatement(statement)) for (const d of statement.getDeclarations()) names.add(d.getName());
+    else if (Node.hasName(statement)) names.add(statement.getName());
+  }
+  localExports.set(source, names);
+  return names;
+};
+
+type ReExport = { target: SourceFile; namespace?: string; names?: Map<string, string> };
+const reExports = new WeakMap<SourceFile, ReExport[]>();
+
+const reExportsOf = (source: SourceFile): ReExport[] => {
+  const known = reExports.get(source);
+  if (known) return known;
+  const list: ReExport[] = [];
+  for (const declaration of source.getExportDeclarations()) {
+    const target = declaration.getModuleSpecifierSourceFile();
+    if (!target || target.getFilePath().includes('/node_modules/')) continue;
+    const namespace = declaration.getNamespaceExport()?.getName();
+    const named = declaration.getNamedExports();
+    list.push({
+      target,
+      namespace,
+      names: named.length ? new Map(named.map((spec) => [spec.getAliasNode()?.getText() ?? spec.getName(), spec.getName()])) : undefined,
+    });
+  }
+  reExports.set(source, list);
+  return list;
+};
+
+const defined = new WeakMap<SourceFile, Map<string, SourceFile | undefined>>();
+
+/** The file that defines `name`, following re-exports from `source`; undefined when it cannot be told. */
+const definingFile = (source: SourceFile, name: string, seen = new Set<SourceFile>()): SourceFile | undefined => {
+  const memo = defined.get(source) ?? new Map<string, SourceFile | undefined>();
+  defined.set(source, memo);
+  if (memo.has(name)) return memo.get(name);
+  if (seen.has(source)) return undefined;
+  seen.add(source);
+  const find = (): SourceFile | undefined => {
+    if (exportedHere(source).has(name)) return source;
+    for (const { target, namespace, names } of reExportsOf(source)) {
+      if (namespace !== undefined) {
+        if (namespace === name) return target;
+        continue;
+      }
+      if (!names) {
+        const found = definingFile(target, name, seen);
+        if (found) return found;
+        continue;
+      }
+      const original = names.get(name);
+      if (original !== undefined) return definingFile(target, original, seen) ?? target;
+    }
+    return undefined;
+  };
+  const found = find();
+  memo.set(name, found);
+  return found;
+};
+
+/**
+ * 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 const collectImports = (source: SourceFile, root: string): { imports: SourcePath[]; barrels: SourcePath[] } => {
+  const imports = new Set<SourcePath>();
+  const barrels = new Set<SourcePath>();
+  const own = (file: SourceFile | undefined): file is SourceFile => !!file && !file.getFilePath().includes('/node_modules/');
+  const relative = (file: SourceFile) => path.relative(root, file.getFilePath());
+
+  for (const declaration of source.getImportDeclarations()) {
+    const target = declaration.getModuleSpecifierSourceFile();
+    if (!own(target)) continue;
+    const named = declaration.getNamedImports();
+    if (named.length === 0 || declaration.getDefaultImport() || declaration.getNamespaceImport()) imports.add(relative(target));
+    for (const spec of named) {
+      const defined = definingFile(target, spec.getName());
+      if (!defined || defined === target) imports.add(relative(target));
+      else {
+        imports.add(relative(defined));
+        barrels.add(relative(target));
+      }
+    }
+  }
+  for (const declaration of source.getExportDeclarations()) {
+    const target = declaration.getModuleSpecifierSourceFile();
+    if (own(target)) imports.add(relative(target));
+  }
+
+  return { imports: [...imports], barrels: [...barrels].filter((b) => !imports.has(b)) };
+};

package/src/knowledge/frontier.ts

@@ -0,0 +1,82 @@
+/**
+ * What is left to press, kept between crawls as `frontier.jsonl`: per place
+ * the agent has stood, which controls were pressed and which are still owed,
+ * so the next run picks up where the last one's budget ran out. Stored the way
+ * edges.jsonl is: appended while a run lasts, merged on read, sorted at the end.
+ */
+import { appendJsonl, readJsonl, today, writeJsonl } from '../files.js';
+
+export type Visited = {
+  /** A route, or a layer open over one (`Settings.Main#account-button`). */
+  node: string;
+  tried: string[];
+  /** Controls seen here and not pressed yet. */
+  left: string[];
+  /** A place only ever seen from outside still owes a first visit. */
+  visited: boolean;
+  last: string;
+};
+
+export type FrontierUpdate = { tried?: string[]; seen?: string[]; visited?: boolean };
+
+const merge = (into: Visited, row: Visited) => {
+  const tried = new Set([...into.tried, ...row.tried]);
+  into.tried = [...tried].sort();
+  into.left = [...new Set([...into.left, ...row.left])].filter((c) => !tried.has(c)).sort();
+  into.visited ||= row.visited;
+  if (row.last > into.last) into.last = row.last;
+};
+
+const add = (byNode: Map<string, Visited>, row: Visited) => {
+  let found = byNode.get(row.node);
+  if (!found) {
+    found = { node: row.node, tried: [], left: [], visited: false, last: '' };
+    byNode.set(row.node, found);
+  }
+  merge(found, row);
+};
+
+const merged = (rows: Visited[]): Map<string, Visited> => {
+  const byNode = new Map<string, Visited>();
+  for (const row of rows) add(byNode, row);
+  return byNode;
+};
+
+const save = (file: string, rows: Visited[]) =>
+  writeJsonl(
+    file,
+    [...rows].sort((a, b) => a.node.localeCompare(b.node)),
+  );
+
+export const load = (file: string): Visited[] => [...merged(readJsonl<Visited>(file)).values()];
+
+/** Places that still owe something, the never-visited first: what they offer is unknown, which is worth more than a known remainder. */
+export const unfinished = (rows: Visited[]): Visited[] =>
+  rows.filter((r) => !r.visited || r.left.length > 0).sort((a, b) => Number(a.visited) - Number(b.visited) || b.left.length - a.left.length);
+
+/** The frontier in a file, kept in memory while a crawl adds to it. */
+export const open = (file: string) => {
+  const rows = merged(readJsonl<Visited>(file));
+  let appended = false;
+  return {
+    tried: (node: string): string[] => rows.get(node)?.tried ?? [],
+    record: (node: string, update: FrontierUpdate): void => {
+      const row: Visited = { node, tried: update.tried ?? [], left: update.seen ?? [], visited: update.visited === true, last: today() };
+      appendJsonl(file, row);
+      appended = true;
+      add(rows, row);
+    },
+    unfinished: (): string[] => unfinished([...rows.values()]).map((r) => r.node),
+    compact: () => {
+      if (appended) save(file, load(file));
+    },
+  };
+};
+
+export const prune = (file: string, routes: Set<string>): number => {
+  const before = load(file);
+  if (before.length === 0) return 0;
+  const after = before.filter((r) => routes.has(r.node.split('#')[0]!));
+  save(file, after);
+  return before.length - after.length;
+};

package/src/knowledge/funnels.ts

@@ -0,0 +1,126 @@
+/**
+ * The analytics contract checked against what a run recorded: not conversion
+ * (a scripted run always converts) but that the funnel a dashboard reads still
+ * exists in the code, in order, with the properties it needs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readJson } from '../files.js';
+import type { AppEvent, RunEvent } from './events.js';
+
+/** A property is either a type the dashboard needs (`string`, `number`, `boolean`) or a value it filters on. */
+export type FunnelStep = { event: string; props?: Record<string, unknown> };
+export type Funnel = { name: string; steps: FunnelStep[] };
+
+const funnelsDir = (lynkeusDir: string) => path.join(lynkeusDir, 'funnels');
+
+export const loadFunnel = (lynkeusDir: string, name: string): Funnel => {
+  const file = path.join(funnelsDir(lynkeusDir), `${name}.json`);
+  if (!fs.existsSync(file)) throw new Error(`no funnel ${name}: write ${path.relative(process.cwd(), file)}`);
+  const funnel = readJson<Funnel>(file);
+  return { ...funnel, name: funnel.name ?? name };
+};
+
+export const listFunnels = (lynkeusDir: string): Funnel[] => {
+  const dir = funnelsDir(lynkeusDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => loadFunnel(lynkeusDir, f.slice(0, -5)));
+};
+
+const TYPES = new Set(['string', 'number', 'boolean']);
+const typeOf = (v: unknown) => (Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v);
+
+const propProblems = (want: Record<string, unknown> = {}, got: Record<string, unknown> = {}): string[] =>
+  Object.entries(want).flatMap(([key, expected]) => {
+    if (!(key in got)) return [`${key} is missing`];
+    const value = got[key];
+    if (typeof expected === 'string' && TYPES.has(expected))
+      return typeOf(value) === expected ? [] : [`${key} is ${typeOf(value)}, the funnel needs ${expected}`];
+    return JSON.stringify(value) === JSON.stringify(expected) ? [] : [`${key} is ${JSON.stringify(value)}, the funnel filters on ${JSON.stringify(expected)}`];
+  });
+
+export type FunnelResult = { funnel: string; ok: boolean; steps: { event: string; ok: boolean; at?: number; problem?: string }[] };
+
+export const checkFunnel = (funnel: Funnel, events: (AppEvent | RunEvent)[]): FunnelResult => {
+  let cursor = 0;
+  const steps = funnel.steps.map((step) => {
+    const index = events.findIndex((e, i) => i >= cursor && e.name === step.event);
+    if (index === -1) {
+      const earlier = events.findIndex((e) => e.name === step.event);
+      return { event: step.event, ok: false, problem: earlier === -1 ? 'never happened' : 'happened, but before the step it should follow' };
+    }
+    cursor = index + 1;
+    const at = 'step' in events[index]! ? (events[index] as RunEvent).step : index;
+    const problems = propProblems(step.props, events[index]!.props);
+    return problems.length ? { event: step.event, ok: false, at, problem: problems.join('; ') } : { event: step.event, ok: true, at };
+  });
+  return { funnel: funnel.name, ok: steps.every((s) => s.ok), steps };
+};
+
+export const describeFunnel = (result: FunnelResult): string =>
+  [
+    `${result.ok ? '✓' : '✗'} ${result.funnel}`,
+    ...result.steps.map(
+      (s, i) => `  ${s.ok ? '✓' : '✗'} ${i + 1} ${s.event}${s.at !== undefined ? `  (step ${s.at})` : ''}${s.problem ? `  — ${s.problem}` : ''}`,
+    ),
+  ].join('\n');
+
+type Shape = Record<string, string>;
+const shapeOf = (events: AppEvent[]): Map<string, Shape> => {
+  const out = new Map<string, Shape>();
+  for (const e of events) {
+    const shape = out.get(e.name) ?? {};
+    for (const [k, v] of Object.entries(e.props ?? {})) shape[k] = typeOf(v);
+    out.set(e.name, shape);
+  }
+  return out;
+};
+
+export type EventsDiff = { added: string[]; lost: string[]; changed: { event: string; changes: string[] }[] };
+
+/** The same case on two builds: events that appeared, disappeared, or changed the shape of their properties. */
+export const diffEvents = (before: AppEvent[], after: AppEvent[]): EventsDiff => {
+  const a = shapeOf(before);
+  const b = shapeOf(after);
+  const added = [...b.keys()].filter((n) => !a.has(n)).sort();
+  const lost = [...a.keys()].filter((n) => !b.has(n)).sort();
+  const changed = [...a.keys()]
+    .filter((n) => b.has(n))
+    .sort()
+    .flatMap((event) => {
+      const was = a.get(event)!;
+      const now = b.get(event)!;
+      const changes = [
+        ...Object.keys(now)
+          .filter((k) => !(k in was))
+          .map((k) => `+${k}`),
+        ...Object.keys(was)
+          .filter((k) => !(k in now))
+          .map((k) => `-${k}`),
+        ...Object.keys(was)
+          .filter((k) => k in now && was[k] !== now[k])
+          .map((k) => `${k} ${was[k]}→${now[k]}`),
+      ];
+      return changes.length ? [{ event, changes }] : [];
+    });
+  return { added, lost, changed };
+};
+
+export const describeEventsDiff = (diff: EventsDiff): string => {
+  const lines = [...diff.added.map((n) => `+ ${n}`), ...diff.lost.map((n) => `- ${n}`), ...diff.changed.map((c) => `~ ${c.event}: ${c.changes.join(', ')}`)];
+  return lines.length ? lines.join('\n') : '(same events, same shapes)';
+};
+
+/** Across runs: which funnel steps some run produced, and which none did. */
+export const funnelCoverage = (funnels: Funnel[], runs: { run: string; events: AppEvent[] }[]) =>
+  funnels.map((funnel) => ({
+    funnel: funnel.name,
+    steps: funnel.steps.map((step) => ({
+      event: step.event,
+      runs: runs.filter((r) => r.events.some((e) => e.name === step.event)).map((r) => r.run),
+    })),
+  }));

package/src/knowledge/lint.ts

@@ -0,0 +1,99 @@
+/** What a person would flag in review, read off one screen: not accessibility certification, the usual suspects. */
+import type { Screen } from 'lynkeus-protocol';
+
+export type Finding = { rule: string; severity: 'warn' | 'info'; element: number; message: string };
+
+const DEFAULT_I18N_KEY_PATTERNS = [/^[a-z][a-z0-9]*(\.[a-z0-9]+){2,}$/i, /^[a-z0-9]+(_[a-z0-9]+){2,}$/i];
+
+const looksLikeI18nKey = (t: string, patterns: RegExp[]): boolean => {
+  const s = t.trim();
+  if (patterns.length === 0) return false;
+  if (s.length < 4 || /\s/.test(s)) return false;
+  if (/^https?:|^[@#$]|^\+?\d[\d\s.,-]*$/.test(s)) return false;
+  return patterns.some((p) => p.test(s));
+};
+
+// Points: what both platforms' guidelines ask for.
+const MIN_TOUCH = 44;
+const label = (e: Screen['elements'][number]) => e.testId ?? e.text ?? e.accessibilityLabel;
+
+type LintOptions = {
+  /** What an untranslated key looks like (default `a.b.c` and `snake_case_key`); `[]` turns the rule off. */
+  i18nKeyPatterns?: RegExp[];
+  minTouchTarget?: number;
+};
+
+export const lintScreen = (screen: Screen, options: LintOptions = {}): Finding[] => {
+  const minTouch = options.minTouchTarget ?? MIN_TOUCH;
+  const out: Finding[] = [];
+  const els = (screen.elements ?? []).filter((e) => !e.hidden);
+  const win = screen.window ?? { w: 0, h: 0 };
+  for (const e of els) {
+    const named = e.text ?? e.accessibilityLabel;
+    if ((e.kind === 'button' || e.kind === 'switch') && named === undefined && e.testId === undefined) {
+      out.push({ rule: 'unlabeled-control', severity: 'warn', element: e.i, message: `${e.kind} with no text, label or testId` });
+    }
+    if ((e.kind === 'button' || e.kind === 'switch') && e.enabled !== false && e.frame) {
+      const { w, h } = e.frame;
+      // A control with text is usually measured at its label, not its touchable area (a tab bar item): only info.
+      if (w > 0 && h > 0 && (w < minTouch || h < minTouch)) {
+        const iconOnly = e.text === undefined && e.accessibilityLabel === undefined;
+        out.push({
+          rule: 'small-target',
+          severity: iconOnly ? 'warn' : 'info',
+          element: e.i,
+          message: `${Math.round(w)}×${Math.round(h)}pt target (< ${minTouch}) ${label(e) ?? ''}`.trim(),
+        });
+      }
+    }
+    if (e.kind === 'text' && e.text && looksLikeI18nKey(e.text, options.i18nKeyPatterns ?? DEFAULT_I18N_KEY_PATTERNS)) {
+      out.push({ rule: 'untranslated', severity: 'warn', element: e.i, message: `"${e.text}" looks like an i18n key, not copy` });
+    }
+    if ((e.kind === 'button' || e.kind === 'input' || e.kind === 'switch') && e.covered && e.enabled !== false) {
+      out.push({
+        rule: 'covered-control',
+        severity: 'info',
+        element: e.i,
+        message: `${e.kind} ${label(e) ?? ''} is covered; a tap would not reach it`.replace('  ', ' ').trim(),
+      });
+    }
+    if (e.frame && win.w > 0 && label(e) !== undefined) {
+      const { x, y, w, h } = e.frame;
+      if (x + w > win.w + 1 || y + h > win.h + 1 || x < -1 || y < -1) {
+        out.push({
+          rule: 'offscreen',
+          severity: 'info',
+          element: e.i,
+          message: `${label(e)} extends past the ${win.w}×${win.h} window (x${Math.round(x)} y${Math.round(y)} ${Math.round(w)}×${Math.round(h)})`,
+        });
+      }
+    }
+    if (e.text && e.frame && (e.frame.w === 0 || e.frame.h === 0)) {
+      out.push({
+        rule: 'zero-size',
+        severity: 'info',
+        element: e.i,
+        message: `"${e.text.slice(0, 30)}" has ${Math.round(e.frame.w)}×${Math.round(e.frame.h)} size`,
+      });
+    }
+  }
+  const byTestId = new Map<string, number[]>();
+  for (const e of els) {
+    if (!e.testId) continue;
+    const list = byTestId.get(e.testId) ?? [];
+    list.push(e.i);
+    byTestId.set(e.testId, list);
+  }
+  for (const [id, at] of byTestId)
+    if (at.length > 1)
+      out.push({ rule: 'duplicate-testid', severity: 'info', element: at[0]!, message: `testId "${id}" is on ${at.length} elements (${at.join(', ')})` });
+  return out;
+};
+
+export const describeFindings = (findings: Finding[], route?: string): string => {
+  if (findings.length === 0) return `${route ?? 'screen'}: clean`;
+  const order = { warn: 0, info: 1 } as const;
+  const sorted = [...findings].sort((a, b) => order[a.severity] - order[b.severity]);
+  const head = `${route ?? 'screen'}: ${findings.filter((f) => f.severity === 'warn').length} warn, ${findings.filter((f) => f.severity === 'info').length} info`;
+  return [head, ...sorted.map((f) => `  ${f.severity === 'warn' ? '⚠' : '·'} [${f.rule}] #${f.element} ${f.message}`)].join('\n');
+};