app/lib/pages/invariants.mjs

Functions

Imports

It imports app/lib/phage-table.mjs, app/lib/phage-tools.mjs, app/lib/phages/compile.mjs. Imported by app/lib/pages/compile.mjs.

Source

1// What a page must keep true because code, a redirect or a calculator depends on it. Each rule used to be a
2// test that read content/pages/*.md in CI; a save through the operator API commits to the repository and
3// the page is live before CI runs, so the rules live here, where compilePage runs them for the build, the
4// sync, CI's tests and the page save alike (docs/PAGES.md). A message names the page and says what to restore.
5
6import { PHAGES_PAGE_PATH, TABLE_MARKER, sortPhages } from "../phages/compile.mjs";
7import { phagesDbUrl } from "../phage-table.mjs";
8import { TOOLS, runTool, toolValues } from "../phage-tools.mjs";
9
10/** @typedef {{ path: string, markdown: string, html: string }} InvariantPage */
11
12/** Every calculator page's address, once. */
13const CALCULATOR_PATHS = [...new Set(Object.values(TOOLS).map((tool) => tool.path))];
14
15/**
16 * Every step of a calculator result, numbered as the page numbers it, must be on the page, so a page
17 * never states a worked example the calculator would not print.
18 *
19 * @param {string} markdown
20 * @param {string} id
21 * @param {Record<string, string>} values
22 * @returns {string[]}
23 */
24function workedOnPage(markdown, id, values) {
25  const result = runTool(id, values);
26  if (!result.ok) return [`the ${id} calculator refuses its own worked example (${result.error}); the page cannot be checked against it`];
27  /** @type {string[]} */
28  const errors = [];
29  for (const section of result.sections) {
30    section.steps.forEach((step, i) => {
31      if (!markdown.includes(`${i + 1}. ${step}\n`)) errors.push(`the page lacks step ${i + 1} the ${id} calculator prints: ${step}`);
32    });
33  }
34  return errors;
35}
36
37/** The titer page's worked examples, and the example every other calculator page opens on. */
38const WORKED = /** @type {Record<string, { runs: Array<[string, Record<string, string>]>, answers: (result: any) => string[] }>} */ ({
39  "/research/tools/titer": {
40    runs: [
41      ["titer", { plaques: "111", volume: "10", dilution: "6" }],
42      ["titer", { plaques: "6", volume: "3", dilution: "3" }],
43    ],
44    answers: (result) => [`The titer is ${result.sections[0].result}.`],
45  },
46  "/research/tools/dilution": {
47    runs: [
48      ["dilution", { start: "1.11e10", target: "1.11e6", transfer: "10", needed: "" }],
49      ["dilution", { start: "3.0e9", target: "6e5", transfer: "10", needed: "" }],
50    ],
51    answers: () => [],
52  },
53  "/research/tools/webbed-plate": {
54    runs: [
55      ["webbed-plate", toolValues("webbed-plate")],
56      ["flood", toolValues("flood")],
57    ],
58    answers: () => [],
59  },
60  "/research/tools/moi": { runs: [["moi", toolValues("moi")]], answers: () => ["The MOI is 0.4 pfu per cell."] },
61  "/research/tools/eop": {
62    runs: [["eop-counts", toolValues("eop-counts")]],
63    answers: () => ["The EOP is 0.02, or 2% of the reference titer."],
64  },
65  "/research/tools/lysate-volume": {
66    runs: [["lysate-volume", toolValues("lysate-volume")]],
67    answers: () => ["The plan is 6 µl of lysate in 60 µl, 10 µl on each of 6 plates."],
68  },
69});
70
71/** @param {InvariantPage} page */
72function calculatorErrors({ path, markdown }) {
73  const rule = WORKED[path];
74  if (!rule) return [];
75  /** @type {string[]} */
76  const errors = [];
77  for (const [id, values] of rule.runs) {
78    errors.push(...workedOnPage(markdown, id, values));
79    const result = runTool(id, values);
80    if (result.ok) {
81      for (const answer of rule.answers(result)) {
82        if (!markdown.includes(answer)) errors.push(`the page lacks the calculator's answer: ${answer}`);
83      }
84    }
85  }
86  return errors;
87}
88
89/** The tools index and the FAQ link every calculator page, and the FAQ states the lysate-per-plate sum. */
90/** @param {InvariantPage} page */
91function calculatorLinkErrors({ path, markdown }) {
92  /** @type {string[]} */
93  const errors = [];
94  if (path === "/research/tools" || path === "/teaching/virus-isolation/faq") {
95    for (const target of CALCULATOR_PATHS) {
96      if (!markdown.includes(`](${target})`)) errors.push(`the page lacks a link to the calculator at ${target}`);
97    }
98  }
99  if (path === "/teaching/virus-isolation/faq") {
100    const sum = "11,100 / 1.11 x 10^10 x 1,000 = 1 x 10^-3 µl of lysate per plate.";
101    if (!markdown.includes(sum)) errors.push(`the page lacks the lysate-per-plate sum the protocol and the calculator agree on: ${sum}`);
102  }
103  return errors;
104}
105
106const text = (/** @type {string} */ cell) => cell.replace(/<[^>]+>/g, "").trim();
107const hrefsOf = (/** @type {string} */ cell) => [...cell.matchAll(/href="([^"]+)"/g)].map((m) => m[1] ?? "");
108
109/** The first table in the served HTML, row by row, each cell's raw HTML. */
110function servedRows(/** @type {string} */ html) {
111  const table = /<table>([\s\S]*?)<\/table>/.exec(html)?.[1] ?? "";
112  const body = /<tbody>([\s\S]*?)<\/tbody>/.exec(table)?.[1] ?? "";
113  return [...body.matchAll(/<tr>([\s\S]*?)<\/tr>/g)].map((row) =>
114    [...(row[1] ?? "").matchAll(/<td[^>]*>([\s\S]*?)<\/td>/g)].map((cell) => cell[1] ?? ""),
115  );
116}
117
118/**
119 * The phage table and its sections, as drawn from the phage rows (docs/PHAGES.md): the table lists every phage in
120 * the page's order with all six columns, a PhagesDB link for exactly the phages with a verified record, at that
121 * record, and a heading per phage, which the old /discovery-of-{name} addresses redirect to. The generated text
122 * satisfies most of this by construction; what these catch is the page's own prose getting in the way: a second
123 * table ahead of the generated one, a heading that repeats a phage's, or a PhagesDB link written by hand.
124 *
125 * @param {InvariantPage} page
126 * @param {import("../phages/compile.mjs").Phage[] | undefined} phages
127 */
128function phageTableErrors({ path, markdown, html }, phages) {
129  if (path !== PHAGES_PAGE_PATH || !phages) return [];
130  /** @type {string[]} */
131  const errors = [];
132  const names = sortPhages(phages).map((p) => p.name);
133  const rows = servedRows(html);
134  const listed = rows.map((cells) => text(cells[0] ?? ""));
135  if (listed.join("\n") !== names.join("\n")) {
136    errors.push(
137      `the first table on the page lists ${listed.length} phage(s) and the phages table holds ${names.length}; the first table must be the drawn one ` +
138        `(${TABLE_MARKER}). Missing: ${names.filter((n) => !listed.includes(n)).join(", ") || "none"}. ` +
139        `Not in the phages table: ${listed.filter((n) => !names.includes(n)).join(", ") || "none"}`,
140    );
141  }
142  const head = /<thead>([\s\S]*?)<\/thead>/.exec(html)?.[1] ?? "";
143  const columns = [...head.matchAll(/<th[^>]*>([\s\S]*?)<\/th>/g)].map((m) => text(m[1] ?? ""));
144  if (columns.join("|") !== "Phage|Year|Host|County|PhagesDB|Paper") {
145    errors.push(`the table's columns are ${columns.join(", ")}; they must be Phage, Year, Host, County, PhagesDB, Paper`);
146  }
147  for (const cells of rows) {
148    const name = text(cells[0] ?? "");
149    if (cells.length !== 6) errors.push(`${name} has ${cells.length} columns; the table has six`);
150    const record = phages.find((p) => p.name === name)?.phagesdb ?? null;
151    const links = hrefsOf(cells[4] ?? "");
152    const want = record ? [phagesDbUrl(record)] : [];
153    if (links.join(" ") !== want.join(" ")) {
154      errors.push(`${name} links ${links.join(", ") || "no PhagesDB record"}; it must link ${want.join(", ") || "none, as it has no verified record"}`);
155    }
156  }
157  const verified = new Set(phages.flatMap((p) => (p.phagesdb ? [phagesDbUrl(p.phagesdb)] : [])));
158  for (const href of [...html.matchAll(/href="(https:\/\/phagesdb\.org[^"]*)"/g)].map((m) => m[1] ?? "")) {
159    if (!verified.has(href)) errors.push(`${href} is a PhagesDB link outside the verified records`);
160  }
161  for (const { name, phagesdb: record } of phages) {
162    const parts = markdown.split(`\n### ${name}\n`);
163    const section = parts[1]?.split("\n### ")[0] ?? "";
164    if (parts.length > 2) errors.push(`${name} has ${parts.length - 1} ### sections; the page's own text repeats the heading the drawn section has`);
165    else if (!section) errors.push(`${name} has no ### section; the old /discovery-of-${name.toLowerCase()} address redirects to its heading`);
166    else if (section.includes("phagesdb.org") !== (record !== null)) {
167      errors.push(`the ${name} section ${record !== null ? "must link" : "must not link"} PhagesDB, as the table does`);
168    }
169  }
170  return errors;
171}
172
173/**
174 * The named software pages: the explanation of the name comes after what the software does (Dustin,
175 * 2026-09-29), the Capsid portal sentence stays, and the Carrel page names neither its address nor its
176 * code repository (Dustin, 2026-09-28).
177 *
178 * @param {InvariantPage} page
179 */
180function softwareNameErrors({ path, markdown }) {
181  /** @type {string[]} */
182  const errors = [];
183  if (["/software/capsid", "/software/enarratio", "/software/carrel", "/software/capsomer"].includes(path)) {
184    const headings = [...markdown.matchAll(/^## (.+)$/gm)].map((m) => m[1]);
185    if (!headings.includes("Why the name")) errors.push('the page has no "Why the name" section');
186    else if (headings[0] === "Why the name") errors.push('the "Why the name" section belongs after what the software does, not first');
187  }
188  if (path === "/software/capsid" && !markdown.includes("Its dashboard, the Capsid Portal, is named for the portal protein")) {
189    errors.push("the Capsid page lacks the sentence naming the Capsid Portal for the portal protein");
190  }
191  if (path === "/software/carrel") {
192    if (markdown.includes("carrel.dustinedwards.info")) errors.push("the Carrel page names the app by its address; it names it nowhere");
193    if (/github\.com\/DrDustinEdwards\/carrel/i.test(markdown)) {
194      errors.push("the Carrel page links its code repository; the repository is public only for now, so a link would rot");
195    }
196  }
197  return errors;
198}
199
200/** The least HTML About may render: below it the page is a blank one that still looks like a successful build. */
201const ABOUT_HTML_FLOOR = 200;
202
203/**
204 * About (check:content used to render it twice and hold it to this floor, and check:links held its links):
205 * an empty or near-empty render is a valid row describing a blank page, which is the one failure here that
206 * looks like success.
207 *
208 * @param {InvariantPage} page
209 */
210function aboutErrors({ path, html }) {
211  if (path !== "/about" || html.length >= ABOUT_HTML_FLOOR) return [];
212  return [`the page renders ${html.length} character(s) of HTML, floor ${ABOUT_HTML_FLOOR}; an empty About would ship as a blank page`];
213}
214
215/**
216 * @param {InvariantPage} page
217 * @param {{ phages?: import("../phages/compile.mjs").Phage[] }} [rows] the phage rows the page was drawn from
218 * @returns {string[]}
219 */
220export function pageInvariantErrors(page, rows = {}) {
221  return [
222    ...calculatorErrors(page),
223    ...calculatorLinkErrors(page),
224    ...phageTableErrors(page, rows.phages),
225    ...softwareNameErrors(page),
226    ...aboutErrors(page),
227  ];
228}