app/kb/procedures/lineage.mjs

Functions

Imports

It imports app/kb/bases.mjs, app/kb/procedures/cite.mjs. Imported by app/components/procedure-materials.tsx, app/components/procedure.tsx, app/kb/procedures/lineage.server.ts, app/kb/procedures/render.mjs, app/routes/procedure.version[.md].ts, app/routes/procedure[.md].ts.

Source

1// A variant's lineage (docs/KNOWLEDGE-BASE.md, P3): the procedure it was copied from with the editor's Duplicate, as the
2// page, the twin and the JSON-LD name it. The file holds only `forked_from: { slug, version }`; the parent's title and
3// address are its own facts, read from its row when the page is served, so a renamed parent reads right everywhere.
4
5import { BASES } from "../bases.mjs";
6import { versionPath } from "./cite.mjs";
7
8/**
9 * @typedef {{ title: string, href: string | null, version: string | null }} Lineage
10 */
11
12/**
13 * Where a variant points: the frozen copy of the version it was copied at when there is one, else the parent's live page,
14 * else (a parent not published) its name with no link.
15 *
16 * @param {{ slug: string, version: string | null } | null} forkedFrom
17 * @param {string} profile
18 * @param {{ live: { title: string, path: string } | null, frozen: { title: string } | null }} parent
19 * @returns {Lineage | null}
20 */
21export function resolveLineage(forkedFrom, profile, parent) {
22  if (!forkedFrom) return null;
23  const root = BASES.find((b) => b.profile === profile)?.entryRoot ?? "/research/protocols/";
24  const path = `${root}${forkedFrom.slug}`;
25  if (forkedFrom.version && parent.frozen) return { title: parent.frozen.title, href: versionPath(path, forkedFrom.version), version: forkedFrom.version };
26  if (parent.live) return { title: parent.live.title, href: parent.live.path, version: forkedFrom.version };
27  return { title: forkedFrom.slug, href: null, version: forkedFrom.version };
28}
29
30/** "Phage DNA extraction, version 2": the words the lineage is shown in. @param {Lineage} lineage */
31export const lineageText = (lineage) => `${lineage.title}${lineage.version ? `, version ${lineage.version}` : ""}`;
32
33/** The twin's fact line for a lineage, as the page's fact reads. @param {Lineage} lineage @param {string} origin */
34const lineageMarkdown = (lineage, origin) => `- Based on: ${lineage.href ? `[${lineageText(lineage)}](${origin}${lineage.href})` : lineageText(lineage)}`;
35
36/**
37 * The fact the stored twin carries for a variant: the parent's file name and version, all the compile knows. The twin's
38 * routes swap it for the parent's title and address when they serve it (`withLineage`).
39 *
40 * @param {{ slug: string, version: string | null }} forkedFrom
41 */
42export const storedLineage = (forkedFrom) => `${forkedFrom.slug}${forkedFrom.version ? `, version ${forkedFrom.version}` : ""}`;
43
44/**
45 * A twin with its stored lineage fact read out in full: the parent's title, linked to the copy it was taken from.
46 *
47 * @param {string} markdown
48 * @param {{ forkedFrom: { slug: string, version: string | null } | null }} record
49 * @param {Lineage | null} lineage
50 * @param {string} origin
51 */
52export function withLineage(markdown, record, lineage, origin) {
53  if (!record.forkedFrom || !lineage) return markdown;
54  return markdown.replace(`- Based on: ${storedLineage(record.forkedFrom)}\n`, `${lineageMarkdown(lineage, origin)}\n`);
55}
56
57/**
58 * What is wrong with a variant's `forked_from` against the procedures in the repository (P3): the parent is a file
59 * here, of the same profile, and the version named is one the parent states (its current version or one in its history),
60 * which is a version that is or will be frozen. The shape is validate.mjs's; this is the corpus check:protocols runs.
61 *
62 * @param {{ forkedFrom: { slug: string, version: string | null } | null, profile: string }} record
63 * @param {Map<string, { profile: string, version: string | null, history: Array<{ version: string }> }>} procedures by slug
64 * @returns {string[]}
65 */
66export function lineageErrors(record, procedures) {
67  const from = record.forkedFrom;
68  if (!from) return [];
69  const parent = procedures.get(from.slug);
70  if (!parent) return [`forked_from names ${from.slug}, which is not a procedure here`];
71  if (parent.profile !== record.profile) return [`forked_from names ${from.slug}, a ${parent.profile}; a variant keeps its parent's profile (${record.profile})`];
72  if (!from.version) return [];
73  const stated = new Set([parent.version, ...parent.history.map((h) => h.version)].filter(Boolean));
74  return stated.has(from.version) ? [] : [`forked_from names version ${from.version} of ${from.slug}, which states ${[...stated].join(", ") || "no version"}`];
75}