app/kb/procedures/validate.mjs

Functions

Imports

It imports app/kb/bases.mjs, app/kb/procedures/cite.mjs, app/kb/procedures/parse.mjs, app/kb/procedures/proof.mjs, app/kb/procedures/taxonomy.mjs, app/lib/phage-tools.mjs. Imported by app/components/procedure-materials.tsx, app/kb/form-fields.mjs, app/kb/libraries.mjs, app/kb/procedures/compile.mjs, app/kb/procedures/render.mjs, app/kb/registry/strain.mjs.

Source

1// Judges a parsed procedure against its profile (docs/PROCEDURES.md). check:protocols and the operator
2// API's save_procedure both call validateProcedure, so a file CI refuses is a file the save tool refuses,
3// for the same reason in the same words.
4//
5// A value nobody has yet is written "MISSING: <why>" in place. It passes and is returned as a gap, so
6// the check can print it and the read tool can show it. A bare MISSING, or a required field left out,
7// is an error: a forgotten field cannot pass as a recorded gap.
8
9import { DOI_PATTERN, VERSION_PATTERN } from "./cite.mjs";
10import { allSteps, PLATFORMS, readCalcs, stepConditions } from "./parse.mjs";
11import { proofErrors } from "./proof.mjs";
12import { COURSES, METHODS, NON_STRAIN_ORGANISMS, PROTOCOL_STATUSES } from "./taxonomy.mjs";
13import { TOOLS } from "../../lib/phage-tools.mjs";
14import { BASES } from "../bases.mjs";
15
16const PROFILES = /** @type {const} */ (["protocol", "recipe", "computational"]);
17
18/** Where each profile's pages live (its knowledge base's root, app/kb/bases.mjs); the file's name is the last segment. */
19const PROFILE_ROOTS = /** @type {Record<(typeof PROFILES)[number], string>} */ (
20  Object.fromEntries(BASES.map((base) => [base.profile, base.entryRoot]))
21);
22
23const NOT_APPLICABLE = "not applicable";
24
25/** A software how-to's form, per Diátaxis (docs/KNOWLEDGE-BASE.md, S1): a lesson that teaches, or a recipe for a task. */
26export const HOWTO_TYPES = /** @type {const} */ ({ tutorial: "Tutorial", "how-to": "How-to" });
27
28/** The sentences a how-to's WHY may run to before its reasoning belongs on an explanation page it links (S1). */
29const HOWTO_WHY_SENTENCES = 3;
30
31/** The sentences in some markdown: each run of words ended by ., ! or ? before a capital or the end, so "e.g. this" is one. @param {string} text */
32export function sentenceCount(text) {
33  return (text.replace(/`[^`]*`/g, "x").match(/[^.!?]*[A-Za-z0-9][^.!?]*[.!?]+(?=[*_]*(?:\s+[*_]*[A-Z0-9]|\s*$))/g) ?? []).length;
34}
35
36/** Units are a closed list. A unit outside it fails until it is added here on purpose. */
37const PROTOCOL_UNITS = [
38  "µl", "µL", "ml", "mL", "l", "L", "M", "mM", "µM", "nM", "mg/ml", "µg/ml", "ng/µl", "%", "U", "g", "mg", "µg", "ng",
39  "volume", "volumes", "tube", "tubes", "reaction", "reactions", "plate", "plates", "x",
40];
41const TIME_UNITS = ["second", "seconds", "sec", "s", "minute", "minutes", "min", "hour", "hours", "h", "day", "days"];
42
43/** A recorded gap: the marker and the reason, never the marker alone. */
44const GAP = /^MISSING:\s*(\S.*)$/s;
45
46/** The levels a protocol's `biosafety_level` may name; each is Dustin's to set. */
47export const BIOSAFETY_LEVELS = ["BSL-1", "BSL-2"];
48
49/** Words kept off a protocol's `biosafety` note: the agent only. The separate `biosafety_level` field holds the level. */
50const BIOSAFETY_BANNED = /\b(BSL|biosafety level|IBC|NIH)\b/i;
51
52/** A primer's id in the lab registry (app/kb/registry/compile.mjs ID_PATTERN): a protocol names primers by it and stores no sequence. */
53const PRIMER_ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
54
55const SEO_TITLE_MAX = 60;
56const DESCRIPTION_MAX = 155;
57
58/**
59 * @param {unknown} value
60 */
61function isGap(value) {
62  return typeof value === "string" && GAP.test(value);
63}
64
65/**
66 * @param {Record<string, unknown>} item
67 * @param {number} index
68 */
69function label(item, index) {
70  for (const key of ["id", "name", "set", "citation", "for"]) {
71    if (typeof item[key] === "string" && item[key]) return /** @type {string} */ (item[key]);
72  }
73  return String(index);
74}
75
76/** What an item in a list is called in words: its name, stage or set, else its id. @param {Record<string, unknown>} item */
77function itemName(item) {
78  for (const key of ["name", "stage", "set", "id", "citation", "for"]) {
79    if (typeof item[key] === "string" && item[key]) return /** @type {string} */ (item[key]);
80  }
81  return null;
82}
83
84/**
85 * Every recorded gap under `value`, by path, with `where`: the same place in words, below the top-level field, so the
86 * admin can say "TES buffer: storage" for solutions[tes-buffer].storage (app/kb/gap-labels.mjs). An unnamed item is its
87 * place in its list ("step 2"), left out when it is the list's only item.
88 *
89 * @param {unknown} value
90 * @param {string} path
91 * @param {Array<{ field: string, reason: string, where?: string[] }>} gaps
92 * @param {string[]} errors
93 * @param {string[]} [where]
94 * @param {string} [key] the key the value sits under
95 */
96function collectGaps(value, path, gaps, errors, where = [], key = "") {
97  if (typeof value === "string") {
98    const m = GAP.exec(value);
99    if (m) gaps.push({ field: path, reason: (m[1] ?? "").trim(), ...(where.length > 0 ? { where } : {}) });
100    else if (/^MISSING\b/.test(value)) errors.push(`${path} is "${value}": write MISSING: and the reason it is missing`);
101  } else if (Array.isArray(value)) {
102    value.forEach((item, i) => {
103      const object = item && typeof item === "object" ? /** @type {Record<string, unknown>} */ (item) : null;
104      const name = object ? itemName(object) : null;
105      const words = name ? [...where, name] : value.length > 1 ? [...where, `${key.replace(/s$/, "")} ${i + 1}`] : where;
106      collectGaps(item, `${path}[${object ? label(object, i) : i}]`, gaps, errors, words, key);
107    });
108  } else if (value && typeof value === "object") {
109    for (const [k, v] of Object.entries(value)) {
110      // A list or a group under a key is named by its items; a value is named by its key.
111      const leaf = path && !(v && typeof v === "object");
112      collectGaps(v, path ? `${path}.${k}` : k, gaps, errors, leaf ? [...where, k.replace(/_c$/, " (°C)").replaceAll("_", " ")] : where, k);
113    }
114  }
115}
116
117/**
118 * "250 µl", "0.5 ml", "100% or 80%", "1.25 to 5 µl", "2.5 volumes".
119 *
120 * @param {string[]} units
121 */
122function quantityPattern(units) {
123  const number = String.raw`\d[\d,]*(?:\.\d+)?`;
124  const unit = units.map((u) => u.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")).join("|");
125  return new RegExp(`^${number}(?: ?(?:${unit}))?(?: (?:to|or) ${number})? ?(?:${unit})$`);
126}
127
128const PROTOCOL_QUANTITY = quantityPattern(PROTOCOL_UNITS);
129
130/**
131 * @param {unknown} value
132 */
133function nonEmptyString(value) {
134  return typeof value === "string" && value.trim().length > 0;
135}
136
137/**
138 * The version history, newest first: each version with its date, what changed and, once Zenodo has minted
139 * one, its DOI. The first entry is the version the page is at, so the version is stored once in `version`
140 * and the history cannot disagree with it.
141 *
142 * @param {Record<string, any>} d
143 * @param {string[]} errors
144 */
145function validateHistory(d, errors) {
146  if (d.history === undefined || isGap(d.history)) return;
147  if (!Array.isArray(d.history) || d.history.length === 0) {
148    errors.push("history must be a list of versions, newest first");
149    return;
150  }
151  const seen = new Set();
152  let newer = "9999-12-31";
153  d.history.forEach((/** @type {any} */ h, /** @type {number} */ i) => {
154    const at = `history[${h?.version ?? i}]`;
155    if (!h || typeof h !== "object") return errors.push(`${at} must be a version`);
156    for (const k of Object.keys(h)) if (!["version", "date", "summary", "doi"].includes(k)) errors.push(`${at}.${k} is not a history field (version, date, summary, doi)`);
157    if (!VERSION_PATTERN.test(String(h.version ?? ""))) errors.push(`${at} needs a version of letters, digits, dots, hyphens and underscores`);
158    if (seen.has(String(h.version))) errors.push(`${at}: the version is listed twice`);
159    seen.add(String(h.version));
160    if (!/^\d{4}-\d{2}-\d{2}$/.test(String(h.date ?? ""))) errors.push(`${at}.date is ${JSON.stringify(h.date)}; write the date as YYYY-MM-DD`);
161    else if (String(h.date) > newer) errors.push(`${at}.date ${h.date} is later than the entry above it; the history is newest first`);
162    else newer = String(h.date);
163    if (!nonEmptyString(h.summary)) errors.push(`${at} needs a summary of what changed`);
164    if (h.doi !== undefined && !DOI_PATTERN.test(String(h.doi))) errors.push(`${at}.doi is ${JSON.stringify(h.doi)}; write the DOI as 10.xxxx/suffix, without the https://doi.org/ address`);
165  });
166  if (d.version === undefined || d.version === null || isGap(d.version)) {
167    errors.push("history needs a version: the first entry is the version the page is at, so set version to it");
168  } else if (String(d.history[0]?.version) !== String(d.version)) {
169    errors.push(`version is ${JSON.stringify(d.version)} but the first history entry is ${JSON.stringify(String(d.history[0]?.version))}; the newest entry is the current version`);
170  }
171}
172
173/**
174 * Checks one parsed procedure.
175 *
176 * @param {import("./parse.mjs").ParsedProcedure} parsed
177 * @param {{ slug: string, primers?: ReadonlySet<string> | null, strains?: ReadonlySet<string> | null, reagents?: ReadonlySet<string> | null, equipment?: ReadonlySet<string> | null }} expect the slug its file name gives, and the ids of the primers and
178 *   host strains the lab registry holds (null or absent when the registry is not at hand, which `compileProcedure` refuses for a protocol that lists primers)
179 * @returns {{ errors: string[], gaps: Array<{ field: string, reason: string, where?: string[], section?: string }> }}
180 */
181export function validateProcedure(parsed, expect) {
182  /** @type {string[]} */
183  const errors = [...parsed.problems];
184  /** @type {Array<{ field: string, reason: string, where?: string[], section?: string }>} */
185  const gaps = [];
186  const d = parsed.data;
187  const profile = /** @type {typeof PROFILES[number]} */ (d.profile);
188
189  if (!PROFILES.includes(profile)) {
190    errors.push(`profile is ${JSON.stringify(d.profile)}; it must be one of ${PROFILES.join(", ")}`);
191    return { errors, gaps };
192  }
193
194  /** @param {string} field */
195  const required = (field) => {
196    const value = d[field];
197    if (value === undefined || value === null || value === "" || (Array.isArray(value) && value.length === 0)) {
198      errors.push(`${field} is required for a ${profile}; write the value, or "MISSING: <why>" if nobody has it yet`);
199      return false;
200    }
201    return true;
202  };
203
204  collectGaps(d, "", gaps, errors);
205
206  // Identity.
207  const root = PROFILE_ROOTS[profile];
208  if (required("path")) {
209    if (typeof d.path !== "string" || d.path !== `${root}${expect.slug}`) {
210      errors.push(`path is ${JSON.stringify(d.path)}; a ${profile} named ${expect.slug}.md lives at ${root}${expect.slug}`);
211    }
212  }
213  for (const field of ["title", "seo_title", "description"]) {
214    if (required(field) && !nonEmptyString(d[field])) errors.push(`${field} must be text`);
215  }
216  if (typeof d.seo_title === "string" && d.seo_title.length > SEO_TITLE_MAX) {
217    errors.push(`seo_title is ${d.seo_title.length} characters; Google clips near ${SEO_TITLE_MAX}`);
218  }
219  if (typeof d.description === "string" && d.description.length > DESCRIPTION_MAX) {
220    errors.push(`description is ${d.description.length} characters; Google clips near ${DESCRIPTION_MAX}`);
221  }
222  if (d.draft !== undefined && typeof d.draft !== "boolean") errors.push("draft must be true or false");
223  // A variant made with the editor's Duplicate names the procedure it was copied from, and the version it was copied at.
224  if (d.forked_from !== undefined) {
225    const f = d.forked_from;
226    if (!f || typeof f !== "object" || Array.isArray(f) || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(String(f.slug ?? ""))) {
227      errors.push("forked_from is { slug, version }: the file name of the procedure this one was copied from, and its version if it had one");
228    } else {
229      for (const key of Object.keys(f)) if (!["slug", "version"].includes(key)) errors.push(`forked_from.${key} is not a forked_from field (slug, version)`);
230      if (f.slug === expect.slug) errors.push("forked_from names this procedure itself");
231    }
232  }
233
234  // What the library filters by. method, organism and course are ids from the closed lists in taxonomy.mjs; target
235  // is the gene, region or sample, in words. Every procedure is some method, so method is required.
236  // An organism is a non-strain organism or a strain of the lab registry (docs/REGISTRY.md), read from it as the host strains are.
237  const organisms = expect.strains ? [...Object.keys(NON_STRAIN_ORGANISMS), ...expect.strains] : null;
238  for (const [field, vocabulary] of /** @type {const} */ ([["method", METHODS], ["organism", null], ["course", COURSES]])) {
239    if (field === "method") required(field);
240    const value = d[field];
241    if (value === undefined || isGap(value)) continue;
242    const allowed = vocabulary ? Object.keys(vocabulary) : organisms;
243    // With no registry at hand an organism cannot be judged, and compileProcedure refuses a file that names one.
244    if (!allowed) continue;
245    if (!Array.isArray(value)) errors.push(`${field} must be a list of ids from: ${allowed.join(", ")}`);
246    else {
247      for (const id of value) {
248        if (allowed.includes(id)) continue;
249        errors.push(
250          vocabulary
251            ? `${field} "${id}" is not one of: ${allowed.join(", ")} (taxonomy.mjs)`
252            : `organism "${id}" is neither one of: ${Object.keys(NON_STRAIN_ORGANISMS).join(", ")} (taxonomy.mjs) nor a strain in the lab registry (there is no content/registry/strain/${id}.md)`,
253        );
254      }
255      if (new Set(value).size !== value.length) errors.push(`${field} names one id twice`);
256    }
257  }
258  if (d.target !== undefined && !isGap(d.target)) {
259    if (!Array.isArray(d.target) || d.target.some((t) => !nonEmptyString(t))) errors.push("target must be a list of the genes, regions or samples it works on, each in words");
260  }
261
262  // Where it stands in the library's "Start here" list: a position (1, 2, ...), stored, never inferred. A position
263  // two procedures share would make the order a guess, so the corpus check refuses it (checkStartHere).
264  if (d.start_here !== undefined && !isGap(d.start_here)) {
265    if (!Number.isInteger(d.start_here) || d.start_here < 1) errors.push("start_here must be a position in the Start here list: 1, 2, 3 ...");
266  }
267
268  // Proof of use: the papers that used the method and the phages it produced, as slugs. Stated, never inferred.
269  if (!isGap(d.proof_of_use)) errors.push(...proofErrors(d.proof_of_use));
270
271  // The shared core.
272  if (required("version") && !isGap(d.version) && !VERSION_PATTERN.test(String(d.version))) {
273    errors.push(`version is ${JSON.stringify(d.version)}; it sits in a URL, so use letters, digits, dots, hyphens and underscores, such as "2" or "1.1"`);
274  }
275  validateHistory(d, errors);
276  if (required("updated") && !isGap(d.updated) && !/^\d{4}-\d{2}-\d{2}$/.test(String(d.updated))) {
277    errors.push(`updated is ${JSON.stringify(d.updated)}; write the date as YYYY-MM-DD`);
278  }
279  if (required("based_on") && !isGap(d.based_on)) {
280    if (!Array.isArray(d.based_on)) errors.push("based_on must be a list of sources");
281    else {
282      d.based_on.forEach((/** @type {any} */ s, /** @type {number} */ i) => {
283        if (!s || typeof s !== "object" || !nonEmptyString(s.citation)) errors.push(`based_on[${i}] needs a citation`);
284        else if (!nonEmptyString(s.for)) errors.push(`based_on[${s.citation}] needs a "for": what it is the source of`);
285      });
286    }
287  }
288  if (required("references") && !isGap(d.references)) {
289    if (!Array.isArray(d.references) || d.references.some((r) => !nonEmptyString(r))) {
290      errors.push("references must be a list of markdown lines");
291    }
292  }
293  for (const field of ["expected_results", "limitations"]) {
294    if (required(field) && !nonEmptyString(d[field])) errors.push(`${field} must be markdown text`);
295  }
296  if (d.time !== undefined) {
297    if (!d.time || typeof d.time !== "object") errors.push("time must hold total and hands_on");
298    else for (const k of Object.keys(d.time)) if (!["total", "hands_on"].includes(k)) errors.push(`time.${k} is not a time field`);
299  }
300
301  // Materials and equipment.
302  /** @type {Map<string, any>} */
303  const materials = new Map();
304  if (profile !== "recipe" || d.materials !== undefined) {
305    if (required("materials")) {
306      if (!Array.isArray(d.materials)) errors.push("materials must be a list");
307      else {
308        d.materials.forEach((/** @type {any} */ m, /** @type {number} */ i) => {
309          if (!m || typeof m !== "object" || !nonEmptyString(m.name)) {
310            errors.push(`materials[${i}] needs a name`);
311            return;
312          }
313          const key = m.name.toLowerCase();
314          if (materials.has(key)) errors.push(`materials lists "${m.name}" twice`);
315          materials.set(key, m);
316        });
317      }
318    }
319  }
320  if (d.equipment !== undefined && !Array.isArray(d.equipment)) errors.push("equipment must be a list");
321  // An item that is lab-registry equipment names it with `equipment: <id>` (docs/REGISTRY.md): the protocol keeps its own phrase for
322  // it (the setting is the protocol's), and who makes it is stored there once.
323  if (Array.isArray(d.equipment)) {
324    for (const e of d.equipment) {
325      if (typeof e !== "object" || e === null || e.equipment === undefined) continue;
326      const at = `equipment[${String(e.name)}]`;
327      if (typeof e.equipment !== "string" || !PRIMER_ID.test(e.equipment)) {
328        errors.push(`${at}.equipment is the id of an equipment item in the lab registry (content/registry/equipment/), such as water-bath`);
329      } else if (expect.equipment && !expect.equipment.has(e.equipment)) {
330        errors.push(`${at}.equipment names no equipment in the lab registry (there is no content/registry/equipment/${e.equipment}.md)`);
331      }
332    }
333  }
334  const equipmentNames = new Set(
335    (Array.isArray(d.equipment) ? d.equipment : []).map((/** @type {any} */ e) =>
336      String(typeof e === "string" ? e : e?.name ?? "").toLowerCase(),
337    ),
338  );
339
340  // Troubleshooting.
341  const troubleIds = new Set();
342  if (d.troubleshooting !== undefined) {
343    if (!Array.isArray(d.troubleshooting)) errors.push("troubleshooting must be a list of rows");
344    else {
345      d.troubleshooting.forEach((/** @type {any} */ row, /** @type {number} */ i) => {
346        const at = `troubleshooting[${row?.id ?? i}]`;
347        if (!row || typeof row !== "object") return errors.push(`${at} must be a row`);
348        if (!/^[a-z0-9-]+$/.test(String(row.id ?? ""))) errors.push(`${at} needs an id in lowercase-with-hyphens`);
349        if (troubleIds.has(row.id)) errors.push(`${at}: the id is used twice`);
350        troubleIds.add(row.id);
351        for (const col of ["step", "problem", "reason", "solution"]) {
352          if (!nonEmptyString(row[col])) errors.push(`${at} needs ${col}: the table's columns are step, problem, possible reason, solution`);
353        }
354        for (const k of Object.keys(row)) {
355          if (!["id", "step", "problem", "reason", "solution"].includes(k)) errors.push(`${at}.${k} is not a column`);
356        }
357      });
358    }
359  }
360
361  // The method.
362  const steps = allSteps(parsed);
363  if (steps.length === 0) errors.push("the procedure has no steps: a method section holds a numbered list");
364  let previous = 0;
365  for (const section of parsed.sections) {
366    for (const block of section.blocks) {
367      if (block.type !== "steps") continue;
368      const first = block.steps[0];
369      if (first && first.number !== 1 && first.number !== previous + 1) {
370        errors.push(`line ${first.line}: step ${first.number} neither restarts at 1 nor follows step ${previous}`);
371      }
372      block.steps.forEach((step, i) => {
373        if (i > 0 && step.number !== (block.steps[i - 1]?.number ?? 0) + 1) {
374          errors.push(`line ${step.line}: step ${step.number} follows step ${block.steps[i - 1]?.number}`);
375        }
376      });
377      previous = block.steps[block.steps.length - 1]?.number ?? previous;
378    }
379  }
380
381  // A step's section, so a gap in it can say where it is (app/kb/gap-labels.mjs).
382  const sectionOf = new Map(parsed.sections.flatMap((section) => section.blocks.flatMap((block) => (block.type === "steps" ? block.steps.map((s) => [s, section.title]) : []))));
383  for (const step of steps) {
384    const at = `line ${step.line}, step ${step.number}`;
385    if (!step.source.trim()) errors.push(`${at} has no words`);
386    for (const reason of step.flags.critical) if (!reason) errors.push(`${at}: CRITICAL needs its reason`);
387    for (const kind of /** @type {const} */ (["pause", "why", "expect", "challenge", "solution"])) {
388      for (const text of step.flags[kind]) if (!text) errors.push(`${at}: an empty ${kind.toUpperCase()} flag`);
389    }
390    for (const id of step.flags.troubleshooting) {
391      if (!troubleIds.has(id)) errors.push(`${at}: TROUBLESHOOTING names "${id}", which is not a row id in troubleshooting`);
392    }
393    if (step.flags.calc.length > 0 && profile !== "protocol") errors.push(`${at}: CALC belongs to the protocol profile`);
394    const calcs = readCalcs(step.flags.calc);
395    if (new Set(calcs.map((c) => c.id)).size !== calcs.length) errors.push(`${at}: CALC names a calculator twice`);
396    for (const { id, values } of calcs) {
397      const tool = Object.hasOwn(TOOLS, id) ? TOOLS[id] : undefined;
398      if (!tool) {
399        errors.push(id ? `${at}: CALC names "${id}", which is not a calculator (${Object.keys(TOOLS).join(", ")})` : `${at}: CALC gives a value before it names a calculator`);
400        continue;
401      }
402      for (const [name, value] of Object.entries(values)) {
403        if (!tool.fields.some((f) => f.name === name)) errors.push(`${at}: CALC ${id} has no field "${name}" (${tool.fields.map((f) => f.name).join(", ")})`);
404        // Every value is the step's own: a number that is not in the step's words is not from the record.
405        else if (!step.source.includes(value)) errors.push(`${at}: CALC ${id} ${name}=${value}, but the step does not state ${value}; a value is filled in only from the step's own words`);
406      }
407    }
408    for (const seg of step.segments) {
409      if (seg.type === "material") {
410        const declared = materials.get(seg.name.toLowerCase());
411        if (!declared && profile !== "recipe") {
412          errors.push(`${at}: @${seg.name} is not in materials; declare it there with its stock and amount`);
413        }
414        if (seg.quantity && profile === "protocol" && !PROTOCOL_QUANTITY.test(`${seg.quantity.amount} ${seg.quantity.unit}`.trim())) {
415          errors.push(`${at}: @${seg.name}'s amount "${seg.quantity.raw}" is not a number and a unit from the closed list (${PROTOCOL_UNITS.join(", ")})`);
416        }
417      }
418      if (seg.type === "equipment" && profile !== "recipe" && !equipmentNames.has(seg.name.toLowerCase())) {
419        errors.push(`${at}: #${seg.name} is not in equipment`);
420      }
421      if (seg.type === "timer") {
422        if (!seg.quantity || seg.quantity.min === null || !TIME_UNITS.includes(seg.quantity.unit)) {
423          errors.push(`${at}: the timer ~{${seg.quantity?.raw ?? ""}} needs a number and a unit of time (${TIME_UNITS.join(", ")})`);
424        }
425      }
426    }
427    if (profile === "protocol") {
428      const { spins } = stepConditions(step);
429      const words = step.segments.map((s) => (s.type === "text" ? s.value : "")).join("");
430      const spinsHere = /\bspin\b|\bspun\b|\bcentrifuge\b/i.test(words.replace(/pulse[- ]spin/gi, ""));
431      const hasG = spins.some((s) => s.unit === "x g");
432      if (spinsHere && !hasG && step.flags.spin.length === 0) {
433        errors.push(`${at} spins with no g-force: add "> SPIN: <n> x g", or "> SPIN: MISSING: <why>" (a speed in rpm needs the rotor)`);
434      }
435      for (const spin of step.flags.spin) {
436        if (isGap(spin)) gaps.push({ field: `step ${step.number} (line ${step.line}).spin`, reason: spin.replace(/^MISSING:\s*/, ""), section: sectionOf.get(step) ?? "" });
437        else if (!/x g\b/.test(spin)) errors.push(`${at}: SPIN "${spin}" is not in x g`);
438      }
439    } else if (step.flags.spin.length > 0) {
440      errors.push(`${at}: SPIN belongs to the protocol profile`);
441    }
442    // A tutorial teaches with challenges; a how-to links its reasoning out (S1, S5).
443    if (step.flags.challenge.length > 0 && !(profile === "computational" && d.type === "tutorial")) {
444      errors.push(`${at}: CHALLENGE belongs to a tutorial (a computational procedure with type: tutorial)`);
445    }
446    if (step.flags.solution.length < step.flags.challenge.length) errors.push(`${at}: each CHALLENGE needs its SOLUTION after it`);
447    if (profile === "computational" && d.type === "how-to") {
448      for (const why of step.flags.why) {
449        const n = sentenceCount(why);
450        if (n > HOWTO_WHY_SENTENCES) {
451          errors.push(`${at}: WHY runs to ${n} sentences; a how-to keeps a reason to ${HOWTO_WHY_SENTENCES} at most, so put the rest on a page and link it under explanation`);
452        }
453      }
454    }
455    /** @type {Set<string>} */
456    const platforms = new Set();
457    for (const cmd of step.commands) {
458      if (cmd.platform === null) continue;
459      if (profile !== "computational") errors.push(`${at}: platform= belongs to the computational profile`);
460      else if (!Object.hasOwn(PLATFORMS, cmd.platform)) errors.push(`${at}: platform=${cmd.platform} is not a platform (${Object.keys(PLATFORMS).join(", ")})`);
461      else if (platforms.has(cmd.platform)) errors.push(`${at}: two blocks for platform=${cmd.platform}; a step gives each platform one block`);
462      platforms.add(cmd.platform);
463    }
464    if (platforms.size === 1) errors.push(`${at}: a block names one platform alone; give each platform its block, or name none`);
465    if (profile === "computational") {
466      for (const cmd of step.commands) {
467        if (cmd.output === null && step.flags.expect.length === 0) {
468          errors.push(`${at}: a command needs its expected output: a \`\`\`output block after it, or an EXPECT flag`);
469        }
470      }
471    } else if (step.commands.length > 0 && profile === "recipe") {
472      errors.push(`${at}: a recipe step carries no commands`);
473    }
474    if (step.photos.length > 0 && profile !== "recipe") errors.push(`${at}: step photos belong to the recipe profile`);
475    for (const photo of step.photos) if (!photo.alt.trim()) errors.push(`${at}: a step photo needs its alt text`);
476  }
477
478  // The profiles.
479  // A recipe's density, so its volume can be shown as weight: a number the recipe states, never a table's (DECIDE 7).
480  for (const m of Array.isArray(d.materials) ? d.materials : []) {
481    if (m?.grams_per_cup === undefined) continue;
482    const at = `materials[${String(m.name)}].grams_per_cup`;
483    if (profile !== "recipe") errors.push(`${at} belongs to the recipe profile`);
484    else if (typeof m.grams_per_cup !== "number" || !(m.grams_per_cup > 0)) errors.push(`${at} is the grams in one US cup of it, a number above 0`);
485  }
486  if (profile === "protocol") protocolRules(d, errors, required, materials, expect.primers ?? null, expect.strains ?? null, expect.reagents ?? null);
487  if (profile === "recipe") recipeRules(d, errors, required);
488  if (profile === "computational") computationalRules(d, errors, required, materials);
489  else {
490    for (const field of ["type", "questions", "objectives", "key_points", "explanation"]) {
491      if (d[field] !== undefined) errors.push(`${field} belongs to the computational profile`);
492    }
493  }
494
495  return { errors, gaps };
496}
497
498/**
499 * @param {Record<string, any>} d
500 * @param {string[]} errors
501 * @param {(field: string) => boolean} required
502 * @param {Map<string, any>} materials
503 * @param {ReadonlySet<string> | null} primerIds the primers the lab registry holds
504 * @param {ReadonlySet<string> | null} strainIds the strains the lab registry holds
505 * @param {ReadonlySet<string> | null} reagentIds the reagents the lab registry holds
506 */
507function protocolRules(d, errors, required, materials, primerIds, strainIds, reagentIds) {
508  for (const field of ["host_strain", "status", "last_run", "biosafety", "biosafety_level", "scale"]) required(field);
509  // A host strain is the lab registry's, named by id and never typed (docs/REGISTRY.md): its organism, designation and
510  // collection number are stored once, on its record.
511  if (d.host_strain !== undefined && d.host_strain !== NOT_APPLICABLE && !isGap(d.host_strain)) {
512    if (!Array.isArray(d.host_strain)) errors.push(`host_strain must be a list of { strain: <id> }, "${NOT_APPLICABLE}" or "MISSING: <why>"`);
513    else {
514      /** @type {Set<string>} */
515      const seenStrains = new Set();
516      for (const s of d.host_strain) {
517        const id = s?.strain;
518        const at = `host_strain[${typeof id === "string" ? id : "?"}]`;
519        if (typeof id !== "string" || !PRIMER_ID.test(id)) {
520          errors.push(`${at} is { strain: <id> }: the id of a strain in the lab registry (content/registry/strain/), such as foliorum. A protocol names its host strains and types none`);
521        } else if (seenStrains.has(id)) {
522          errors.push(`${at} is listed twice`);
523        } else {
524          seenStrains.add(id);
525          if (strainIds && !strainIds.has(id)) errors.push(`${at} names no strain in the lab registry (there is no content/registry/strain/${id}.md)`);
526        }
527        for (const key of Object.keys(s ?? {})) {
528          if (key !== "strain") errors.push(`${at}.${key} is not a protocol field: a strain's organism and collection number are stored once, in the lab registry`);
529        }
530      }
531    }
532  }
533  if (d.status !== undefined && !isGap(d.status) && !Object.keys(PROTOCOL_STATUSES).includes(d.status)) {
534    errors.push(`status is ${JSON.stringify(d.status)}; it is one of ${Object.keys(PROTOCOL_STATUSES).join(", ")} (taxonomy.mjs), or "MISSING: <why>"`);
535  }
536  if (d.biosafety_level !== undefined && !isGap(d.biosafety_level) && !BIOSAFETY_LEVELS.includes(d.biosafety_level)) {
537    errors.push(`biosafety_level is ${JSON.stringify(d.biosafety_level)}; it is one of ${BIOSAFETY_LEVELS.join(", ")}, or "MISSING: <why>" until Dustin sets it`);
538  }
539  if (d.biosafety && !isGap(d.biosafety) && d.biosafety !== NOT_APPLICABLE) {
540    if (typeof d.biosafety !== "object" || !nonEmptyString(d.biosafety.organism)) {
541      errors.push('biosafety lists the agent only: { organism, strain, atcc }, or "not applicable"');
542    } else {
543      for (const k of Object.keys(d.biosafety)) {
544        if (!["organism", "strain", "atcc"].includes(k)) errors.push(`biosafety.${k}: the agent only (organism, strain, ATCC number)`);
545      }
546    }
547  }
548  if (BIOSAFETY_BANNED.test(JSON.stringify(d.biosafety ?? ""))) {
549    errors.push("biosafety names a biosafety level, an IBC or the NIH Guidelines; it lists the agent only");
550  }
551  if (d.scale && !isGap(d.scale)) {
552    if (typeof d.scale !== "object" || !(Number(d.scale.count) > 0) || !nonEmptyString(d.scale.unit)) {
553      errors.push("scale needs a count and a unit, such as { count: 5, unit: tube }");
554    }
555  }
556  const solutionIds = new Set();
557  if (d.solutions !== undefined) {
558    if (!Array.isArray(d.solutions)) errors.push("solutions must be a list");
559    else {
560      for (const s of d.solutions) {
561        const at = `solutions[${s?.id ?? "?"}]`;
562        if (!s || !/^[a-z0-9-]+$/.test(String(s.id ?? ""))) errors.push(`${at} needs an id in lowercase-with-hyphens`);
563        solutionIds.add(s?.id);
564        if (!nonEmptyString(s?.name)) errors.push(`${at} needs a name`);
565        if (!Array.isArray(s?.components) || s.components.length === 0) errors.push(`${at} needs its components`);
566        for (const field of ["storage", "shelf_life"]) {
567          if (!nonEmptyString(s?.[field])) errors.push(`${at} needs ${field}, or "MISSING: <why>"`);
568        }
569        for (const c of Array.isArray(s?.components) ? s.components : []) {
570          if (!nonEmptyString(c?.name)) errors.push(`${at} has a component with no name`);
571          for (const q of ["final", "amount"]) {
572            if (c?.[q] !== undefined && !isGap(c[q]) && !PROTOCOL_QUANTITY.test(String(c[q]))) {
573              errors.push(`${at}.${c.name}.${q} is "${c[q]}", not a number and a unit from the closed list`);
574            }
575          }
576        }
577      }
578    }
579  }
580  for (const m of materials.values()) {
581    const at = `materials[${m.name}]`;
582    // A material that is a reagent of the lab registry names it by id (docs/REGISTRY.md): who supplies it and its catalog number
583    // are stored there once, and the protocol keeps its own amount, stock and final.
584    if (m.reagent !== undefined) {
585      if (typeof m.reagent !== "string" || !PRIMER_ID.test(m.reagent)) {
586        errors.push(`${at}.reagent is the id of a reagent in the lab registry (content/registry/reagent/), such as zinc-chloride`);
587      } else if (reagentIds && !reagentIds.has(m.reagent)) {
588        errors.push(`${at}.reagent names no reagent in the lab registry (there is no content/registry/reagent/${m.reagent}.md)`);
589      }
590    }
591    for (const key of ["amount", "final", "per"]) {
592      const q = m[key];
593      if (q === undefined || isGap(q)) continue;
594      if (key === "per" && typeof q === "string" && !/^\d/.test(q)) continue;
595      if (typeof q !== "string" || !PROTOCOL_QUANTITY.test(q)) {
596        errors.push(`${at}.${key} is "${String(q)}", not a number and a unit from the closed list (${PROTOCOL_UNITS.join(", ")})`);
597      }
598    }
599    if (m.stock !== undefined) {
600      const stocks = Array.isArray(m.stock) ? m.stock : [m.stock];
601      for (const s of stocks) {
602        if (!isGap(s) && !PROTOCOL_QUANTITY.test(String(s))) errors.push(`${at}.stock "${s}" is not a number and a unit from the closed list`);
603      }
604    }
605    if (m.solution !== undefined && !solutionIds.has(m.solution)) errors.push(`${at}.solution names "${m.solution}", which is not in solutions`);
606  }
607  if (d.primers !== undefined && d.primers !== NOT_APPLICABLE && !isGap(d.primers)) {
608    if (!Array.isArray(d.primers)) errors.push(`primers must be a list, or "${NOT_APPLICABLE}"`);
609    else {
610      /** @type {Set<string>} */
611      const seen = new Set();
612      for (const p of d.primers) {
613        const id = p?.primer;
614        const at = `primers[${typeof id === "string" ? id : "?"}]`;
615        if (typeof id !== "string" || !PRIMER_ID.test(id)) {
616          errors.push(`${at} is { primer: <id> }: the id of a primer in the lab registry (content/registry/primer/), such as lco1490. A protocol names its primers and stores no sequence`);
617        } else if (seen.has(id)) {
618          errors.push(`${at} is listed twice`);
619        } else {
620          seen.add(id);
621          if (primerIds && !primerIds.has(id)) errors.push(`${at} names no primer in the lab registry (there is no content/registry/primer/${id}.md)`);
622        }
623        for (const key of Object.keys(p ?? {})) {
624          if (key !== "primer") errors.push(`${at}.${key} is not a protocol field: a primer's sequence, direction and set are stored once, in the lab registry`);
625        }
626      }
627    }
628  }
629  if (d.cycling !== undefined) {
630    if (!Array.isArray(d.cycling)) errors.push("cycling must be a list of programs");
631    else {
632      const walk = (/** @type {any} */ stage, /** @type {string} */ at) => {
633        if (Array.isArray(stage?.steps)) stage.steps.forEach((/** @type {any} */ s, /** @type {number} */ i) => walk(s, `${at}.steps[${i}]`));
634        if (typeof stage?.temperature_c === "string" && /^\d+ to \d+$/.test(stage.temperature_c) && stage.touchdown_step_c === undefined) {
635          errors.push(`${at} is a touchdown (${stage.temperature_c} °C) with no touchdown_step_c; write it, or "MISSING: <why>"`);
636        }
637      };
638      d.cycling.forEach((/** @type {any} */ program, /** @type {number} */ i) => {
639        const at = `cycling[${program?.set ?? i}]`;
640        if (!Array.isArray(program?.program)) errors.push(`${at} needs its program: a list of stages`);
641        else program.program.forEach((/** @type {any} */ stage, /** @type {number} */ j) => walk(stage, `${at}.program[${stage?.stage ?? j}]`));
642      });
643    }
644  }
645}
646
647/**
648 * @param {Record<string, any>} d
649 * @param {string[]} errors
650 * @param {(field: string) => boolean} required
651 */
652function recipeRules(d, errors, required) {
653  for (const field of ["servings", "cuisine", "category", "prep_time", "cook_time", "image"]) required(field);
654  if (d.servings !== undefined && !isGap(d.servings) && !(Number(d.servings) > 0)) errors.push("servings must be a number");
655  for (const field of ["prep_time", "cook_time"]) {
656    if (d[field] !== undefined && !isGap(d[field]) && !/^\d+(?:\.\d+)? (minutes?|hours?)$/.test(String(d[field]))) {
657      errors.push(`${field} is "${d[field]}"; write it as "20 minutes" or "1.5 hours"`);
658    }
659  }
660  if (d.image !== undefined && !isGap(d.image) && (!nonEmptyString(d.image?.src) || !nonEmptyString(d.image?.alt))) {
661    errors.push("image needs src and alt");
662  }
663  if (d.substitutions !== undefined) {
664    if (!Array.isArray(d.substitutions)) errors.push("substitutions must be a list");
665    else for (const s of d.substitutions) if (!nonEmptyString(s?.for) || !nonEmptyString(s?.use)) errors.push("each substitution needs for and use");
666  }
667  if (d.scale !== undefined) errors.push("a recipe scales by servings, not scale");
668}
669
670/**
671 * @param {Record<string, any>} d
672 * @param {string[]} errors
673 * @param {(field: string) => boolean} required
674 * @param {Map<string, any>} materials
675 */
676function computationalRules(d, errors, required, materials) {
677  required("environment");
678  if (required("type") && !Object.hasOwn(HOWTO_TYPES, d.type)) {
679    errors.push(`type is ${JSON.stringify(d.type)}; it is one of ${Object.keys(HOWTO_TYPES).join(", ")}`);
680  }
681  // A tutorial opens as a Carpentries episode does: what it answers, what the reader will be able to do, and how long (S2).
682  for (const field of ["questions", "objectives", "key_points"]) {
683    if (d[field] === undefined || isGap(d[field])) continue;
684    if (!Array.isArray(d[field]) || d[field].some((/** @type {unknown} */ x) => !nonEmptyString(x))) errors.push(`${field} must be a list of lines`);
685  }
686  if (d.type === "tutorial") {
687    required("objectives");
688    if (!d.time || !nonEmptyString(d.time.total)) errors.push("a tutorial states its time: time.total, such as 30 minutes");
689  }
690  if (d.explanation !== undefined && !isGap(d.explanation)) {
691    if (!Array.isArray(d.explanation)) errors.push("explanation must be a list of pages, each with a title and a url");
692    else {
693      d.explanation.forEach((/** @type {any} */ e, /** @type {number} */ i) => {
694        if (!e || typeof e !== "object" || !nonEmptyString(e.title)) errors.push(`explanation[${i}] needs a title`);
695        else if (typeof e.url !== "string" || !/^(\/[^/\s]|https:\/\/\S)/.test(e.url)) errors.push(`explanation[${e.title}].url is a page on this site (/...) or an https address`);
696      });
697    }
698  }
699  if (required("prerequisites") && !isGap(d.prerequisites) && !Array.isArray(d.prerequisites)) {
700    errors.push("prerequisites must be a list");
701  }
702  if (d.scale !== undefined || d.servings !== undefined) errors.push("a computational procedure does not scale");
703  for (const m of materials.values()) {
704    if (!["software", "data", "file"].includes(m.kind)) errors.push(`materials[${m.name}].kind must be software, data or file`);
705    if (m.kind === "software" && !nonEmptyString(m.version)) errors.push(`materials[${m.name}] is software and needs its version`);
706  }
707}