app/kb/registry/compile.mjs

Functions

Imports

It imports app/kb/registry/kinds.mjs, app/lib/content/hashes.mjs, app/lib/cv/view.mjs. Imported by app/db/registry.ts, app/kb/admin.mjs, app/kb/editor.server.ts, app/kb/registry/host.server.ts, app/kb/registry/save.server.ts, app/lib/carrel/registry-handler.server.ts, app/lib/health/checks.server.ts, app/lib/operator/api.server.ts, app/lib/operator/sync-tools.server.ts.

Source

1// The one door from a registry file to the row the registry is drawn from (docs/REGISTRY.md): parse, validate, hash.
2// build:content, sync:content, the gates and the adapter's registry save all call compileRegistryItem, so a file CI
3// passes is the file the save accepts. Pure and dependency-light, so the Worker and the Node scripts import the same
4// module.
5//
6// An item is ONE file, `content/registry/<kind>/<id>.md`, and the file is its front matter and nothing else. What
7// every kind has (a name, and `draft` for its status) is the table's own columns; what a kind knows beyond that is its `fields`
8// (app/kb/registry/kinds.mjs), judged by that kind's rules. The validator REFUSES any field the kind does not
9// declare, so nothing enters the repository or D1 that a page would not show, and it states a value nobody has yet
10// as "MISSING: <why>", never a guess.
11
12import matter from "gray-matter";
13
14import { gitBlobSha } from "../../lib/content/hashes.mjs";
15import { foldText } from "../../lib/cv/view.mjs";
16import { KINDS, kindKeys } from "./kinds.mjs";
17
18export const REGISTRY_DIR = "content/registry";
19
20/** An id within a kind: lower-case letters, digits and hyphens, so it is a file name and a URL segment as written. */
21export const ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
22/** A kind is a key of KINDS: the same shape, so it is a directory and a URL segment as written. */
23const KIND_PATTERN = /^[a-z][a-z-]{0,30}$/;
24const NAME_MAX = 120;
25
26const GAP = /^MISSING:\s*(\S.*)$/s;
27
28/** True for a recorded gap: `MISSING: <why>`. @param {unknown} value @returns {value is string} */
29export function isGap(value) {
30  return typeof value === "string" && GAP.test(value);
31}
32
33/** The registry address of an item, `<kind>/<id>`: what the drift check, the sync and Carrel read it by. */
34export function registrySlug(/** @type {string} */ kind, /** @type {string} */ id) {
35  return `${kind}/${id}`;
36}
37
38/**
39 * The kind and id a slug names, or null when it is not exactly `<kind>/<id>` in the allowed shapes, so a slug can
40 * never name another path.
41 *
42 * @param {string} slug
43 * @returns {{ kind: string, id: string } | null}
44 */
45export function parseRegistrySlug(slug) {
46  const parts = slug.split("/");
47  if (parts.length !== 2) return null;
48  const [kind = "", id = ""] = parts;
49  return KIND_PATTERN.test(kind) && ID_PATTERN.test(id) ? { kind, id } : null;
50}
51
52/** The repository path of an item's file, from its slug. */
53export function registryPath(/** @type {string} */ slug) {
54  return `${REGISTRY_DIR}/${slug}.md`;
55}
56
57/**
58 * @typedef {import("./kinds.mjs").KindSpec} KindSpec
59 * @typedef {import("./kinds.mjs").RegistryItem} RegistryItem
60 * @typedef {import("./kinds.mjs").RegistryHost} RegistryHost
61 * `findWideDashes` is injected, as the page compile injects the pipeline's: the Worker loads it lazily.
62 * @typedef {{ findWideDashes: (text: string) => Array<{ line: number, column: number, char: string, excerpt: string }> }} RegistryPipeline
63 */
64
65/**
66 * Judges one file and, when it passes, builds the item. Every message the file has is returned, never the first
67 * alone, so a writer fixes all of them at once.
68 *
69 * @param {{ slug: string, raw: string, host: RegistryHost, pipeline: RegistryPipeline, kinds?: Readonly<Record<string, KindSpec>>, sourcePath?: string }} input
70 * @returns {Promise<
71 *   | { ok: false, errors: string[] }
72 *   | { ok: true, errors: [], item: RegistryItem, record: string, gaps: Array<{ field: string, reason: string }>, sourcePath: string, sourceBlobSha: string }
73 * >}
74 */
75export async function compileRegistryItem({ slug, raw, host, pipeline, kinds = KINDS, sourcePath }) {
76  /** @type {string[]} */
77  const errors = pipeline
78    .findWideDashes(raw)
79    .map((hit) => `line ${hit.line}, column ${hit.column}: wide dash ${hit.char}; house style uses commas, periods, parentheses or colons ("${hit.excerpt}")`);
80
81  const address = parseRegistrySlug(slug);
82  if (!address) {
83    return { ok: false, errors: [...errors, `"${slug}" is not a registry address; it is <kind>/<id>, such as ${kindKeys(kinds)[0] ?? "primer"}/m13-forward (lower-case letters, digits and hyphens)`] };
84  }
85  const { kind, id } = address;
86  const spec = kinds[kind];
87  if (!spec) {
88    return { ok: false, errors: [...errors, `"${kind}" is not a registry kind; the kinds are ${kindKeys(kinds).join(", ") || "none yet"}`] };
89  }
90  if (!raw.startsWith("---")) errors.push("the file must start with a --- front matter block");
91
92  let parsed;
93  try {
94    // An options object, even an empty one: gray-matter caches by input when it is omitted.
95    parsed = matter(raw, {});
96  } catch (error) {
97    return { ok: false, errors: [...errors, `the front matter is not valid YAML: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`] };
98  }
99  const data = /** @type {Record<string, unknown>} */ (parsed.data);
100  if (parsed.content.trim() !== "") errors.push(`the body must be empty: a ${spec.singular} is its front matter and nothing else`);
101
102  const allowed = ["name", "draft", ...Object.keys(spec.fields)];
103  for (const key of Object.keys(data)) {
104    if (!allowed.includes(key)) errors.push(`${key} is not a ${spec.singular} field; a ${spec.singular} carries ${allowed.join(", ")} and nothing else`);
105  }
106
107  const { name, draft } = data;
108  if (typeof name !== "string" || name.trim() === "" || name !== name.trim() || /[\r\n]/.test(name) || name.length > NAME_MAX) {
109    errors.push(`name is ${JSON.stringify(name)}; it is the ${spec.singular}'s name on one line, at most ${NAME_MAX} characters`);
110  }
111  if (draft !== undefined && typeof draft !== "boolean") {
112    errors.push(`draft is ${JSON.stringify(draft)}; it is true or false, or absent for a published item`);
113  }
114
115  /** @type {Record<string, unknown>} */
116  const fields = {};
117  /** @type {Array<{ field: string, reason: string }>} */
118  const gaps = [];
119  for (const [field, fieldSpec] of Object.entries(spec.fields)) {
120    const value = data[field];
121    if (value === undefined || value === null) {
122      if (fieldSpec.required) errors.push(`${field} is required for a ${spec.singular}; write the value, or "MISSING: <why>" if nobody has it yet`);
123      fields[field] = null;
124      continue;
125    }
126    if (typeof value === "string" && /^MISSING\b/.test(value) && !isGap(value)) {
127      errors.push(`${field} is ${JSON.stringify(value)}; write MISSING: and the reason it is missing`);
128      continue;
129    }
130    if (isGap(value)) {
131      gaps.push({ field, reason: value.replace(/^MISSING:\s*/, "") });
132      fields[field] = value;
133      continue;
134    }
135    const message = await fieldSpec.check(value, { host, data });
136    if (message) errors.push(`${field}: ${message}`);
137    fields[field] = value;
138  }
139  if (errors.length > 0) return { ok: false, errors };
140
141  /** @type {RegistryItem} */
142  const item = {
143    kind,
144    id,
145    name: /** @type {string} */ (name),
146    status: draft === true ? "draft" : "published",
147    fields,
148  };
149  return {
150    ok: true,
151    errors: [],
152    item,
153    // Only what the shared columns do not hold: a name is stored once, in its column.
154    record: JSON.stringify(fields),
155    gaps,
156    sourcePath: sourcePath ?? registryPath(slug),
157    sourceBlobSha: await gitBlobSha(raw),
158  };
159}
160
161/**
162 * What only the whole set can say: two items of a kind cannot share a name (folded, so case and accents do not make
163 * two), and a kind's own rules about its set. An empty set is not a fault: the registry has no records until a kind
164 * brings its own.
165 *
166 * @param {RegistryItem[]} items
167 * @param {Readonly<Record<string, KindSpec>>} [kinds]
168 * @returns {string[]}
169 */
170export function registrySetErrors(items, kinds = KINDS) {
171  /** @type {string[]} */
172  const errors = [];
173  /** @type {Map<string, string>} */
174  const names = new Map();
175  for (const { kind, id, name } of items) {
176    const key = `${kind}\u0000${foldText(name)}`;
177    const other = names.get(key);
178    if (other !== undefined) errors.push(`${kind}/${id} and ${kind}/${other} are both named "${name}"`);
179    else names.set(key, id);
180  }
181  for (const [kind, spec] of Object.entries(kinds)) {
182    const mine = items.filter((item) => item.kind === kind);
183    if (spec.setErrors) errors.push(...spec.setErrors(mine));
184  }
185  return errors;
186}
187
188/**
189 * The items in the site's order: kinds as they are defined, then name folded so case and accents do not matter.
190 *
191 * @param {RegistryItem[]} items
192 * @param {Readonly<Record<string, KindSpec>>} [kinds]
193 */
194export function sortRegistry(items, kinds = KINDS) {
195  const order = new Map(kindKeys(kinds).map((kind, i) => [kind, i]));
196  return [...items].sort(
197    (a, b) =>
198      (order.get(a.kind) ?? 0) - (order.get(b.kind) ?? 0) ||
199      foldText(a.name).localeCompare(foldText(b.name), "en", { numeric: true }),
200  );
201}
202
203/**
204 * An item from a row of the table: the shared columns, and the kind's fields from `record`.
205 *
206 * @param {{ kind: string, id: string, name: string, status: string, record: string }} row
207 * @returns {RegistryItem}
208 */
209export function itemFromRow(row) {
210  return {
211    kind: row.kind,
212    id: row.id,
213    name: row.name,
214    status: row.status === "draft" ? "draft" : "published",
215    fields: JSON.parse(row.record),
216  };
217}