app/lib/roster/compile.mjs

Functions

Imports

It imports app/lib/content/hashes.mjs. Imported by app/components/phage-roster.tsx, app/db/roster.ts, app/lib/carrel/roster-handler.server.ts, app/lib/health/checks.server.ts, app/lib/operator/sync-tools.server.ts, app/lib/roster/save.server.ts, app/routes/content-page.tsx, app/routes/home.tsx.

Source

1// The one door from a roster file to the cohort the site draws (docs/ROSTER.md): parse, validate, hash.
2// build:content, sync:content, the gates and the adapter's roster save all call compileCohort, so a file CI
3// passes is the file the save accepts and the pages draw. Pure and dependency-light, so the Worker and the
4// Node scripts import the same module.
5//
6// The shape is the one app/data/phage-hunters.ts had and no wider: a year, a group photo that is a path
7// under /phage-hunters/ with its measured size and its alt text, and the names. The validator REFUSES any
8// other field, so nothing a visitor cannot already see on the roster page can enter the repository or D1.
9
10import matter from "gray-matter";
11
12import { gitBlobSha } from "../content/hashes.mjs";
13
14export const ROSTER_DIR = "content/roster";
15
16/** The repository path of a cohort's file, from its file key (the year). */
17export function rosterPath(/** @type {string} */ slug) {
18  return `${ROSTER_DIR}/${slug}.md`;
19}
20
21/**
22 * Where the roster is drawn: the one page that carries it, and the heading id the old WordPress profile
23 * paths land on (app/lib/wordpress-redirects.mjs). The route
24 * places the roster by this constant, and test/roster.test.mjs holds it to the registered page paths, the
25 * redirect target and the component's own heading id, so the three cannot drift apart.
26 */
27export const ROSTER_PAGE_PATH = "/teaching/phage-discovery";
28export const ROSTER_ANCHOR = "roster";
29
30/** The directory the cohort photographs are served from. They stay static assets, referenced by path. */
31export const ROSTER_PHOTO_DIR = "/phage-hunters/";
32
33const FIELDS = ["year", "photo", "researchers"];
34const PHOTO_FIELDS = ["src", "width", "height", "alt"];
35const PHOTO_SRC = /^\/phage-hunters\/[A-Za-z0-9._-]+\.webp$/;
36const NAME_MAX = 80;
37const ALT_MAX = 200;
38
39/**
40 * @typedef {{ src: string, width: number, height: number, alt: string }} CohortPhoto
41 * @typedef {{ year: number, photo: CohortPhoto | null, researchers: string[] }} Cohort
42 * @typedef {{ photo: (src: string) => Promise<boolean> }} RosterHost
43 * `findWideDashes` is injected, as the page compile injects the pipeline's: the Worker loads it lazily.
44 * @typedef {{ findWideDashes: (text: string) => Array<{ line: number, column: number, char: string, excerpt: string }> }} RosterPipeline
45 */
46
47/** Newest cohort first: the order the page lists them and the order the files are read in. */
48export function sortCohorts(/** @type {Cohort[]} */ cohorts) {
49  return [...cohorts].sort((a, b) => b.year - a.year);
50}
51
52/**
53 * The home page's counts: counted, never typed. The names stay out of what the home page sends.
54 *
55 * @param {Cohort[]} cohorts
56 * @returns {{ researchers: number, cohorts: number, since: number }}
57 */
58export function rosterFacts(cohorts) {
59  if (cohorts.length === 0) throw new Error("the roster has no cohorts, so there is nothing to count");
60  return {
61    researchers: cohorts.reduce((n, c) => n + c.researchers.length, 0),
62    cohorts: cohorts.length,
63    since: Math.min(...cohorts.map((c) => c.year)),
64  };
65}
66
67/** @param {unknown} value @returns {value is Record<string, unknown>} */
68const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
69
70/** @param {unknown} value */
71const isPositiveInteger = (value) => typeof value === "number" && Number.isInteger(value) && value > 0;
72
73/**
74 * @param {unknown} photo
75 * @param {RosterHost} host
76 * @returns {Promise<string[]>}
77 */
78async function photoErrors(photo, host) {
79  if (!isRecord(photo)) return ["photo is a mapping (src, width, height, alt) or null"];
80  /** @type {string[]} */
81  const errors = [];
82  for (const key of Object.keys(photo)) {
83    if (!PHOTO_FIELDS.includes(key)) errors.push(`photo.${key} is not a roster field; a photo carries ${PHOTO_FIELDS.join(", ")} and nothing else`);
84  }
85  const { src, width, height, alt } = photo;
86  if (typeof src !== "string" || !PHOTO_SRC.test(src)) {
87    errors.push(`photo.src is ${JSON.stringify(src)}; it is a .webp path under ${ROSTER_PHOTO_DIR}, such as ${ROSTER_PHOTO_DIR}example.webp`);
88  } else if (!(await host.photo(src))) {
89    errors.push(`photo.src ${src} is not in the repository (public${src}); the photograph is a static asset and is not uploaded here`);
90  }
91  if (!isPositiveInteger(width)) errors.push(`photo.width is ${JSON.stringify(width)}; it is the photograph's real width in pixels`);
92  if (!isPositiveInteger(height)) errors.push(`photo.height is ${JSON.stringify(height)}; it is the photograph's real height in pixels`);
93  if (typeof alt !== "string" || alt.trim() === "") {
94    errors.push("photo.alt is required: the photographs are content, and alt text that is empty fails WCAG");
95  } else if (alt !== alt.trim() || alt.length > ALT_MAX) {
96    errors.push(`photo.alt is padded or longer than ${ALT_MAX} characters`);
97  }
98  return errors;
99}
100
101/**
102 * @param {unknown} researchers
103 * @returns {string[]}
104 */
105function researcherErrors(researchers) {
106  if (!Array.isArray(researchers)) return ["researchers is a list of names (an empty list renders as 'Roster to be added')"];
107  /** @type {string[]} */
108  const errors = [];
109  const seen = new Set();
110  researchers.forEach((name, i) => {
111    const at = `researchers[${i}]`;
112    if (typeof name !== "string" || name.trim() === "") {
113      errors.push(`${at} is ${JSON.stringify(name)}; a name is a non-empty string`);
114      return;
115    }
116    if (name !== name.trim() || /\s{2}|[\r\n\t]/.test(name)) errors.push(`${at} has stray whitespace; names are kept as given, on one line`);
117    if (name.length > NAME_MAX) errors.push(`${at} is longer than ${NAME_MAX} characters`);
118    if (seen.has(name)) errors.push(`${at} repeats a name already in this cohort`);
119    seen.add(name);
120  });
121  return errors;
122}
123
124/**
125 * Judges one file and, when it passes, builds the cohort. Every message the file has is returned, never the
126 * first alone, so a writer fixes all of them at once.
127 *
128 * @param {{ slug: string, raw: string, host: RosterHost, pipeline: RosterPipeline, sourcePath?: string }} input
129 * @returns {Promise<
130 *   | { ok: false, errors: string[] }
131 *   | { ok: true, errors: [], cohort: Cohort, record: string, sourcePath: string, sourceBlobSha: string }
132 * >}
133 */
134export async function compileCohort({ slug, raw, host, pipeline, sourcePath }) {
135  /** @type {string[]} */
136  const errors = pipeline
137    .findWideDashes(raw)
138    .map((hit) => `line ${hit.line}, column ${hit.column}: wide dash ${hit.char}; house style uses commas, periods, parentheses or colons ("${hit.excerpt}")`);
139  if (!raw.startsWith("---")) errors.push("the file must start with a --- front matter block");
140
141  let parsed;
142  try {
143    // An options object, even an empty one: gray-matter caches by input when it is omitted.
144    parsed = matter(raw, {});
145  } catch (error) {
146    return { ok: false, errors: [...errors, `the front matter is not valid YAML: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`] };
147  }
148  const data = parsed.data;
149  if (parsed.content.trim() !== "") errors.push("the body must be empty: a cohort is its front matter and nothing else");
150  for (const key of Object.keys(data)) {
151    if (!FIELDS.includes(key)) {
152      errors.push(`${key} is not a roster field; a cohort carries ${FIELDS.join(", ")} and nothing else (no contact details, locations or other personal data)`);
153    }
154  }
155
156  const { year, photo, researchers } = data;
157  if (typeof year !== "number" || !Number.isInteger(year) || year < 2000 || year > 2099) {
158    errors.push(`year is ${JSON.stringify(year)}; it is the cohort's four-digit year`);
159  } else if (slug !== String(year)) {
160    errors.push(`year is ${year}, but the file is ${rosterPath(slug)}: a cohort's file is named for its year (${year}.md)`);
161  }
162  if (!/^\d{4}$/.test(slug)) errors.push(`"${slug}" is not a cohort file key; the file is named for the year, such as 2025.md`);
163
164  if (photo === undefined) errors.push("photo is required (a mapping, or null for a cohort with no photograph)");
165  else if (photo !== null) errors.push(...(await photoErrors(photo, host)));
166  errors.push(...researcherErrors(researchers));
167  if (errors.length > 0) return { ok: false, errors };
168
169  /** @type {Cohort} */
170  const cohort = {
171    year: /** @type {number} */ (year),
172    photo: photo === null ? null : (({ src, width, height, alt }) => ({ src, width, height, alt }))(/** @type {CohortPhoto} */ (photo)),
173    researchers: /** @type {string[]} */ (researchers),
174  };
175  return {
176    ok: true,
177    errors: [],
178    cohort,
179    record: JSON.stringify(cohort),
180    sourcePath: sourcePath ?? rosterPath(slug),
181    sourceBlobSha: await gitBlobSha(raw),
182  };
183}
184
185/**
186 * What only the whole set can say: the files are the roster, so an empty set is a fault, and two files
187 * cannot be one year.
188 *
189 * @param {Cohort[]} cohorts
190 * @returns {string[]}
191 */
192export function rosterSetErrors(cohorts) {
193  /** @type {string[]} */
194  const errors = [];
195  if (cohorts.length === 0) errors.push(`${ROSTER_DIR} holds no cohort files; the roster cannot be empty`);
196  const years = new Set();
197  for (const { year } of cohorts) {
198    if (years.has(year)) errors.push(`two files are the ${year} cohort`);
199    years.add(year);
200  }
201  return errors;
202}