app/kb/form.mjs

Functions

Imports

It imports app/lib/yaml-plain.mjs. Imported by app/components/admin/kb-form-steps.tsx, app/components/admin/kb-form.tsx, app/kb/form.server.ts.

Source

1// The Knowledge Base's form editor, the part that needs no runtime (docs/KNOWLEDGE-BASE.md): a file read into a form's
2// model, and a form's model written back into the file. The file stays the source, so what the form
3// writes goes through the same save and the same checks as the raw editor. What the form did not touch is written back
4// byte for byte: a front-matter field whose value is unchanged keeps the text it was written in, and a step keeps its
5// lines, so a save from the form changes only what was changed. formToFile(fileToForm(raw)) === raw for every file.
6
7import matter from "gray-matter";
8
9import { yamlPlain } from "../lib/yaml-plain.mjs";
10
11/** YAML through gray-matter, the reader every content file is parsed with, so the form reads a field as the compile does. */
12const yaml = {
13  /** @param {string} text */
14  load: (text) => /** @type {Record<string, unknown>} */ (matter(`---\n${text}\n---\n`).data),
15  /** @param {Record<string, unknown>} value */
16  dump: (value) => matter.stringify("", value).replace(/^---\n/, "").replace(/\n---\n*$/, "\n"),
17};
18
19/**
20 * @typedef {{ kind: string, text: string, indent: string } | { raw: string }} StepLine
21 * @typedef {{ number: number, text: string, lines: StepLine[], blanksBefore: number }} FormStep
22 * @typedef {{ type: "prose", text: string } | { type: "steps", start: number, steps: FormStep[] }} FormBlock
23 * @typedef {{ heading: string, blocks: FormBlock[] }} FormSection
24 * @typedef {{ intro: string, sections: FormSection[] }} FormBody
25 * @typedef {{ data: Record<string, unknown>, order: string[], body: FormBody | null }} FormModel
26 */
27
28/** The step flags the procedure format has (docs/PROCEDURES.md), in the order the form offers them. */
29export const STEP_FLAGS = /** @type {const} */ (["CRITICAL", "PAUSE POINT", "WHY", "EXPECT", "SPIN", "TROUBLESHOOTING", "CALC", "CHALLENGE", "SOLUTION"]);
30
31const FRONT = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/;
32const KEY = /^([A-Za-z_][\w-]*):(?:\s|$)/;
33const DAY = /^\d{4}-\d{2}-\d{2}$/;
34
35/** Equal as data, whatever order an object's keys came in. @param {unknown} a @param {unknown} b @returns {boolean} */
36function sameValue(a, b) {
37  if (Array.isArray(a) || Array.isArray(b)) {
38    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, i) => sameValue(x, b[i]));
39  }
40  if (a && b && typeof a === "object" && typeof b === "object") {
41    const ka = Object.keys(a);
42    const kb = Object.keys(b);
43    return ka.length === kb.length && ka.every((k) => sameValue(/** @type {any} */ (a)[k], /** @type {any} */ (b)[k]));
44  }
45  return a === b;
46}
47
48/**
49 * The file's front matter, split into each top-level field's own text. Lines before the first field (a comment) are
50 * kept as the prelude.
51 *
52 * @param {string} raw
53 */
54export function splitFile(raw) {
55  const match = FRONT.exec(raw);
56  if (!match) throw new Error("the file does not start with front matter between --- lines");
57  const lines = (match[1] ?? "").split(/\r?\n/);
58  /** @type {string[]} */
59  const prelude = [];
60  /** @type {Array<{ key: string, text: string }>} */
61  const fields = [];
62  for (const line of lines) {
63    const key = KEY.exec(line);
64    if (key) fields.push({ key: /** @type {string} */ (key[1]), text: line });
65    else if (fields.length > 0) /** @type {{ text: string }} */ (fields[fields.length - 1]).text += `\n${line}`;
66    else prelude.push(line);
67  }
68  return { prelude, fields, after: match[2] ?? "\n", body: raw.slice(match[0].length) };
69}
70
71/** One field's value, read from its own text. @param {string} text */
72function readField(text) {
73  const parsed = yaml.load(text);
74  return parsed && typeof parsed === "object" ? yamlPlain(Object.values(parsed)[0]) : undefined;
75}
76
77/** A plain one-line string YAML reads back as itself, unquoted. @param {string} value */
78function bare(value) {
79  if (value === "" || value !== value.trim() || /[\n:#]|^[-?[\]{},&*!|>'"%@`]/.test(value)) return false;
80  try {
81    return yaml.load(`v: ${value}`)["v"] === value;
82  } catch {
83    return false;
84  }
85}
86
87/** A field written fresh, for a value the form changed. @param {string} key @param {unknown} value */
88function writeField(key, value) {
89  if (typeof value === "string") {
90    if (DAY.test(value) || bare(value)) return `${key}: ${value}`;
91    return `${key}: ${JSON.stringify(value)}`;
92  }
93  if (typeof value === "number" || typeof value === "boolean") return `${key}: ${value}`;
94  return yaml.dump({ [key]: value }).replace(/\n$/, "");
95}
96
97/**
98 * A step list's own lines: a numbered item, then its indented lines (flags, commands, wrapped words), with the blank
99 * lines inside the list kept where they were.
100 *
101 * @param {string[]} lines
102 * @param {number} i the index of the item line
103 */
104function readStep(lines, i) {
105  const item = /^(\d+)\.\s+(.*)$/.exec(lines[i] ?? "");
106  /** @type {StepLine[]} */
107  const stepLines = [];
108  let j = i + 1;
109  while (j < lines.length) {
110    const next = lines[j] ?? "";
111    if (/^\s{2,}\S/.test(next)) {
112      const flag = /^(\s+)>\s*(CRITICAL|PAUSE POINT|WHY|TROUBLESHOOTING|EXPECT|SPIN|CALC|CHALLENGE|SOLUTION)\s*:\s?(.*)$/.exec(next);
113      // A flag is the form's to edit when its line is exactly what the form would write back.
114      if (flag && next === `${flag[1]}> ${flag[2]}: ${flag[3]}`) stepLines.push({ kind: /** @type {string} */ (flag[2]), text: flag[3] ?? "", indent: flag[1] ?? "   " });
115      else stepLines.push({ raw: next });
116      j += 1;
117    } else if (next.trim() === "" && /^\s{2,}\S/.test(lines[j + 1] ?? "")) {
118      stepLines.push({ raw: next });
119      j += 1;
120    } else break;
121  }
122  return { step: { number: Number(item?.[1]), text: item?.[2] ?? "", lines: stepLines, blanksBefore: 0 }, next: j };
123}
124
125/** A section's lines as blocks: step lists, and everything else as prose kept line for line. @param {string[]} lines */
126function readBlocks(lines) {
127  /** @type {FormBlock[]} */
128  const blocks = [];
129  /** @type {string[]} */
130  let prose = [];
131  let inFence = false;
132  let i = 0;
133  const flush = () => {
134    if (prose.length > 0) blocks.push({ type: "prose", text: prose.join("\n") });
135    prose = [];
136  };
137  while (i < lines.length) {
138    const text = lines[i] ?? "";
139    if (text.startsWith("```")) inFence = !inFence;
140    if (!inFence && /^\d+\.\s/.test(text)) {
141      flush();
142      /** @type {FormStep[]} */
143      const steps = [];
144      let blanks = 0;
145      while (i < lines.length && /^\d+\.\s/.test(lines[i] ?? "")) {
146        const { step, next } = readStep(lines, i);
147        steps.push({ ...step, blanksBefore: blanks });
148        i = next;
149        // Blank lines between two items keep the list going; any other line ends it.
150        blanks = 0;
151        let k = i;
152        while (k < lines.length && (lines[k] ?? "").trim() === "") k += 1;
153        if (k > i && /^\d+\.\s/.test(lines[k] ?? "")) {
154          blanks = k - i;
155          i = k;
156        }
157      }
158      blocks.push({ type: "steps", start: steps[0]?.number ?? 1, steps });
159      continue;
160    }
161    prose.push(text);
162    i += 1;
163  }
164  flush();
165  return blocks;
166}
167
168/**
169 * A procedure's body as the form shows it: the intro, then each `## ` section with its prose and its steps.
170 *
171 * @param {string} body
172 * @returns {FormBody}
173 */
174function readBody(body) {
175  const lines = body.split("\n");
176  /** @type {string[]} */
177  const intro = [];
178  /** @type {Array<{ heading: string, lines: string[] }>} */
179  const raw = [];
180  let inFence = false;
181  for (const line of lines) {
182    if (line.startsWith("```")) inFence = !inFence;
183    if (!inFence && line.startsWith("## ")) raw.push({ heading: line.slice(3), lines: [] });
184    else if (raw.length > 0) /** @type {{ lines: string[] }} */ (raw[raw.length - 1]).lines.push(line);
185    else intro.push(line);
186  }
187  return { intro: intro.join("\n"), sections: raw.map((s) => ({ heading: s.heading, blocks: readBlocks(s.lines) })) };
188}
189
190/** A step's lines, numbered. @param {FormStep} step @param {number} number */
191function writeStep(step, number) {
192  const lines = [`${number}. ${step.text}`];
193  for (const line of step.lines) {
194    if ("raw" in line) lines.push(line.raw);
195    else lines.push(`${line.indent || "   "}> ${line.kind}: ${line.text}`);
196  }
197  return [...Array(step.blanksBefore).fill(""), ...lines].join("\n");
198}
199
200/** The body the form describes. A step list is numbered from where it started, in the order the form put it. @param {FormBody} body */
201function writeBody(body) {
202  const parts = [body.intro];
203  for (const section of body.sections) {
204    const lines = [`## ${section.heading}`];
205    for (const block of section.blocks) {
206      if (block.type === "prose") lines.push(block.text);
207      else lines.push(block.steps.map((step, i) => writeStep(step, block.start + i)).join("\n"));
208    }
209    parts.push(lines.join("\n"));
210  }
211  return parts.join("\n");
212}
213
214/**
215 * A file as a form's model: every front-matter field's value, in the file's order, and for a procedure its body.
216 *
217 * @param {string} raw
218 * @param {{ body?: boolean }} [options] body: false for a registry item, whose file is its front matter alone
219 * @returns {FormModel}
220 */
221export function fileToForm(raw, options = {}) {
222  const { fields, body } = splitFile(raw);
223  /** @type {Record<string, unknown>} */
224  const data = {};
225  for (const field of fields) data[field.key] = readField(field.text);
226  return { data, order: fields.map((f) => f.key), body: options.body === false ? null : readBody(body) };
227}
228
229/**
230 * The file a form's model describes, written over the file it was read from: an unchanged field keeps its text, a
231 * changed one is written fresh, a new one goes after the rest, and a field the form removed (undefined) is left out.
232 *
233 * @param {string} original
234 * @param {FormModel} model
235 */
236export function formToFile(original, model) {
237  const { prelude, fields, after, body } = splitFile(original);
238  const known = new Map(fields.map((f) => [f.key, f.text]));
239  const keys = [...model.order.filter((k) => known.has(k) || k in model.data), ...Object.keys(model.data).filter((k) => !model.order.includes(k))];
240  /** @type {string[]} */
241  const out = [...prelude];
242  for (const key of new Set(keys)) {
243    const value = model.data[key];
244    if (value === undefined) continue;
245    const text = known.get(key);
246    out.push(text !== undefined && sameValue(readField(text), value) ? text : writeField(key, value));
247  }
248  return `---\n${out.join("\n")}\n---${after}${model.body ? writeBody(model.body) : body}`;
249}