explico 0.12.0 → 0.13.1

package/src/compiler/cli.ts

@@ -25,6 +25,9 @@
  *     on any renderability error (unparseable MDX, KaTeX error, unresolved
  *     notation, unknown `[[key]]`, unknown citation), on top of the manifest's
  *     schema / ref / math / equation diagnostics for that lesson.
+ *   - Beside the manifest's diagnostics, every command lists what the last
+ *     `astro build` found on the rendered pages (`render-diagnostics.ts`),
+ *     under the `render:` source.
  */
 
 import { execFileSync } from 'node:child_process';
@@ -37,6 +40,7 @@ import {
   parseFrontmatter,
 } from '@astrojs/markdown-remark';
 import rehypeKatex from 'rehype-katex';
+import remarkDirective from 'remark-directive';
 import remarkMath from 'remark-math';
 import remarkMdx from 'remark-mdx';
 
@@ -51,6 +55,7 @@ import remarkShortNote from '../reference/remark-short-note.mjs';
 import type { DiagnosticSeverity } from '../reference/types';
 import type { EquationLink } from '../reference/gate-math';
 import type { Manifest, ManifestLesson } from './manifest';
+import { readRenderDiagnostics, type RenderDiagnostic } from './render-diagnostics';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
 import { isCourseRuleId, ownerOf, ELEMENTS, type Element, type Enforcement } from '../rules/catalog';
 import {
@@ -59,6 +64,7 @@ import {
   type RuleInEffect,
   type RulesFilter,
 } from '../rules/in-effect';
+import { RESERVED_KEY_PREFIXES, reservedKeyPrefix } from '../reference/references';
 
 const REPOSITORY_ROOT = process.cwd();
 // Content and its course math are the top-level `content/` folder (Phase F).
@@ -132,6 +138,17 @@ function withOwner(diagnostic: CliDiagnostic): CliDiagnostic {
   return { ...diagnostic, ...ownerFields(diagnostic.code) };
 }
 
+/** A finding the last `astro build` made on a rendered page, as a CLI diagnostic. */
+function renderedCliDiagnostic(diagnostic: RenderDiagnostic): CliDiagnostic {
+  return {
+    code: `render:${diagnostic.code}`,
+    ...ownerFields(diagnostic.code),
+    severity: diagnosticSeverity(diagnostic.severity),
+    message: diagnostic.message,
+    file: diagnostic.file,
+  };
+}
+
 function mentions(message: string, lessonId: string, file: string): boolean {
   return (
     message.includes(lessonId) ||
@@ -149,10 +166,19 @@ function mentions(message: string, lessonId: string, file: string): boolean {
 export function lessonDiagnostics(
   manifest: Manifest,
   lesson: ManifestLesson,
+  rendered: readonly RenderDiagnostic[] = readRenderDiagnostics(),
 ): CliDiagnostic[] {
   const out: CliDiagnostic[] = [];
   const { file, id } = lesson;
   const assessments = new Set(lesson.assessments);
+  // The shared entries this page shows a card of: a fault in one (a formula
+  // naming an unknown key, say) is the page's too, as `validate:content` says.
+  const bundle = new Set(lesson.notation.definitionIds);
+  const entryFiles = new Set(
+    manifest.notation.definitions
+      .filter((definition) => definition.scope.kind === 'shared' && bundle.has(definition.id))
+      .map((definition) => definition.source.file),
+  );
   const withFile = (value?: string) =>
     value === undefined ? {} : { file: value };
 
@@ -174,6 +200,7 @@ export function lessonDiagnostics(
     if (
       entry.lessonId !== id &&
       entryFile !== file &&
+      !(entryFile !== undefined && entryFiles.has(entryFile)) &&
       !mentions(entry.message, id, file)
     ) {
       continue;
@@ -189,6 +216,7 @@ export function lessonDiagnostics(
   for (const diagnostic of manifest.diagnostics.math) {
     const forLesson =
       diagnostic.file === file ||
+      entryFiles.has(diagnostic.file) ||
       (diagnostic.context === 'assessment' &&
         [...assessments].some((assessmentId) =>
           diagnostic.file.startsWith(`${assessmentId} `),
@@ -257,6 +285,11 @@ export function lessonDiagnostics(
     });
   }
 
+  for (const diagnostic of rendered) {
+    if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
+    out.push(renderedCliDiagnostic(diagnostic));
+  }
+
   return out
     .map(withOwner)
     .sort(
@@ -280,6 +313,11 @@ function processorFor(manifest: Manifest) {
       // as the real Astro/MDX build, so `remarkNotation` sees the same tree
       // shape here that it does there (D7/F-tables-figures parity).
       remarkMdx,
+      // Starlight parses `:::note` asides as directives in the real build
+      // (on every page, not only its own `src/content/docs/`); without this
+      // an aside's body read as top-level lesson flow here, so its equation
+      // took a number the build does not give it.
+      remarkDirective,
       remarkMath,
       remarkShortNote,
       remarkMemo,
@@ -303,9 +341,12 @@ function processorFor(manifest: Manifest) {
   return processorPromise;
 }
 
-/** Drop `import` / `export` lines so they don't render as stray prose. */
+/**
+ * Empty `import` / `export` lines so they don't render as stray prose. The
+ * line itself stays, so a render error names the line it has in the file.
+ */
 function stripEsm(body: string): string {
-  return body.replace(/^(?:import|export)\s[^\n]*\n?/gm, '');
+  return body.replace(/^(?:import|export)\s[^\n]*/gm, '');
 }
 
 /** Classify a render error by which pipeline stage raised it. */
@@ -347,22 +388,60 @@ export async function renderLesson(
     relative(DOCS_ROOT, input.path).replace(/\\/g, '/'),
   );
   try {
-    await processor.render(stripEsm(input.body), {
-      frontmatter: { ...input.frontmatter, lessonId },
-      fileURL: pathToFileURL(input.path),
-    });
+    await withoutParseLogs(() =>
+      processor.render(stripEsm(input.body), {
+        frontmatter: { ...input.frontmatter, lessonId },
+        fileURL: pathToFileURL(input.path),
+      }),
+    );
     return { rendered: true, diagnostics: [] };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    // A VFileMessage knows its place in the file (the body keeps the
+    // frontmatter's lines, `lessonSource`).
+    const { line, column } = (error ?? {}) as { line?: unknown; column?: unknown };
     return {
       rendered: false,
       diagnostics: [
-        { code: renderErrorCode(message), severity: 'error', message },
+        {
+          code: renderErrorCode(message),
+          severity: 'error',
+          message,
+          ...(typeof line === 'number' ? { line } : {}),
+          ...(typeof column === 'number' ? { column } : {}),
+        },
       ],
     };
   }
 }
 
+/**
+ * Astro's processor `console.error`s a failed render (the whole VFileMessage,
+ * its syntax tree included) before rethrowing it; the check reports the error
+ * itself, once, as a diagnostic. Renders run concurrently, so the swap is
+ * counted and only that one log is dropped.
+ */
+let quietRenders = 0;
+let consoleError: typeof console.error | undefined;
+async function withoutParseLogs<T>(work: () => Promise<T>): Promise<T> {
+  if (quietRenders++ === 0) {
+    const original = console.error;
+    consoleError = original;
+    console.error = (...args: unknown[]) => {
+      if (args[0] instanceof Error && args[0].message.startsWith('Failed to parse Markdown file')) return;
+      original(...args);
+    };
+  }
+  try {
+    return await work();
+  } finally {
+    if (--quietRenders === 0 && consoleError !== undefined) {
+      console.error = consoleError;
+      consoleError = undefined;
+    }
+  }
+}
+
 // --- token estimate ----------------------------------------------------
 
 /** Rough token estimate — ~4 chars/token, the usual GPT-family heuristic. */
@@ -461,6 +540,22 @@ function lessonRaw(lesson: ManifestLesson): {
   };
 }
 
+/**
+ * A lesson file's frontmatter and its body for rendering: the frontmatter is
+ * blanked with spaces, as Astro's MDX plugin does, so line N of the body is
+ * line N of the file and a render error points where the build's would.
+ */
+export function lessonSource(text: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+} {
+  const parsed = parseFrontmatter(text, { frontmatter: 'empty-with-spaces' });
+  return {
+    frontmatter: (parsed.frontmatter ?? {}) as Record<string, unknown>,
+    body: parsed.content,
+  };
+}
+
 // --- domain signatures ------------------------------------------------
 
 /**
@@ -546,10 +641,6 @@ export interface StatusReport {
     readonly keyedDiagrams: number;
     readonly keyedExamples: number;
   };
-  readonly draftDebt: {
-    readonly lessons: readonly string[];
-    readonly notation: readonly string[];
-  };
   readonly orphans: readonly CliDiagnostic[];
   readonly diagnostics: {
     readonly errors: number;
@@ -558,16 +649,10 @@ export interface StatusReport {
   };
 }
 
-export function contentStatus(manifest: Manifest): StatusReport {
-  const draftLessons = manifest.lessons
-    .filter((lesson) => lesson.status === 'draft')
-    .map((lesson) => lesson.id)
-    .sort();
-  const draftNotation = manifest.notation.definitions
-    .filter((definition) => definition.status === 'draft')
-    .map((definition) => definition.id)
-    .sort();
-
+export function contentStatus(
+  manifest: Manifest,
+  rendered: readonly RenderDiagnostic[] = readRenderDiagnostics(),
+): StatusReport {
   const orphans: CliDiagnostic[] = manifest.notation.diagnostics
     .filter((diagnostic) => diagnostic.code === 'unused-definition')
     .map((diagnostic) => ({
@@ -598,6 +683,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
     ...manifest.diagnostics.config.map((d) => d.severity),
     ...manifest.diagnostics.waivers.map((d) => d.severity),
+    ...rendered.map((d) => diagnosticSeverity(d.severity)),
   ];
 
   const keyedEquations = manifest.lessons.reduce(
@@ -639,7 +725,6 @@ export function contentStatus(manifest: Manifest): StatusReport {
       keyedDiagrams,
       keyedExamples,
     },
-    draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
     diagnostics: {
       errors: allDiagnostics.filter((severity) => severity === 'error').length,
@@ -699,10 +784,14 @@ const SEVERITY_RANK: Readonly<Record<DiagnosticSeverity, number>> = {
   error: 2,
 };
 
-/** Manifest diagnostics at or above a severity, normalized for tooling. */
+/**
+ * Manifest diagnostics at or above a severity, and those the last
+ * `astro build` found on rendered pages, normalized for tooling.
+ */
 export function contentDiagnostics(
   manifest: Manifest,
   minimumSeverity: DiagnosticThreshold = 'info',
+  rendered: readonly RenderDiagnostic[] = readRenderDiagnostics(),
 ): DiagnosticsReport {
   const lessonFileByHint = new Map<string, string>();
   for (const lesson of manifest.lessons) {
@@ -762,6 +851,10 @@ export function contentDiagnostics(
       });
     }
   }
+  for (const diagnostic of rendered) {
+    const cli = renderedCliDiagnostic(diagnostic);
+    if (SEVERITY_RANK[cli.severity] >= SEVERITY_RANK[minimumSeverity]) diagnostics.push(cli);
+  }
 
   diagnostics.sort(
     (left, right) =>
@@ -779,8 +872,11 @@ export function contentDiagnostics(
 }
 
 /** Every warning exactly; errors and informational advice are excluded. */
-export function contentWarnings(manifest: Manifest): WarningsReport {
-  const warnings = contentDiagnostics(manifest, 'warning').diagnostics.filter(
+export function contentWarnings(
+  manifest: Manifest,
+  rendered: readonly RenderDiagnostic[] = readRenderDiagnostics(),
+): WarningsReport {
+  const warnings = contentDiagnostics(manifest, 'warning', rendered).diagnostics.filter(
     (diagnostic) => diagnostic.severity === 'warning',
   );
   return { count: warnings.length, warnings };
@@ -850,7 +946,6 @@ export interface ContextReport {
     readonly file: string;
     readonly title: string;
     readonly description: string;
-    readonly status: string;
     readonly teaches: readonly string[];
     readonly requires: readonly string[];
     readonly assumptions: readonly string[];
@@ -928,7 +1023,6 @@ export function contentContext(
       file: lesson.file,
       title: lesson.title,
       description: lesson.description,
-      status: lesson.status,
       teaches: lesson.teaches,
       requires: lesson.requires,
       assumptions: lesson.assumptions,
@@ -999,7 +1093,9 @@ async function checkOneLesson(
   lesson: ManifestLesson,
 ): Promise<CheckLessonResult> {
   const manifestDiagnostics = lessonDiagnostics(manifest, lesson);
-  const { frontmatter, body } = lessonRaw(lesson);
+  const { frontmatter, body } = lessonSource(
+    readFileSync(lessonAbsolutePath(lesson), 'utf8'),
+  );
   const render = await renderLesson(manifest, {
     body,
     frontmatter,
@@ -1057,20 +1153,26 @@ export function changedLessonIds(): string[] {
 
 export async function contentCheck(
   manifest: Manifest,
-  options: { lesson?: string; changed?: boolean },
+  options: {
+    lesson?: string;
+    /** Several lessons, each checked; `lesson` is the one-lesson form. */
+    lessons?: readonly string[];
+    changed?: boolean;
+  },
 ): Promise<CheckReport> {
   let targets: ManifestLesson[];
+  const named = [...(options.lesson ? [options.lesson] : []), ...(options.lessons ?? [])];
   if (options.changed) {
     const ids = changedLessonIds();
     targets = manifest.lessons.filter((lesson) => ids.includes(lesson.id));
   } else {
-    if (!options.lesson) {
+    if (named.length === 0) {
       throw new ContentCliError(
         'usage',
         'content check needs a <lesson> id or --changed.',
       );
     }
-    targets = [findLesson(manifest, options.lesson)];
+    targets = named.map((id) => findLesson(manifest, id));
   }
 
   const lessons = await Promise.all(
@@ -1129,7 +1231,6 @@ export function scaffoldLesson(rawId: string): Scaffold {
   const contents = `---
 title: ${title}
 description: One sentence on what the reader can do after this lesson.
-editorialStatus: draft
 teaches: []
 assumptions: []
 ---
@@ -1172,6 +1273,14 @@ export function scaffoldTerm(rawKey: string): Scaffold {
       `A notation key is lower-case, dot/hyphen separated, got ${JSON.stringify(rawKey)}.`,
     );
   }
+  const reserved = reservedKeyPrefix(key);
+  if (reserved !== undefined) {
+    throw new ContentCliError(
+      'invalid-id',
+      `A notation key may not start with ${RESERVED_KEY_PREFIXES.join(', ')}: [[${key}]] would be ` +
+        `read as a reference to that kind of float. Got ${JSON.stringify(rawKey)}.`,
+    );
+  }
   const relPath = `content/notation/${key}.md`;
   if (existsSync(join(REPOSITORY_ROOT, relPath))) {
     throw new ContentCliError(
@@ -1190,13 +1299,12 @@ sources: []
 seeAlso: []
 alignment:
   kind: general
-  rationale: Draft scaffold — set a real alignment before review.
-editorialStatus: draft
+  rationale: Draft scaffold — set a real alignment.
 aiAssisted: true
 ---
 
 Draft definition for [[${key}]]. Replace this body and the placeholder
-frontmatter before moving the entry past \`draft\`.
+frontmatter.
 `;
 
   return { path: relPath, contents, companions: [] };

package/src/compiler/collections.ts

@@ -25,7 +25,6 @@ import type {
 } from '../curriculum/validation';
 import type {
   AbbreviationDefinitionInput,
-  EditorialStatus,
   LocalNotationDefinitionInput,
   NotationAlignment,
   NotationLessonInput,
@@ -48,6 +47,9 @@ import { parseMemoRef } from '../reference/remark-memo.mjs';
 import { parseSectionRef } from '../reference/sections.mjs';
 import { resolveLabel } from '../reference/label';
 import { resolveGlosses } from '../reference/gloss';
+import { indexEntryFormula } from '../reference/derived-notation.mjs';
+import { isIndexEntryLatex } from './content-schemas';
+import type { ContentRecord } from '../reference/gate-retired-keys';
 import {
   deriveRequires,
   deriveSources,
@@ -194,13 +196,6 @@ function boolean(value: unknown, label: string): boolean {
   return value;
 }
 
-function status(value: unknown, label: string): EditorialStatus {
-  if (value !== 'draft' && value !== 'in-review' && value !== 'reviewed') {
-    throw new TypeError(`${label} must be draft, in-review, or reviewed`);
-  }
-  return value;
-}
-
 function alignment(value: unknown, label: string): NotationAlignment {
   const data = record(value, label);
   if (data.kind === 'general') {
@@ -400,7 +395,6 @@ function lessonEntries(
     const teaches = (data.teaches as string[] | undefined) ?? [];
     lessons.push({
       id: lessonIdFromSlug(slug),
-      status: (data.editorialStatus as LessonDefinition['status']) ?? 'draft',
       requires: deriveRequires(teaches, prerequisitesById),
       teaches,
       assessments: lessonCheckIds(path),
@@ -471,6 +465,41 @@ function glossEntries(
   return glosses;
 }
 
+/**
+ * Rule N23's optional fields: `reads` (index entry), `range`, `fixedIndex`.
+ * An index entry's `formula` names the symbol it indexes as `{base}`: the
+ * entry's own card shows it over a square bound to the entry, and the raw
+ * template stays as `formulaTemplate` for the derived cards.
+ */
+function indexFields(
+  data: Record<string, unknown>,
+  at: string,
+  key: string,
+  latex: string,
+  formula: string | undefined,
+): {
+  reads?: string;
+  range?: string;
+  fixedIndex?: true;
+  formula?: string;
+  formulaTemplate?: string;
+} {
+  const reads = optionalString(data.reads, `${at}.reads`);
+  const range = optionalString(data.range, `${at}.range`);
+  const fixedIndex =
+    data.fixedIndex === undefined ? false : boolean(data.fixedIndex, `${at}.fixedIndex`);
+  const template =
+    formula !== undefined && isIndexEntryLatex(latex) ? formula : undefined;
+  return {
+    ...(reads === undefined ? {} : { reads }),
+    ...(range === undefined ? {} : { range }),
+    ...(fixedIndex ? { fixedIndex: true as const } : {}),
+    ...(template === undefined
+      ? {}
+      : { formula: indexEntryFormula(template, key), formulaTemplate: template }),
+  };
+}
+
 function localDefinition(
   raw: unknown,
   file: string,
@@ -483,10 +512,6 @@ function localDefinition(
   const meaning = meaningText(data.meaning, `${at}.meaning`);
   const formula = optionalString(data.formula, `${at}.formula`);
   const units = optionalString(data.units, `${at}.units`);
-  const definitionText = [meaning, formula]
-    .filter((value): value is string => value !== undefined)
-    .join('\n');
-
   return {
     key,
     notation: latex,
@@ -498,11 +523,15 @@ function localDefinition(
       data.alignment === undefined
         ? { kind: 'general', rationale: 'Lesson-local symbol.' }
         : alignment(data.alignment, `${at}.alignment`),
-    references: extractNotationReferences(definitionText, file, 'definition'),
+    references: [
+      ...extractNotationReferences(meaning, file, 'definition'),
+      ...(formula === undefined ? [] : extractNotationReferences(formula, file, 'formula')),
+    ],
     glosses: glossEntries(data.glosses, key, `${at}.glosses`),
     source: { file },
     ...(formula === undefined ? {} : { formula }),
     ...(units === undefined ? {} : { units }),
+    ...indexFields(data, at, key, latex, formula),
   };
 }
 
@@ -527,15 +556,22 @@ function sharedNotationEntries(): SharedNotationDefinitionInput[] {
       domain: string(data.domain, `${file} domain`),
       sources: sourceIds(data.sources, `${file} sources`),
       seeAlso: strings(data.seeAlso, `${file} seeAlso`),
-      alignment: alignment(data.alignment, `${file} alignment`),
-      status: status(data.editorialStatus, `${file} editorialStatus`),
-      aiAssisted: boolean(data.aiAssisted, `${file} aiAssisted`),
+      // The collection schema's defaults (`compiler/content-schemas.ts`).
+      alignment:
+        data.alignment === undefined
+          ? { kind: 'general', rationale: 'General notation.' }
+          : alignment(data.alignment, `${file} alignment`),
+      aiAssisted:
+        data.aiAssisted === undefined
+          ? false
+          : boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
       references: extractNotationReferences(body, file, undefined),
       glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
       ...(formula === undefined ? {} : { formula }),
       ...(units === undefined ? {} : { units }),
+      ...indexFields(data, file, key, string(data.latex, `${file} latex`), formula),
     };
   });
 }
@@ -629,7 +665,6 @@ function notationLessonEntries(): NotationLessonInput[] {
     );
     lessons.push({
       lessonId: lessonIdFromSlug(slug),
-      status: status(data.editorialStatus, `${file} editorialStatus`),
       localDefinitions,
       suspended: notationSuspensions(notation.suspend, localDefinitions, file),
       references: extractNotationReferences(body, file, undefined),
@@ -680,7 +715,6 @@ export function loadNonChapterPages(): NonChapterPage[] {
       bodyLine,
       notation: {
         lessonId: id,
-        status: status(data.editorialStatus ?? 'draft', `${file} editorialStatus`),
         localDefinitions: [],
         suspended: [],
         references: extractNotationReferences(body, file, undefined),
@@ -712,6 +746,45 @@ export function loadNotationDefinitions(): Record<string, unknown>[] {
   );
 }
 
+/**
+ * Every content file's top-level fields and text: the frontmatter of a page,
+ * a notation entry or an abbreviation, and the object of a competency,
+ * assessment, source or track. The typed loaders above drop keys they do not
+ * know; the retired-key gate (`reference/gate-retired-keys.ts`) needs them.
+ */
+export function loadContentRecords(): ContentRecord[] {
+  const below = (directory: string, extensions: readonly string[]) => {
+    const path = join(CONTENT_ROOT, directory);
+    return existsSync(path) ? filesBelow(path, extensions) : [];
+  };
+  const records: ContentRecord[] = [];
+  for (const directory of ['docs', 'notation', 'abbreviations']) {
+    for (const path of below(directory, ['.md', '.mdx'])) {
+      const text = readFileSync(path, 'utf8');
+      records.push({
+        file: relative(REPOSITORY_ROOT, path),
+        data: (parseFrontmatter(text).frontmatter ?? {}) as Record<string, unknown>,
+        text,
+      });
+    }
+  }
+  for (const directory of ['competencies', 'assessments', 'sources', 'tracks']) {
+    for (const path of below(directory, ['.json'])) {
+      const text = readFileSync(path, 'utf8');
+      const data: unknown = JSON.parse(text);
+      records.push({
+        file: relative(REPOSITORY_ROOT, path),
+        data:
+          data !== null && typeof data === 'object' && !Array.isArray(data)
+            ? (data as Record<string, unknown>)
+            : {},
+        text,
+      });
+    }
+  }
+  return records;
+}
+
 /** Parsed `src/content/sources/*.json` records for `remark-citation`. */
 export function loadSourceRecords(): Record<string, unknown>[] {
   return jsonEntries<SourceDefinition & { readonly id: string }>(

package/src/compiler/content-schema.ts

@@ -0,0 +1,108 @@
+/**
+ * The content-schema check (invariant `content-schema`). Every content file
+ * must satisfy its collection's schema — the same zod schema `astro build`
+ * loads it with (`content-schemas.ts`) — so `pnpm validate:content` and
+ * `pnpm content check` reject what the build would, at the key's line,
+ * instead of passing it and leaving `astro build` to fail with
+ * `InvalidContentEntryDataError`.
+ */
+import type { CurriculumIssue } from '../curriculum/validation';
+import { keyLine, type ContentRecord } from '../reference/gate-retired-keys';
+import { CONTENT_SCHEMAS } from './content-schemas';
+
+export type ContentCollection = keyof typeof CONTENT_SCHEMAS;
+
+/**
+ * The collection a repository-relative content file belongs to, or `null`
+ * for one Astro's loaders skip (`src/content-config.ts`): a docs page whose
+ * name starts with `_`, a notation or abbreviation file that is not `.md`.
+ */
+export function collectionOf(file: string): ContentCollection | null {
+  const parts = file.replace(/\\/g, '/').split('/');
+  if (parts[0] !== 'content' || parts.length < 3) return null;
+  const directory = parts[1] ?? '';
+  const name = parts[parts.length - 1] ?? '';
+  if (!Object.hasOwn(CONTENT_SCHEMAS, directory)) return null;
+  const collection = directory as ContentCollection;
+  if (collection === 'docs') {
+    return /\.mdx?$/.test(name) && !name.startsWith('_') ? collection : null;
+  }
+  if (collection === 'notation' || collection === 'abbreviations') {
+    return name.endsWith('.md') ? collection : null;
+  }
+  return name.endsWith('.json') ? collection : null;
+}
+
+/**
+ * The 1-based line of the value at `path` in a YAML or JSON `text`: each name
+ * is searched for after the previous one, and an array index skips that many
+ * `- ` items of a YAML list. Falls back to the deepest line found.
+ */
+export function lineOfPath(
+  text: string,
+  path: readonly (string | number)[],
+): number | undefined {
+  const first = path[0];
+  if (typeof first !== 'string') return undefined;
+  const start = keyLine(text, first);
+  if (start === undefined) return undefined;
+  const lines = text.split('\n');
+  let at = start - 1;
+  for (const segment of path.slice(1)) {
+    if (typeof segment === 'number') {
+      let seen = -1;
+      let found = -1;
+      for (let index = at + 1; index < lines.length; index += 1) {
+        if (/^\s*-\s/.test(lines[index] ?? '')) seen += 1;
+        if (seen === segment) {
+          found = index;
+          break;
+        }
+      }
+      if (found === -1) break;
+      at = found;
+      continue;
+    }
+    const name = segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`^[\\s-]*(?:"${name}"|${name})[ \\t]*:`);
+    let found = -1;
+    for (let index = at; index < lines.length; index += 1) {
+      if (pattern.test(lines[index] ?? '')) {
+        found = index;
+        break;
+      }
+    }
+    if (found === -1) break;
+    at = found;
+  }
+  return at + 1;
+}
+
+/** One `content-schema` issue per schema problem in each record, in record order. */
+export function validateContentSchemas(
+  records: readonly ContentRecord[],
+): CurriculumIssue[] {
+  const issues: CurriculumIssue[] = [];
+  for (const { file, data, text } of records) {
+    const collection = collectionOf(file);
+    if (!collection) continue;
+    const result = CONTENT_SCHEMAS[collection].safeParse(data);
+    if (result.success) continue;
+    for (const problem of result.error.issues) {
+      const path = problem.path.filter(
+        (segment): segment is string | number =>
+          typeof segment === 'string' || typeof segment === 'number',
+      );
+      const line = lineOfPath(text, path);
+      const at = line === undefined ? file : `${file}:${line}`;
+      const field = path.length > 0 ? `${path.join('.')}: ` : '';
+      issues.push({
+        kind: 'content-schema',
+        message: `${at}: ${field}${problem.message} (the ${collection} collection's schema, which astro build applies too)`,
+        file,
+        ...(line === undefined ? {} : { line }),
+      });
+    }
+  }
+  return issues;
+}