lynkeus 0.2.0

package/lib/knowledge/lint.js

@@ -0,0 +1,89 @@
+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, patterns) => {
+    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) => e.testId ?? e.text ?? e.accessibilityLabel;
+export const lintScreen = (screen, options = {}) => {
+    const minTouch = options.minTouchTarget ?? MIN_TOUCH;
+    const out = [];
+    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();
+    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, route) => {
+    if (findings.length === 0)
+        return `${route ?? 'screen'}: clean`;
+    const order = { warn: 0, info: 1 };
+    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');
+};

package/lib/knowledge/perf.d.ts

@@ -0,0 +1,32 @@
+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;
+};
+export declare const visitsFrom: (events: TraceEvent[]) => Visit[];
+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 declare const summarize: (visits: Visit[]) => RouteSummary[];
+export declare const describePerf: (summary: RouteSummary[]) => string;

package/lib/knowledge/perf.js

@@ -0,0 +1,91 @@
+const pathOf = (url) => {
+    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) => {
+    const visits = [];
+    let current = null;
+    let burstEnd = 0;
+    let burstOver = false;
+    const close = (endT) => {
+        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;
+};
+/** Per route, averaged over its visits, the costliest arrival first. */
+export const summarize = (visits) => {
+    const by = new Map();
+    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) => {
+    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/lib/knowledge/plan.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { type ObservedEdge } from './edges.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';
+};
+/** Breadth-first over places. A bare route as the destination accepts arriving with something open over it. */
+export declare const plan: (graph: ScreenGraph, from: string, to: string, observed?: ObservedEdge[], maxDepth?: number) => PlanStep[] | null;
+export declare const describePlan: (steps: PlanStep[]) => string;

package/lib/knowledge/plan.js

@@ -0,0 +1,81 @@
+/**
+ * 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, splitNode } from './edges.js';
+import { vocabularyOf } from './query.js';
+const movesFrom = (graph, node, observed) => {
+    const moves = 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, from, to, observed = [], maxDepth = 6) => {
+    const byNode = new Map();
+    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) => node === to || splitNode(node).route === to;
+    if (arrived(from))
+        return [];
+    const previous = new Map();
+    const queue = [from];
+    const depth = new Map([[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 = [];
+                for (let at = 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) => 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/lib/knowledge/problems.d.ts

@@ -0,0 +1,5 @@
+import type { RequestRecord, Screen } from 'lynkeus-protocol';
+export declare const withoutHost: (url: string) => string;
+export declare const pathOf: (url: string) => string;
+/** What a person would call broken on a screen: nothing on it, the app's own error copy, a request that failed. */
+export declare const problemsOf: (screen: Screen, requests: RequestRecord[], errorCopy?: RegExp) => string[];

package/lib/knowledge/problems.js

@@ -0,0 +1,8 @@
+export const withoutHost = (url) => url.replace(/^https?:\/\/[^/]+/, '');
+export const pathOf = (url) => 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, requests, errorCopy) => [
+    ...(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/lib/knowledge/query.d.ts

@@ -0,0 +1,36 @@
+import { type ObservedEdge } from './edges.js';
+import type { NavigationEdge, RouteName, ScreenGraph, Selector, SourcePath } from './types.js';
+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 declare const vocabularyOf: (graph: ScreenGraph, route: RouteName, maxDepth?: number) => Vocabulary | null;
+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 declare const pathsTo: (graph: ScreenGraph, destination: RouteName, observed?: ObservedEdge[]) => Approach[];
+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 declare const screensAffectedBy: (graph: ScreenGraph, changedFiles: SourcePath[], maxDepth?: number) => Affected[];

package/lib/knowledge/query.js

@@ -0,0 +1,127 @@
+import { edgeFrom } from './edges.js';
+// Bounded: through barrels an unbounded closure reaches most of the app and makes every screen look the same.
+const closureOf = (graph, entry, maxDepth = 2) => {
+    const seen = new Set([entry]);
+    let frontier = [entry];
+    for (let depth = 0; depth < maxDepth; depth++) {
+        const next = [];
+        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;
+};
+/**
+ * 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, route, maxDepth = 1) => {
+    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 = [];
+    const navigatesTo = [];
+    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 };
+};
+/** The controls that lead to a route, the walked ones first: they beat an inference from source. */
+export const pathsTo = (graph, destination, observed = []) => {
+    const approaches = 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;
+};
+/** 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, changedFiles, maxDepth = 4) => {
+    const importedBy = new Map();
+    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();
+    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]);
+        }
+    }
+    const reached = new Map();
+    let frontier = [];
+    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 = [];
+        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 = [];
+    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/lib/knowledge/route-params.d.ts

@@ -0,0 +1,6 @@
+export type RouteParamsInfo = {
+    route: string;
+    free: boolean;
+    shape: string;
+};
+export declare const readRouteParams: (root: string, paramsFile?: string) => RouteParamsInfo[];

package/lib/knowledge/route-params.js

@@ -0,0 +1,42 @@
+/**
+ * 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 const readRouteParams = (root, paramsFile = 'app/navigation/types.d.ts') => {
+    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();
+    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/lib/knowledge/screens.d.ts

@@ -0,0 +1,30 @@
+import type { Screen } from 'lynkeus-protocol';
+type Frame = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type ScreenChange = {
+    route: string;
+    date: string;
+    added: string[];
+    removed: string[];
+    changedText: string[];
+    moved?: string[];
+};
+export declare const diffGeometry: (before: Record<string, Frame>, after: Record<string, Frame>, tolerance?: number) => string[];
+/** Stores the screen under its route and returns what changed since the previous read. */
+export declare const record: (lynkeusDir: string, screen: Screen) => ScreenChange | null;
+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 declare const observed: (lynkeusDir: string) => Map<string, Observed>;
+export declare const changes: (lynkeusDir: string, last?: number) => ScreenChange[];
+export declare const describeChange: (c: ScreenChange) => string;
+export {};