app/lib/cv/validate.mjs

Functions

Imports

It imports app/lib/content/wide-dash.mjs, app/lib/cv/view.mjs, app/lib/publications/authors.mjs. Imported by app/lib/cv/compile.mjs.

Source

1// The one validation module for the CV (docs/CV.md). CI (build:content, test/cv.test.mjs), sync:content and the
2// CV save all call it, so a file CI passes is the file a save accepts. It holds a file to its shape, to the
3// privacy rules, to the house style (no wide dash) and, once the files are joined to the publications, to the
4// rules that need the whole CV: a cited paper exists and lists Dustin, and each section reads newest first.
5// Pure: no Env, no filesystem, no clock beyond the year bound below.
6
7import matter from "gray-matter";
8
9import { findWideDashes } from "../content/wide-dash.mjs";
10import { canonicalAuthor } from "../publications/authors.mjs";
11import { AREAS, ROLES } from "./view.mjs";
12
13const AREA_IDS = new Set(AREAS.map(([id]) => /** @type {string} */ (id)));
14const ROLE_IDS = new Set(ROLES.map(([id]) => /** @type {string} */ (id)));
15
16/** The owner, whom every paper the CV claims must list (as the CV's role for it is read from the author list). */
17const OWNER = "Dustin Edwards";
18
19/** The edition stamp the CV prints: a season and a year, as "Fall 2026". */
20const EDITION_PATTERN = /^(Spring|Summer|Fall|Winter) (\d{4})$/;
21
22/** Entries are dated between these years, so a typo such as 2205 is refused rather than charted. */
23const YEAR_MIN = 1950;
24const YEAR_MAX = 2100;
25
26const DOI_PATTERN = /^10\.\d{4,9}\/\S+$/;
27const HTTPS = /^https:\/\/\S+$/;
28
29/** The sections an appointment or a service line sits under, in the order the CV prints them. */
30const APPOINTMENT_SECTIONS = ["Positions", "Administrative and leadership"];
31const SERVICE_SECTIONS = [
32  "Department",
33  "College",
34  "University",
35  "Professional",
36  "Community",
37  "Compensated professional consulting",
38  "Professional memberships",
39];
40
41/**
42 * What no CV line may carry (the privacy rules): an email, a phone number, a room, a private community group.
43 * Read from the values, so a comment explaining the rule cannot trip it.
44 */
45const PRIVACY = /** @type {const} */ ([
46  [/@[a-z0-9-]+\.[a-z]{2,}/i, "an email address"],
47  [/\(\d{3}\)\s*\d{3}-\d{4}|\b\d{3}-\d{3}-\d{4}\b/, "a phone number"],
48  [/\bRoom\b|\bSuite\b|\bOffice \d/i, "a room"],
49  [/Mountains Lake/i, "a private community group"],
50]);
51
52/**
53 * A field's kind, for one entry type: `s` a non-empty string, `n` a non-negative integer, `money` US dollars to the cent, `b` a boolean, and
54 * a trailing `?` makes it optional. The shared fields (year, endYear, areas, role, links) are checked apart.
55 */
56const SHAPES = /** @type {const} */ ({
57  appointment: { section: "s", title: "s", org: "s", detail: "s?", duties: "duties?", headline: "b?" },
58  education: { title: "s", org: "s", detail: "s?" },
59  grant: { amount: "money", title: "s", funder: "s?", note: "s?" },
60  award: { title: "s", org: "s?", place: "s?" },
61  talk: { title: "s", presenters: "strings", venue: "s" },
62  course: { code: "s", title: "s", org: "s", term: "s" },
63  mentoring: { section: "s", count: "n", unit: "unit", level: "s", program: "s", org: "s", detail: "s?", cohort: "b" },
64  service: { section: "s", title: "s", org: "s?", place: "s?" },
65  development: { title: "s", org: "s?", place: "s?" },
66});
67
68/** The inline paper (one the site has no record for) states its own citation. */
69const INLINE_PAPER = /** @type {const} */ ({
70  title: "s",
71  authors: "strings",
72  journal: "s",
73  volume: "s?",
74  issue: "s?",
75  pages: "s?",
76});
77
78const SHARED_KEYS = ["year", "endYear", "areas", "role", "links"];
79
80/** @param {unknown} value @returns {value is Record<string, unknown>} */
81const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
82
83/** @param {unknown} value */
84const isText = (value) => typeof value === "string" && value.length > 0 && value === value.trim();
85
86/** @param {unknown} value @returns {value is number} */
87const isCount = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
88
89/**
90 * @param {unknown} value
91 * @param {string} kind
92 * @returns {string | null} a reason, or null when the value fits
93 */
94function misfit(value, kind) {
95  const optional = kind.endsWith("?");
96  const base = optional ? kind.slice(0, -1) : kind;
97  if (value === undefined) return optional ? null : "is missing";
98  switch (base) {
99    case "s":
100      return isText(value) ? null : "must be non-empty text with no space at either end";
101    case "n":
102      return isCount(value) ? null : "must be a whole number, zero or more";
103    case "money":
104      return typeof value === "number" && Number.isFinite(value) && value >= 0 && Math.round(value * 100) === value * 100
105        ? null
106        : "must be dollars, zero or more, to the cent";
107    case "b":
108      return typeof value === "boolean" ? null : "must be true or false";
109    case "strings":
110      return Array.isArray(value) && value.length > 0 && value.every(isText) ? null : "must be a non-empty list of text";
111    case "unit":
112      return value === "students" || value === "awards" ? null : 'must be "students" or "awards"';
113    case "duties":
114      return Array.isArray(value) &&
115        value.length > 0 &&
116        value.every(
117          (duty) =>
118            isRecord(duty) &&
119            Object.keys(duty).every((key) => key === "heading" || key === "items") &&
120            isText(duty.heading) &&
121            Array.isArray(duty.items) &&
122            duty.items.length > 0 &&
123            duty.items.every(isText),
124        )
125        ? null
126        : "must be a non-empty list of { heading, items } with items a non-empty list of text";
127    default:
128      throw new Error(`cv validate: unknown field kind ${kind}`);
129  }
130}
131
132/**
133 * @param {Record<string, unknown>} entry
134 * @param {Record<string, string>} shape
135 * @param {string} where
136 * @param {string[]} errors
137 */
138function checkShape(entry, shape, where, errors) {
139  for (const [key, kind] of Object.entries(shape)) {
140    const reason = misfit(entry[key], kind);
141    if (reason) errors.push(`${where}: ${key} ${reason}`);
142  }
143}
144
145/**
146 * The fields every dated entry carries, and the keys it may not.
147 *
148 * @param {Record<string, unknown>} entry
149 * @param {string} where
150 * @param {string[]} errors
151 */
152function checkShared(entry, where, errors) {
153  const { year, endYear, areas, role, links } = entry;
154  const yearOk = year === null || (typeof year === "number" && Number.isInteger(year) && year >= YEAR_MIN && year <= YEAR_MAX);
155  if (!yearOk) errors.push(`${where}: year must be a whole year from ${YEAR_MIN} to ${YEAR_MAX}, or null for an undated line`);
156  if (endYear !== undefined) {
157    if (year === null) errors.push(`${where}: an undated line (year: null) has no endYear`);
158    else if (endYear !== "present" && !(typeof endYear === "number" && Number.isInteger(endYear) && endYear <= YEAR_MAX)) {
159      errors.push(`${where}: endYear must be a whole year or "present"`);
160    } else if (typeof endYear === "number" && typeof year === "number" && endYear < year) {
161      errors.push(`${where}: endYear ${endYear} is before year ${year}`);
162    }
163  }
164  if (!Array.isArray(areas) || !areas.every((a) => typeof a === "string" && AREA_IDS.has(a))) {
165    errors.push(`${where}: areas must be a list (empty is allowed) of ${[...AREA_IDS].join(", ")}`);
166  } else if (new Set(areas).size !== areas.length) {
167    errors.push(`${where}: areas names one area twice`);
168  }
169  if (role !== null && !(typeof role === "string" && ROLE_IDS.has(role))) {
170    errors.push(`${where}: role must be null or one of ${[...ROLE_IDS].join(", ")}`);
171  }
172  if (links !== undefined) {
173    const linksOk =
174      Array.isArray(links) &&
175      links.length > 0 &&
176      links.every((l) => isRecord(l) && Object.keys(l).length === 2 && isText(l.label) && typeof l.href === "string" && HTTPS.test(l.href));
177    if (!linksOk) errors.push(`${where}: links must be a non-empty list of { label, href } with an https href`);
178  }
179}
180
181/**
182 * One entry of a section file, held to its type's shape.
183 *
184 * @param {import("./types.ts").CvType} type
185 * @param {unknown} entry
186 * @param {string} where
187 * @param {string[]} errors
188 */
189function checkEntry(type, entry, where, errors) {
190  if (!isRecord(entry)) {
191    errors.push(`${where}: an entry is a mapping of fields`);
192    return;
193  }
194  if ("type" in entry) errors.push(`${where}: an entry does not state its type; the file's front matter does`);
195
196  if (type === "publication" && "doi" in entry) {
197    for (const key of Object.keys(entry)) {
198      if (key !== "doi") {
199        errors.push(`${where}: a paper named by DOI states nothing else (${key}); its facts come from content/publications/`);
200      }
201    }
202    if (typeof entry.doi !== "string" || !DOI_PATTERN.test(entry.doi)) errors.push(`${where}: doi is not a DOI`);
203    return;
204  }
205
206  /** @type {Record<string, string>} */
207  const shape = type === "publication" ? INLINE_PAPER : SHAPES[/** @type {Exclude<typeof type, "publication">} */ (type)];
208  checkShape(entry, shape, where, errors);
209  checkShared(entry, where, errors);
210  const known = new Set([...Object.keys(shape), ...SHARED_KEYS]);
211  for (const key of Object.keys(entry)) {
212    if (!known.has(key)) errors.push(`${where}: "${key}" is not a field of a ${type} entry`);
213  }
214  if (type === "appointment" && !APPOINTMENT_SECTIONS.includes(/** @type {string} */ (entry.section))) {
215    errors.push(`${where}: section must be one of ${APPOINTMENT_SECTIONS.join(", ")}`);
216  }
217  if (type === "service" && !SERVICE_SECTIONS.includes(/** @type {string} */ (entry.section))) {
218    errors.push(`${where}: section must be one of ${SERVICE_SECTIONS.join(", ")}`);
219  }
220}
221
222/**
223 * The profile: the edition stamp, the person and the presentation totals.
224 *
225 * @param {Record<string, unknown>} data
226 * @param {string[]} errors
227 */
228function checkProfile(data, errors) {
229  const { edition, person, presentations } = data;
230  for (const key of Object.keys(data)) {
231    if (!["edition", "person", "presentations"].includes(key)) errors.push(`profile: "${key}" is not a field of the profile`);
232  }
233  if (typeof edition !== "string" || !EDITION_PATTERN.test(edition)) {
234    errors.push('edition must be a season and a year, such as "Fall 2026"');
235  }
236  if (!isRecord(person)) {
237    errors.push("person must be a mapping of name, degree, discipline, department and org");
238  } else {
239    for (const key of ["name", "degree", "discipline", "department", "org"]) {
240      if (!isText(person[key])) errors.push(`person.${key} must be non-empty text with no space at either end`);
241    }
242    for (const key of Object.keys(person)) {
243      if (!["name", "degree", "discipline", "department", "org"].includes(key)) {
244        errors.push(
245          key === "title"
246            ? 'person.title is not a field of the person: the title is derived from the current appointment and the discipline (app/lib/identity.mjs)'
247            : `person.${key} is not a field of the person`,
248        );
249      }
250    }
251    if (person.name !== OWNER) errors.push(`person.name is "${String(person.name)}", the site's one name for him is "${OWNER}"`);
252  }
253  if (!isRecord(presentations)) {
254    errors.push("presentations must be a mapping of international, national, from and to");
255  } else {
256    for (const key of ["international", "national"]) {
257      if (!isCount(presentations[key])) errors.push(`presentations.${key} must be a whole number, zero or more`);
258    }
259    for (const key of ["from", "to"]) {
260      const value = presentations[key];
261      if (!(typeof value === "number" && Number.isInteger(value) && value >= YEAR_MIN && value <= YEAR_MAX)) {
262        errors.push(`presentations.${key} must be a whole year from ${YEAR_MIN} to ${YEAR_MAX}`);
263      }
264    }
265    for (const key of Object.keys(presentations)) {
266      if (!["international", "national", "from", "to"].includes(key)) errors.push(`presentations.${key} is not a field of the presentations`);
267    }
268    if (typeof presentations.from === "number" && typeof presentations.to === "number" && presentations.from > presentations.to) {
269      errors.push("presentations.from is after presentations.to");
270    }
271  }
272}
273
274/**
275 * Parses and judges one CV file.
276 *
277 * @param {{ slug: string, type: import("./types.ts").CvType | "profile" }} file the registry's entry for it
278 * @param {string} raw the whole file, front matter included
279 * @returns {{ ok: false, errors: string[] } | { ok: true, errors: [], record: import("./types.ts").CvFileRecord }}
280 */
281export function parseCvFile(file, raw) {
282  /** @type {string[]} */
283  const errors = [];
284  for (const hit of findWideDashes(raw)) {
285    errors.push(`line ${hit.line}, column ${hit.column}: wide dash ${hit.char}; house style uses commas, periods, parentheses or colons ("${hit.excerpt}")`);
286  }
287  let parsed;
288  try {
289    parsed = matter(raw);
290  } catch (error) {
291    return { ok: false, errors: [...errors, `the front matter is not valid YAML: ${error instanceof Error ? error.message : String(error)}`] };
292  }
293  const data = /** @type {Record<string, unknown>} */ (parsed.data);
294  if (parsed.content.trim() !== "") errors.push("the file has text after its front matter, which no page shows; the CV is the front matter alone");
295
296  const { slug, type } = file;
297  if (type === "profile") {
298    checkProfile(data, errors);
299  } else {
300    for (const key of Object.keys(data)) {
301      if (key !== "type" && key !== "entries") errors.push(`"${key}" is not a field of a section file (type, entries)`);
302    }
303    if (data.type !== type) errors.push(`type is ${JSON.stringify(data.type)}, but ${slug} holds ${type} entries`);
304    if (!Array.isArray(data.entries) || data.entries.length === 0) {
305      errors.push("entries must be a non-empty list");
306    } else {
307      data.entries.forEach((entry, i) => checkEntry(type, entry, `entries[${i}]`, errors));
308    }
309  }
310
311  // The privacy rules read the values, not the comments: JSON of what the file states.
312  const values = JSON.stringify(data);
313  for (const [pattern, what] of PRIVACY) {
314    if (pattern.test(values)) errors.push(`the file carries ${what}; the CV never does`);
315  }
316  if (errors.length > 0) return { ok: false, errors };
317
318  /** @type {import("./types.ts").CvFileRecord} */
319  const record =
320    type === "profile"
321      ? {
322          slug: "profile",
323          type: "profile",
324          edition: /** @type {string} */ (data.edition),
325          person: /** @type {import("./types.ts").CvPerson} */ (data.person),
326          presentations: /** @type {import("./types.ts").CvPresentations} */ (data.presentations),
327        }
328      : {
329          slug,
330          type,
331          // The file states the type once; each entry carries it from here on.
332          entries: /** @type {Array<Record<string, unknown>>} */ (data.entries).map(
333            (e) => /** @type {import("./types.ts").CvSourceEntry} */ ({ type, ...e }),
334          ),
335        };
336  return { ok: true, errors: [], record };
337}
338
339/**
340 * The paper references against the publication records: each DOI exists as a published paper, appears once,
341 * and the paper lists the owner among its authors (the CV cannot claim a paper he did not write).
342 *
343 * @param {import("./types.ts").CvSourceEntry[]} entries
344 * @param {Map<string, import("../publications/types.ts").Publication>} byDoi the published records by lower-cased DOI
345 * @returns {string[]}
346 */
347export function paperRefErrors(entries, byDoi) {
348  /** @type {string[]} */
349  const errors = [];
350  const seen = new Set();
351  for (const entry of entries) {
352    if (entry.type !== "publication" || !("doi" in entry)) continue;
353    const key = entry.doi.toLowerCase();
354    if (seen.has(key)) errors.push(`DOI ${entry.doi} is listed twice`);
355    seen.add(key);
356    const paper = byDoi.get(key);
357    if (!paper) {
358      errors.push(`no published publication has DOI ${entry.doi}; add its file to content/publications/ first, and publish it`);
359    } else if (!paper.authors.some((name) => canonicalAuthor(name) === OWNER)) {
360      errors.push(`DOI ${entry.doi} does not list ${OWNER} among its authors, so the CV cannot claim it`);
361    }
362  }
363  return errors;
364}
365
366/**
367 * The types whose sections read newest first, undated lines last, so the page, the twin and the PDF agree on
368 * an order the twin states for grants. Service and mentoring lines keep the CV's own order within a section (a
369 * committee is listed with its chair first, a cohort by program), so the rule does not reach them.
370 */
371const NEWEST_FIRST_TYPES = [
372  "appointment",
373  "education",
374  "publication",
375  "grant",
376  "award",
377  "talk",
378  "course",
379  "development",
380];
381
382/**
383 * Judged on the resolved entries, so a paper's year is the record's.
384 *
385 * @param {Array<{ id: string, type: string, section: string | null, year: number | null }>} entries
386 * @returns {string[]}
387 */
388export function orderErrors(entries) {
389  /** @type {string[]} */
390  const errors = [];
391  /** @type {Map<string, { year: number | null, id: string }>} */
392  const last = new Map();
393  for (const e of entries) {
394    if (!NEWEST_FIRST_TYPES.includes(e.type)) continue;
395    const key = `${e.type}/${e.section ?? ""}`;
396    const before = last.get(key);
397    if (before) {
398      if (before.year === null && e.year !== null) {
399        errors.push(`${e.id} is dated ${e.year} but follows the undated ${before.id}; undated lines come last in their section`);
400      } else if (before.year !== null && e.year !== null && e.year > before.year) {
401        errors.push(`${e.id} (${e.year}) follows ${before.id} (${before.year}); each section reads newest first`);
402      }
403    }
404    last.set(key, { year: e.year, id: e.id });
405  }
406  return errors;
407}