tinybeeai 0.0.0-stage → 0.16.1

package/dist/reports/trace-map.js

@@ -0,0 +1,1278 @@
+// Traceability map (docs/TRACE-MAP.md, KAT-189). The app under test as the dot's test runs saw it: app (host) >
+// section (first path segment) > page (route pattern) > state (a distinct heading set or dialog on one route),
+// built from the observations.jsonl of recent runs (src/runner/observe.ts). A section with one page is that page.
+// A requirement attaches to a page only on evidence: a spec linked to it visited the page, its text names the
+// route, or a file its PRs changed is the page's source or sits in the page's product area (the repo profile). A
+// run on the requirement's PR that merely visited a page is not evidence: a full suite visits every page. A
+// requirement with no evidence sits in Requirements without a page only. Routes the code (the
+// repo scan's page routes and the routes its specs open), a requirement or a probe names that no run visited are
+// coverage gaps: Needs tests, or Not run yet when a spec covers them. A visited page whose source a merge changed
+// after its latest visit is Not run yet too.
+//
+// Two halves: gatherFacts reads what is stored (observations, runs, the traceability rows, links, profiles), and
+// mapTree is a pure function from those facts to the tree, so the rules are unit tested without a database.
+// Nothing here calls a tracker or a model; the routes warm the ticket titles first (ticket-titles.ts).
+import { createHash } from 'node:crypto';
+import { log } from '../config.js';
+import { list } from '../db.js';
+import { enqueue } from '../queue.js';
+import { parseIssueRef } from '../integrations/github-issues.js';
+import { linksOfWatch } from '../links.js';
+import { latestProfile } from '../profile/store.js';
+import { watchRepos } from '../repos.js';
+import { anyGlob } from '../review/glob.js';
+import { artifactUrl, resolveArtifactPath } from '../runner/artifacts.js';
+import { readObservations, routeOf } from '../runner/observe.js';
+import { buildAll, classify, issueUrl, mdLink, mdText } from './traceability.js';
+/**
+ * A screenshot check against the artifacts folder, cached for one build. The artifact cap deletes old runs' files
+ * while their observations stay, so a URL in the payload could 404 and the app would show a broken box. A missing
+ * file is left out (the node takes an older screenshot, else none) and logged once per process.
+ */
+export function artifactShotCheck() {
+    const seen = new Map();
+    return (runId, name) => {
+        const k = `${runId}/${name}`;
+        let ok = seen.get(k);
+        if (ok === undefined) {
+            ok = resolveArtifactPath(runId, name) !== null;
+            seen.set(k, ok);
+            if (!ok)
+                log.warnOnce('trace-map-missing-shot', `trace map: screenshot ${artifactUrl(runId, name)} is gone from the artifacts folder (artifact cap?); the map leaves it and any other missing file out`);
+        }
+        return ok;
+    };
+}
+export const STATUS_WORD = {
+    covered: 'Covered',
+    partly: 'Partly covered',
+    failing: 'Failing',
+    needs_tests: 'Needs tests',
+    not_run: 'Not run yet',
+};
+const STATS_KEY = {
+    covered: 'covered',
+    partly: 'partly',
+    failing: 'failing',
+    needs_tests: 'needsTests',
+    not_run: 'notRun',
+};
+export const isGap = (s) => s === 'needs_tests' || s === 'not_run';
+const NO_PAGE_SECTION = 'Requirements without a page';
+/** A route as a pattern: `/products/[id]` and `/products/{id}` read `/products/:id`. Catch-all routes are not pages. */
+export function patternOf(raw) {
+    const r = trimRoute(raw.trim().split(/[?#]/)[0] ?? '');
+    if (!r.startsWith('/') || r.includes('*') || /\[\.\.\./.test(r))
+        return null;
+    const out = r
+        .split('/')
+        .filter((seg) => !/^\(.*\)$/.test(seg))
+        .map((seg) => seg.replace(/^\[(\w+)\]$/, ':$1').replace(/^\{(\w+)\}$/, ':$1'))
+        .join('/');
+    return /[:]/.test(out) ? trimRoute(out || '/') : routeOf(out || '/');
+}
+const nodeId = (kind, key) => `${kind}-${createHash('sha256').update(key).digest('hex').slice(0, 10)}`;
+const bag = () => ({ obs: [], tests: new Set(), reqs: new Set(), defects: new Set(), dots: new Set(), needsTests: false, notRun: false });
+const natural = (a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+export const testKey = (file, title, host) => (host ? `${file}\u0000${title}\u0000${host}` : `${file}\u0000${title}`);
+/** The key of the test an observation ran. It carries the app host, so a test of another app with the same file and title is not this one. Two dots on one app run one test. */
+const obsKey = (o) => testKey(o.test, o.title, o.host);
+/** The stored result of a test key: the app's own, else one saved without an app. */
+const factOf = (tests, key) => tests.get(key) ?? tests.get(key.split('\u0000').slice(0, 2).join('\u0000'));
+/** Same file whichever side carries a folder prefix: `e2e/a.spec.ts` and `tests/e2e/a.spec.ts`. */
+export const samePath = (a, b) => {
+    const x = a.replace(/^\.\//, '');
+    const y = b.replace(/^\.\//, '');
+    return x === y || x.endsWith(`/${y}`) || y.endsWith(`/${x}`);
+};
+const trimRoute = (r) => (r.length > 1 ? r.replace(/\/+$/, '') : r);
+/** `/products/:id`, `/products/[id]` and `/products/{id}` match `/products/12`. Exact text always matches. */
+export function routeMatches(pattern, route) {
+    const p = trimRoute(pattern.trim());
+    const r = trimRoute(route.trim().split(/[?#]/)[0] ?? '');
+    if (!p || !r)
+        return false;
+    if (p.toLowerCase() === r.toLowerCase())
+        return true;
+    const re = p
+        .split('/')
+        .map((seg) => (/^(:\w+\??|\[\.{0,3}[^\]]+\]|\{[^}]+\}|\*)$/.test(seg) ? '[^/]+' : seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+        .join('/');
+    return new RegExp(`^${re}$`, 'i').test(r);
+}
+/** Either side may be the pattern: a scanned `/products/[id]` and an observed `/products/:id` are the same page. */
+const sameRoute = (a, b) => routeMatches(a, b) || routeMatches(b, a);
+const hostOf = (u) => {
+    try {
+        return new URL(u).host.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * Page routes a text names: absolute URLs, and paths that stand on their own (`/checkout` in "fails on /checkout.").
+ * API paths and file names are not pages. Each comes with the host of its URL, when it had one.
+ */
+export function routesIn(text) {
+    const out = new Map();
+    for (const m of text.matchAll(/https?:\/\/[^\s)<>"'`]+/gi)) {
+        const host = hostOf(m[0]);
+        const route = routeOf(m[0].replace(/[.,;:!?]+$/, ''));
+        if (host)
+            out.set(`${host} ${route}`, { host, route });
+    }
+    const bare = text.replace(/https?:\/\/[^\s)<>"'`]+/gi, ' ');
+    for (const m of bare.matchAll(/(?:^|[\s(`'"])(\/[a-z0-9][\w\-./:[\]{}]*)/gi)) {
+        const raw = m[1].replace(/[.,;:!?]+$/, '');
+        if (/\.[a-z0-9]{1,5}$/i.test(raw))
+            continue;
+        const route = raw.includes(':') || raw.includes('[') || raw.includes('{') ? trimRoute(raw.toLowerCase()) : routeOf(raw);
+        out.set(` ${route}`, { route });
+    }
+    return [...out.values()].filter((r) => !/^\/api(\/|$)/.test(r.route));
+}
+/** The first path segment, the key of a page's section: `/runs/:id` reads `runs`, `/` reads ``. */
+export const sectionOf = (route) => route.split('/').filter(Boolean)[0] ?? '';
+/** The app that holds the local servers test runs start on a random port (an e2e suite that boots its own server). */
+export const LOCAL_TEST_APP = 'Local test servers';
+const LOOPBACK_PORT = /^(?:127\.0\.0\.1|localhost|\[::1\]|0\.0\.0\.0):\d+$/i;
+/**
+ * The app key of a host. A loopback host with a port that no dot names (base URL or probe) is a server a test run
+ * started for itself, on a new port each run: all of them are one app, not one app per port.
+ */
+export function appHostFor(owned) {
+    return (host) => (host && LOOPBACK_PORT.test(host) && !owned.has(host.toLowerCase()) ? LOCAL_TEST_APP : host);
+}
+/** The input with the hosts of local test servers folded into one app. */
+function foldTestServers(input) {
+    const owned = new Set([...input.baseUrls, ...input.knownUrls.map((k) => k.url)].map(hostOf).filter(Boolean));
+    const appHost = appHostFor(owned);
+    if (!input.observations.some((o) => o.host && appHost(o.host) !== o.host))
+        return { input, appHost };
+    return { input: { ...input, observations: input.observations.map((o) => (o.host ? { ...o, host: appHost(o.host) } : o)) }, appHost };
+}
+const titleCase = (s) => (s ? s.replace(/[-_]+/g, ' ').replace(/^\w/, (c) => c.toUpperCase()) : 'Home');
+/** The test result a lookup gives, else the observation's own. */
+function resultOf(key, tests, obs) {
+    const t = factOf(tests, key);
+    if (t)
+        return t.result;
+    const o = obs.find((x) => obsKey(x) === key && x.result);
+    if (!o)
+        return 'not_run';
+    return o.result === 'passed' ? 'passed' : o.result === 'failed' || o.result === 'timedOut' ? 'failed' : 'not_run';
+}
+function countsOf(b, l) {
+    // Gap counts are filled once the tree stands (mapTree, countGaps).
+    const results = [...b.tests].map((k) => resultOf(k, l.tests, b.obs));
+    const defects = [...b.defects].map((r) => l.defects.get(r)).filter((d) => !!d);
+    return {
+        requirements: b.reqs.size,
+        tests: { passed: results.filter((r) => r === 'passed').length, failed: results.filter((r) => r === 'failed').length, total: results.length },
+        defects: { open: defects.filter((d) => d.state === 'open').length, total: defects.length },
+        gaps: { needsTests: 0, notRun: 0 },
+    };
+}
+/**
+ * The status, bottom-up. No run saw anything here: Needs tests when a page below has no test, else Not run yet.
+ * Failing: a test that visited it failed its latest run, an open defect, or a failing requirement. A page whose
+ * source changed after its latest visit (`changed`) is Not run yet. Covered: every test passed, every requirement
+ * passes, and no page below is a gap. Anything in between is Partly covered.
+ */
+export function statusOf(b, l, changed = false) {
+    if (!b.obs.length)
+        return b.needsTests || !b.notRun ? 'needs_tests' : 'not_run';
+    const results = [...b.tests].map((k) => resultOf(k, l.tests, b.obs));
+    const reqs = [...b.reqs].map((r) => l.reqs.get(r)).filter((r) => !!r);
+    const openDefect = [...b.defects].some((r) => l.defects.get(r)?.state === 'open');
+    if (openDefect || results.includes('failed') || reqs.some((r) => r.row.statusCode === 'failing'))
+        return 'failing';
+    if (changed)
+        return 'not_run';
+    const ok = results.every((r) => r === 'passed') && reqs.every((r) => r.row.statusCode === 'passing');
+    return ok && !b.needsTests && !b.notRun ? 'covered' : 'partly';
+}
+function union(into, from) {
+    for (const o of from.obs)
+        into.obs.push(o);
+    for (const k of ['tests', 'reqs', 'defects', 'dots'])
+        for (const v of from[k])
+            into[k].add(v);
+    if (from.needsTests)
+        into.needsTests = true;
+    if (from.notRun)
+        into.notRun = true;
+}
+/** The state of a page an observation shows: its dialog, else its heading set. */
+const stateKeyOf = (o) => (o.dialog ? `d:${o.dialog}` : `h:${o.headings.map((h) => h.text).join('|')}`);
+/** The most common heading over observations, from the top level present: a section's or a state's name. */
+function commonHeading(obs) {
+    const all = obs.flatMap((o) => o.headings);
+    if (!all.length)
+        return undefined;
+    const top = Math.min(...all.map((h) => h.level));
+    const votes = new Map();
+    for (const h of all)
+        if (h.level === top)
+            votes.set(h.text, (votes.get(h.text) ?? 0) + 1);
+    return [...votes].sort((a, b) => b[1] - a[1])[0]?.[0];
+}
+const MAX_STATES = 8;
+/** The pure half: facts in, tree and index out. */
+export function mapTree(raw, opts = {}) {
+    const { input, appHost } = foldTestServers(raw);
+    const hasShot = opts.hasShot ?? (() => true);
+    const shown = (o) => !!o.screenshot && hasShot(o.runId, o.screenshot);
+    const tests = new Map(input.tests.map((t) => [testKey(t.file, t.title, t.host), t]));
+    const l = {
+        tests,
+        reqs: new Map(input.requirements.map((r) => [r.row.ref, r])),
+        defects: new Map(input.defects.map((d) => [d.ref, d])),
+    };
+    const index = new Map();
+    const reqRoutes = new Map(input.requirements.map((r) => [r.row.ref, routesIn(r.text)]));
+    const defectRoutes = new Map(input.defects.map((d) => [d.ref, routesIn(d.text)]));
+    // The page routes the files of a PR touch: routes whose scanned source it changed, and the routes of an area whose
+    // paths hold a changed file.
+    const prFiles = new Map();
+    for (const c of input.prChanges ?? [])
+        prFiles.set(c.pr.toLowerCase(), [...(prFiles.get(c.pr.toLowerCase()) ?? []), c]);
+    const pages = input.code.filter((c) => !c.method && !c.api);
+    const touched = (prs) => {
+        const out = new Map();
+        for (const f of prs.flatMap((p) => prFiles.get(p.toLowerCase()) ?? [])) {
+            for (const c of pages)
+                if (c.repo === f.repo && samePath(c.file, f.path))
+                    out.set(`${c.host ?? ''} ${c.route}`, { ...(c.host ? { host: c.host } : {}), route: c.route });
+            for (const a of input.areas ?? [])
+                if (a.paths?.length && (!a.repo || a.repo === f.repo) && anyGlob(f.path, a.paths))
+                    for (const r of a.routes)
+                        out.set(`${a.host ?? ''} ${r}`, { ...(a.host ? { host: a.host } : {}), route: r });
+        }
+        return [...out.values()];
+    };
+    const reqChanged = new Map(input.requirements.map((r) => [r.row.ref, touched(r.prs)]));
+    const defectChanged = new Map(input.defects.map((d) => [d.ref, touched(d.prs)]));
+    /**
+     * A route a PR touched is this page: on the host the scan is for, any host when the scan names none, and the local
+     * test servers, which serve the dot's own app on a random port.
+     */
+    const touches = (rs, host, route) => (rs ?? []).some((r) => (!r.host || r.host === host || host === LOCAL_TEST_APP) && sameRoute(route, r.route));
+    const placed = new Set();
+    const make = (kind, key, name, extra = {}) => ({
+        id: nodeId(kind, key),
+        kind,
+        name,
+        status: 'needs_tests',
+        counts: { requirements: 0, tests: { passed: 0, failed: 0, total: 0 }, defects: { open: 0, total: 0 }, gaps: { needsTests: 0, notRun: 0 } },
+        children: [],
+        ...extra,
+    });
+    const fill = (n, b, changed = false) => {
+        n.counts = countsOf(b, l);
+        n.status = statusOf(b, l, changed);
+        const ms = {};
+        for (const r of b.defects) {
+            const d = l.defects.get(r);
+            if (d?.state === 'open' && d.milestone)
+                ms[d.milestone] = (ms[d.milestone] ?? 0) + 1;
+        }
+        if (Object.keys(ms).length)
+            n.milestones = ms;
+        // A coverage gap shows no screenshot: what a run saw before the change is not the page now.
+        // A screenshot whose file is gone is left out: the node takes the newest one still on disk.
+        const shot = isGap(n.status) ? undefined : [...b.obs].filter(shown).sort((a, c) => c.at.localeCompare(a.at))[0];
+        if (shot)
+            n.screenshot = artifactUrl(shot.runId, shot.screenshot);
+        else
+            delete n.screenshot;
+    };
+    /**
+     * Requirements and defects of a set of observations on one route, on evidence only: a linked spec visited it, their
+     * text names the route, or their PRs changed the route's source or a file of its area. A run on their PR that
+     * visited the page is not enough: the run visits every page its suite opens.
+     */
+    const attach = (b, host, route, primary) => {
+        const files = [...new Set(b.obs.map((o) => o.test))];
+        const names = (rs) => (rs ?? []).some((r) => (r.host ? r.host === host : primary) && sameRoute(route, r.route));
+        for (const r of input.requirements) {
+            if (r.specs.some((s) => files.some((f) => samePath(s, f))) || names(reqRoutes.get(r.row.ref)) || touches(reqChanged.get(r.row.ref), host, route))
+                b.reqs.add(r.row.ref);
+        }
+        for (const d of input.defects) {
+            if (d.requirements.some((r) => b.reqs.has(r)) || names(defectRoutes.get(d.ref)) || touches(defectChanged.get(d.ref), host, route))
+                b.defects.add(d.ref);
+        }
+        for (const r of b.reqs)
+            placed.add(r);
+    };
+    // Apps: the dots' base URL hosts first, then every host a run visited, the most visited first.
+    const visits = new Map();
+    for (const o of input.observations)
+        if (o.host)
+            visits.set(o.host, (visits.get(o.host) ?? 0) + 1);
+    const hosts = [...new Set([...input.baseUrls.map(hostOf).filter(Boolean), ...[...visits].sort((a, b) => b[1] - a[1]).map(([h]) => h)])];
+    const primaryHost = hosts[0];
+    const pagesBy = new Map();
+    for (const o of input.observations) {
+        if (!o.host)
+            continue;
+        const route = routeOf(o.url || o.route);
+        const key = `${o.host} ${route}`;
+        const p = pagesBy.get(key) ?? { host: o.host, route, obs: [] };
+        p.obs.push(o);
+        pagesBy.set(key, p);
+    }
+    const gaps = new Map();
+    const visitedRoute = (host, route) => [...pagesBy.values()].some((p) => p.host === host && sameRoute(p.route, route));
+    const addGap = (host, raw, more = {}) => {
+        const h = host ?? primaryHost;
+        const route = patternOf(raw);
+        if (!h || !hosts.includes(h) || !route || visitedRoute(h, route))
+            return;
+        const had = [...gaps.values()].find((g) => g.host === h && sameRoute(g.route, route));
+        const g = had ?? { host: h, route, reqs: new Set(), dots: new Set(), specs: new Set() };
+        if (more.ref)
+            g.reqs.add(more.ref);
+        if (more.dot)
+            g.dots.add(more.dot);
+        if (more.spec)
+            g.specs.add(more.spec);
+        if (!had)
+            gaps.set(`${h} ${route}`, g);
+    };
+    for (const r of input.requirements)
+        for (const x of reqRoutes.get(r.row.ref) ?? [])
+            addGap(x.host, x.route, { ref: r.row.ref, ...(r.dots?.[0] ? { dot: r.dots[0] } : {}) });
+    for (const k of input.knownUrls) {
+        const h = hostOf(k.url);
+        if (h)
+            addGap(h, routeOf(k.url), k.dotId ? { dot: k.dotId } : {});
+    }
+    for (const c of input.code)
+        if (!c.method && !c.api)
+            addGap(c.host, c.route, c.dotId ? { dot: c.dotId } : {});
+    for (const s of input.specs ?? [])
+        for (const r of s.routes)
+            addGap(s.host, r, { spec: s.file, ...(s.dotId ? { dot: s.dotId } : {}) });
+    // A requirement whose PRs changed the source of a page no run visited belongs to that page.
+    for (const g of gaps.values())
+        for (const r of input.requirements)
+            if (touches(reqChanged.get(r.row.ref), g.host, g.route))
+                g.reqs.add(r.row.ref);
+    // A requirement's specs cover the routes the requirement names.
+    for (const g of gaps.values())
+        for (const ref of g.reqs)
+            for (const s of l.reqs.get(ref)?.specs ?? [])
+                g.specs.add(s);
+    for (const g of gaps.values())
+        for (const s of input.specs ?? [])
+            if ((!s.host || s.host === g.host) && s.routes.some((r) => sameRoute(r, g.route)))
+                g.specs.add(s.file);
+    /** Visited pages whose source changed after the latest run that saw them: Not run yet. */
+    const changedSince = (host, route, obs) => {
+        const changes = input.changes ?? [];
+        if (!changes.length)
+            return false;
+        const seen = obs.reduce((m, o) => (o.at > m ? o.at : m), '');
+        const files = input.code.filter((c) => !c.method && !c.api && (!c.host || c.host === host) && sameRoute(c.route, route));
+        return changes.some((ch) => ch.at > seen && files.some((f) => f.repo === ch.repo && samePath(f.file, ch.path)));
+    };
+    const appNodes = [];
+    const multi = hosts.length !== 1;
+    const root = multi ? make('root', `root:${input.title}`, input.title) : null;
+    const rootBag = bag();
+    if (root)
+        index.set(root.id, { node: root, bag: rootBag, path: [], pages: [] });
+    /** Moves a node and everything below it one level up: the path loses the collapsed section. */
+    const reparent = (n, drop) => {
+        const e = index.get(n.id);
+        if (e)
+            e.path = e.path.filter((p) => p.id !== drop);
+        for (const c of n.children)
+            reparent(c, drop);
+    };
+    /** Puts a section under its parent, or its only page in its place: a one-page section says the same thing twice. */
+    const addSection = (parent, parentBag, sNode, sBag) => {
+        const only = sNode.children.length === 1 ? sNode.children[0] : null;
+        if (only) {
+            index.delete(sNode.id);
+            reparent(only, sNode.id);
+            parent.children.push(only);
+        }
+        else
+            parent.children.push(sNode);
+        union(parentBag, sBag);
+    };
+    for (const host of hosts) {
+        const aNode = make('app', `app:${host}`, host);
+        const aBag = bag();
+        const aPath = root ? [{ id: root.id, name: root.name }] : [];
+        const aPages = [];
+        index.set(aNode.id, { node: aNode, bag: aBag, path: aPath, host, pages: aPages });
+        const primary = host === primaryHost;
+        // A section is a product area of the repo scan when one lists the route, else the first path segment.
+        const areas = (input.areas ?? []).filter((a) => !a.host || a.host === host);
+        const sections = new Map();
+        const sectionFor = (route) => {
+            const area = areas.find((a) => a.routes.some((r) => sameRoute(r, route)));
+            const key = area ? `area:${area.name}` : sectionOf(route);
+            const s = sections.get(key) ?? { ...(area ? { name: area.name } : {}), seg: area ? '' : sectionOf(route), pages: [], gaps: [] };
+            sections.set(key, s);
+            return s;
+        };
+        for (const p of pagesBy.values())
+            if (p.host === host)
+                sectionFor(p.route).pages.push(p);
+        for (const g of gaps.values())
+            if (g.host === host)
+                sectionFor(g.route).gaps.push(g);
+        const sectionPath = [...aPath, { id: aNode.id, name: aNode.name }];
+        const sortKey = (s) => s.name ?? s.seg;
+        for (const [key, s] of [...sections].sort((a, b) => (a[0] ? 1 : 0) - (b[0] ? 1 : 0) || natural(sortKey(a[1]), sortKey(b[1])))) {
+            const seg = s.seg;
+            const sName = s.name ?? commonHeading(s.pages.flatMap((p) => p.obs)) ?? titleCase(seg);
+            const sNode = make('section', `section:${host}:${key}`, sName, s.name ? {} : { route: seg ? `/${seg}` : '/' });
+            const sBag = bag();
+            const sPages = [];
+            index.set(sNode.id, { node: sNode, bag: sBag, path: sectionPath, host, pages: sPages });
+            const pagePath = [...sectionPath, { id: sNode.id, name: sNode.name }];
+            const rows = [
+                ...s.pages.map((p) => ({ route: p.route, page: p, g: undefined })),
+                ...s.gaps.map((g) => ({ route: g.route, page: undefined, g })),
+            ].sort((a, b) => natural(a.route, b.route));
+            for (const row of rows) {
+                const pBag = bag();
+                const latest = row.page ? [...row.page.obs].filter((o) => o.pageTitle).sort((a, b) => b.at.localeCompare(a.at))[0] : undefined;
+                const pNode = make('page', `page:${host}:${row.route}`, row.route, { route: row.route, ...(latest?.pageTitle ? { pageTitle: latest.pageTitle } : {}) });
+                const pPath = [...pagePath, { id: pNode.id, name: pNode.name }];
+                const entry = { node: pNode, bag: pBag, path: pagePath, host, pages: [{ host, route: row.route }] };
+                index.set(pNode.id, entry);
+                let changed = false;
+                if (row.page) {
+                    for (const o of row.page.obs) {
+                        pBag.obs.push(o);
+                        pBag.tests.add(obsKey(o));
+                        if (o.dotId)
+                            pBag.dots.add(o.dotId);
+                    }
+                    attach(pBag, host, row.route, primary);
+                    changed = changedSince(host, row.route, row.page.obs);
+                    if (changed) {
+                        pBag.notRun = true;
+                        entry.changed = true;
+                    }
+                    // States: distinct dialogs and heading sets, when there is more than one. A visit with no heading yet
+                    // (the page still loading) is not a state of its own.
+                    const byState = new Map();
+                    for (const o of row.page.obs) {
+                        const k = stateKeyOf(o);
+                        if (k === 'h:')
+                            continue;
+                        byState.set(k, [...(byState.get(k) ?? []), o]);
+                    }
+                    const states = [...byState].sort((a, b) => b[1].length - a[1].length).slice(0, MAX_STATES);
+                    if (states.length > 1) {
+                        const names = new Map();
+                        for (const [k, obs] of states) {
+                            const base = k.startsWith('d:') ? `Dialog: ${k.slice(2)}` : (commonHeading(obs) ?? 'No heading');
+                            const n = (names.get(base) ?? 0) + 1;
+                            names.set(base, n);
+                            const stNode = make('state', `state:${host}:${row.route}:${k}`, n > 1 ? `${base} (${n})` : base, { route: row.route });
+                            const stBag = bag();
+                            for (const o of obs) {
+                                stBag.obs.push(o);
+                                stBag.tests.add(obsKey(o));
+                                if (o.dotId)
+                                    stBag.dots.add(o.dotId);
+                            }
+                            attach(stBag, host, row.route, primary);
+                            fill(stNode, stBag);
+                            pNode.children.push(stNode);
+                            index.set(stNode.id, { node: stNode, bag: stBag, path: pPath, host, pages: [{ host, route: row.route }] });
+                        }
+                    }
+                }
+                else if (row.g) {
+                    for (const r of row.g.reqs) {
+                        pBag.reqs.add(r);
+                        placed.add(r);
+                        for (const d of l.reqs.get(r)?.dots ?? [])
+                            pBag.dots.add(d);
+                    }
+                    for (const d of row.g.dots)
+                        pBag.dots.add(d);
+                    for (const f of row.g.specs)
+                        pBag.tests.add(testKey(f, ''));
+                    for (const d of input.defects)
+                        if ((defectRoutes.get(d.ref) ?? []).some((x) => sameRoute(row.route, x.route)) || touches(defectChanged.get(d.ref), host, row.route))
+                            pBag.defects.add(d.ref);
+                    if (row.g.specs.size)
+                        pBag.notRun = true;
+                    else
+                        pBag.needsTests = true;
+                }
+                fill(pNode, pBag, changed);
+                sNode.children.push(pNode);
+                sPages.push({ host, route: row.route });
+                union(sBag, pBag);
+            }
+            fill(sNode, sBag);
+            aPages.push(...sPages);
+            addSection(aNode, aBag, sNode, sBag);
+        }
+        appNodes.push({ node: aNode, bag: aBag, host });
+    }
+    // Requirements no page took: one node each, under the app of each dot the requirement belongs to (the first app when
+    // no dot names one, or the root when there is no app). Linked specs mean Not run yet.
+    const left = input.requirements.filter((r) => !placed.has(r.row.ref));
+    if (left.length) {
+        const dotHosts = new Map();
+        const own = (dotId, host) => {
+            if (!dotId || !host || !hosts.includes(host))
+                return;
+            dotHosts.set(dotId, (dotHosts.get(dotId) ?? new Set()).add(host));
+        };
+        for (const a of input.dotApps ?? [])
+            own(a.dotId, a.host);
+        // A dot with no base URL owns the hosts its probes, scanned routes and specs name.
+        const based = new Set((input.dotApps ?? []).map((a) => a.dotId));
+        for (const k of input.knownUrls)
+            if (!based.has(k.dotId ?? ''))
+                own(k.dotId, hostOf(k.url));
+        for (const c of [...input.code, ...(input.specs ?? [])])
+            if (!based.has(c.dotId ?? ''))
+                own(c.dotId, c.host);
+        const byApp = new Map();
+        for (const r of left) {
+            const targets = new Set((r.dots ?? []).flatMap((d) => [...(dotHosts.get(d) ?? [])]));
+            const into = appNodes.filter((a) => targets.has(a.host)).map((a) => a.host);
+            for (const h of into.length ? into : [appNodes[0]?.host ?? ''])
+                byApp.set(h, [...(byApp.get(h) ?? []), r]);
+        }
+        for (const [host, reqs] of byApp) {
+            const parent = appNodes.find((a) => a.host === host);
+            const sNode = make('section', `section:${host}:${NO_PAGE_SECTION}`, NO_PAGE_SECTION);
+            const sBag = bag();
+            const parentPath = parent
+                ? [...(root ? [{ id: root.id, name: root.name }] : []), { id: parent.node.id, name: parent.node.name }]
+                : [{ id: root.id, name: root.name }];
+            index.set(sNode.id, { node: sNode, bag: sBag, path: parentPath, ...(host ? { host } : {}), pages: [] });
+            for (const r of reqs) {
+                const rBag = bag();
+                rBag.reqs.add(r.row.ref);
+                for (const d of r.dots ?? [])
+                    rBag.dots.add(d);
+                for (const d of input.defects)
+                    if (d.requirements.includes(r.row.ref))
+                        rBag.defects.add(d.ref);
+                for (const f of r.specs)
+                    rBag.tests.add(testKey(f, ''));
+                if (r.specs.length)
+                    rBag.notRun = true;
+                else
+                    rBag.needsTests = true;
+                const rNode = make('page', `req:${host}:${r.row.ref}`, `${r.row.key}${r.row.title ? ` ${r.row.title}` : ''}`);
+                fill(rNode, rBag);
+                sNode.children.push(rNode);
+                index.set(rNode.id, { node: rNode, bag: rBag, path: [...parentPath, { id: sNode.id, name: sNode.name }], pages: [] });
+                union(sBag, rBag);
+            }
+            fill(sNode, sBag);
+            if (parent)
+                addSection(parent.node, parent.bag, sNode, sBag);
+            else
+                addSection(root, rootBag, sNode, sBag);
+        }
+    }
+    for (const a of appNodes) {
+        fill(a.node, a.bag);
+        if (root) {
+            root.children.push(a.node);
+            union(rootBag, a.bag);
+        }
+    }
+    if (root)
+        fill(root, rootBag);
+    const tree = root ?? appNodes[0].node;
+    // Gap counts: the pages at or below each node that need tests or a run.
+    const countGaps = (n) => {
+        const g = { needsTests: 0, notRun: 0 };
+        if (n.kind === 'page' && n.status === 'needs_tests')
+            g.needsTests++;
+        if (n.kind === 'page' && n.status === 'not_run')
+            g.notRun++;
+        for (const c of n.children) {
+            const x = countGaps(c);
+            g.needsTests += x.needsTests;
+            g.notRun += x.notRun;
+        }
+        n.counts.gaps = g;
+        return g;
+    };
+    countGaps(tree);
+    const stats = { total: 0, covered: 0, partly: 0, failing: 0, needsTests: 0, notRun: 0 };
+    for (const { node } of index.values()) {
+        stats.total++;
+        stats[STATS_KEY[node.status]]++;
+    }
+    const milestones = [...new Set([...input.requirements.map((r) => r.row.milestone), ...input.defects.map((d) => d.milestone ?? '')].filter(Boolean))].sort(natural);
+    return { map: { tree, stats, milestones, observed: input.observations.length > 0 }, index, input, tests, appHost, hasShot };
+}
+// ---------- the code drawer ----------
+/** Source files of the node's pages and the API routes they called, from the repo scan. Detail only. */
+export function codeOf(m, n) {
+    const files = new Map();
+    for (const pg of n.pages)
+        for (const c of m.input.code) {
+            if (c.method || c.api || !sameRoute(c.route, pg.route))
+                continue;
+            files.set(`${c.repo} ${c.file}`, { repo: c.repo, file: c.file, ...(c.line ? { line: c.line } : {}) });
+        }
+    const api = new Map();
+    for (const req of new Set(n.bag.obs.flatMap((o) => o.requests ?? []))) {
+        const [method, route = ''] = req.split(' ');
+        const c = m.input.code.find((x) => (x.method || x.api) && (!x.method || x.method.toUpperCase() === method) && sameRoute(x.route, route));
+        api.set(req, { ...(method ? { method } : {}), route: c?.route ?? route, ...(c ? { repo: c.repo, file: c.line ? `${c.file}:${c.line}` : c.file } : {}) });
+    }
+    return {
+        files: [...files.values()].sort((a, b) => natural(a.file, b.file)),
+        api: [...api.values()].sort((a, b) => natural(a.route, b.route) || natural(a.method ?? '', b.method ?? '')),
+    };
+}
+const MASCOTS = ['pip', 'nova', 'bolt', 'moss'];
+/** The dot's mascot, else the one its id hashes to: the same hash as the client's mascotFor. */
+export function avatarOf(w) {
+    if (w.mascot && MASCOTS.includes(w.mascot))
+        return w.mascot;
+    let h = 0;
+    for (let i = 0; i < w.id.length; i++)
+        h = (Math.imul(h, 31) + w.id.charCodeAt(i)) | 0;
+    return MASCOTS[Math.abs(h) % MASCOTS.length];
+}
+/** The stage words of a run: "Reviewing PR #34", or "Running tests" without a PR. */
+export function runLabel(kind, pr) {
+    if (pr == null)
+        return kind === 'rerun' ? 'Rerunning tests' : 'Running tests';
+    const word = {
+        pr_check: 'Reviewing',
+        post_merge: 'Testing the merge of',
+        ci_failure: 'Reading the CI failure on',
+        rerun: 'Rerunning',
+    };
+    return `${word[kind] ?? 'Working on'} PR #${pr}`;
+}
+/**
+ * Puts `dots` on every section, page and state node: the dots whose runs visited it, or whose requirement it is.
+ * A dot with a run in progress that has reached the page, or that is on a PR whose changed files hold the page's
+ * source (from the repo scan), carries the run as `running`.
+ */
+export function attachDots(model, dots) {
+    for (const n of model.index.values()) {
+        if (n.node.kind === 'root' || n.node.kind === 'app')
+            continue;
+        const sources = codeOf(model, n).files;
+        const out = [];
+        for (const d of dots) {
+            const run = d.running.find((r) => r.pages.some((p) => n.pages.some((x) => x.host === model.appHost(p.host) && sameRoute(x.route, p.route))) ||
+                r.files.some((f) => sources.some((s) => s.repo === f.repo && samePath(s.file, f.path))));
+            if (!n.bag.dots.has(d.id) && !run)
+                continue;
+            out.push({ id: d.id, name: d.name, avatar: d.avatar, ...(run ? { running: { runId: run.runId, label: run.label } } : {}) });
+        }
+        n.node.dots = out;
+    }
+}
+// ---------- the all-dots map ----------
+/** One input from several dots' facts: observations side by side, requirements and defects merged, the newest test result wins. */
+export function mergeInputs(title, inputs) {
+    const reqs = new Map();
+    const tests = new Map();
+    const defects = new Map();
+    const code = new Map();
+    const uniq = (xs) => [...new Set(xs)];
+    for (const i of inputs) {
+        for (const r of i.requirements) {
+            const had = reqs.get(r.row.ref);
+            if (!had)
+                reqs.set(r.row.ref, { ...r, prs: [...r.prs], specs: [...r.specs], dots: [...(r.dots ?? [])] });
+            else {
+                had.prs = uniq([...had.prs, ...r.prs]);
+                had.specs = uniq([...had.specs, ...r.specs]);
+                had.dots = uniq([...(had.dots ?? []), ...(r.dots ?? [])]);
+            }
+        }
+        for (const t of i.tests) {
+            const k = testKey(t.file, t.title, t.host);
+            const had = tests.get(k);
+            if (!had || (t.at ?? '') > (had.at ?? ''))
+                tests.set(k, t);
+        }
+        for (const d of i.defects) {
+            const had = defects.get(d.ref);
+            if (!had)
+                defects.set(d.ref, { ...d, requirements: [...d.requirements], prs: [...d.prs] });
+            else {
+                had.requirements = uniq([...had.requirements, ...d.requirements]);
+                had.prs = uniq([...had.prs, ...d.prs]);
+                if (had.state === 'unknown')
+                    had.state = d.state;
+            }
+        }
+        for (const c of i.code)
+            code.set(`${c.repo} ${c.host ?? ''} ${c.method ?? ''} ${c.route} ${c.file}`, c);
+    }
+    return {
+        title,
+        baseUrls: uniq(inputs.flatMap((i) => i.baseUrls)),
+        observations: inputs.flatMap((i) => i.observations),
+        tests: [...tests.values()],
+        requirements: [...reqs.values()],
+        defects: [...defects.values()],
+        code: [...code.values()],
+        knownUrls: inputs.flatMap((i) => i.knownUrls),
+        specs: inputs.flatMap((i) => i.specs ?? []),
+        changes: inputs.flatMap((i) => i.changes ?? []),
+        areas: inputs.flatMap((i) => i.areas ?? []),
+        prChanges: inputs.flatMap((i) => i.prChanges ?? []),
+        dotApps: inputs.flatMap((i) => i.dotApps ?? []),
+    };
+}
+// ---------- facts from the database ----------
+const MAX_RUNS = 1000;
+/** The recent runs whose observations make the map. */
+const MAX_OBS_RUNS = 60;
+const MAX_OBS_LINES = 20_000;
+const MAX_SHOTS = 12;
+const FAILED = (c) => c.status === 'failed' || c.status === 'timedOut';
+const prRefOf = (r) => r.trigger?.pr && r.trigger.repo ? `${r.trigger.repo.owner}/${r.trigger.repo.name}#${r.trigger.pr.number}`.toLowerCase() : null;
+const ranTests = (r) => (r.status === 'done' || r.status === 'running') && !!r.report && !r.report.notRun;
+/** Up to three lines a person can repeat: numbered or bulleted steps first, else the first line of the text. */
+export function reproLines(text) {
+    const lines = (text ?? '')
+        .split(/\r?\n/)
+        .map((x) => x.trim())
+        .filter(Boolean);
+    const steps = lines.filter((x) => /^(\d+[.)]|[-*])\s+/.test(x)).map((x) => x.replace(/^(\d+[.)]|[-*])\s+/, ''));
+    return (steps.length ? steps : lines.slice(0, 1)).slice(0, 3).map((x) => x.slice(0, 200));
+}
+/** The observation lines of a run with the run's facts on each. */
+export function observationsOfRun(r) {
+    const pr = prRefOf(r);
+    return readObservations(r.id).map((o) => ({ ...o, runId: r.id, runAt: r.createdAt, ...(pr ? { pr } : {}), dotId: r.watchId }));
+}
+function gatherFacts(w) {
+    const built = buildAll(w);
+    const runs = list('runs', { watchId: w.id }, { orderBy: 'createdAt DESC', limit: MAX_RUNS });
+    // Observations of the recent runs that ran tests.
+    const observations = [];
+    for (const r of runs.filter((x) => ranTests(x) || x.status === 'running').slice(0, MAX_OBS_RUNS)) {
+        if (observations.length >= MAX_OBS_LINES)
+            break;
+        observations.push(...observationsOfRun(r).slice(0, MAX_OBS_LINES - observations.length));
+    }
+    // The latest result of each test: the newest run that holds it, the same reading as flows/testStatus.ts.
+    // A result belongs to the app the dot tests, so two dots on one app share a test (KAT-250).
+    const appHost = w.baseUrl ? hostOf(w.baseUrl) : '';
+    const tests = new Map();
+    for (const r of runs.filter(ranTests)) {
+        for (const c of r.report.cases) {
+            const k = testKey(c.file, c.title, appHost);
+            if (tests.has(k))
+                continue;
+            const result = FAILED(c) ? 'failed' : c.status === 'passed' || c.status === 'flaky' ? 'passed' : 'not_run';
+            tests.set(k, {
+                file: c.file,
+                title: c.title,
+                result,
+                runId: r.id,
+                at: r.createdAt,
+                ...(appHost ? { host: appHost } : {}),
+                ...(FAILED(c) && c.error ? { error: c.error.split('\n')[0].slice(0, 240) } : {}),
+            });
+        }
+    }
+    const requirements = built.all.map((row) => {
+        const s = built.statuses.get(row.ref);
+        const info = built.catalog.get(row.ref);
+        return {
+            row,
+            prs: (s?.prs ?? []).map((p) => p.ref),
+            specs: (s?.specs ?? []).map((x) => x.path),
+            text: `${info?.title ?? row.title}\n${info?.description ?? ''}`,
+            dots: [w.id],
+        };
+    });
+    // Defects: the ones a requirement's status names, the defect issues the dot has read, and localdost' own defect links.
+    const prRefs = new Set(runs.map(prRefOf).filter((p) => !!p));
+    const defects = new Map();
+    const defect = (ref) => {
+        let d = defects.get(ref);
+        if (d)
+            return d;
+        const info = built.catalog.get(ref);
+        const gh = parseIssueRef(ref);
+        const url = info?.url ?? (gh ? issueUrl(gh.full, gh.number) : undefined);
+        d = {
+            ref,
+            key: info?.key ?? (gh ? ref : ref.toUpperCase()),
+            state: info?.state ?? 'unknown',
+            ...(info?.title ? { title: info.title } : {}),
+            ...(url ? { url } : {}),
+            ...(info?.milestone ? { milestone: info.milestone } : {}),
+            repro: reproLines(info?.description),
+            text: `${info?.title ?? ''}\n${info?.description ?? ''}`,
+            requirements: [],
+            prs: [],
+        };
+        defects.set(ref, d);
+        return d;
+    };
+    for (const s of built.statuses.values()) {
+        for (const x of s.defects) {
+            const d = defect(x.ref);
+            if (x.state !== 'unknown')
+                d.state = x.state;
+            if (!d.requirements.includes(s.ref))
+                d.requirements.push(s.ref);
+        }
+    }
+    for (const info of built.catalog.values())
+        if (classify(w, info) === 'defect')
+            defect(info.ref);
+    for (const lk of linksOfWatch(w.id, 5000)) {
+        if (lk.source !== 'defect')
+            continue;
+        const d = defect(lk.fromRef);
+        if (prRefs.has(lk.toRef))
+            d.prs.push(lk.toRef);
+        else if (!d.requirements.includes(lk.toRef))
+            d.requirements.push(lk.toRef);
+    }
+    const rowOf = new Map(built.all.map((r) => [r.ref, r]));
+    for (const d of defects.values()) {
+        const ms = d.milestone ?? d.requirements.map((r) => rowOf.get(r)?.milestone).find(Boolean);
+        if (ms)
+            d.milestone = ms;
+    }
+    // The repo scan: routes with their source files, for the drawer only.
+    const code = [];
+    const specs = [];
+    const areas = [];
+    const host = w.baseUrl ? hostOf(w.baseUrl) : '';
+    const at = host ? { host, dotId: w.id } : { dotId: w.id };
+    for (const repo of watchRepos(w)) {
+        const p = latestProfile(repo.id)?.profile;
+        if (!p)
+            continue;
+        areas.push(...areasOfProfile(p, host, repo.id));
+        for (const sp of p.tests.specs)
+            if (sp.routes.length)
+                specs.push({ file: sp.path, routes: sp.routes, ...at });
+        const apiApps = new Set(p.apps.filter((a) => a.kind === 'api').map((a) => a.id));
+        for (const r of p.routes)
+            code.push({
+                repo: repo.id,
+                route: r.route,
+                file: r.file,
+                ...(r.line ? { line: r.line } : {}),
+                ...(r.method ? { method: r.method.toUpperCase() } : {}),
+                ...(apiApps.has(r.app) || /^\/api(\/|$)/.test(r.route) ? { api: true } : {}),
+                ...at,
+            });
+    }
+    // What merges changed, and when: the source of a page that changed after its latest visit makes it Not run yet.
+    const changes = [];
+    for (const r of runs) {
+        if (r.kind !== 'post_merge')
+            continue;
+        const repo = r.trigger?.repo ? `${r.trigger.repo.owner}/${r.trigger.repo.name}`.toLowerCase() : watchRepos(w)[0]?.id;
+        if (!repo)
+            continue;
+        for (const f of r.diff ?? r.trigger?.inlineDiff ?? [])
+            changes.push({ repo, path: f.path, at: r.createdAt });
+    }
+    // The files each PR changed, from the runs on it: what ties the PR's requirements to pages.
+    const prChanges = new Map();
+    for (const r of runs) {
+        const pr = prRefOf(r);
+        if (!pr)
+            continue;
+        const repo = `${r.trigger.repo.owner}/${r.trigger.repo.name}`.toLowerCase();
+        for (const f of r.diff ?? r.trigger?.inlineDiff ?? [])
+            prChanges.set(`${pr} ${f.path}`, { pr, repo, path: f.path });
+    }
+    return {
+        title: w.name,
+        baseUrls: w.baseUrl ? [w.baseUrl] : [],
+        observations,
+        tests: [...tests.values()],
+        requirements,
+        defects: [...defects.values()],
+        code,
+        knownUrls: (w.probes ?? []).map((p) => ({ url: p.url, dotId: w.id })),
+        specs,
+        changes,
+        areas,
+        prChanges: [...prChanges.values()],
+        ...(host ? { dotApps: [{ dotId: w.id, host }] } : {}),
+    };
+}
+/**
+ * The product areas of a repo profile with their page routes (the area's own list, and the scanned routes tagged
+ * with it) and the path globs of their files.
+ */
+export function areasOfProfile(p, host, repo) {
+    const by = new Map();
+    const get = (id, name) => {
+        const a = by.get(id) ?? { name: name ?? titleCase(id), routes: new Set(), paths: [] };
+        by.set(id, a);
+        return a;
+    };
+    for (const a of p.areas ?? []) {
+        const x = get(a.id, a.name);
+        x.paths.push(...(a.paths ?? []));
+        for (const r of a.routes)
+            x.routes.add(r);
+    }
+    for (const r of p.routes ?? []) {
+        if (!r.area || r.method || /^\/api(\/|$)/.test(r.route))
+            continue;
+        get(r.area, p.areas?.find((a) => a.id === r.area)?.name).routes.add(r.route);
+    }
+    return [...by.values()]
+        .filter((a) => a.routes.size)
+        .map((a) => ({
+        name: a.name,
+        routes: [...a.routes],
+        ...(host ? { host } : {}),
+        ...(a.paths.length ? { paths: a.paths } : {}),
+        ...(a.paths.length && repo ? { repo } : {}),
+    }));
+}
+// ---------- reads ----------
+/** GET /api/dots/:id/trace/map. */
+export function buildTraceMap(w) {
+    const model = mapTree(gatherFacts(w), { hasShot: artifactShotCheck() });
+    attachDots(model, dotFacts(liveDots()));
+    return model;
+}
+const liveDots = () => list('watches').filter((w) => !w.archived);
+/** The presence facts of the dots: their runs in progress, with the pages seen so far and the PR's files. */
+function dotFacts(dots) {
+    const running = list('runs', { status: 'running' }, { orderBy: 'createdAt DESC', limit: 200 });
+    return dots.map((w) => {
+        const repo = watchRepos(w)[0]?.id;
+        return {
+            id: w.id,
+            name: w.name,
+            avatar: avatarOf(w),
+            running: running
+                .filter((r) => r.watchId === w.id)
+                .map((r) => {
+                const runRepo = r.trigger?.repo ? `${r.trigger.repo.owner}/${r.trigger.repo.name}`.toLowerCase() : repo;
+                return {
+                    runId: r.id,
+                    label: runLabel(r.kind, r.trigger?.pr?.number),
+                    pages: readObservations(r.id).map((o) => ({ host: o.host, route: routeOf(o.url || o.route) })),
+                    files: runRepo ? (r.diff ?? r.trigger?.inlineDiff ?? []).map((f) => ({ repo: runRepo, path: f.path })) : [],
+                };
+            }),
+        };
+    });
+}
+/** GET /api/trace/map: every live dot's observed apps on one canvas. */
+export function buildAllDotsMap() {
+    const dots = liveDots();
+    const model = mapTree(mergeInputs(ALL_DOTS, dots.map(gatherFacts)), { hasShot: artifactShotCheck() });
+    attachDots(model, dotFacts(dots));
+    return model;
+}
+export const ALL_DOTS = 'All dots';
+/** The skill scope of the all-dots map: no single dot, so the base URL is the page's app. */
+export const ALL_DOTS_SCOPE = { name: ALL_DOTS };
+const resultWord = { passed: 'Passed', failed: 'Failed', not_run: 'Not run' };
+function testsOf(m, n) {
+    return [...n.bag.tests]
+        .map((k) => {
+        const t = factOf(m.tests, k);
+        const o = n.bag.obs.find((x) => obsKey(x) === k);
+        // A spec that covers a page no run visited has no title: the key is the file alone.
+        const [file = '', title = ''] = k.split('\u0000');
+        const name = t?.title ?? o?.title ?? title;
+        return {
+            path: t?.file ?? o?.test ?? file,
+            ...(name ? { title: name } : {}),
+            result: resultOf(k, m.tests, n.bag.obs),
+            ...(t?.runId ? { runId: t.runId } : o ? { runId: o.runId } : {}),
+            ...(t?.at ? { at: t.at } : {}),
+            ...(t?.error ? { error: t.error } : {}),
+        };
+    })
+        .sort((a, b) => (a.result === 'failed' ? 0 : 1) - (b.result === 'failed' ? 0 : 1) || natural(a.path, b.path) || natural(a.title ?? '', b.title ?? ''));
+}
+const SHOT_RESULT = (r) => r === 'passed' ? 'passed' : r === 'failed' || r === 'timedOut' ? 'failed' : r ? 'not_run' : undefined;
+/** One screenshot per test per route, the latest, with the test's result in that run. Newest first. */
+function shotsOf(m, n) {
+    const seen = new Set();
+    return n.bag.obs
+        .filter((o) => !!o.screenshot && m.hasShot(o.runId, o.screenshot))
+        .sort((a, b) => b.at.localeCompare(a.at))
+        .filter((o) => {
+        const k = `${obsKey(o)}\u0000${routeOf(o.url || o.route)}`;
+        return seen.has(k) ? false : (seen.add(k), true);
+    })
+        .slice(0, MAX_SHOTS)
+        .map((o) => {
+        const result = SHOT_RESULT(o.result) ?? resultOf(obsKey(o), m.tests, n.bag.obs);
+        return {
+            url: artifactUrl(o.runId, o.screenshot),
+            name: o.screenshot,
+            runId: o.runId,
+            spec: o.test,
+            test: o.title,
+            route: routeOf(o.url || o.route),
+            at: o.at,
+            result,
+        };
+    });
+}
+/** Spec files of the tests at or below a node: what Run tests runs. */
+export function specsOf(n) {
+    return [...new Set([...n.bag.tests].map((k) => k.split('\u0000')[0]).filter(Boolean))].sort(natural);
+}
+/** The pages at or below a node, itself included, that need tests or a run. */
+export function gapsOf(m, n) {
+    const out = [];
+    const walk = (x) => {
+        const e = m.index.get(x.id);
+        if (e && x.kind === 'page' && isGap(x.status))
+            out.push({
+                id: x.id,
+                name: x.name,
+                ...(x.route ? { route: x.route } : {}),
+                status: x.status,
+                ...(e.changed ? { changed: true } : {}),
+                specs: specsOf(e),
+            });
+        for (const c of x.children)
+            walk(c);
+    };
+    walk(n.node);
+    return out;
+}
+/** A code span that cannot be broken out of: backticks become quotes. */
+const code = (s) => `\`${s.replace(/`/g, "'").replace(/\s+/g, ' ')}\``;
+const joinUrl = (base, route) => `${base.replace(/\/+$/, '')}/${route.replace(/^\/+/, '')}`;
+/** The base URL of a node's app: the dot's own when it is on that host, else the origin a run saw. */
+function baseOf(w, n) {
+    if (w.baseUrl && (!n.host || hostOf(w.baseUrl) === n.host))
+        return w.baseUrl;
+    const seen = n.bag.obs.find((o) => o.url)?.url;
+    if (seen) {
+        try {
+            return new URL(seen).origin;
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return w.baseUrl;
+}
+const uniqBy = (xs, key) => {
+    const seen = new Set();
+    return xs.filter((x) => (seen.has(key(x)) ? false : (seen.add(key(x)), true)));
+};
+/** Headings and landmarks of the newest observations of a node. */
+function onPage(n) {
+    const obs = [...n.bag.obs].sort((a, b) => b.at.localeCompare(a.at));
+    return {
+        headings: uniqBy(obs.flatMap((o) => o.headings.map((h) => `h${h.level} ${h.text}`)), (x) => x).slice(0, 12),
+        landmarks: [...new Set(obs.flatMap((o) => o.landmarks))].slice(0, 12),
+        urls: [...new Set(obs.map((o) => o.url))].slice(0, 5),
+        titles: [...new Set(obs.map((o) => o.pageTitle).filter((t) => !!t))].slice(0, 3),
+    };
+}
+/** Markdown an agent can follow for one node, from observations only. `depth` 1 makes the title an h1. */
+export function nodeSkill(w, m, n, depth = 1) {
+    const h = (k) => '#'.repeat(Math.min(6, depth + k - 1));
+    const c = n.node.counts;
+    const tests = testsOf(m, n);
+    const defects = [...n.bag.defects].map((r) => m.input.defects.find((d) => d.ref === r)).filter(Boolean);
+    const open = defects.filter((d) => d.state === 'open');
+    const kind = { root: 'Map', app: 'App', section: 'Section', page: 'Page', state: 'State' }[n.node.kind];
+    const seen = onPage(n);
+    const out = [
+        `${h(1)} ${kind}: ${mdText(n.node.name)}`,
+        '',
+        `Status: ${STATUS_WORD[n.node.status]}. ${c.tests.passed} of ${c.tests.total} tests passed, ${c.tests.failed} failed, ${c.defects.open} open ${c.defects.open === 1 ? 'bug' : 'bugs'}, ${c.requirements} ${c.requirements === 1 ? 'requirement' : 'requirements'}.`,
+        `Node id: \`${n.node.id}\`${n.path.length ? `. Path: ${n.path.map((p) => mdText(p.name)).join(' > ')} > ${mdText(n.node.name)}` : ''}`,
+        '',
+        `${h(2)} How to reach it`,
+        '',
+    ];
+    const base = baseOf(w, n);
+    out.push(`- ${base ? `App base URL: ${mdText(base)}` : 'App base URL: not set on the dot. Set it in the dot settings.'}`);
+    if (n.node.route && n.node.kind !== 'section') {
+        const open = base && !/[:[{*]/.test(n.node.route) ? `, open ${mdLink(joinUrl(base, n.node.route), joinUrl(base, n.node.route))}` : '';
+        out.push(`- Route: \`${n.node.route}\`${open}`);
+    }
+    else if (n.node.kind === 'section' || n.node.kind === 'app') {
+        const pages = n.pages.map((p) => `\`${p.route}\``);
+        if (pages.length)
+            out.push(`- Pages: ${pages.join(', ')}`);
+    }
+    if (n.node.status === 'needs_tests')
+        out.push('- No test covers it yet, and no run has visited it. Write a test that opens it: the next run adds what is on it, a screenshot, and the steps.');
+    if (n.node.status === 'not_run')
+        out.push(n.changed
+            ? '- Its source changed after the latest run that visited it. Run its tests again.'
+            : `- Tests cover it, but no run has executed them yet. Run them: ${specsOf(n)
+                .map((f) => `\`${f}\``)
+                .join(', ')}.`);
+    for (const u of seen.urls.slice(0, 3))
+        out.push(`- Seen at ${mdText(u)}`);
+    // The clicks tests used to get here, with the page they came from.
+    const ways = uniqBy(n.bag.obs.filter((o) => o.action), (o) => `${o.from ?? ''} ${o.action}`).slice(0, 4);
+    for (const o of ways)
+        out.push(`- ${o.from ? `From \`${o.from}\`: ` : ''}${code(o.action)} (${mdText(o.title)})`);
+    if (n.node.kind === 'page' || n.node.kind === 'state') {
+        out.push('', `${h(2)} What is on it`, '');
+        if (!n.bag.obs.length)
+            out.push('Not seen yet.');
+        else {
+            if (seen.titles.length)
+                out.push(`- Page title: ${seen.titles.map(mdText).join(' / ')}`);
+            out.push(`- Headings: ${seen.headings.length ? seen.headings.map(mdText).join('; ') : 'none seen'}`);
+            out.push(`- Landmarks: ${seen.landmarks.length ? seen.landmarks.map(mdText).join(', ') : 'none seen'}`);
+            const states = n.node.children.filter((x) => x.kind === 'state').map((x) => mdText(x.name));
+            if (states.length)
+                out.push(`- States: ${states.join('; ')}`);
+            const reqs = [...new Set(n.bag.obs.flatMap((o) => o.requests ?? []))].slice(0, 10);
+            if (reqs.length)
+                out.push(`- Requests: ${reqs.map((r) => `\`${r}\``).join(', ')}`);
+        }
+    }
+    out.push('', `${h(2)} Tests that cover it`, '');
+    if (!tests.length)
+        out.push('No test has visited it yet.');
+    else {
+        out.push('| Test | Spec | Last result | Run |', '|---|---|---|---|');
+        for (const t of tests)
+            out.push(`| ${mdText(t.title ?? '')} | \`${t.path}\` | ${resultWord[t.result]} | ${t.runId ? `\`${t.runId}\`` : '-'} |`);
+    }
+    out.push('', `${h(2)} Open bugs`, '');
+    if (!open.length)
+        out.push('None open.');
+    for (const d of open) {
+        out.push(`- ${mdLink(`${d.key}${d.title ? ` ${d.title}` : ''}`, d.url)}`);
+        for (const r of d.repro)
+            out.push(`  - Repro: ${mdText(r)}`);
+    }
+    // Gotchas: steps that failed on this page, then failed tests that visited it.
+    const failedSteps = uniqBy(n.bag.obs.flatMap((o) => (o.steps ?? []).filter((s) => s.error).map((s) => ({ step: s.title, error: s.error }))), (x) => `${x.step} ${x.error}`).slice(0, 6);
+    const failedTests = tests.filter((t) => t.result === 'failed' && t.error && !failedSteps.some((s) => s.error === t.error));
+    out.push('', `${h(2)} Known gotchas`, '');
+    if (!failedSteps.length && !failedTests.length)
+        out.push('None seen in the latest results.');
+    for (const s of failedSteps)
+        out.push(`- ${code(s.step)} failed: ${mdText(s.error)}`);
+    for (const t of failedTests)
+        out.push(`- \`${t.path}\` failed: ${mdText(t.error)}`);
+    const shot = shotsOf(m, n)[0];
+    out.push('', `${h(2)} Latest screenshot`, '', shot ? `${shot.url} (run \`${shot.runId}\`, ${shot.at.slice(0, 16).replace('T', ' ')} UTC)` : 'None yet.');
+    const reqs = [...n.bag.reqs].map((r) => m.input.requirements.find((x) => x.row.ref === r)?.row).filter((r) => !!r);
+    if (reqs.length) {
+        out.push('', `${h(2)} Requirements`, '');
+        for (const r of reqs)
+            out.push(`- ${mdLink(`${r.key}${r.title ? ` ${r.title}` : ''}`, r.url)}: ${mdText(r.status)}`);
+    }
+    const scan = codeOf(m, n);
+    if (scan.files.length || scan.api.length) {
+        out.push('', `${h(2)} Code`, '');
+        for (const f of scan.files.slice(0, 10))
+            out.push(`- Source: \`${f.file}${f.line ? `:${f.line}` : ''}\` (${mdText(f.repo)})`);
+        for (const a of scan.api.slice(0, 10))
+            out.push(`- API: \`${a.method ? `${a.method} ` : ''}${a.route}\`${a.file ? ` in \`${a.file}\`` : ''}`);
+    }
+    out.push('');
+    return out.join('\n');
+}
+/** GET /api/dots/:id/trace/map/:nodeId and GET /api/trace/map/:nodeId. Null when the node is not in the tree. */
+export function traceMapDetail(w, id, model) {
+    const n = model.index.get(id);
+    if (!n)
+        return null;
+    const { children, ...node } = n.node;
+    const seen = onPage(n);
+    return {
+        node: {
+            ...node,
+            path: n.path,
+            children: children.map((x) => ({ id: x.id, name: x.name, kind: x.kind, status: x.status })),
+            urls: seen.urls,
+            headings: seen.headings,
+            landmarks: seen.landmarks,
+        },
+        requirements: [...n.bag.reqs]
+            .map((r) => model.input.requirements.find((x) => x.row.ref === r))
+            .filter((r) => !!r)
+            .map((r) => ({ ...r.row, ...(r.dots?.length ? { dotIds: [...r.dots] } : {}) })),
+        tests: testsOf(model, n),
+        defects: [...n.bag.defects]
+            .map((r) => model.input.defects.find((d) => d.ref === r))
+            .filter(Boolean)
+            .sort((a, b) => (a.state === 'open' ? 0 : 1) - (b.state === 'open' ? 0 : 1) || natural(a.key, b.key))
+            .map(({ text: _t, requirements: _r, prs: _p, ...d }) => d),
+        screenshots: shotsOf(model, n),
+        gaps: gapsOf(model, n),
+        code: codeOf(model, n),
+        skill: nodeSkill(w, model, n),
+    };
+}
+/** GET /api/dots/:id/trace/map/skill.md (and the all-dots one): a router (the tree with status and ids), then one section per page and state. */
+export function traceMapSkill(w, model) {
+    const out = [
+        `# App map: ${mdText(w.name)}`,
+        '',
+        'The app as the test runs saw it. Find the page for your task in the router, then read its section: how to reach it, what is on it, the tests that cover it, open bugs, and known gotchas.',
+        '',
+        '## Router',
+        '',
+    ];
+    const walk = (n, depth) => {
+        out.push(`${'  '.repeat(depth)}- ${mdText(n.name)} (${n.kind}): ${STATUS_WORD[n.status]}, ${n.counts.tests.passed}/${n.counts.tests.total} tests, ${n.counts.defects.open} open bugs. \`${n.id}\``);
+        for (const c of n.children)
+            walk(c, depth + 1);
+    };
+    walk(model.map.tree, 0);
+    out.push('');
+    for (const n of model.index.values())
+        if (n.node.kind === 'page' || n.node.kind === 'state')
+            out.push(nodeSkill(w, model, n, 2));
+    return out.join('\n');
+}
+/**
+ * POST .../trace/map/:nodeId/run: queues a rerun job of the dot with the spec files that cover the node. A node no
+ * test covers has nothing to run: 409 with the next step in words.
+ */
+export function queueNodeRun(w, model, id) {
+    const n = model.index.get(id);
+    if (!n)
+        return { code: 404, body: { error: "no such node in this dot's map" } };
+    const specs = specsOf(n);
+    if (!specs.length)
+        return { code: 409, body: { error: 'No test covers this part yet. Write a test for it first.' } };
+    const minute = new Date().toISOString().slice(0, 16);
+    const jobId = enqueue({
+        kind: 'rerun',
+        watchId: w.id,
+        dedupeKey: `rerun:${w.id}:map:${id}:${minute}`,
+        payload: { specs, requestedBy: 'user' },
+    });
+    if (!jobId)
+        return { code: 200, body: { queued: false, specs, reason: 'The same tests were queued in the last minute.' } };
+    return { code: 202, body: { queued: true, jobId, specs } };
+}
+//# sourceMappingURL=trace-map.js.map