app/kb/procedures/compile.mjs

Functions

Imports

It imports app/kb/procedures/parse.mjs, app/kb/procedures/render.mjs, app/kb/procedures/taxonomy.mjs, app/kb/procedures/validate.mjs, app/kb/registry/catalog.mjs, app/lib/content/hashes.mjs. Imported by app/kb/procedures/save.server.ts.

Source

1// One door from a procedure file to everything derived from it: parse, validate, render, the markdown
2// twin and the search input. check:protocols, sync:content and the operator API's save_procedure all
3// call compileProcedure, so a file CI passes is the file the save tool accepts and the page draws.
4
5import { gitBlobSha } from "../../lib/content/hashes.mjs";
6import { itemPath } from "../registry/catalog.mjs";
7import { NON_STRAIN_ORGANISMS } from "./taxonomy.mjs";
8import { parseProcedure, procedurePath } from "./parse.mjs";
9import { procedureSearchInput, renderProcedure } from "./render.mjs";
10import { validateProcedure } from "./validate.mjs";
11
12/** The file name a slug is written in; the same rule as a post's. */
13const PROCEDURE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
14
15/**
16 * @param {{
17 *   slug: string,
18 *   raw: string,
19 *   pipeline: { renderBody: import("./render.mjs").RenderBody, findWideDashes: (text: string) => Array<{ line: number, column: number, char: string, excerpt: string }> },
20 *   resolveImage?: (src: string) => Promise<{ width: number, height: number }>,
21 *   registry?: {
22 *     primers: (ids: string[]) => Promise<Map<string, import("./render.mjs").StoredPrimer>>,
23 *     strains: (ids: string[]) => Promise<Map<string, import("./render.mjs").StoredStrain>>,
24 *     reagents: (ids: string[]) => Promise<Map<string, import("./render.mjs").StoredReagent>>,
25 *     equipment: (ids: string[]) => Promise<Map<string, import("./render.mjs").StoredEquipment>>,
26 *   },
27 * }} input
28 * @returns {Promise<
29 *   | { ok: false, errors: string[], gaps: Array<{ field: string, reason: string }> }
30 *   | { ok: true, errors: [], gaps: Array<{ field: string, reason: string }>, record: import("./render.mjs").ProcedureRecord,
31 *       markdown: string, searchInput: ReturnType<typeof procedureSearchInput>, sourcePath: string, sourceBlobSha: string }
32 * >}
33 */
34export async function compileProcedure({ slug, raw, pipeline, resolveImage, registry }) {
35  if (!PROCEDURE_SLUG.test(slug)) {
36    return { ok: false, errors: [`"${slug}" is not a lowercase kebab-case slug`], gaps: [] };
37  }
38  const file = procedurePath(slug);
39  const dashes = pipeline.findWideDashes(raw).map(
40    (hit) => `line ${hit.line}, column ${hit.column}: wide dash ${hit.char}; house style uses commas, periods, parentheses or colons ("${hit.excerpt}")`,
41  );
42  const parsed = parseProcedure({ file, raw });
43  // A protocol names its primers by their id in the lab registry and stores no sequence (docs/REGISTRY.md); the registry's
44  // rows are read here, so the record carries them and a frozen version freezes them. A caller with no registry cannot
45  // compile a protocol that names primers: writing a record with no primer table would be silent.
46  const named = Array.isArray(parsed.data.primers) ? parsed.data.primers.flatMap((p) => (typeof p?.primer === "string" ? [p.primer] : [])) : [];
47  const namedStrains = Array.isArray(parsed.data.host_strain) ? parsed.data.host_strain.flatMap((s) => (typeof s?.strain === "string" ? [s.strain] : [])) : [];
48  // An organism that is not a non-strain organism is a strain of the registry, so it is read from there too.
49  const organismIds = Array.isArray(parsed.data.organism) ? parsed.data.organism.filter((id) => typeof id === "string" && !Object.hasOwn(NON_STRAIN_ORGANISMS, id)) : [];
50  // A material that is a reagent of the registry names it by id; its facts are the registry's, not typed in the protocol.
51  const namedReagents = Array.isArray(parsed.data.materials) ? parsed.data.materials.flatMap((m) => (typeof m?.reagent === "string" ? [m.reagent] : [])) : [];
52  // An equipment entry that is an item of the registry names it by id.
53  const namedEquipment = Array.isArray(parsed.data.equipment) ? parsed.data.equipment.flatMap((e) => (typeof e?.equipment === "string" ? [e.equipment] : [])) : [];
54  if ((named.length > 0 || namedStrains.length > 0 || organismIds.length > 0 || namedReagents.length > 0 || namedEquipment.length > 0) && !registry) {
55    return { ok: false, errors: ["this compile was given no lab registry, so the primers, host strains, organisms, reagents and equipment the file names cannot be read"], gaps: [] };
56  }
57  const primerRows = named.length > 0 && registry ? await registry.primers(named) : new Map();
58  const strainIds = [...new Set([...namedStrains, ...organismIds])];
59  const strainRows = strainIds.length > 0 && registry ? await registry.strains(strainIds) : new Map();
60  const equipmentIds = [...new Set(namedEquipment)];
61  const equipmentRows = equipmentIds.length > 0 && registry ? await registry.equipment(equipmentIds) : new Map();
62  const reagentIds = [...new Set(namedReagents)];
63  const reagentRows = reagentIds.length > 0 && registry ? await registry.reagents(reagentIds) : new Map();
64  const { errors, gaps } = validateProcedure(parsed, { slug, primers: new Set(primerRows.keys()), strains: new Set(strainRows.keys()), reagents: new Set(reagentRows.keys()), equipment: new Set(equipmentRows.keys()) });
65  // A draft primer is the admin's alone, so a published protocol may not print it.
66  if (parsed.data.draft !== true) {
67    for (const [id, row] of primerRows) if (row.status === "draft") errors.push(`primers[${id}] is a draft in the lab registry, so a published protocol cannot print it`);
68    for (const [id, row] of strainRows) if (row.status === "draft") errors.push(`strain ${id} is a draft in the lab registry, so a published protocol cannot name it`);
69    for (const [id, row] of reagentRows) if (row.status === "draft") errors.push(`reagent ${id} is a draft in the lab registry, so a published protocol cannot name it`);
70    for (const [id, row] of equipmentRows) if (row.status === "draft") errors.push(`equipment ${id} is a draft in the lab registry, so a published protocol cannot name it`);
71  }
72  errors.unshift(...dashes);
73  if (errors.length > 0) return { ok: false, errors, gaps };
74
75  let record;
76  try {
77    record = await renderProcedure({
78      slug,
79      parsed,
80      gaps,
81      renderBody: pipeline.renderBody,
82      resolveImage,
83      primerRows: named.flatMap((id) => (primerRows.has(id) ? [primerRows.get(id)] : [])),
84      // The strain's page is where the protocol links it, computed from its id here and not typed anywhere.
85      strainRows: namedStrains.flatMap((id) => (strainRows.has(id) ? [{ ...strainRows.get(id), path: itemPath("strain", id) }] : [])),
86      // The reagents the materials name, as the registry states them, so the table shows where each comes from and types none.
87      reagentRows: reagentIds.flatMap((id) => (reagentRows.has(id) ? [reagentRows.get(id)] : [])),
88      // The equipment the list names, as the registry states it, so the table shows who makes each and types none.
89      equipmentRows: equipmentIds.flatMap((id) => (equipmentRows.has(id) ? [equipmentRows.get(id)] : [])),
90      // The words for each organism id the protocol names, from the registry (or the non-strain list), so the library needs no list of its own.
91      organismNames: Object.fromEntries(
92        (Array.isArray(parsed.data.organism) ? parsed.data.organism : []).flatMap((id) => {
93          const words = Object.hasOwn(NON_STRAIN_ORGANISMS, id) ? /** @type {Record<string, string>} */ (NON_STRAIN_ORGANISMS)[id] : strainRows.get(id)?.organism;
94          return words ? [[id, words]] : [];
95        }),
96      ),
97    });
98  } catch (error) {
99    return { ok: false, errors: [error instanceof Error ? error.message : String(error)], gaps };
100  }
101  const searchInput = procedureSearchInput(record, parsed);
102  return {
103    ok: true,
104    errors: [],
105    gaps,
106    record,
107    markdown: searchInput.markdown,
108    searchInput,
109    sourcePath: file,
110    sourceBlobSha: await gitBlobSha(raw),
111  };
112}