app/lib/dictionary/compile.mjs

Functions

Imports

It imports app/lib/carrel/content-id.mjs, app/lib/content-pages.mjs, app/lib/content/hashes.mjs, app/lib/dictionary-entries.mjs, app/lib/dictionary/parse.mjs. Imported by app/lib/dictionary/save.server.ts.

Source

1// One door from a dictionary entry file to everything derived from it: parse, validate, the entry every
2// surface reads. check:content, build:content, sync:content and the Carrel adapter's save all call
3// compileDictionaryEntry, so a file CI passes is the file the save accepts and the page draws. The rules
4// below are the ones the CI tests used to read the entries for (docs/DICTIONARY.md).
5
6import { contentIdFits } from "../carrel/content-id.mjs";
7import { gitBlobSha } from "../content/hashes.mjs";
8import { CONTENT_PAGE_PATHS } from "../content-pages.mjs";
9import { SOFTWARE_LABEL, dictionaryEntryMarkdown, definedTermJsonLd } from "../dictionary-entries.mjs";
10import { dictionaryPath, parseDictionaryEntry } from "./parse.mjs";
11
12const DICTIONARY_KIND = "dictionary";
13
14/** Every key a file may carry. Anything else is a typo that would be silently ignored. */
15const FRONT_MATTER_FIELDS = new Set([
16  "path", "term", "syllables", "ipa", "respelling", "partOfSpeech", "plural", "etymology", "senses",
17  "senseLabels", "audio", "draft",
18]);
19
20const KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
21const AUDIO_PATTERN = /^\/audio\/[a-z]+\.mp3$/;
22const LANGUAGE_PATTERN = /^[a-z]{2,3}$/;
23/** A pronunciation clip is a few seconds of speech, not a recording. */
24const AUDIO_MAX_BYTES = 32 * 1024;
25
26/**
27 * @typedef {object} DictionaryHost
28 * @property {(path: string) => Promise<{ size: number, head?: number[] } | null>} audio the repository file at
29 *   a site-absolute public path (`/audio/capsid.mp3`), or null when it is not there. `head` is its first two
30 *   bytes where the host can read them (CI); the Worker's GitHub listing cannot, so the MPEG frame sync is
31 *   checked in CI only.
32 *
33 * @typedef {{ key: string, path: string }} OtherEntry
34 */
35
36/** @param {unknown} value @returns {value is string} */
37const isFilled = (value) => typeof value === "string" && value.trim() !== "";
38
39/**
40 * @param {Record<string, unknown>} data
41 * @returns {string[]}
42 */
43function shapeProblems(data) {
44  /** @type {string[]} */
45  const errors = [];
46  const bad = (/** @type {string} */ field, /** @type {string} */ message) => errors.push(`${field}: ${message}`);
47
48  for (const field of Object.keys(data)) {
49    if (!FRONT_MATTER_FIELDS.has(field)) bad(field, `is not a field of a dictionary entry (${[...FRONT_MATTER_FIELDS].join(", ")})`);
50  }
51  for (const field of ["term", "syllables", "ipa", "respelling", "partOfSpeech"]) {
52    if (!isFilled(data[field])) bad(field, "is required text");
53  }
54  if (isFilled(data.ipa) && !/^\/.+\/$/.test(String(data.ipa))) bad("ipa", "sits between slashes, as /ˈkæp.sɪd/");
55  if (isFilled(data.respelling) && !/^[A-Za-z-]+$/.test(String(data.respelling))) bad("respelling", "is letters and hyphens only, as KAP-sid");
56  if (isFilled(data.term) && isFilled(data.syllables) && String(data.syllables).replaceAll("·", "") !== String(data.term).toLowerCase()) {
57    bad("syllables", `joined without its dots it is "${String(data.syllables).replaceAll("·", "")}", not the term "${String(data.term).toLowerCase()}" in lower case`);
58  }
59  if (data.plural !== undefined && data.plural !== null) {
60    if (!Array.isArray(data.plural) || data.plural.length === 0 || !data.plural.every(isFilled)) {
61      bad("plural", "is a list of forms, or absent");
62    }
63  }
64  if (!Array.isArray(data.etymology) || data.etymology.length === 0) {
65    bad("etymology", "is a list: text, and [language, word] pairs for foreign words");
66  } else {
67    data.etymology.forEach((part, i) => {
68      const pair = Array.isArray(part) && part.length === 2 && LANGUAGE_PATTERN.test(String(part[0])) && isFilled(part[1]);
69      if (!(typeof part === "string" && part !== "") && !pair) {
70        bad(`etymology[${i}]`, "is text, or a [language, word] pair with a language code such as la");
71      }
72    });
73  }
74  if (!Array.isArray(data.senses) || data.senses.length !== 2 || !data.senses.every(isFilled)) {
75    bad("senses", "is exactly two senses: the word's meaning, then the software");
76  }
77  const labels = data.senseLabels;
78  if (!Array.isArray(labels) || labels.length !== 2 || labels[0] !== null || labels[1] !== SOFTWARE_LABEL) {
79    bad("senseLabels", `is [null, ${SOFTWARE_LABEL}]: sense 1 carries no label, and sense 2 is the software`);
80  }
81  if (data.draft !== undefined && typeof data.draft !== "boolean") bad("draft", `is ${JSON.stringify(data.draft)}; it is true or false`);
82  // The entries describe the words and the software, and say nothing possessive about the site's owner.
83  if (/Dustin/.test(JSON.stringify(data))) bad("front matter", "names the site's owner; an entry says nothing possessive about him");
84  return errors;
85}
86
87/**
88 * The entry as the surfaces read it, in the order the page, the twin and the search record expect.
89 *
90 * @param {Record<string, unknown>} data a file's front matter that passed shapeProblems
91 * @returns {import("../dictionary-entries.mjs").DictionaryEntry}
92 */
93function entryFromData(data) {
94  return {
95    path: String(data.path),
96    term: String(data.term),
97    syllables: String(data.syllables),
98    ipa: String(data.ipa),
99    respelling: String(data.respelling),
100    partOfSpeech: String(data.partOfSpeech),
101    plural: Array.isArray(data.plural) ? data.plural.map(String) : null,
102    etymology: /** @type {import("../dictionary-entries.mjs").EtymologyPart[]} */ (
103      /** @type {unknown[]} */ (data.etymology).map((part) => (Array.isArray(part) ? [String(part[0]), String(part[1])] : String(part)))
104    ),
105    senses: /** @type {[string, string]} */ (/** @type {unknown[]} */ (data.senses).map(String)),
106    senseLabels: [null, SOFTWARE_LABEL],
107    audio: String(data.audio),
108  };
109}
110
111/**
112 * @param {object} input
113 * @param {string} input.key the file's name without `.md`
114 * @param {string} input.raw the whole file
115 * @param {{ findWideDashes: (text: string) => Array<{ line: number, column: number, char: string, excerpt: string }> }} input.pipeline
116 * @param {DictionaryHost} input.host
117 * @param {OtherEntry[]} [input.others] every OTHER entry, for uniqueness
118 * @returns {Promise<
119 *   | { ok: false, errors: string[] }
120 *   | { ok: true, errors: [], key: string, entry: import("../dictionary-entries.mjs").DictionaryEntry, draft: boolean,
121 *       body: string, sourcePath: string, sourceBlobSha: string }
122 * >}
123 */
124export async function compileDictionaryEntry({ key, raw, pipeline, host, others = [] }) {
125  const file = dictionaryPath(key);
126  const parsed = parseDictionaryEntry({ file, raw });
127  const errors = [
128    ...parsed.problems,
129    ...pipeline.findWideDashes(raw).map(
130      (hit) => `line ${hit.line}, column ${hit.column}: wide dash ${hit.char}; house style uses commas, periods, parentheses or colons ("${hit.excerpt}")`,
131    ),
132  ];
133  if (parsed.problems.length > 0) return { ok: false, errors };
134
135  if (!KEY_PATTERN.test(key)) errors.push(`the file name "${key}" is not a lowercase kebab-case key`);
136  else if (!contentIdFits(DICTIONARY_KIND, key)) errors.push(`the key "${key}" is too long for a Carrel id`);
137  errors.push(...shapeProblems(parsed.data));
138
139  const path = typeof parsed.data.path === "string" ? parsed.data.path : "";
140  if (!path.startsWith("/software/") || !(/** @type {readonly string[]} */ (CONTENT_PAGE_PATHS).includes(path))) {
141    errors.push(`path: "${path}" is not a registered Software page (CONTENT_PAGE_PATHS in app/lib/content-pages.mjs); an entry opens a named software page`);
142  } else if (path !== `/software/${key}`) {
143    errors.push(`path: ${path} belongs in ${dictionaryPath(path.slice("/software/".length))}; the file name is the entry's key`);
144  }
145  const taken = others.find((other) => other.path === path);
146  if (path && taken) errors.push(`path: ${path} already has an entry (${taken.key}); a page opens with one entry`);
147
148  const audio = typeof parsed.data.audio === "string" ? parsed.data.audio : "";
149  if (!AUDIO_PATTERN.test(audio)) {
150    errors.push(`audio: "${audio}" is not a clip under /audio/ named in lower-case letters, as /audio/name.mp3`);
151  } else {
152    const clip = await host.audio(audio);
153    if (!clip) errors.push(`audio: ${audio} is not in the repository (public${audio}); a referenced clip must exist, and uploading one is a code change`);
154    else {
155      if (clip.size >= AUDIO_MAX_BYTES) errors.push(`audio: ${audio} is ${clip.size} bytes; a pronunciation clip is under ${AUDIO_MAX_BYTES}`);
156      // An MPEG audio frame sync, not an HTML error page saved under an .mp3 name.
157      if (clip.head && (clip.head[0] !== 0xff || ((clip.head[1] ?? 0) & 0xe0) !== 0xe0)) {
158        errors.push(`audio: ${audio} does not start with an MPEG audio frame`);
159      }
160    }
161  }
162  if (errors.length > 0) return { ok: false, errors };
163
164  const entry = entryFromData(parsed.data);
165  // What the twin and the JSON-LD say, each a function of the entry alone: a file that passes cannot fail the page.
166  const twin = dictionaryEntryMarkdown(entry).split("\n");
167  if (!twin.includes(`2. *${SOFTWARE_LABEL}.* ${entry.senses[1]}`)) errors.push("twin: sense 2 does not carry the software label in its own line");
168  if (definedTermJsonLd(entry, "https://example.invalid").description !== entry.senses[1]) errors.push("JSON-LD: the DefinedTerm does not describe the software (sense 2)");
169  if (errors.length > 0) return { ok: false, errors };
170
171  return {
172    ok: true,
173    errors: [],
174    key,
175    entry,
176    draft: parsed.data.draft === true,
177    body: parsed.body,
178    sourcePath: file,
179    sourceBlobSha: await gitBlobSha(raw),
180  };
181}