explico 0.11.1 → 0.13.0

package/dist/compiler/cli.js

@@ -7,6 +7,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";
 import { createNotationKatexOptions } from "../reference/katex-options.mjs";
@@ -17,12 +18,14 @@ import remarkNotation, {
   createRemarkNotationOptions
 } from "../reference/remark-notation.mjs";
 import remarkShortNote from "../reference/remark-short-note.mjs";
+import { readRenderDiagnostics } from "./render-diagnostics.js";
 import { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation.js";
 import { isCourseRuleId, ownerOf, ELEMENTS } from "../rules/catalog.js";
 import {
   renderRulesInEffect,
   rulesInEffect
 } from "../rules/in-effect.js";
+import { RESERVED_KEY_PREFIXES, reservedKeyPrefix } from "../reference/references.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const DOCS_ROOT = join(CONTENT_ROOT, "docs");
@@ -47,13 +50,26 @@ function ownerFields(code) {
 function withOwner(diagnostic) {
   return { ...diagnostic, ...ownerFields(diagnostic.code) };
 }
+function renderedCliDiagnostic(diagnostic) {
+  return {
+    code: `render:${diagnostic.code}`,
+    ...ownerFields(diagnostic.code),
+    severity: diagnosticSeverity(diagnostic.severity),
+    message: diagnostic.message,
+    file: diagnostic.file
+  };
+}
 function mentions(message, lessonId, file) {
   return message.includes(lessonId) || message.includes(file) || message.includes(file.replace(/^content\/docs\//, ""));
 }
-function lessonDiagnostics(manifest, lesson) {
+function lessonDiagnostics(manifest, lesson, rendered = readRenderDiagnostics()) {
   const out = [];
   const { file, id } = lesson;
   const assessments = new Set(lesson.assessments);
+  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) => value === void 0 ? {} : { file: value };
   for (const issue of manifest.diagnostics.curriculum) {
     if (!mentions(issue.message, id, file)) continue;
@@ -69,7 +85,7 @@ function lessonDiagnostics(manifest, lesson) {
   ]) {
     const [group, entry] = diagnostic;
     const entryFile = entry.source?.file;
-    if (entry.lessonId !== id && entryFile !== file && !mentions(entry.message, id, file)) {
+    if (entry.lessonId !== id && entryFile !== file && !(entryFile !== void 0 && entryFiles.has(entryFile)) && !mentions(entry.message, id, file)) {
       continue;
     }
     out.push({
@@ -80,7 +96,7 @@ function lessonDiagnostics(manifest, lesson) {
     });
   }
   for (const diagnostic of manifest.diagnostics.math) {
-    const forLesson = diagnostic.file === file || diagnostic.context === "assessment" && [...assessments].some(
+    const forLesson = diagnostic.file === file || entryFiles.has(diagnostic.file) || diagnostic.context === "assessment" && [...assessments].some(
       (assessmentId) => diagnostic.file.startsWith(`${assessmentId} `)
     );
     if (!forLesson) continue;
@@ -133,6 +149,10 @@ function lessonDiagnostics(manifest, lesson) {
       ...withFile(diagnostic.file)
     });
   }
+  for (const diagnostic of rendered) {
+    if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
+    out.push(renderedCliDiagnostic(diagnostic));
+  }
   return out.map(withOwner).sort(
     (a, b) => a.code.localeCompare(b.code) || a.message.localeCompare(b.message)
   );
@@ -148,6 +168,11 @@ function processorFor(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,
@@ -171,7 +196,7 @@ function processorFor(manifest) {
   return processorPromise;
 }
 function stripEsm(body) {
-  return body.replace(/^(?:import|export)\s[^\n]*\n?/gm, "");
+  return body.replace(/^(?:import|export)\s[^\n]*/gm, "");
 }
 function renderErrorCode(message) {
   if (/Unresolved notation/i.test(message)) return "render:notation";
@@ -195,21 +220,50 @@ async function renderLesson(manifest, input) {
     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);
+    const { line, column } = error ?? {};
     return {
       rendered: false,
       diagnostics: [
-        { code: renderErrorCode(message), severity: "error", message }
+        {
+          code: renderErrorCode(message),
+          severity: "error",
+          message,
+          ...typeof line === "number" ? { line } : {},
+          ...typeof column === "number" ? { column } : {}
+        }
       ]
     };
   }
 }
+let quietRenders = 0;
+let consoleError;
+async function withoutParseLogs(work) {
+  if (quietRenders++ === 0) {
+    const original = console.error;
+    consoleError = original;
+    console.error = (...args) => {
+      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 !== void 0) {
+      console.error = consoleError;
+      consoleError = void 0;
+    }
+  }
+}
 function estimateTokens(text) {
   return Math.ceil(text.length / 4);
 }
@@ -272,6 +326,13 @@ function lessonRaw(lesson) {
     body: parsed.content.replace(/^\n/, "")
   };
 }
+function lessonSource(text) {
+  const parsed = parseFrontmatter(text, { frontmatter: "empty-with-spaces" });
+  return {
+    frontmatter: parsed.frontmatter ?? {},
+    body: parsed.content
+  };
+}
 const DOMAIN_DIRS_BY_SECTION = {
   foundations: [".", "rates", "valuation"],
   bonds: ["bonds", "rates"],
@@ -317,9 +378,7 @@ function domainSignaturesForSection(section) {
     signatures: signaturesInFile(path)
   })).filter((entry) => entry.signatures.length > 0);
 }
-function contentStatus(manifest) {
-  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();
+function contentStatus(manifest, rendered = readRenderDiagnostics()) {
   const orphans = manifest.notation.diagnostics.filter((diagnostic) => diagnostic.code === "unused-definition").map((diagnostic) => ({
     code: `notation:${diagnostic.code}`,
     ...ownerFields(diagnostic.code),
@@ -343,7 +402,8 @@ function contentStatus(manifest) {
     ...manifest.diagnostics.consistency.map((d) => d.severity),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
     ...manifest.diagnostics.config.map((d) => d.severity),
-    ...manifest.diagnostics.waivers.map((d) => d.severity)
+    ...manifest.diagnostics.waivers.map((d) => d.severity),
+    ...rendered.map((d) => diagnosticSeverity(d.severity))
   ];
   const keyedEquations = manifest.lessons.reduce(
     (count, lesson) => count + lesson.equations.length,
@@ -383,7 +443,6 @@ function contentStatus(manifest) {
       keyedDiagrams,
       keyedExamples
     },
-    draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
     diagnostics: {
       errors: allDiagnostics.filter((severity) => severity === "error").length,
@@ -405,7 +464,7 @@ const SEVERITY_RANK = {
   warning: 1,
   error: 2
 };
-function contentDiagnostics(manifest, minimumSeverity = "info") {
+function contentDiagnostics(manifest, minimumSeverity = "info", rendered = readRenderDiagnostics()) {
   const lessonFileByHint = /* @__PURE__ */ new Map();
   for (const lesson of manifest.lessons) {
     lessonFileByHint.set(lesson.id, lesson.file);
@@ -439,6 +498,10 @@ function contentDiagnostics(manifest, minimumSeverity = "info") {
       });
     }
   }
+  for (const diagnostic of rendered) {
+    const cli = renderedCliDiagnostic(diagnostic);
+    if (SEVERITY_RANK[cli.severity] >= SEVERITY_RANK[minimumSeverity]) diagnostics.push(cli);
+  }
   diagnostics.sort(
     (left, right) => (left.file ?? "").localeCompare(right.file ?? "") || (left.line ?? 0) - (right.line ?? 0) || (left.column ?? 0) - (right.column ?? 0) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message)
   );
@@ -448,8 +511,8 @@ function contentDiagnostics(manifest, minimumSeverity = "info") {
     diagnostics
   };
 }
-function contentWarnings(manifest) {
-  const warnings = contentDiagnostics(manifest, "warning").diagnostics.filter(
+function contentWarnings(manifest, rendered = readRenderDiagnostics()) {
+  const warnings = contentDiagnostics(manifest, "warning", rendered).diagnostics.filter(
     (diagnostic) => diagnostic.severity === "warning"
   );
   return { count: warnings.length, warnings };
@@ -515,7 +578,6 @@ function contentContext(manifest, rawId) {
       file: lesson.file,
       title: lesson.title,
       description: lesson.description,
-      status: lesson.status,
       teaches: lesson.teaches,
       requires: lesson.requires,
       assumptions: lesson.assumptions,
@@ -561,7 +623,9 @@ function contentContext(manifest, rawId) {
 }
 async function checkOneLesson(manifest, lesson) {
   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,
@@ -611,17 +675,18 @@ ${untracked}`;
 }
 async function contentCheck(manifest, options) {
   let targets;
+  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(
     targets.map((lesson) => checkOneLesson(manifest, lesson))
@@ -655,7 +720,6 @@ function scaffoldLesson(rawId) {
   const contents = `---
 title: ${title}
 description: One sentence on what the reader can do after this lesson.
-editorialStatus: draft
 teaches: []
 assumptions: []
 ---
@@ -698,6 +762,13 @@ function scaffoldTerm(rawKey) {
       `A notation key is lower-case, dot/hyphen separated, got ${JSON.stringify(rawKey)}.`
     );
   }
+  const reserved = reservedKeyPrefix(key);
+  if (reserved !== void 0) {
+    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(
@@ -715,13 +786,12 @@ sources: []
 seeAlso: []
 alignment:
   kind: general
-  rationale: Draft scaffold \u2014 set a real alignment before review.
-editorialStatus: draft
+  rationale: Draft scaffold \u2014 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: [] };
 }
@@ -737,6 +807,7 @@ export {
   estimateTokens,
   findLesson,
   lessonDiagnostics,
+  lessonSource,
   normalizeLessonId,
   parseRulesFilter,
   renderLesson,

package/dist/compiler/collections.d.ts

@@ -1,5 +1,6 @@
 import { CurriculumCatalog } from '../curriculum/validation.js';
-import { NotationReferenceInput, AbbreviationDefinitionInput, NotationRegistryInput, LocalNotationDefinitionInput, NotationSuspension } from '../reference/types.js';
+import { NotationLessonInput, NotationReferenceInput, AbbreviationDefinitionInput, NotationRegistryInput, LocalNotationDefinitionInput, NotationSuspension } from '../reference/types.js';
+import { ContentRecord } from '../reference/gate-retired-keys.js';
 
 /**
  * The single path from content files to typed data.
@@ -54,12 +55,42 @@ declare function loadAbbreviationRegistryInput(): Promise<readonly AbbreviationD
  * decoration (the page would contradict itself) each fail the load.
  */
 declare function notationSuspensions(raw: unknown, localDefinitions: readonly LocalNotationDefinitionInput[], file: string): NotationSuspension[];
+/**
+ * A docs page that is **not a chapter** (rule S10): the landing page, a part's
+ * overview page, and any other page outside a part directory — every slug
+ * `isLessonSlug` rejects. Such a page may explain its symbols like a chapter,
+ * but it recalls them only: it takes no `notation.local` and no float numbers.
+ */
+interface NonChapterPage {
+    /** `lessonIdFromSlug(slug)` — `index`, `motion.index`, `glossary`. Never a lesson id. */
+    readonly id: string;
+    /** Docs slug without extension, e.g. `motion/index`. */
+    readonly slug: string;
+    readonly file: string;
+    readonly data: Record<string, unknown>;
+    readonly body: string;
+    readonly bodyLine: number;
+    /**
+     * The page as notation input — no local entries, no suspensions — so the
+     * registry resolves its `[[key]]` references and the text and math gates
+     * scan it exactly as they scan a chapter.
+     */
+    readonly notation: NotationLessonInput;
+}
+declare function loadNonChapterPages(): NonChapterPage[];
 declare function loadNotationRegistryInput(): Promise<NotationRegistryInput>;
 /**
  * Notation frontmatter objects for `remark-notation`'s `definitions` option.
  * Returned synchronously because the remark transform reads the loader inline.
  */
 declare 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.
+ */
+declare function loadContentRecords(): ContentRecord[];
 /** Parsed `src/content/sources/*.json` records for `remark-citation`. */
 declare function loadSourceRecords(): Record<string, unknown>[];
 /**
@@ -101,4 +132,4 @@ declare function notationSourceLocatorGaps(): {
     total: number;
 };
 
-export { type NotationSpec, type PartOverviewPage, extractNotationReferences, loadAbbreviationRegistryInput, loadCurriculumCatalog, loadLessonChecks, loadNotationDefinitions, loadNotationRegistryInput, loadNotationSpecs, loadPartOverviews, loadSourceRecords, notationSourceLocatorGaps, notationSuspensions };
+export { type NonChapterPage, type NotationSpec, type PartOverviewPage, extractNotationReferences, loadAbbreviationRegistryInput, loadContentRecords, loadCurriculumCatalog, loadLessonChecks, loadNonChapterPages, loadNotationDefinitions, loadNotationRegistryInput, loadNotationSpecs, loadPartOverviews, loadSourceRecords, notationSourceLocatorGaps, notationSuspensions };

package/dist/compiler/collections.js

@@ -13,6 +13,8 @@ import { parseMemoRef } from "../reference/remark-memo.mjs";
 import { parseSectionRef } from "../reference/sections.mjs";
 import { resolveLabel } from "../reference/label.js";
 import { resolveGlosses } from "../reference/gloss.js";
+import { indexEntryFormula } from "../reference/derived-notation.mjs";
+import { isIndexEntryLatex } from "./content-schemas.js";
 import {
   deriveRequires,
   deriveSources,
@@ -100,12 +102,6 @@ function boolean(value, label) {
   }
   return value;
 }
-function status(value, label) {
-  if (value !== "draft" && value !== "in-review" && value !== "reviewed") {
-    throw new TypeError(`${label} must be draft, in-review, or reviewed`);
-  }
-  return value;
-}
 function alignment(value, label) {
   const data = record(value, label);
   if (data.kind === "general") {
@@ -139,16 +135,20 @@ function sourceSpan(file, text, index) {
     column: (lines.at(-1)?.length ?? 0) + 1
   };
 }
-function maskMarkdownLiterals(text) {
+function maskMarkdownLiterals(text, mdx) {
   const mask = (value) => value.replace(/[^\n]/g, " ");
-  return text.replace(
+  const fenced = text.replace(
     /(^|\n)[ \t]{0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:\n[ \t]{0,3}\2[^\n]*(?=\n|$)|$)/g,
     mask
-  ).replace(/^(?: {4}|\t).*$/gm, mask).replace(/(`+)(?!`)([^\n]*?)\1/g, mask);
+  );
+  return (mdx ? fenced : fenced.replace(/^(?: {4}|\t).*$/gm, mask)).replace(
+    /(`+)(?!`)([^\n]*?)\1/g,
+    mask
+  );
 }
 function extractNotationReferences(text, file, kind) {
   const references = [];
-  const searchable = maskMarkdownLiterals(text);
+  const searchable = maskMarkdownLiterals(text, file.endsWith(".mdx"));
   const patterns = [
     [/\[\[\s*([^\][]+?)\s*\]\]/g, kind ?? "prose"],
     [/\\explain\{([^{}]+)\}/g, kind ?? "math"]
@@ -221,7 +221,6 @@ function lessonEntries(prerequisitesById) {
     const teaches = data.teaches ?? [];
     lessons.push({
       id: lessonIdFromSlug(slug),
-      status: data.editorialStatus ?? "draft",
       requires: deriveRequires(teaches, prerequisitesById),
       teaches,
       assessments: lessonCheckIds(path),
@@ -276,6 +275,18 @@ function glossEntries(raw, ownerKey, at) {
   }
   return glosses;
 }
+function indexFields(data, at, key, latex, formula) {
+  const reads = optionalString(data.reads, `${at}.reads`);
+  const range = optionalString(data.range, `${at}.range`);
+  const fixedIndex = data.fixedIndex === void 0 ? false : boolean(data.fixedIndex, `${at}.fixedIndex`);
+  const template = formula !== void 0 && isIndexEntryLatex(latex) ? formula : void 0;
+  return {
+    ...reads === void 0 ? {} : { reads },
+    ...range === void 0 ? {} : { range },
+    ...fixedIndex ? { fixedIndex: true } : {},
+    ...template === void 0 ? {} : { formula: indexEntryFormula(template, key), formulaTemplate: template }
+  };
+}
 function localDefinition(raw, file, index) {
   const at = `${file} notation.local[${index}]`;
   const data = record(raw, at);
@@ -284,7 +295,6 @@ function localDefinition(raw, file, index) {
   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 !== void 0).join("\n");
   return {
     key,
     notation: latex,
@@ -293,11 +303,15 @@ function localDefinition(raw, file, index) {
     sources: sourceIds(data.sources, `${at}.sources`),
     seeAlso: strings(data.seeAlso, `${at}.seeAlso`),
     alignment: data.alignment === void 0 ? { kind: "general", rationale: "Lesson-local symbol." } : alignment(data.alignment, `${at}.alignment`),
-    references: extractNotationReferences(definitionText, file, "definition"),
+    references: [
+      ...extractNotationReferences(meaning, file, "definition"),
+      ...formula === void 0 ? [] : extractNotationReferences(formula, file, "formula")
+    ],
     glosses: glossEntries(data.glosses, key, `${at}.glosses`),
     source: { file },
     ...formula === void 0 ? {} : { formula },
-    ...units === void 0 ? {} : { units }
+    ...units === void 0 ? {} : { units },
+    ...indexFields(data, at, key, latex, formula)
   };
 }
 function sharedNotationEntries() {
@@ -321,15 +335,16 @@ function sharedNotationEntries() {
       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 === void 0 ? { kind: "general", rationale: "General notation." } : alignment(data.alignment, `${file} alignment`),
+      aiAssisted: data.aiAssisted === void 0 ? false : boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
       references: extractNotationReferences(body, file, void 0),
       glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
       ...formula === void 0 ? {} : { formula },
-      ...units === void 0 ? {} : { units }
+      ...units === void 0 ? {} : { units },
+      ...indexFields(data, file, key, string(data.latex, `${file} latex`), formula)
     };
   });
 }
@@ -401,7 +416,6 @@ function notationLessonEntries() {
     );
     lessons.push({
       lessonId: lessonIdFromSlug(slug),
-      status: status(data.editorialStatus, `${file} editorialStatus`),
       localDefinitions,
       suspended: notationSuspensions(notation.suspend, localDefinitions, file),
       references: extractNotationReferences(body, file, void 0),
@@ -412,6 +426,33 @@ function notationLessonEntries() {
   }
   return lessons;
 }
+function loadNonChapterPages() {
+  const pages = [];
+  for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
+    const slug = docSlug(path);
+    if (isLessonSlug(slug)) continue;
+    const { file, data, body, bodyLine } = parseDocument(path);
+    const id = lessonIdFromSlug(slug);
+    pages.push({
+      id,
+      slug: slug.replace(/\.(md|mdx)$/, ""),
+      file,
+      data,
+      body,
+      bodyLine,
+      notation: {
+        lessonId: id,
+        localDefinitions: [],
+        suspended: [],
+        references: extractNotationReferences(body, file, void 0),
+        body,
+        bodyLine,
+        source: { file }
+      }
+    });
+  }
+  return pages;
+}
 async function loadNotationRegistryInput() {
   return {
     sharedDefinitions: sharedNotationEntries(),
@@ -423,6 +464,35 @@ function loadNotationDefinitions() {
     (path) => parseDocument(path).data
   );
 }
+function loadContentRecords() {
+  const below = (directory, extensions) => {
+    const path = join(CONTENT_ROOT, directory);
+    return existsSync(path) ? filesBelow(path, extensions) : [];
+  };
+  const records = [];
+  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 ?? {},
+        text
+      });
+    }
+  }
+  for (const directory of ["competencies", "assessments", "sources", "tracks"]) {
+    for (const path of below(directory, [".json"])) {
+      const text = readFileSync(path, "utf8");
+      const data = JSON.parse(text);
+      records.push({
+        file: relative(REPOSITORY_ROOT, path),
+        data: data !== null && typeof data === "object" && !Array.isArray(data) ? data : {},
+        text
+      });
+    }
+  }
+  return records;
+}
 function loadSourceRecords() {
   return jsonEntries(
     join(CONTENT_ROOT, "sources")
@@ -504,8 +574,10 @@ function notationSourceLocatorGaps() {
 export {
   extractNotationReferences,
   loadAbbreviationRegistryInput,
+  loadContentRecords,
   loadCurriculumCatalog,
   loadLessonChecks,
+  loadNonChapterPages,
   loadNotationDefinitions,
   loadNotationRegistryInput,
   loadNotationSpecs,

package/dist/compiler/content-schema.d.ts

@@ -0,0 +1,31 @@
+import { CurriculumIssue } from '../curriculum/validation.js';
+import { ContentRecord } from '../reference/gate-retired-keys.js';
+import { CONTENT_SCHEMAS } from './content-schemas.js';
+import 'astro/zod';
+
+/**
+ * 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`.
+ */
+
+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`.
+ */
+declare function collectionOf(file: string): ContentCollection | 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.
+ */
+declare function lineOfPath(text: string, path: readonly (string | number)[]): number | undefined;
+/** One `content-schema` issue per schema problem in each record, in record order. */
+declare function validateContentSchemas(records: readonly ContentRecord[]): CurriculumIssue[];
+
+export { type ContentCollection, collectionOf, lineOfPath, validateContentSchemas };

package/dist/compiler/content-schema.js

@@ -0,0 +1,82 @@
+import { keyLine } from "../reference/gate-retired-keys.js";
+import { CONTENT_SCHEMAS } from "./content-schemas.js";
+function collectionOf(file) {
+  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;
+  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;
+}
+function lineOfPath(text, path) {
+  const first = path[0];
+  if (typeof first !== "string") return void 0;
+  const start = keyLine(text, first);
+  if (start === void 0) return void 0;
+  const lines = text.split("\n");
+  let at = start - 1;
+  for (const segment of path.slice(1)) {
+    if (typeof segment === "number") {
+      let seen = -1;
+      let found2 = -1;
+      for (let index = at + 1; index < lines.length; index += 1) {
+        if (/^\s*-\s/.test(lines[index] ?? "")) seen += 1;
+        if (seen === segment) {
+          found2 = index;
+          break;
+        }
+      }
+      if (found2 === -1) break;
+      at = found2;
+      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;
+}
+function validateContentSchemas(records) {
+  const issues = [];
+  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) => typeof segment === "string" || typeof segment === "number"
+      );
+      const line = lineOfPath(text, path);
+      const at = line === void 0 ? 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 === void 0 ? {} : { line }
+      });
+    }
+  }
+  return issues;
+}
+export {
+  collectionOf,
+  lineOfPath,
+  validateContentSchemas
+};