app/kb/procedures/proof.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/procedure.tsx, app/components/protocol-proof.tsx, app/kb/procedures/proof.server.ts, app/kb/procedures/render.mjs, app/kb/procedures/validate.mjs, app/routes/procedure[.md].ts.

Source

1// Proof of use (docs/PROCEDURES.md): the papers that used a protocol's method and the phages it produced, as the
2// procedure's file states them. Stored and never inferred: a protocol with no `proof_of_use` shows nothing. The file
3// holds slugs only (a paper's publication slug, a phage's key); the words and addresses are read from the publication and
4// phage rows when the page is drawn, so a corrected title reaches every protocol that cites the paper.
5
6/** A publication slug and a phage key, as the files that hold them spell them. */
7const PAPER_SLUG = /^[0-9a-z][0-9a-z-]*$/;
8const PHAGE_KEY = /^[a-z][a-z0-9]*$/;
9
10/**
11 * The errors in a `proof_of_use` value, or none.
12 *
13 * @param {unknown} value
14 * @returns {string[]}
15 */
16export function proofErrors(value) {
17  if (value === undefined) return [];
18  if (!value || typeof value !== "object" || Array.isArray(value)) {
19    return ["proof_of_use must be a mapping with `papers` (publication slugs) and/or `phages` (phage keys)"];
20  }
21  const errors = [];
22  const record = /** @type {Record<string, unknown>} */ (value);
23  for (const key of Object.keys(record)) {
24    if (key !== "papers" && key !== "phages") errors.push(`proof_of_use has no field "${key}"; it has papers and phages`);
25  }
26  for (const [key, pattern] of /** @type {const} */ ([["papers", PAPER_SLUG], ["phages", PHAGE_KEY]])) {
27    const list = record[key];
28    if (list === undefined) continue;
29    if (!Array.isArray(list) || list.length === 0) errors.push(`proof_of_use.${key} must be a non-empty list`);
30    else {
31      for (const item of list) {
32        if (typeof item !== "string" || !pattern.test(item)) errors.push(`proof_of_use.${key} has ${JSON.stringify(item)}, which is not a ${key === "papers" ? "publication slug" : "phage key (lower case letters and digits)"}`);
33      }
34      if (new Set(list).size !== list.length) errors.push(`proof_of_use.${key} names one entry twice`);
35    }
36  }
37  if (record.papers === undefined && record.phages === undefined) errors.push("proof_of_use is empty: leave it out until there is something to state");
38  return errors;
39}
40
41/**
42 * The stored proof as the record carries it: slugs only, or null.
43 *
44 * @param {unknown} value
45 * @returns {{ papers: string[], phages: string[] } | null}
46 */
47export function proofFromFile(value) {
48  if (!value || typeof value !== "object") return null;
49  const record = /** @type {{ papers?: string[], phages?: string[] }} */ (value);
50  const papers = record.papers ?? [];
51  const phages = record.phages ?? [];
52  return papers.length + phages.length > 0 ? { papers, phages } : null;
53}
54
55/**
56 * The proof with its words and addresses, from the rows the page reads. A slug the rows do not hold is kept as its
57 * slug, unlinked, so a stale reference is visible on the page instead of dropped; check:protocols refuses it before it
58 * ships.
59 *
60 * @param {{ papers: string[], phages: string[] } | null} proof
61 * @param {{ papers: ReadonlyMap<string, { title: string, year: number }>, phages: ReadonlyMap<string, string> }} rows
62 */
63export function resolveProof(proof, rows) {
64  if (!proof) return null;
65  return {
66    papers: proof.papers.map((slug) => {
67      const paper = rows.papers.get(slug);
68      return { slug, title: paper?.title ?? slug, year: paper?.year ?? null, href: paper ? `/research/publications/${slug}/` : null };
69    }),
70    phages: proof.phages.map((key) => {
71      const name = rows.phages.get(key);
72      return { key, name: name ?? key, href: name ? `/research/phages#${key}` : null };
73    }),
74  };
75}
76
77/**
78 * The twin's section, with absolute links.
79 *
80 * @param {ReturnType<typeof resolveProof>} proof
81 * @param {string} origin
82 */
83export function proofMarkdown(proof, origin) {
84  if (!proof) return "";
85  const link = (/** @type {string} */ text, /** @type {string | null} */ href) => (href ? `[${text}](${origin}${href})` : text);
86  return [
87    "## Proof of use",
88    ...(proof.papers.length > 0
89      ? ["", "Papers that used this method:", "", ...proof.papers.map((p) => `- ${link(p.title, p.href)}${p.year ? ` (${p.year})` : ""}`)]
90      : []),
91    ...(proof.phages.length > 0
92      ? ["", "Phages it produced:", "", ...proof.phages.map((p) => `- ${link(p.name, p.href)}`)]
93      : []),
94  ].join("\n");
95}