tinybeeai 0.0.0-stage → 0.16.1

package/dist/refs.js

@@ -0,0 +1,756 @@
+// Titled references (KAT-225). Every reference a person reads (a PR, an issue, a ticket in Jira, Linear,
+// or GitHub Issues, a run, a defect) shows a short plain title with its link embedded, never a bare number
+// such as "PR #30" or "KAT-142":
+//
+//   markdown  [Queued checks show at once (#30)](https://github.com/acme/shop/pull/30)
+//   mrkdwn    <https://github.com/acme/shop/pull/30|Queued checks show at once (#30)>
+//   text      Queued checks show at once (#30)          (push, voice, Activity rows: no link syntax)
+//
+// renderRefs() is the post-processor every model answer passes through (web chat, Slack, voice, digests,
+// notifications). It finds bare references, looks the title up (cache, then the dot's GitHub data and the
+// connected tracker, then the runs already stored), and rewrites them. A reference with a keyword
+// ("PR #999") that no source knows becomes a plain link when its repo is certain; anything else is left as
+// written. Code, existing links, and URLs it cannot title are never touched, so a second pass changes nothing.
+import { config, liveEnv, log } from './config.js';
+import { get, list } from './db.js';
+import { watchRepos } from './repos.js';
+import { trackerProjectKeys } from './ticket-keys.js';
+// ---------- cache ----------
+const HIT_TTL_MS = 10 * 60_000;
+const MISS_TTL_MS = 60_000;
+const CACHE_CAP = 500;
+const LOOKUP_TIMEOUT_MS = 3000;
+const MAX_REPOS = 6;
+const MAX_TITLE = 80;
+const cache = new Map();
+function cacheGet(key) {
+    const e = cache.get(key);
+    if (!e)
+        return undefined;
+    if (Date.now() - e.at > (e.hit ? HIT_TTL_MS : MISS_TTL_MS)) {
+        cache.delete(key);
+        return undefined;
+    }
+    return e.hit;
+}
+function cachePut(key, hit) {
+    cache.delete(key);
+    cache.set(key, { at: Date.now(), hit });
+    if (cache.size > CACHE_CAP) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    }
+}
+const inflight = new Map();
+/** Two references to the same item in one answer share one lookup. */
+function once(key, fn) {
+    const running = inflight.get(key);
+    if (running)
+        return running;
+    const p = fn().finally(() => inflight.delete(key));
+    inflight.set(key, p);
+    return p;
+}
+/** Forgets every cached title. Tests call it between cases. */
+export function clearRefCache() {
+    cache.clear();
+}
+let depsOverride;
+/** Test and eval seam: answer lookups from `d` instead of GitHub and the trackers. Pass undefined to reset. */
+export function setRefDeps(d) {
+    depsOverride = d;
+    cache.clear();
+}
+// ---------- titles ----------
+/**
+ * Untrusted text (a PR, ticket, finding or action title, test output) made safe to join into Markdown that
+ * toMrkdwn turns into Slack mrkdwn: `[` and `]` become full-width look-alikes, so `[x](https://evil)` cannot
+ * parse as a link and only the links the server builds become Slack links.
+ */
+export function mdText(s) {
+    return s.replace(/\[/g, '\uff3b').replace(/\]/g, '\uff3d');
+}
+/** A short plain title: one line, no brackets, no trailing "(#30)" a squash merge adds, at most 80 characters. */
+export function cleanTitle(raw) {
+    const one = raw
+        .replace(/\s+/g, ' ')
+        .replace(/\[/g, '(')
+        .replace(/\]/g, ')')
+        .replace(/\s*\((?:#\d+|[A-Z][A-Z0-9]{1,9}-\d+)\)\s*$/, '')
+        .trim()
+        .replace(/[.:;,]+$/, '');
+    return one.length > MAX_TITLE ? `${one.slice(0, MAX_TITLE - 3).trimEnd()}...` : one;
+}
+/** The short plain title of the PR a trigger is about, or an empty string. */
+export function prTitleOf(t) {
+    return t?.title ? cleanTitle(stripPrefix(t.title)) : '';
+}
+/** "PR #12: Fix it", "Merged PR #12: Fix it", "Merge #12: Fix it" -> "Fix it". */
+function stripPrefix(title) {
+    return title.replace(/^\s*(?:merged\s+)?(?:PR|pull request|merge)\s*#?\d+\s*[:\-–—]?\s*/i, '').trim();
+}
+const RUN_LABEL = {
+    workflow: 'Workflow run',
+    pr_check: 'PR check',
+    post_merge: 'Merge check',
+    ci_failure: 'CI failure triage',
+    ticket_review: 'Ticket review',
+    outage: 'Outage',
+    recovery: 'Recovery',
+    digest: 'Daily digest',
+    rerun: 'Test rerun',
+    repo_scan: 'Repo scan',
+    test_design: 'Test design',
+    nightly_run: 'Nightly test run',
+};
+/** The title a person sees for a run: what it did and what it was about. */
+export function runTitle(run) {
+    const label = RUN_LABEL[run.kind] ?? 'Run';
+    const raw = run.trigger?.title ? stripPrefix(run.trigger.title).replace(/^[A-Z][A-Z0-9]{1,9}-\d+\s*:\s*/, '') : '';
+    // The nightly run's trigger title is "Nightly, Thu 22 Oct, 02:00": the label and the time, said once.
+    if (raw && run.kind === 'nightly_run')
+        return cleanTitle(`${label}, ${raw.replace(/^Nightly,\s*/i, '')}`);
+    if (raw && run.kind !== 'digest')
+        return cleanTitle(`${label}: ${raw}`);
+    return `${label}, ${run.createdAt.slice(0, 10)}`;
+}
+const webBase = () => (liveEnv.GITHUB_SERVER_URL ?? 'https://github.com').replace(/\/$/, '');
+function runUrl(id, absolute) {
+    if (!absolute)
+        return `/#/runs/${id}`;
+    const base = config.publicUrl?.replace(/\/$/, '');
+    return base ? `${base}/#/runs/${id}` : undefined;
+}
+// ---------- stored runs ----------
+function repoOfRun(r, watchOf) {
+    const t = r.trigger?.repo;
+    if (t?.owner && t.name)
+        return `${t.owner}/${t.name}`.toLowerCase();
+    const w = watchOf(r.watchId);
+    const first = w ? watchRepos(w)[0] : undefined;
+    return first ? first.id.toLowerCase() : undefined;
+}
+/** Titles of the PRs and tickets that the given runs were about. Newest run wins. */
+export function buildRefIndex(runs, watchOf = (id) => get('watches', id)) {
+    const idx = { prs: new Map(), tickets: new Map() };
+    for (const r of runs) {
+        const t = r.trigger;
+        if (!t)
+            continue;
+        if (t.pr) {
+            const repo = repoOfRun(r, watchOf);
+            const title = cleanTitle(stripPrefix(t.title ?? ''));
+            const key = repo ? `${repo}#${t.pr.number}` : '';
+            if (key && title && !idx.prs.has(key)) {
+                const url = t.url && /\/pull\/\d+/.test(t.url) ? t.url : `${webBase()}/${repo}/pull/${t.pr.number}`;
+                idx.prs.set(key, { title, url, id: `#${t.pr.number}`, kind: 'pr' });
+            }
+        }
+        if (t.ticket) {
+            const key = t.ticket.key.toUpperCase();
+            const raw = t.inlineTicket?.title ?? (t.title ?? '').replace(new RegExp(`^\\s*${escapeRe(t.ticket.key)}\\s*[:\\-–—]?\\s*`, 'i'), '');
+            const title = cleanTitle(raw);
+            if (title && !idx.tickets.has(key)) {
+                const url = t.inlineTicket?.url ?? (t.url && !/\/pull\/\d+/.test(t.url) ? t.url : undefined);
+                idx.tickets.set(key, { title, ...(url ? { url } : {}), id: t.ticket.key, kind: 'ticket' });
+            }
+        }
+    }
+    return idx;
+}
+/** A trigger's title with its number moved behind the title: "Fix it (#12)", "Review it (KAT-3)". */
+export function titledTrigger(t) {
+    const trig = t;
+    if (!trig || typeof trig.title !== 'string')
+        return undefined;
+    if (trig.pr) {
+        const title = cleanTitle(stripPrefix(trig.title));
+        return title ? `${title} (#${trig.pr.number})` : undefined;
+    }
+    if (trig.ticket) {
+        const title = cleanTitle(trig.title.replace(new RegExp(`^\\s*${escapeRe(trig.ticket.key)}\\s*[:\\-–—]?\\s*`, 'i'), ''));
+        return title ? `${title} (${trig.ticket.key})` : undefined;
+    }
+    return undefined;
+}
+function localIndex(watches) {
+    const runs = [];
+    const per = Math.max(40, Math.floor(300 / Math.max(1, watches.length)));
+    for (const w of watches)
+        runs.push(...list('runs', { watchId: w.id }, { orderBy: 'id DESC', limit: per }));
+    runs.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const byId = new Map(watches.map((w) => [w.id, w]));
+    return buildRefIndex(runs, (id) => byId.get(id) ?? get('watches', id));
+}
+// ---------- finding references ----------
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Places the rewriter never edits: code, links, angle brackets, URLs, HTML entities. */
+const PROTECT = new RegExp([
+    String.raw `(?<fence>\x60{3}[\s\S]*?(?:\x60{3}|$))`,
+    String.raw `(?<code>\x60[^\x60\n]+\x60)`,
+    String.raw `(?<mdlink>(?<!!)\[(?<ltext>[^\]\n]*)\]\((?<lurl>[^)\s]*)(?:\s+"[^"]*")?\))`,
+    String.raw `(?<angle><[^>\n]+>)`,
+    String.raw `(?<url>https?://[^\s<>)\]]+)`,
+    String.raw `(?<entity>&#?\w+;)`,
+].join('|'), 'g');
+const KW = String.raw `(?:PRs?|pull\s+requests?|merged?|issues?|defects?|bugs?)`;
+const REF = new RegExp([
+    String.raw `(?<![\w./-])(?<repo>[\w.-]+/[\w.-]+)#(?<rn>\d{1,6})(?![\w-])`,
+    String.raw `(?:(?<kw>\b${KW})\s+)?(?<![\w&/])#(?<n>\d{1,6})(?![\w-])`,
+    String.raw `(?<kw2>\b(?:PR|pull\s+request))\s+(?<n2>\d{1,6})(?![\w-])`,
+    String.raw `(?<![\w/#.-])(?<key>[A-Z][A-Z0-9]{1,9}-\d{1,9})(?![\w-])`,
+    String.raw `(?:(?<rkw>\bruns?)\s+)?(?<![\w-])(?<rid>(?=[0-9a-z]*\d)[0-9a-z]{18})(?![\w-])`,
+    // A commit: 7 to 40 lower-case hex characters. Without the word "commit" it needs a digit and a letter, so a count, a date, or a word is not a sha.
+    String.raw `(?:(?<ckw>\bcommits?)\s+)?(?<![\w./#-])(?<sha>[0-9a-f]{7,40})(?![\w.-]*\w)`,
+].join('|'), 'gi');
+const PR_URL = /^https?:\/\/([^/]+)\/([\w.-]+)\/([\w.-]+)\/(pull|issues)\/(\d{1,9})(?:[/?#].*)?$/i;
+const JIRA_URL = /^https?:\/\/[^/]+\/(?:browse\/|[^\s]*?[?&](?:selectedIssue|issueKey)=)([A-Z][A-Z0-9_]{0,19}-\d{1,9})(?:[/?#&].*)?$/;
+const LINEAR_URL = /^https?:\/\/linear\.app\/[\w-]+\/issue\/([A-Z][A-Z0-9]{0,9}-\d{1,9})(?:[/?#].*)?$/;
+function trackerPrefixes(w) {
+    return trackerProjectKeys(w);
+}
+function wantOf(kw) {
+    if (!kw)
+        return undefined;
+    return /^(issue|defect|bug)/i.test(kw) ? 'issue' : 'pr';
+}
+/** Reads one reference that spans exactly `s` (a link text), or null. */
+function wholeRef(s, scope) {
+    const t = s.trim();
+    if (!t)
+        return null;
+    const re = new RegExp(REF.source, 'i');
+    const m = re.exec(t);
+    if (!m || m.index !== 0 || m[0].length !== t.length)
+        return null;
+    return fromMatch(m, scope);
+}
+function fromMatch(m, scope) {
+    const g = m.groups ?? {};
+    if (g.repo)
+        return { kind: 'num', n: Number(g.rn), repo: g.repo.toLowerCase(), keyworded: true };
+    if (g.n)
+        return { kind: 'num', n: Number(g.n), ...(g.kw ? { want: wantOf(g.kw), keyworded: true } : {}) };
+    if (g.n2)
+        return { kind: 'num', n: Number(g.n2), want: 'pr', keyworded: true };
+    if (g.key) {
+        // Ticket keys are upper case, and the prefix must belong to a tracker the dots use.
+        if (g.key !== g.key.toUpperCase() || !scope.prefixes.has(g.key.split('-')[0]))
+            return null;
+        return { kind: 'ticket', key: g.key };
+    }
+    if (g.rid) {
+        if (g.rid !== g.rid.toLowerCase())
+            return null;
+        return { kind: 'run', id: g.rid };
+    }
+    if (g.sha) {
+        if (g.sha !== g.sha.toLowerCase())
+            return null;
+        if (!g.ckw && !(/\d/.test(g.sha) && /[a-f]/.test(g.sha)))
+            return null;
+        return { kind: 'commit', sha: g.sha, ...(g.ckw ? { keyworded: true } : {}) };
+    }
+    return null;
+}
+function fromUrl(url) {
+    const gh = PR_URL.exec(url);
+    if (gh) {
+        const host = gh[1].toLowerCase();
+        let web = 'github.com';
+        try {
+            web = new URL(webBase()).host.toLowerCase();
+        }
+        catch {
+            /* keep github.com */
+        }
+        if (host !== 'github.com' && host !== web)
+            return null;
+        return { kind: 'num', n: Number(gh[5]), repo: `${gh[2]}/${gh[3]}`.toLowerCase(), want: gh[4].toLowerCase() === 'pull' ? 'pr' : 'issue', keyworded: true };
+    }
+    const key = JIRA_URL.exec(url)?.[1] ?? LINEAR_URL.exec(url)?.[1];
+    if (key && !/^https?:\/\/(?:www\.)?github\.com\//i.test(url))
+        return { kind: 'ticket', key: key.toUpperCase() };
+    return null;
+}
+function collect(text, scope) {
+    const out = [];
+    const free = (from, to) => {
+        if (to <= from)
+            return;
+        const re = new RegExp(REF.source, 'gi');
+        re.lastIndex = from;
+        for (let m = re.exec(text); m && m.index < to; m = re.exec(text)) {
+            if (m.index + m[0].length > to)
+                break;
+            const c = fromMatch(m, scope);
+            if (c)
+                out.push({ ...c, start: m.index, end: m.index + m[0].length, text: m[0], mode: 'plain' });
+            if (m[0].length === 0)
+                re.lastIndex++;
+        }
+    };
+    let last = 0;
+    for (const m of text.matchAll(PROTECT)) {
+        const g = m.groups ?? {};
+        const start = m.index ?? 0;
+        free(last, start);
+        last = start + m[0].length;
+        if (g.mdlink) {
+            // [#30](url): the link text is a bare number. Give it a title and keep the link.
+            const c = wholeRef(g.ltext ?? '', scope);
+            if (c) {
+                // A link that already points into a repo names it: the number belongs to that repo, not to the dot's primary one.
+                const target = c.kind === 'num' && !c.repo && g.lurl ? fromUrl(g.lurl) : null;
+                const named = target?.kind === 'num' && target.repo ? { repo: target.repo, ...(target.want ? { want: target.want } : {}) } : {};
+                out.push({ ...c, ...named, start, end: last, text: g.ltext ?? '', mode: 'mdlink', givenUrl: g.lurl });
+            }
+        }
+        else if (g.url) {
+            // A bare URL: strip the punctuation a sentence puts after it.
+            const trail = /[.,;:!?]+$/.exec(g.url)?.[0] ?? '';
+            const url = trail ? g.url.slice(0, -trail.length) : g.url;
+            const c = fromUrl(url);
+            if (c)
+                out.push({ ...c, start, end: start + url.length, text: url, mode: 'url', givenUrl: url });
+        }
+    }
+    free(last, text.length);
+    return out.sort((a, b) => a.start - b.start);
+}
+function withTimeout(p, ms = LOOKUP_TIMEOUT_MS) {
+    let timer;
+    const limit = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ms);
+        timer.unref?.();
+    });
+    return Promise.race([p, limit]).finally(() => clearTimeout(timer));
+}
+function repoCandidates(c, scope) {
+    const out = [];
+    const seen = new Set();
+    for (const w of scope.watches) {
+        const repos = watchRepos(w);
+        const extra = w.tracker?.kind === 'github' ? (w.tracker.repos ?? []).map((r) => r.toLowerCase()) : [];
+        const ids = [...repos.map((r) => r.id.toLowerCase()), ...extra];
+        ids.forEach((id, i) => {
+            if (seen.has(id) || (c.repo && c.repo !== id))
+                return;
+            seen.add(id);
+            out.push({ repo: id, watch: w, primary: i === 0 });
+        });
+    }
+    return out.slice(0, MAX_REPOS);
+}
+const prUrl = (repo, n, kind) => `${webBase()}/${repo}/${kind === 'pr' ? 'pull' : 'issues'}/${n}`;
+async function defaultDeps() {
+    const gh = await import('./integrations/github.js');
+    const issues = await import('./integrations/github-issues.js');
+    const tickets = await import('./review/ticket-on-demand.js');
+    return {
+        async pull(repo, n, watch) {
+            const [owner, name] = repo.split('/');
+            const found = await gh.githubFor(watch, { repo: { owner, name } }).getPull(n);
+            return found ? { title: found.summary.title, ...(found.summary.url ? { url: found.summary.url } : {}) } : null;
+        },
+        async issue(repo, n) {
+            if (gh.githubMode() === 'demo')
+                return null;
+            try {
+                const t = await issues.issueApi(repo).getIssue(n);
+                return { title: t.title, ...(t.url ? { url: t.url } : {}) };
+            }
+            catch {
+                return null;
+            }
+        },
+        async commit(repo, sha, watch) {
+            const [owner, name] = repo.split('/');
+            const found = await gh.githubFor(watch, { repo: { owner, name } }).getCommit(sha);
+            const title = found?.message.split('\n', 1)[0] ?? '';
+            return found && title ? { title, ...(found.url ? { url: found.url } : {}) } : null;
+        },
+        async ticket(key, watch) {
+            const parsed = tickets.parseTicketInput(key, watch);
+            if (!parsed.ok)
+                return null;
+            const res = await tickets.fetchTicketRef(watch, parsed.ref);
+            return res.ok ? { title: res.ticket.title, ...(res.ticket.url ? { url: res.ticket.url } : {}) } : null;
+        },
+    };
+}
+let defaults;
+async function deps() {
+    defaults ??= defaultDeps();
+    const base = await defaults;
+    return { ...base, ...depsOverride };
+}
+/** One repo, one number: cache, then GitHub, then the stored runs. A pull request is tried before an issue unless the text said issue. */
+function lookupNumber(repo, n, watch, want, scope, remote) {
+    return once(`num:${repo}#${n}:${want ?? ''}:${remote}`, () => lookupNumberOnce(repo, n, watch, want, scope, remote));
+}
+async function lookupNumberOnce(repo, n, watch, want, scope, remote) {
+    const key = `num:${repo}#${n}:${want ?? ''}`;
+    const cached = cacheGet(key);
+    if (cached !== undefined)
+        return cached;
+    let hit = null;
+    const order = want === 'issue' ? ['issue', 'pr'] : ['pr', 'issue'];
+    if (remote) {
+        const d = await deps();
+        for (const kind of order) {
+            try {
+                const found = await withTimeout(kind === 'pr' ? d.pull(repo, n, watch) : d.issue(repo, n, watch));
+                const title = found ? cleanTitle(found.title) : '';
+                if (found && title) {
+                    hit = { title, url: found.url ?? prUrl(repo, n, kind), id: `#${n}`, kind };
+                    break;
+                }
+            }
+            catch (err) {
+                log.warn(`refs: could not read ${repo}#${n}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    hit ??= scope.index.prs.get(`${repo}#${n}`) ?? null;
+    if (remote)
+        cachePut(key, hit);
+    return hit;
+}
+async function resolveNumber(c, scope, remote) {
+    const n = c.n;
+    const cands = repoCandidates(c, scope);
+    // owner/name#N for a repo no dot holds: the stored runs may still know it.
+    if (!cands.length && c.repo) {
+        const local = scope.index.prs.get(`${c.repo}#${n}`);
+        return local ? { hit: local } : { plainUrl: prUrl(c.repo, n, c.want ?? 'pr'), repo: c.repo };
+    }
+    if (!cands.length)
+        return {};
+    const hits = (await Promise.all(cands.map(async (r) => ({ r, hit: await lookupNumber(r.repo, n, r.watch, c.want, scope, remote) })))).filter((x) => x.hit);
+    if (hits.length === 1)
+        return { hit: hits[0].hit };
+    if (hits.length > 1) {
+        // The same number in two repos: the dot's primary repo wins when only it matches; otherwise the text is ambiguous.
+        const primary = hits.filter((h) => h.r.primary);
+        if (scope.watches.length === 1 && primary.length === 1)
+            return { hit: primary[0].hit };
+        return {};
+    }
+    // Nobody knows it. With a keyword and one possible repo the link is still certain.
+    return c.keyworded && cands.length === 1 ? { plainUrl: prUrl(cands[0].repo, n, c.want ?? 'pr'), repo: cands[0].repo } : {};
+}
+/**
+ * The cache key of a ticket. The same key can name different tickets in different trackers (SHOP-12 in two Jira
+ * sites), and each dot reads its own tracker, so the key also names the dots that answer for it.
+ */
+function ticketCacheKey(key, owners) {
+    return `ticket:${owners.map((w) => w.id).join(',')}:${key}`;
+}
+const ownersOf = (key, scope) => scope.watches.filter((w) => trackerPrefixes(w).includes(key.split('-')[0]));
+async function ticketHit(key, owners, scope, remote) {
+    const cacheKey = ticketCacheKey(key, owners);
+    const cached = cacheGet(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    let hit = null;
+    if (remote && owners.length) {
+        const d = await deps();
+        for (const w of owners) {
+            try {
+                const found = await withTimeout(d.ticket(key, w));
+                const title = found ? cleanTitle(found.title) : '';
+                if (found && title) {
+                    hit = { title, ...(found.url ? { url: found.url } : {}), id: key, kind: 'ticket' };
+                    break;
+                }
+            }
+            catch (err) {
+                log.warn(`refs: could not read ${key}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    hit ??= scope.index.tickets.get(key) ?? null;
+    if (remote)
+        cachePut(cacheKey, hit);
+    return hit;
+}
+async function resolveTicket(c, scope, remote) {
+    const key = c.key.toUpperCase();
+    const owners = ownersOf(key, scope);
+    const hit = await once(`${ticketCacheKey(key, owners)}:${remote}`, () => ticketHit(key, owners, scope, remote));
+    if (hit)
+        return { hit };
+    // Jira keys have a fixed address; Linear and GitHub Issues keys do not.
+    const jira = owners.find((w) => w.tracker?.kind === 'jira');
+    if (jira?.tracker?.kind === 'jira' && jira.tracker.baseUrl)
+        return { plainUrl: `${jira.tracker.baseUrl.replace(/\/$/, '')}/browse/${key}` };
+    return {};
+}
+/** One repo, one sha: cache, then GitHub. */
+function lookupCommit(repo, sha, watch, remote) {
+    return once(`commit:${repo}@${sha}:${remote}`, async () => {
+        const key = `commit:${repo}@${sha}`;
+        const cached = cacheGet(key);
+        if (cached !== undefined)
+            return cached;
+        let hit = null;
+        if (remote) {
+            try {
+                const found = await withTimeout((await deps()).commit(repo, sha, watch));
+                const title = found ? cleanTitle(found.title) : '';
+                if (found && title)
+                    hit = { title, url: found.url ?? commitUrl(repo, sha), id: sha.slice(0, 7), kind: 'commit' };
+            }
+            catch (err) {
+                log.warn(`refs: could not read commit ${sha} of ${repo}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            cachePut(key, hit);
+        }
+        return hit;
+    });
+}
+async function resolveCommit(c, scope, remote) {
+    const sha = c.sha;
+    const cands = repoCandidates(c, scope);
+    if (!cands.length)
+        return {};
+    const hits = (await Promise.all(cands.map((r) => lookupCommit(r.repo, sha, r.watch, remote)))).filter((h) => Boolean(h));
+    if (hits.length === 1)
+        return { hit: hits[0] };
+    if (hits.length > 1)
+        return {};
+    return c.keyworded && cands.length === 1 ? { plainUrl: commitUrl(cands[0].repo, sha), repo: cands[0].repo } : {};
+}
+function resolveRun(c, absolute) {
+    const run = get('runs', c.id);
+    if (!run)
+        return {};
+    const url = runUrl(run.id, absolute);
+    return { hit: { title: runTitle(run), ...(url ? { url } : {}), id: '', kind: 'run' } };
+}
+// ---------- writing ----------
+function mrkdwnText(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\|/g, '/');
+}
+function mdUrl(u) {
+    return u.replace(/\(/g, '%28').replace(/\)/g, '%29').replace(/\s/g, '%20');
+}
+function labelOf(h) {
+    return h.id ? `${h.title} (${h.id})` : h.title;
+}
+function link(label, url, format) {
+    if (!url || format === 'text')
+        return label;
+    return format === 'mrkdwn' ? `<${url}|${mrkdwnText(label)}>` : `[${label}](${mdUrl(url)})`;
+}
+/** True when `given` is the address `canon` with a fragment, a query or a longer path added: the same host and the same pull request or issue. */
+function continuesAddress(given, canon) {
+    if (!given || !canon || given === canon || !given.startsWith(canon))
+        return false;
+    return /^[#/?]/.test(given.slice(canon.length));
+}
+function apply(text, cands, results, format, trust) {
+    let out = '';
+    let cursor = 0;
+    cands.forEach((c, i) => {
+        const r = results[i];
+        if (c.start < cursor)
+            return;
+        if (r.hit) {
+            let start = c.start;
+            let end = c.end;
+            if (c.mode === 'plain') {
+                const title = r.hit.title;
+                // "PR #12: Fix cart total rounding": the writer already gave the title. One title, one link.
+                const after = new RegExp(`^\\s*[:\\-–—,]?\\s*["“'‘]?${escapeRe(title)}["”'’]?(?![\\w])`, 'i').exec(text.slice(end));
+                if (after)
+                    end += after[0].length;
+                else if (!c.keyworded && text[end] === ')') {
+                    // "Fix cart total rounding (#12)": the title stands before the number.
+                    const before = new RegExp(`(?:^|[\\s"“'‘])(${escapeRe(title)})\\s*\\($`, 'id').exec(text.slice(cursor, start));
+                    if (before?.indices?.[1]) {
+                        start = cursor + before.indices[1][0];
+                        end += 1;
+                    }
+                }
+            }
+            // The address the lookup gave comes first: a link the text carried is the writer's, and it keeps only when the lookup has none (KAT-380).
+            // A bare address that goes on from the lookup's own (a comment's fragment, the Files tab) keeps what it adds, so it opens that place.
+            const url = c.mode !== 'mdlink' && continuesAddress(c.givenUrl, r.hit.url) ? c.givenUrl : (r.hit.url ?? c.givenUrl);
+            if (url && url === r.hit.url && format !== 'text')
+                trust?.add(url);
+            out += text.slice(cursor, start) + link(labelOf(r.hit), url, format);
+            cursor = end;
+        }
+        else if (r.plainUrl && c.mode === 'plain' && format !== 'text') {
+            trust?.add(r.plainUrl);
+            out += text.slice(cursor, c.start) + link(c.text, r.plainUrl, format);
+            cursor = c.end;
+        }
+    });
+    return out + text.slice(cursor);
+}
+/**
+ * True when the text names a repo other than `repo` ("issue #9 in acme/other"). A plain link built from the
+ * dot's own repo would then point at the wrong place, so the number stays as written. Sentences with a
+ * slash such as "pass/fail" also stop the link, which is the safe side.
+ */
+function namesOtherRepo(text, repo) {
+    const bare = text.replace(/https?:\/\/\S+/g, ' ').replace(/\x60[^\x60]*\x60/g, ' ');
+    for (const m of bare.matchAll(/(?<![\w/.-])([A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*)(?![\w/-])/g))
+        if (m[1].toLowerCase() !== repo)
+            return true;
+    return false;
+}
+/** Drops plain links the text contradicts. */
+function guardPlain(text, results) {
+    return results.map((r) => (r.plainUrl && r.repo && namesOtherRepo(text, r.repo) ? {} : r));
+}
+// ---------- entry points ----------
+/** Quick test: false means the text cannot hold a reference, so callers can skip the (async) rewrite. */
+export function mayHaveRefs(text) {
+    return MAYBE_REF.test(text);
+}
+const MAYBE_REF = /#\d|(?<![\w-])(?=[0-9a-f]*\d)[0-9a-f]{7,40}(?![\w-])|[A-Z][A-Z0-9]{1,9}-\d|\b(?=[0-9a-z]*\d)[0-9a-z]{18}\b|\/(?:pull|issues|browse|issue)\/|\bPR\s+\d|pull\s+request\s+\d/i;
+function scopeFor(opts) {
+    const watches = opts.dotId ? [get('watches', opts.dotId)].filter((w) => Boolean(w)) : list('watches').filter((w) => !w.archived);
+    let index = opts.index;
+    const lazy = {
+        watches,
+        get index() {
+            index ??= localIndex(watches);
+            return index;
+        },
+        get prefixes() {
+            const set = new Set(watches.flatMap(trackerPrefixes));
+            for (const k of this.index.tickets.keys())
+                set.add(k.split('-')[0]);
+            return set;
+        },
+    };
+    return lazy;
+}
+/**
+ * Rewrites the bare references in `text` into titled links. Looks titles up in the cache, GitHub, the
+ * connected trackers, and the stored runs, in that order. Never throws: on any failure the text comes back
+ * unchanged.
+ */
+export async function renderRefs(text, opts = {}) {
+    if (!text || !MAYBE_REF.test(text))
+        return text;
+    try {
+        const format = opts.format ?? 'markdown';
+        const absolute = opts.absolute ?? format !== 'markdown';
+        const scope = scopeFor(opts);
+        const cands = collect(text, scope);
+        if (!cands.length)
+            return text;
+        const results = await Promise.all(cands.map((c) => c.kind === 'num'
+            ? resolveNumber(c, scope, true)
+            : c.kind === 'ticket'
+                ? resolveTicket(c, scope, true)
+                : c.kind === 'commit'
+                    ? resolveCommit(c, scope, true)
+                    : resolveRun(c, absolute)));
+        return apply(text, cands, guardPlain(text, results), format, opts.trust);
+    }
+    catch (err) {
+        log.warn(`refs: could not title the references: ${err instanceof Error ? err.message : String(err)}`);
+        return text;
+    }
+}
+/**
+ * The same rewrite without a network call: the cache, the runs in `opts.index`, and the stored runs. For
+ * code that cannot wait, such as the Activity list.
+ */
+export function renderRefsSync(text, opts = {}) {
+    if (!text || !MAYBE_REF.test(text))
+        return text;
+    try {
+        const format = opts.format ?? 'text';
+        const absolute = opts.absolute ?? format !== 'markdown';
+        const scope = scopeFor(opts);
+        const cands = collect(text, scope);
+        if (!cands.length)
+            return text;
+        const results = cands.map((c) => {
+            if (c.kind === 'run')
+                return resolveRun(c, absolute);
+            if (c.kind === 'commit') {
+                const hits = repoCandidates(c, scope)
+                    .map((r) => cacheGet(`commit:${r.repo}@${c.sha}`))
+                    .filter((h) => Boolean(h));
+                return hits.length === 1 ? { hit: hits[0] } : {};
+            }
+            if (c.kind === 'ticket') {
+                const key = c.key.toUpperCase();
+                const hit = cacheGet(ticketCacheKey(key, ownersOf(key, scope))) ?? scope.index.tickets.get(key);
+                return hit ? { hit } : {};
+            }
+            const repos = repoCandidates(c, scope);
+            const hits = repos
+                .map((r) => cacheGet(`num:${r.repo}#${c.n}:${c.want ?? ''}`) ?? scope.index.prs.get(`${r.repo}#${c.n}`))
+                .filter((h) => Boolean(h));
+            return hits.length === 1 ? { hit: hits[0] } : {};
+        });
+        return apply(text, cands, results, format);
+    }
+    catch (err) {
+        log.warn(`refs: could not title the references: ${err instanceof Error ? err.message : String(err)}`);
+        return text;
+    }
+}
+/**
+ * The title and link of one reference written as `KAT-295` or `owner/name#12`, or undefined when nobody knows it.
+ * The same lookup renderRefs uses (cache, GitHub, the dot's tracker, the stored runs), for code that needs the
+ * title as data, such as the Inbox. Never throws.
+ */
+export async function lookupRef(text, opts = {}) {
+    const t = text.trim();
+    if (!t || !MAYBE_REF.test(t))
+        return undefined;
+    try {
+        const scope = scopeFor(opts);
+        const c = collect(t, scope).find((x) => x.start === 0 && x.end === t.length);
+        if (!c || c.kind === 'run')
+            return undefined;
+        if (opts.want && c.kind === 'num')
+            c.want = opts.want;
+        const remote = opts.remote ?? true;
+        const res = c.kind === 'num'
+            ? await resolveNumber(c, scope, remote)
+            : c.kind === 'commit'
+                ? await resolveCommit(c, scope, remote)
+                : await resolveTicket(c, scope, remote);
+        return res.hit;
+    }
+    catch (err) {
+        log.warn(`refs: could not look up ${t}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * The titles of the PRs and tickets that the stored runs of one dot (or of every live dot) were about. Reading them costs a
+ * pass over recent runs, so a caller that looks up many references builds it once and passes it as `index`.
+ */
+export function storedRefIndex(dotId) {
+    const watches = dotId ? [get('watches', dotId)].filter((w) => Boolean(w)) : list('watches').filter((w) => !w.archived);
+    return localIndex(watches);
+}
+/** The web address of a commit on the GitHub the server talks to. */
+export function commitUrl(repo, sha) {
+    return `${webBase()}/${repo}/commit/${sha}`;
+}
+/** A verdict with its headline as plain text and its summary as Markdown, references titled. */
+export async function renderVerdictRefs(verdict, opts = {}) {
+    const [headline, summary] = await Promise.all([
+        renderRefs(verdict.headline, { ...opts, format: 'text' }),
+        renderRefs(verdict.summary, { ...opts, format: 'markdown' }),
+    ]);
+    return { ...verdict, headline, summary };
+}
+//# sourceMappingURL=refs.js.map