explico 0.4.0 → 0.5.0

package/src/reference/consistency.ts

@@ -22,6 +22,10 @@
  *   (h) operator-explained           a named operator a lesson uses is on the
  *                                     shipped/course operator allowlist or
  *                                     carries a notation entry (rule N8)
+ *   (i) roman-label-explained        a `\mathrm{…}` multi-letter label a lesson
+ *                                     uses is on the shipped/course roman-label
+ *                                     allowlist or carries a notation entry
+ *                                     (rule N10)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
@@ -30,12 +34,14 @@
 import type {
   CourseConventions,
   CourseOperators,
+  CourseRomanLabels,
 } from '../compiler/course-config';
 import type { CurriculumCatalog } from '../curriculum/validation';
 import type { NotationSpec } from '../compiler/collections';
 import type { LintIgnore } from './lint-ignore';
 import { effectiveOperatorAllowlist } from './base-operators.mjs';
-import { collectOperators } from './math-glyphs.mjs';
+import { effectiveRomanLabelAllowlist } from './base-roman-labels.mjs';
+import { collectOperators, collectRomanLabels } from './math-glyphs.mjs';
 import { offVocabularyTokens } from './units-vocab';
 import type {
   NotationDefinitionRecord,
@@ -54,7 +60,8 @@ export type ConsistencyCode =
   | 'gloss-wants-promoting'
   | 'card-wants-demoting'
   | 'gloss-name-shape'
-  | 'operator-explained';
+  | 'operator-explained'
+  | 'roman-label-explained';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -79,6 +86,8 @@ export interface ConsistencyInput {
   readonly conventions: CourseConventions;
   /** This course's edits to the named-operator baseline (rule N8). */
   readonly operators?: CourseOperators;
+  /** This course's edits to the roman-label baseline (rule N10). */
+  readonly romanLabels?: CourseRomanLabels;
 }
 
 const CONVENTION_RE =
@@ -551,6 +560,66 @@ function checkOperatorExplained(
   }
 }
 
+/**
+ * (i) roman-label-explained (rule N10) — the `\mathrm{…}` twin of (h)
+ * above: N3 requires the *format* (`\mathrm{KE}`, never bare `KE`) but has
+ * no opinion on whether the label is ever explained, because the glyph
+ * resolver skips a `\mathrm{…}` body whole. This is the check that looks at
+ * them; it reads `collectRomanLabels`, which parses with the same pinned
+ * KaTeX as the completeness gate.
+ */
+function checkRomanLabelExplained(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveRomanLabelAllowlist(input.romanLabels);
+  const byId = new Map<string, NotationDefinitionRecord>(
+    input.registry.definitions.map((definition) => [definition.id, definition]),
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings]),
+  );
+
+  for (const lesson of input.notationInput.lessons) {
+    // Labels the reader is shown on this page: the lesson's own
+    // `notation.local` entries, plus every shared card it binds with `[[key]]`.
+    const explained = new Set<string>();
+    const noteEntryLabels = (latex: string): void => {
+      for (const label of collectRomanLabels(latex)) {
+        explained.add(label.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryLabels(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryLabels(definition.notation);
+    }
+
+    const reported = new Set<string>();
+    for (const span of mathSpans(lesson.body)) {
+      for (const label of collectRomanLabels(span.latex)) {
+        if (allowlist.has(label.name)) continue;
+        if (explained.has(label.name)) continue;
+        if (reported.has(label.name)) continue;
+        reported.add(label.name);
+        if (input.lintIgnore.matches('roman-label-explained', label.name)) {
+          continue;
+        }
+        out.push({
+          code: 'roman-label-explained',
+          severity: 'warning',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: label.name,
+          message: `${lesson.lessonId}: roman label ${JSON.stringify(`\\mathrm{${label.name}}`)} is neither on the course roman-label allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(`\\mathrm{${label.name}}`)}) introduced with [[key]], or add ${JSON.stringify(label.name)} to romanLabels.allow in course.config.ts`,
+        });
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -565,6 +634,7 @@ const CHECKS: ((
   checkCardWantsDemoting,
   checkGlossNameShape,
   checkOperatorExplained,
+  checkRomanLabelExplained,
 ];
 
 /**
@@ -603,6 +673,7 @@ export function consistencyCounts(
     'card-wants-demoting': 0,
     'gloss-name-shape': 0,
     'operator-explained': 0,
+    'roman-label-explained': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/diagrams-validate.ts

@@ -0,0 +1,40 @@
+/** `validateKeyedFloats` for `<Diagram>` — see `keyed-float-validate.ts`. */
+
+import {
+  validateKeyedFloats,
+  type KeyedFloatLabelRecord,
+  type KeyedFloatLessonInput,
+  type KeyedFloatValidation,
+} from './keyed-float-validate';
+
+export type DiagramDiagnosticCode =
+  | 'dia-invalid-key'
+  | 'dia-duplicate-key'
+  | 'dia-ref-resolves'
+  | 'dia-key-unused';
+
+export interface DiagramDiagnostic {
+  readonly code: DiagramDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export type DiagramLabelRecord = KeyedFloatLabelRecord;
+export type DiagramLessonInput = KeyedFloatLessonInput;
+
+export interface DiagramValidation extends KeyedFloatValidation {
+  readonly diagnostics: readonly DiagramDiagnostic[];
+}
+
+export function validateDiagrams(
+  lessons: readonly DiagramLessonInput[],
+): DiagramValidation {
+  return validateKeyedFloats(lessons, {
+    tagName: 'Diagram',
+    prefix: 'dia',
+    noun: 'diagram',
+  }) as DiagramValidation;
+}

package/src/reference/equations.mjs

@@ -128,9 +128,36 @@ export function stripFencedCode(markdown) {
  * `keep`, when given, leaves a component of that name untouched instead of
  * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
  * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ *
+ * `transparent`, when given, removes only those components' opening/closing
+ * tags and exposes their body to the later blanking pass. `<Memo>` and
+ * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
+ * wrapper, their bodies are details in the lesson's reading order, so numbered
+ * equations/floats in them stay in the official sequence. Section headings in
+ * a transparent body do not change the surrounding page's section counter.
  */
-export function stripJsxComponents(markdown, keep) {
-  return String(markdown).replace(
+export function stripJsxComponents(markdown, keep, transparent = []) {
+  let source = String(markdown);
+  const attributes = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+  for (const name of transparent) {
+    const component = new RegExp(
+      `<${name}\\b${attributes}>([\\s\\S]*?)<\\/${name}\\s*>`,
+      'g',
+    );
+    source = source.replace(component, (block, body) => {
+      const bodyStart = block.indexOf(body);
+      const visibleBody = body.replace(
+        /(^|\n)([ \t]{0,3})##(?=[ \t]+\S)/g,
+        (match) => match.replace(/#/g, ' '),
+      );
+      return (
+        block.slice(0, bodyStart).replace(/[^\n]/g, ' ') +
+        visibleBody +
+        block.slice(bodyStart + body.length).replace(/[^\n]/g, ' ')
+      );
+    });
+  }
+  return source.replace(
     /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
     (block, name) => (name === keep ? block : block.replace(/[^\n]/g, ' ')),
   );
@@ -149,7 +176,10 @@ export function stripJsxComponents(markdown, keep) {
  */
 export function scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown));
+  const text = stripJsxComponents(stripFencedCode(markdown), undefined, [
+    'Memo',
+    'ShortNote',
+  ]);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -225,17 +255,13 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // Only top-level blocks: a `$$…$$` nested in an MDX component (a
-  // `<CompactExample>` worked example, an `<Aside>`) is illustrative, not part
-  // of the lesson's equation sequence, and its container may be collapsed.
-  const children = Array.isArray(tree?.children) ? tree.children : [];
-  for (const node of children) {
-    if (!node || typeof node !== 'object') continue;
-    if (node.type === 'heading' && node.depth === 2) {
-      section += 1;
-      indexInSection = 0;
-      continue;
-    }
+  // Top-level blocks plus the bodies of `<Memo>` and `<ShortNote>`: other MDX
+  // components (a `<CompactExample>` worked example, an `<Aside>`) remain
+  // illustrative and outside the lesson's official equation sequence. These
+  // two detail components are deliberately transparent because they occupy an
+  // exact point in the reading order, even while visually collapsed.
+  const collectFromDetail = (node) => {
+    if (!node || typeof node !== 'object') return;
     if (node.type === 'math') {
       indexInSection += 1;
       indexInLesson += 1;
@@ -254,6 +280,33 @@ export function collectDisplayEquations(tree, numbering) {
         indexInSection,
         node,
       });
+      return;
+    }
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      node.name !== 'Memo' &&
+      node.name !== 'ShortNote'
+    ) {
+      return;
+    }
+    if (!Array.isArray(node.children)) return;
+    for (const child of node.children) collectFromDetail(child);
+  };
+
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.type === 'heading' && node.depth === 2) {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    if (node.type === 'math') collectFromDetail(node);
+    else if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Memo' || node.name === 'ShortNote')
+    ) {
+      collectFromDetail(node);
     }
   }
   return equations;

package/src/reference/gate-abbreviations.ts

@@ -0,0 +1,128 @@
+/**
+ * The abbreviation-notation gate (rule N14): every acronym-shaped or
+ * dotted-abbreviation-shaped token sitting in plain lesson prose is either
+ * universal, explained by the abbreviations table, or already explained as a
+ * math quantity elsewhere on the same page.
+ *
+ * This is the prose-shaped twin of [N8](#n8)/[N10](#n10)
+ * (`checkOperatorExplained` / `checkRomanLabelExplained` in `consistency.ts`)
+ * rather than a rewrite of them: those two already require every
+ * `\operatorname{…}` / `\mathrm{…}` used *inside* `$…$` to be universal or
+ * explained, so an abbreviation that is also a math quantity — `MSE` written
+ * `\mathrm{MSE}` in an equation and bound to a notation entry — is already
+ * covered there. What N8/N10 cannot see is the same word sitting in ordinary
+ * prose ("the OLS estimator…") with no `$…$` around it at all; that is this
+ * gate's whole job, so it reuses `pageScope` plus `collectRomanLabels` /
+ * `collectOperators` (the exact functions N8/N10 already call) to recognize
+ * when a prose token is covered by that other mechanism instead of asking the
+ * author to explain the same term twice.
+ *
+ * Ships straight as an error, same as N9 (`gate-prose-notation.ts`): the
+ * corpus has no prior instances to absorb, so there is no Tier-3 warm-up
+ * period and no `lint-ignore.yml` entry.
+ */
+import { collectOperators, collectRomanLabels } from './math-glyphs.mjs';
+import { isBaseAbbreviation } from './base-abbreviations.mjs';
+import { pageScope } from './gate-math';
+import type { MathGateDiagnostic, ScopeEntry } from './gate-math';
+import { lineOf, proseOnly } from './gate-prose-notation';
+import type {
+  AbbreviationDefinitionInput,
+  NotationRegistryInput,
+} from './types';
+import type { CourseAbbreviations } from '../compiler/course-config';
+
+// An all-caps run of 2+ letters, an optional trailing plural/possessive `s`
+// or `'s` (`OLSs`, `SSR's`) stripped from the reported token so it matches
+// the table/baseline entry for the singular form.
+const CAPS_RUN = /\b([A-Z]{2,})(?:'s|s)?\b/g;
+// A run of 2+ single-letter-then-period groups: `w.r.t.`, `i.i.d.`, `e.g.`.
+const DOTTED_ABBR = /\b(?:[A-Za-z]\.){2,}/g;
+
+interface AbbreviationMatch {
+  readonly token: string;
+  readonly index: number;
+}
+
+/** Every abbreviation-shaped token in an already-prose-only string, in source order. */
+function findAbbreviationLikeTokens(text: string): AbbreviationMatch[] {
+  const out: AbbreviationMatch[] = [];
+  for (const match of text.matchAll(CAPS_RUN)) {
+    out.push({ token: match[1] ?? match[0], index: match.index ?? 0 });
+  }
+  for (const match of text.matchAll(DOTTED_ABBR)) {
+    out.push({ token: match[0], index: match.index ?? 0 });
+  }
+  return out.sort((a, b) => a.index - b.index);
+}
+
+const FIX =
+  'Add it to an abbreviations-table entry (content/abbreviations/*.md), ' +
+  'allowlist it in abbreviations.allow in course.config.ts if it is common, ' +
+  'non-technical usage, or — if it names a math quantity — introduce it as ' +
+  '\\mathrm{…} (or \\operatorname{…}) bound to a notation entry the reader ' +
+  'can hover. See docs/authoring/notation.md#n14.';
+
+/**
+ * Scan every lesson body for an abbreviation-shaped token outside `$…$` that
+ * is neither universal nor explained. Returns one `MathGateDiagnostic`
+ * (context `'abbreviation'`, always an error) per unresolved token, deduped
+ * per lesson so a term used many times on one page is reported once.
+ */
+export function gateAbbreviations(input: {
+  readonly notationInput: NotationRegistryInput;
+  readonly abbreviations: readonly AbbreviationDefinitionInput[];
+  readonly courseAbbreviations?: CourseAbbreviations;
+}): MathGateDiagnostic[] {
+  const { notationInput, abbreviations, courseAbbreviations } = input;
+
+  const tableTokens = new Set<string>();
+  for (const entry of abbreviations) {
+    tableTokens.add(entry.abbr);
+    for (const alias of entry.aliases) tableTokens.add(alias);
+  }
+
+  const sharedByKey = new Map<string, ScopeEntry>(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation },
+    ]),
+  );
+
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const lesson of notationInput.lessons) {
+    // Terms already explained as a math quantity on this page (N8/N10): every
+    // roman label / named operator carried by a bound local or `[[key]]`
+    // /`\explain`-referenced shared definition.
+    const mathQuantityNames = new Set<string>();
+    for (const entry of pageScope(lesson, sharedByKey)) {
+      for (const label of collectRomanLabels(entry.notation)) {
+        mathQuantityNames.add(label.name);
+      }
+      for (const operator of collectOperators(entry.notation)) {
+        mathQuantityNames.add(operator.name);
+      }
+    }
+
+    const text = proseOnly(lesson.body);
+    const reported = new Set<string>();
+    for (const { token, index } of findAbbreviationLikeTokens(text)) {
+      if (reported.has(token)) continue;
+      if (isBaseAbbreviation(token, courseAbbreviations)) continue;
+      if (tableTokens.has(token)) continue;
+      if (mathQuantityNames.has(token)) continue;
+      reported.add(token);
+      diagnostics.push({
+        context: 'abbreviation',
+        severity: 'error',
+        file: lesson.source.file,
+        line: lineOf(lesson.body, index),
+        token,
+        message: `Unexplained abbreviation ${JSON.stringify(token)} outside math. ${FIX}`,
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/gate-math.ts

@@ -20,14 +20,25 @@ import type {
 } from './types';
 
 export interface MathGateDiagnostic {
-  readonly context: 'body' | 'formula' | 'assessment';
+  readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation';
   /**
    * Body / component-slot math blocks the build (the render path needs every
    * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
    * a formula's glyphs are now rendered live and explorable, so an unresolved
    * one is a hole the reader can see, and the corpus was brought to zero when
-   * the tier was promoted. `assessment` math stays a Tier-3 warning until its
-   * own reviewed content pass (D6/D13/D14).
+   * the tier was promoted. `assessment` joined the same way when
+   * `AssessmentRunner` started rendering `prompt` / `explanation` through
+   * KaTeX (`mixed-content.ts`) instead of showing them as raw text: an
+   * unresolved glyph is now a visible hole in the assessment UI, not an
+   * invisible warning, so the corpus was brought to zero and the tier
+   * promoted in the same change — see `CHANGELOG.md`. `prose` (N9,
+   * `gate-prose-notation.ts`) is the complementary direction — plain-text
+   * notation sitting *outside* `$…$` — and ships straight as an error: it has
+   * no partial corpus to absorb, since every prior instance was fixed in the
+   * same change that introduced the check. `abbreviation` (N14,
+   * `gate-abbreviations.ts`) is the same "ships straight as an error" story
+   * for a different shape of plain-text token — an unexplained acronym or
+   * dotted abbreviation, rather than a mis-typed quantity/unit.
    */
   readonly severity: 'error' | 'warning';
   readonly file: string;
@@ -39,7 +50,9 @@ export interface MathGateDiagnostic {
 const SEVERITY: Record<MathGateDiagnostic['context'], 'error' | 'warning'> = {
   body: 'error',
   formula: 'error',
-  assessment: 'warning',
+  assessment: 'error',
+  prose: 'error',
+  abbreviation: 'error',
 };
 
 interface AssessmentItemLike {
@@ -93,11 +106,18 @@ function mathSpans(body: string): MathSpan[] {
   return spans;
 }
 
-type ScopeEntry = { key: string; notation: string };
+export type ScopeEntry = { key: string; notation: string };
 
-function pageScope(
+/**
+ * A lesson's flat glyph table: its own `notation.local` entries plus every
+ * shared card it introduces with `[[key]]` / `\explain{key}`. Exported so a
+ * caller that needs the *same* scope for a different purpose — rendering an
+ * assessment's math (`mixed-content.ts`), say — doesn't reconstruct it by
+ * hand and risk drifting from what the completeness gate actually checks.
+ */
+export function pageScope(
   lesson: NotationLessonInput,
-  sharedByKey: ReadonlyMap<string, SharedNotationDefinitionInput>,
+  sharedByKey: ReadonlyMap<string, ScopeEntry>,
 ): ScopeEntry[] {
   const local = lesson.localDefinitions.map((definition) => ({
     key: definition.key,