src/job-body-check.ts

Functions

Imports

It imports no other module of this repo. Imported by src/complete-ci.ts, src/job-checklist.ts, src/job-fact-check.ts, src/jobs-edit.ts, src/tools/jobs.ts.

Source

1// A job body a session can act on (job_9a8d13d2d926, Dustin 2026-10-10). Three checks, run
2// by the capsid_work_jobs tool on a caller's post and edit, and by nothing else: the
3// watcher, the skills refresh and the finalize step post through postJob and are not
4// subject to them.
5//
6// 1. An unfilled placeholder is refused. Tonight two sessions stalled on a pasted
7//    template that still read <ID>. Text in a code block or an external fence is exempt,
8//    since a body may quote a template or relay text it did not write.
9// 2. A body missing any of the five headed parts is accepted with a warning, because a
10//    refusal nobody can predict teaches people to route around the queue
11//    (src/provenance.ts makes the same call).
12// 3. A body stating a pull request merged, a version tagged or a package version published
13//    is checked against GitHub and npm, and refused when what Capsid reads says otherwise;
14//    a claim that could not be checked is a warning (src/job-fact-check.ts, which reads
15//    prose through proseOnly and the parts through heading, both exported for it).
16
17// A fenced block: ``` or ~~~ (an external fence is a ~~~ fence), closed by a line of at
18// least as many of the same character, or by the end of the text.
19const FENCE_OPEN = /^[ \t]{0,3}(`{3,}|~{3,})/;
20
21/** `text` with fenced blocks and inline code spans blanked, so what is left is prose a
22 *  session would read as instruction. Line structure is kept. */
23export function proseOnly(text: string): string {
24  const out: string[] = [];
25  let fence: { char: string; length: number } | null = null;
26  for (const line of text.split(/\r?\n/)) {
27    if (fence) {
28      const close = /^[ \t]{0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
29      if (close && close[1][0] === fence.char && close[1].length >= fence.length) fence = null;
30      out.push("");
31      continue;
32    }
33    const open = FENCE_OPEN.exec(line);
34    if (open) {
35      fence = { char: open[1][0], length: open[1].length };
36      out.push("");
37      continue;
38    }
39    out.push(line.replace(/(`+)[^`\n]*?\1/g, ""));
40  }
41  return out.join("\n");
42}
43
44const PLACEHOLDERS: Array<{ name: string; pattern: RegExp }> = [
45  { name: "<ID>", pattern: /<id>/i },
46  { name: "<...>", pattern: /<\.\.\.>/ },
47  { name: "{{...}}", pattern: /\{\{[^{}\n]*\}\}/ },
48  { name: "TODO:", pattern: /\bTODO:/ },
49  { name: "TBD", pattern: /\bTBD\b/ },
50];
51
52/** The refusal for the first unfilled placeholder in `text`, naming it and where it is, or
53 *  null. `field` is "title" or "body". */
54export function placeholderRefusal(field: string, text: string): string | null {
55  const lines = proseOnly(text).split("\n");
56  for (const { name, pattern } of PLACEHOLDERS) {
57    const at = lines.findIndex((line) => pattern.test(line));
58    if (at >= 0) {
59      // The text as written, so <id> is named as <id> and not as the <ID> pattern.
60      const found = pattern.exec(lines[at])?.[0] ?? name;
61      return `the ${field} has an unfilled placeholder, ${found} (line ${at + 1}). A session would stall on it. Fill it in, or put it in a code block or an external fence if it is meant literally. Nothing was written.`;
62    }
63  }
64  return null;
65}
66
67/** The refusal for an unfilled placeholder in a job's title or body, or null. */
68export function jobTextRefusal(title: string | undefined, body: string | undefined): string | null {
69  return (title === undefined ? null : placeholderRefusal("title", title)) ?? (body === undefined ? null : placeholderRefusal("body", body));
70}
71
72// The five headed parts. DECIDED and RULES are alternatives for the fifth.
73// A heading is the keyword at the start of a line, optionally behind a markdown heading
74// marker or bold, and followed by a delimiter, so "DO NOT touch" and "GOALS" are prose.
75export const heading = (words: string) => new RegExp(`^[ \\t]*(?:#{1,6}[ \\t]+)?\\*{0,2}(?:${words})(?=\\*{0,2}(?:[:.,(]|[ \\t]*$)|[ \\t]+\\()`, "m");
76const PARTS: Array<{ name: string; heading: RegExp }> = [
77  { name: "GOAL", heading: heading("GOAL") },
78  { name: "DO", heading: heading("DO") },
79  { name: "OUT OF SCOPE", heading: heading("OUT OF SCOPE") },
80  { name: "DONE WHEN", heading: heading("DONE WHEN") },
81  { name: "DECIDED or RULES", heading: heading("DECIDED|RULES") },
82];
83
84/** A warning naming the headed parts `body` lacks, or null when it has all five. */
85export function missingPartsWarning(body: string): string | null {
86  const prose = proseOnly(body);
87  const missing = PARTS.filter((part) => !part.heading.test(prose)).map((part) => part.name);
88  if (missing.length === 0) return null;
89  return `the body has no heading for: ${missing.join(", ")}. Posted anyway. A session acts best on a body with GOAL, DO, OUT OF SCOPE, DONE WHEN and DECIDED or RULES (docs/work-queue.md, "A body a session can act on").`;
90}