src/job-fact-check.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/job-body-check.ts, src/ops-packages.ts. Imported by src/jobs-edit.ts, src/tools/jobs.ts.

Source

1import type { Env } from "./env";
2import { encodePath, ghFetch } from "./github/client";
3import { npmVersions, readPackageConfig, type FetchLike } from "./ops-packages";
4import { heading, proseOnly } from "./job-body-check";
5
6// The third job body check (src/job-body-check.ts): a body that states a pull request is
7// merged, a version is tagged or a package version is published is checked against GitHub
8// and npm at post and edit, and refused when what Capsid reads says otherwise. The case:
9// a seat told job_d62abdbfc270 that Enarratio 0.3.0 was on npm while it was only staged,
10// and the session built on a release that did not exist.
11//
12// The parser is deliberately narrow, because a false refusal costs more than a miss. It
13// reads only prose (proseOnly: code blocks, fences and inline code are exempt), skips the
14// DONE WHEN and OUT OF SCOPE parts (they state targets and exclusions, not facts), block
15// quotes and text in double quotes, and any sentence that is a question or carries a word
16// of plan, condition, negation or report ("once", "will", "not", "said", ...). What is left
17// is a claim stated as done: "#12 is merged", "merged #12", "tagged v1.2.0",
18// "enarratio@0.3.0 is published", "Enarratio 0.3.0 is on npm".
19//
20// A claim Capsid could not check (a read failed, the repo is not one the namespace maps,
21// the package is not known) is accepted with a warning that says so, never refused. At most
22// MAX_CLAIMS claims and MAX_READS network reads are spent on one body.
23
24const MAX_CLAIMS = 10;
25const MAX_READS = 20;
26
27export type FactClaim =
28  | { kind: "merged"; line: number; said: string; repo: string | null; number: number }
29  | { kind: "tagged"; line: number; said: string; name: string | null; version: string }
30  // at: written name@version, npm's own spelling. npm: the sentence names npm, or uses it.
31  | { kind: "published"; line: number; said: string; name: string | null; at: boolean; npm: boolean; version: string };
32
33// A sentence holding any of these is not a claim stated as done.
34const NOT_DONE =
35  /\b(?:not|no|never|yet|once|after|before|when|whenever|until|unless|if|whether|will|would|should|shall|must|can|could|may|might|needs?|needed|pending|planned|plans?|going\s+to|about\s+to|ready|wait|waiting|waits|ensure|make\s+sure|check|verify|confirm|expect|expected|assume|assuming|hope|be|get|gets|getting|said|says|claimed|claims|reported|told|supposedly|allegedly|later|soon|tomorrow|otherwise)\b|n[’']t\b/i;
36
37const SKIPPED_PARTS = heading("DONE WHEN|OUT OF SCOPE");
38const OTHER_PARTS = heading("GOAL|DO|DECIDED|RULES");
39
40const PR_ITEM = String.raw`(?:https:\/\/github\.com\/[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/pull\/\d+|#\d+)(?![\w/])`;
41const PR_LIST = String.raw`${PR_ITEM}(?:(?:\s*,\s*(?:and\s+)?|\s+and\s+|\s*&\s*)${PR_ITEM})*`;
42const PR_NOUN = String.raw`(?:(?:PRs?|pull\s+requests?)\s+)?`;
43// The verb's state, required except at the start of a sentence ("- #12 merged").
44const BE = String.raw`\s+(?:is|was|are|were|has\s+been|have\s+been|got)(?:\s+(?:now|already|also|both|all))?`;
45const LEAD = String.raw`^\s*(?:[-*+]\s+|\d+[.)]\s+)?`;
46const NAME = String.raw`(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[A-Za-z0-9~][A-Za-z0-9._~-]*`;
47const VERSION = String.raw`v?\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?(?![0-9A-Za-z]|\.\d)`;
48// [name][@ or space]version: groups name, separator, version.
49const VITEM = String.raw`(?:(?<![\w@./-])(${NAME})(@|\s+))?(?<![\w.-])(${VERSION})`;
50
51const MERGED: RegExp[] = [
52  new RegExp(`(${PR_LIST})${BE}\\s+merged\\b`, "gi"),
53  new RegExp(`${LEAD}${PR_NOUN}(${PR_LIST})(?:\\s+(?:now|already|both|all))?\\s+merged\\b`, "gi"),
54  new RegExp(`\\bmerged\\s+${PR_NOUN}(${PR_LIST})`, "gi"),
55];
56const TAGGED: RegExp[] = [
57  new RegExp(`${VITEM}${BE}\\s+tagged\\b`, "gi"),
58  new RegExp(`${LEAD}${VITEM}\\s+tagged\\b`, "gi"),
59  new RegExp(`\\btagged\\s+(?:as\\s+)?${VITEM}`, "gi"),
60];
61const PUBLISHED: RegExp[] = [
62  new RegExp(`${VITEM}${BE}\\s+(?:published|(?:(?:live|out|available)\\s+)?on\\s+npm)\\b`, "gi"),
63  new RegExp(`${LEAD}${VITEM}\\s+published\\b`, "gi"),
64  new RegExp(`\\bpublished\\s+${VITEM}`, "gi"),
65];
66
67// Words that stand before a version without naming a package ("published version 0.3.0").
68const NOT_NAMES = new Set(["a", "an", "and", "as", "build", "it", "npm", "or", "package", "release", "tag", "the", "then", "version", "now", "is", "was"]);
69const NPM_NAME = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/;
70
71// The claim as written, for the messages, without a list marker.
72const said = (match: string) => match.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "").trim();
73
74function named(raw: string | undefined): string | null {
75  return raw && !NOT_NAMES.has(raw.toLowerCase()) && !/^v?\d/.test(raw) ? raw : null;
76}
77
78/** The sentences of a line, each with whether it ends as a question. A dot inside a version
79 *  or a URL does not end a sentence; one followed by a space or the line's end does. */
80function sentences(line: string): Array<{ text: string; question: boolean }> {
81  return (line.match(/(?:[^.!?;:]|[.!?;:](?!\s|$))+[.!?;:]?/g) ?? []).map((text) => ({ text, question: text.trim().endsWith("?") }));
82}
83
84/** Every checkable claim `body` states as done, in order, each once. Pure. */
85export function factClaims(body: string): FactClaim[] {
86  const claims: FactClaim[] = [];
87  const seen = new Set<string>();
88  const add = (key: string, claim: FactClaim) => {
89    if (seen.has(key)) return;
90    seen.add(key);
91    claims.push(claim);
92  };
93  let skipping = false;
94  proseOnly(body)
95    .split("\n")
96    .forEach((raw, index) => {
97      if (SKIPPED_PARTS.test(raw)) skipping = true;
98      else if (OTHER_PARTS.test(raw)) skipping = false;
99      if (skipping || /^\s*>/.test(raw)) return;
100      const line = raw.replace(/"[^"\n]*"|“[^”\n]*”/g, " ");
101      for (const { text, question } of sentences(line)) {
102        if (question || NOT_DONE.test(text)) continue;
103        const npm = /\bnpm\b/i.test(text);
104        for (const pattern of MERGED) {
105          for (const m of text.matchAll(pattern)) {
106            for (const item of m[1].match(new RegExp(PR_ITEM, "g")) ?? []) {
107              const url = /github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/.exec(item);
108              const repo = url ? url[1] : null;
109              const number = Number(url ? url[2] : item.slice(1));
110              add(`merged:${repo ?? ""}#${number}`, { kind: "merged", line: index + 1, said: said(m[0]), repo, number });
111            }
112          }
113        }
114        for (const pattern of TAGGED) {
115          for (const m of text.matchAll(pattern)) {
116            const name = named(m[1]);
117            add(`tagged:${name ?? ""}@${m[3]}`, { kind: "tagged", line: index + 1, said: said(m[0]), name, version: m[3] });
118          }
119        }
120        for (const pattern of PUBLISHED) {
121          for (const m of text.matchAll(pattern)) {
122            const name = named(m[1]);
123            const at = name !== null && m[2] === "@";
124            add(`published:${name ?? ""}@${m[3]}`, { kind: "published", line: index + 1, said: said(m[0]), name, at, npm: npm || at, version: m[3] });
125          }
126        }
127      }
128    });
129  return claims;
130}
131
132// ---- Checking ------------------------------------------------------------------------------
133
134type FactRead<T> = { ok: true; value: T } | { ok: false; reason: string };
135
136/** What the check reads, injected so the tests need no network. */
137export interface FactReaders {
138  /** The repos the job's namespace maps, as owner/name. */
139  repos(): Promise<FactRead<string[]>>;
140  /** The npm packages configured in the Portal (ops_packages), with their repos. */
141  packages(): Promise<FactRead<Array<{ name: string; repo: string | null }>>>;
142  /** A pull request's state, or null when GitHub has none by that number. */
143  pull(repo: string, number: number): Promise<FactRead<{ merged: boolean; state: string } | null>>;
144  /** Whether the repo has the tag. */
145  tag(repo: string, tag: string): Promise<FactRead<boolean>>;
146  /** Every version npm lists for the package, or null when npm has no such package. */
147  npm(name: string): Promise<FactRead<string[] | null>>;
148}
149
150type Verdict = { state: "true" } | { state: "false"; read: string } | { state: "unchecked"; reason: string } | { state: "skip" };
151
152const same = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
153const bare = (version: string) => version.replace(/^v/, "");
154
155export interface FactCheck {
156  refusal: string | null;
157  warnings: string[];
158}
159
160/** Check each claim `body` states against what `readers` read. Refuses only a claim read as
161 *  false; a claim that could not be read is a warning. */
162export async function checkBodyFacts(namespace: string, body: string, readers: FactReaders): Promise<FactCheck> {
163  const claims = factClaims(body);
164  if (claims.length === 0) return { refusal: null, warnings: [] };
165  let reads = 0;
166  const budget = () => reads < MAX_READS;
167  let repos: Promise<FactRead<string[]>> | null = null;
168  let packages: Promise<FactRead<Array<{ name: string; repo: string | null }>>> | null = null;
169  const npmDocs = new Map<string, Promise<FactRead<string[] | null>>>();
170  const mapped = () => (repos ??= readers.repos());
171  const configured = () => (packages ??= readers.packages());
172
173  async function merged(claim: Extract<FactClaim, { kind: "merged" }>): Promise<Verdict> {
174    const list = await mapped();
175    if (!list.ok) return { state: "unchecked", reason: list.reason };
176    let repo: string | undefined;
177    if (claim.repo) {
178      repo = list.value.find((r) => same(r, claim.repo!));
179      if (!repo) return { state: "unchecked", reason: `${claim.repo} is not a repo ${namespace} maps, so Capsid does not read it` };
180    } else if (list.value.length === 1) {
181      repo = list.value[0];
182    } else {
183      return { state: "unchecked", reason: `${namespace} maps ${list.value.length} repos, so #${claim.number} names none of them for certain; write the pull request's URL` };
184    }
185    if (!budget()) return { state: "unchecked", reason: `the limit of ${MAX_READS} reads for one body was reached` };
186    reads++;
187    const pr = await readers.pull(repo, claim.number);
188    if (!pr.ok) return { state: "unchecked", reason: pr.reason };
189    if (pr.value === null) return { state: "unchecked", reason: `GitHub has no pull request ${repo}#${claim.number}` };
190    if (pr.value.merged) return { state: "true" };
191    return { state: "false", read: `GitHub shows ${repo}#${claim.number} ${pr.value.state === "open" ? "open, not merged" : "closed without merging"}` };
192  }
193
194  async function tagged(claim: Extract<FactClaim, { kind: "tagged" }>): Promise<Verdict> {
195    const list = await mapped();
196    if (!list.ok) return { state: "unchecked", reason: list.reason };
197    if (list.value.length === 0) return { state: "unchecked", reason: `${namespace} maps no repo` };
198    const v = bare(claim.version);
199    const lower = claim.name?.toLowerCase();
200    const candidates = [...new Set([`v${v}`, v, ...(lower ? [`${lower}@${v}`, `${lower}-v${v}`] : [])])];
201    let unread: string | null = null;
202    for (const repo of list.value) {
203      for (const tag of candidates) {
204        if (!budget()) return { state: "unchecked", reason: `the limit of ${MAX_READS} reads for one body was reached` };
205        reads++;
206        const got = await readers.tag(repo, tag);
207        if (!got.ok) unread ??= got.reason;
208        else if (got.value) return { state: "true" };
209      }
210    }
211    if (unread) return { state: "unchecked", reason: unread };
212    return { state: "false", read: `no tag ${candidates.join(", ")} exists in ${list.value.join(", ")}` };
213  }
214
215  async function packageName(claim: Extract<FactClaim, { kind: "published" }>): Promise<FactRead<string> | null> {
216    if (claim.at && claim.name && NPM_NAME.test(claim.name)) return { ok: true, value: claim.name };
217    const pkgs = await configured();
218    if (!pkgs.ok) return claim.npm ? { ok: false, reason: pkgs.reason } : null;
219    let matches: Array<{ name: string; repo: string | null }>;
220    if (claim.name) {
221      const name = claim.name;
222      matches = pkgs.value.filter((p) => same(p.name, name) || same(p.name.replace(/^@[^/]+\//, ""), name));
223      if (matches.length === 0) return claim.npm ? { ok: false, reason: `no package configured in the Portal is named ${name}, and the name is not written as name@version` } : null;
224    } else {
225      const list = await mapped();
226      if (!list.ok) return claim.npm ? { ok: false, reason: list.reason } : null;
227      matches = pkgs.value.filter((p) => p.repo !== null && list.value.some((r) => same(r, p.repo!)));
228      if (matches.length !== 1) {
229        return claim.npm ? { ok: false, reason: `the claim names no package and ${namespace} has ${matches.length} configured; write it as name@${bare(claim.version)}` } : null;
230      }
231    }
232    if (matches.length > 1) return { ok: false, reason: `${claim.name} could be any of ${matches.map((p) => p.name).join(", ")}` };
233    return { ok: true, value: matches[0].name };
234  }
235
236  async function published(claim: Extract<FactClaim, { kind: "published" }>): Promise<Verdict> {
237    const name = await packageName(claim);
238    // Not said to be on npm and naming no npm package Capsid knows: a GitHub release or
239    // another registry, which this check does not read.
240    if (name === null) return { state: "skip" };
241    if (!name.ok) return { state: "unchecked", reason: name.reason };
242    let doc = npmDocs.get(name.value);
243    if (!doc) {
244      if (!budget()) return { state: "unchecked", reason: `the limit of ${MAX_READS} reads for one body was reached` };
245      reads++;
246      doc = readers.npm(name.value);
247      npmDocs.set(name.value, doc);
248    }
249    const versions = await doc;
250    if (!versions.ok) return { state: "unchecked", reason: versions.reason };
251    if (versions.value === null) return { state: "false", read: `npm has no package ${name.value}` };
252    const v = bare(claim.version);
253    if (versions.value.includes(v)) return { state: "true" };
254    const last = versions.value.slice(-3).join(", ");
255    return { state: "false", read: `npm lists no version ${v} of ${name.value}${last ? ` (the last it lists: ${last})` : ""}` };
256  }
257
258  const falses: string[] = [];
259  const warnings: string[] = [];
260  for (const claim of claims.slice(0, MAX_CLAIMS)) {
261    let verdict: Verdict;
262    try {
263      verdict = claim.kind === "merged" ? await merged(claim) : claim.kind === "tagged" ? await tagged(claim) : await published(claim);
264    } catch (err) {
265      verdict = { state: "unchecked", reason: err instanceof Error ? err.message : String(err) };
266    }
267    const where = `line ${claim.line}, "${claim.said}"`;
268    if (verdict.state === "false") falses.push(`${where}: ${verdict.read}`);
269    else if (verdict.state === "unchecked") warnings.push(`Capsid could not check ${where}: ${verdict.reason}. Not refused; check it before a session relies on it.`);
270  }
271  if (claims.length > MAX_CLAIMS) {
272    warnings.push(`the body states ${claims.length} merged, tagged or published claims; the first ${MAX_CLAIMS} were checked and the rest were not.`);
273  }
274  if (falses.length === 0) return { refusal: null, warnings };
275  return {
276    refusal: `the body states as done what Capsid read as not so: ${falses.join("; ")}. A session would build on it. If it has not happened yet, say so ("once #12 is merged", "0.3.0 is not published yet"); if you are quoting it, put it in a code block or an external fence. Nothing was written.`,
277    warnings,
278  };
279}
280
281// ---- The live readers ----------------------------------------------------------------------
282
283const reason = (err: unknown) => (err instanceof Error ? err.message : String(err)).slice(0, 160);
284
285/** The readers post and edit use: the namespace's mapping in D1, the Portal's package rows,
286 *  GitHub through the App, and npm's registry. */
287function liveFactReaders(env: Env, namespace: string, fetchImpl: FetchLike = (url, init) => fetch(url, init)): FactReaders {
288  const gh = async (repo: string, path: string): Promise<Response> => {
289    const [owner, name] = repo.split("/");
290    return ghFetch(env, owner, name, `/repos/${owner}/${name}${path}`);
291  };
292  return {
293    async repos() {
294      try {
295        const row = await env.DB.prepare("SELECT repos FROM namespaces WHERE namespace = ?1").bind(namespace).first<{ repos: string | null }>();
296        if (!row) return { ok: false, reason: `${namespace} is not a registered namespace` };
297        const list: unknown = JSON.parse(row.repos || "[]");
298        if (!Array.isArray(list)) return { ok: false, reason: `${namespace}'s repos mapping is not a list` };
299        return { ok: true, value: list.map((r: { repo?: unknown }) => r.repo).filter((r): r is string => typeof r === "string" && r.includes("/")) };
300      } catch (err) {
301        return { ok: false, reason: `${namespace}'s repos mapping could not be read: ${reason(err)}` };
302      }
303    },
304    async packages() {
305      try {
306        return { ok: true, value: (await readPackageConfig(env.DB)).map((p) => ({ name: p.name, repo: p.repo })) };
307      } catch (err) {
308        return { ok: false, reason: `the Portal's package rows could not be read: ${reason(err)}` };
309      }
310    },
311    async pull(repo, number) {
312      try {
313        const res = await gh(repo, `/pulls/${number}`);
314        if (res.status === 404) return { ok: true, value: null };
315        if (!res.ok) return { ok: false, reason: `GitHub answered ${res.status} for ${repo}#${number}` };
316        const pr = (await res.json()) as { merged?: unknown; merged_at?: unknown; state?: unknown };
317        return { ok: true, value: { merged: pr.merged === true || typeof pr.merged_at === "string", state: typeof pr.state === "string" ? pr.state : "unknown" } };
318      } catch (err) {
319        return { ok: false, reason: `GitHub could not be read: ${reason(err)}` };
320      }
321    },
322    async tag(repo, tag) {
323      try {
324        // The singular ref endpoint matches exactly: 404 for a tag that does not exist.
325        const res = await gh(repo, `/git/ref/tags/${encodePath(tag)}`);
326        await res.body?.cancel();
327        if (res.status === 404) return { ok: true, value: false };
328        if (!res.ok) return { ok: false, reason: `GitHub answered ${res.status} for tag ${tag} in ${repo}` };
329        return { ok: true, value: true };
330      } catch (err) {
331        return { ok: false, reason: `GitHub could not be read: ${reason(err)}` };
332      }
333    },
334    async npm(name) {
335      try {
336        return { ok: true, value: await npmVersions(fetchImpl, name) };
337      } catch (err) {
338        return { ok: false, reason: reason(err) };
339      }
340    },
341  };
342}
343
344/** The check post and edit run, on the live readers. */
345export function factCheckBody(env: Env, namespace: string, body: string): Promise<FactCheck> {
346  return checkBodyFacts(namespace, body, liveFactReaders(env, namespace));
347}