explico 0.8.0 → 0.11.1

package/src/reference/gate-part-pages.ts

@@ -0,0 +1,217 @@
+/**
+ * The part-page gate (rule S2): a part's overview page
+ * (`content/docs/<dir>/index.mdx`) states, in two authored paragraphs, how
+ * the course got here and where this part goes —
+ *
+ * - `<PartBridge>` — how the earlier parts lead into this one. Required on
+ *   every part after the first; optional on the first, which has no earlier
+ *   part to link from.
+ * - `<PartScope>` — what this part itself covers. Required on every part page.
+ *
+ * Each must appear once, hold exactly one paragraph, and fall inside the
+ * course's rule-S2 word range (`rules.S2.*`, see `partPageLimits`); the bridge comes
+ * first. What a paragraph *says* is Review-only — the gate checks that the
+ * slot is there and sized, not that its prose is about the right thing. See
+ * docs/authoring/structure-rules.md#s2.
+ *
+ * A part without an overview page is not in scope: overview pages stay
+ * opt-in, and this gate only shapes the ones a course authors. Ships straight
+ * as an error, same as S1.
+ */
+import type { NormalizedPartPages } from '../compiler/course-config';
+import { stripFencedCode } from './equations.mjs';
+import type { MathGateDiagnostic } from './gate-math';
+import { lessonLine } from './gate-prose-notation';
+
+/** One part overview page, as the manifest compiler loads it. */
+export interface PartPageInput {
+  readonly dir: string;
+  /** 1-based position in `courseConfig.parts`. */
+  readonly ordinal: number;
+  readonly file: string;
+  readonly body: string;
+  readonly bodyLine: number;
+}
+
+type Slot = 'bridge' | 'scope';
+
+const TAG_BY_SLOT: Record<Slot, string> = {
+  bridge: 'PartBridge',
+  scope: 'PartScope',
+};
+
+const SUBJECT_BY_SLOT: Record<Slot, string> = {
+  bridge: 'how the earlier parts lead into this one',
+  scope: 'what this part covers',
+};
+
+interface Occurrence {
+  readonly index: number;
+  /** `undefined` for a self-closing `<PartBridge />`. */
+  readonly content: string | undefined;
+}
+
+/** Blank MDX comments (`{/* … *\/}`) and code, keeping every newline. */
+function scannable(body: string): string {
+  return stripFencedCode(body).replace(/\{\/\*[\s\S]*?\*\/\}/g, (comment) =>
+    comment.replace(/[^\n]/g, ' '),
+  );
+}
+
+function occurrencesOf(text: string, tag: string): Occurrence[] {
+  const pattern = new RegExp(
+    `<${tag}\\b[^>]*?(?:\\/>|>([\\s\\S]*?)<\\/${tag}\\s*>)`,
+    'g',
+  );
+  return [...text.matchAll(pattern)].map((match) => ({
+    index: match.index ?? 0,
+    content: match[1],
+  }));
+}
+
+/** The blank-line-separated blocks of a slot's content. */
+function paragraphsOf(content: string): string[] {
+  return content
+    .trim()
+    .split(/\n[ \t]*\n/)
+    .filter((block) => block.trim().length > 0);
+}
+
+/**
+ * Words a reader reads in a paragraph of MDX prose. A math span, a `[[key]]`
+ * reference, or a link each count by what they render as: one token for the
+ * first two, the link text for the third. Citations and markup count nothing.
+ */
+export function proseWordCount(markdown: string): number {
+  return markdown
+    .replace(/\$\$[\s\S]*?\$\$/g, ' math ')
+    .replace(/\$[^$\n]+\$/g, ' math ')
+    .replace(/\[@[^\]]*\]/g, ' ')
+    .replace(/\[\[[^\][]+\]\]/g, ' term ')
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, ' $1 ')
+    .replace(/<\/?[A-Za-z][^>]*>/g, ' ')
+    .split(/\s+/)
+    .filter((token) => /[\p{L}\p{N}]/u.test(token)).length;
+}
+
+function slotFindings(
+  page: PartPageInput,
+  text: string,
+  slot: Slot,
+  limits: NormalizedPartPages,
+): { index: number; token: string; message: string }[] {
+  const tag = TAG_BY_SLOT[slot];
+  const found = occurrencesOf(text, tag);
+  const required = slot === 'scope' || page.ordinal > 1;
+  const out: { index: number; token: string; message: string }[] = [];
+
+  if (found.length === 0) {
+    if (required) {
+      out.push({
+        index: 0,
+        token: `<${tag}>`,
+        message:
+          `Part ${page.ordinal} ("${page.dir}") has an overview page with no ` +
+          `<${tag}> paragraph (rule S2). Add one paragraph on ` +
+          `${SUBJECT_BY_SLOT[slot]}, wrapped in <${tag}>…</${tag}>.`,
+      });
+    }
+    return out;
+  }
+
+  for (const extra of found.slice(1)) {
+    out.push({
+      index: extra.index,
+      token: `<${tag}>`,
+      message:
+        `A part overview page carries one <${tag}> (rule S2); this is ` +
+        'another. Merge the two into one paragraph.',
+    });
+  }
+
+  const [first] = found;
+  const paragraphs = paragraphsOf(first.content ?? '');
+  if (paragraphs.length === 0) {
+    out.push({
+      index: first.index,
+      token: `<${tag}>`,
+      message:
+        `<${tag}> is empty (rule S2). Write one paragraph on ` +
+        `${SUBJECT_BY_SLOT[slot]} inside it.`,
+    });
+    return out;
+  }
+  if (paragraphs.length > 1) {
+    out.push({
+      index: first.index,
+      token: `<${tag}>`,
+      message:
+        `<${tag}> holds ${paragraphs.length} paragraphs; rule S2 allows one. ` +
+        'Join them, or move the rest of the prose outside the slot.',
+    });
+    return out;
+  }
+
+  const { minWords, maxWords } = limits[slot];
+  const words = proseWordCount(paragraphs[0]);
+  if (words < minWords || words > maxWords) {
+    out.push({
+      index: first.index,
+      token: `<${tag}>`,
+      message:
+        `<${tag}> is ${words} words; rule S2 wants ${minWords}–${maxWords} ` +
+        `(rules.S2.${slot}MinWords / ${slot}MaxWords in the course settings). ` +
+        (words < minWords
+          ? `Say more about ${SUBJECT_BY_SLOT[slot]}.`
+          : 'Cut it to the connections a reader needs before the chapter list.'),
+    });
+  }
+  return out;
+}
+
+/**
+ * Check every part overview page for its S2 paragraphs. Returns one
+ * `MathGateDiagnostic` (context `'structure'`, code `part-page-paragraph`,
+ * always an error) per finding.
+ */
+export function gatePartPages(
+  pages: readonly PartPageInput[],
+  limits: NormalizedPartPages,
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const page of pages) {
+    const text = scannable(page.body);
+    const findings = [
+      ...slotFindings(page, text, 'bridge', limits),
+      ...slotFindings(page, text, 'scope', limits),
+    ];
+
+    const [bridge] = occurrencesOf(text, TAG_BY_SLOT.bridge);
+    const [scope] = occurrencesOf(text, TAG_BY_SLOT.scope);
+    if (bridge && scope && bridge.index > scope.index) {
+      findings.push({
+        index: bridge.index,
+        token: '<PartBridge>',
+        message:
+          '<PartBridge> comes after <PartScope> (rule S2). Move it first: ' +
+          'the reader needs the link from the earlier parts before this ' +
+          "part's own scope.",
+      });
+    }
+
+    for (const finding of findings.sort((a, b) => a.index - b.index)) {
+      diagnostics.push({
+        context: 'structure',
+        severity: 'error',
+        code: 'part-page-paragraph',
+        file: page.file,
+        line: lessonLine(page, finding.index),
+        token: finding.token,
+        message: finding.message,
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/gate-prose-notation.ts

@@ -3,7 +3,8 @@
  * completeness gate (`gate-math.ts`). Where that gate asks "does every glyph
  * *inside* `$…$` resolve", this one asks the complementary question: "is
  * anything that reads as math sitting *outside* `$…$` in the first place" —
- * a unit abbreviation, a division of two variable-like symbols, an escaped
+ * a unit abbreviation, a unit spelled out as a word next to a number or
+ * `per` (`unit-words.ts`), a division of two variable-like symbols, an escaped
  * absolute-value bar, a hand-typed sub/superscript. Both gates share one
  * `MathGateDiagnostic` shape and one output array (`manifest.diagnostics.math`)
  * so the CLI needs no separate wiring.
@@ -19,6 +20,7 @@
  */
 import type { MathGateDiagnostic } from './gate-math';
 import type { NotationLessonInput } from './types';
+import { findSpelledUnits } from './unit-words';
 
 interface AssessmentItemLike {
   readonly id?: string;
@@ -54,13 +56,22 @@ const JSX_TAG = /<\/?[A-Za-z][^<>]*>/g;
  * really prose" surface as N9, instead of drifting with a second copy of
  * these regexes.
  */
-export function proseOnly(body: string): string {
+/** `{/* … *\/}` — an MDX comment never renders, so its text is not prose. */
+const MDX_COMMENT = /\{\/\*[\s\S]*?\*\/\}/g;
+
+/**
+ * `keepMath` leaves `$…$` / `$$…$$` in place (everything else still blanked,
+ * offsets unchanged) — for a check that needs to see what a math span sits
+ * next to, such as `$x = 3$ meters`.
+ */
+export function proseOnly(body: string, options: { readonly keepMath?: boolean } = {}): string {
   const blank = (match: string) => match.replace(/[^\n]/g, ' ');
-  return body
+  const code = body
+    .replace(MDX_COMMENT, blank)
     .replace(CODE_FENCE, blank)
-    .replace(INLINE_CODE, (match, lead: string) => lead + blank(match.slice(lead.length)))
-    .replace(DISPLAY_MATH, blank)
-    .replace(INLINE_MATH, blank)
+    .replace(INLINE_CODE, (match, lead: string) => lead + blank(match.slice(lead.length)));
+  const math = options.keepMath ? code : code.replace(DISPLAY_MATH, blank).replace(INLINE_MATH, blank);
+  return math
     .replace(IMPORT_LINE, blank)
     .replace(KEY_REFERENCE, blank)
     .replace(JSX_TAG, blank);
@@ -122,10 +133,21 @@ const SLASH_TOKENS = /\b([A-Za-z]{1,6})\/([A-Za-z]{1,6})\b/g;
 // hand-typed sub/superscript that was never wrapped in `$…$`.
 const FAKE_SCRIPT = /[A-Za-z0-9][_^][A-Za-z0-9{]/g;
 
+/** Every N9 finding that is not a spelled-out unit. */
+const PROSE_NOTATION_CODE = 'prose-notation' as const;
+
 interface Finding {
   readonly index: number;
   readonly token: string;
   readonly message: string;
+  /** `spelled-unit` for a unit written as a word; `prose-notation` otherwise. */
+  readonly code?: 'spelled-unit';
+}
+
+/** Rule N9's settings the gate reads (`rules.N9` in the course settings). */
+export interface ProseNotationOptions {
+  /** Unit words this course lets prose spell out (`rules.N9.allow`), singular or plural. */
+  readonly allowSpelledUnits?: readonly string[];
 }
 
 function findAll(text: string, pattern: RegExp, toFinding: (m: RegExpExecArray) => Finding): Finding[] {
@@ -141,9 +163,25 @@ function findAll(text: string, pattern: RegExp, toFinding: (m: RegExpExecArray)
 
 const FIX = 'Wrap it in $…$ (or $$…$$) instead — see docs/authoring/notation.md#n9.';
 
-/** Every N9 finding in one already-prose-only string, in source order. */
-function findingsIn(text: string): Finding[] {
+/**
+ * Every N9 finding in one text: `text` is `proseOnly(raw)`, `withMath` is
+ * `proseOnly(raw, { keepMath: true })` (same offsets).
+ */
+function findingsIn(text: string, withMath: string, options: ProseNotationOptions): Finding[] {
+  const spelled = findSpelledUnits(text, withMath, options.allowSpelledUnits).map(
+    (unit): Finding => ({
+      index: unit.index,
+      token: unit.token,
+      code: 'spelled-unit',
+      message:
+        `Spelled-out unit ${JSON.stringify(unit.token)}: write it as ${unit.suggestion}. ` +
+        'A unit that quantifies something is an upright symbol inside $…$, even in flowing prose. ' +
+        'Where the sentence defines or names the unit itself, waive the block with ' +
+        '{/* explico-allow N9: reason */} — see docs/authoring/notation.md#n9.',
+    }),
+  );
   return [
+    ...spelled,
     ...findAll(text, /\\\|/g, (m) => ({
       index: m.index,
       token: m[0],
@@ -177,19 +215,25 @@ function findingsIn(text: string): Finding[] {
 
 /**
  * Scan every lesson body for plain-text math notation outside `$…$`. Returns
- * one `MathGateDiagnostic` (context `'prose'`, always an error — N9 has no
- * escape hatch) per finding.
+ * one `MathGateDiagnostic` (context `'prose'`, always an error) per finding:
+ * code `spelled-unit` for a unit written as a word ("2 meters per second
+ * squared", "30 degrees"), `prose-notation` for everything else. A place is
+ * excused with a waiver (`{/* explico-allow N9: reason *\/}`), applied by the
+ * manifest.
  */
 export function gateProseNotation(
   lessons: readonly NotationLessonInput[],
+  options: ProseNotationOptions = {},
 ): MathGateDiagnostic[] {
   const diagnostics: MathGateDiagnostic[] = [];
 
   for (const lesson of lessons) {
     const text = proseOnly(lesson.body);
-    for (const finding of findingsIn(text)) {
+    const withMath = proseOnly(lesson.body, { keepMath: true });
+    for (const finding of findingsIn(text, withMath, options)) {
       diagnostics.push({
         context: 'prose',
+        code: finding.code ?? PROSE_NOTATION_CODE,
         severity: 'error',
         file: lesson.source.file,
         line: lessonLine(lesson, finding.index),
@@ -214,6 +258,7 @@ export function gateProseNotation(
  */
 export function gateProseNotationInAssessments(
   assessments: readonly AssessmentLike[],
+  options: ProseNotationOptions = {},
 ): MathGateDiagnostic[] {
   const diagnostics: MathGateDiagnostic[] = [];
 
@@ -221,9 +266,11 @@ export function gateProseNotationInAssessments(
     for (const item of assessment.items ?? []) {
       for (const field of [item.prompt, item.explanation]) {
         if (typeof field !== 'string') continue;
-        for (const finding of findingsIn(proseOnly(field))) {
+        const withMath = proseOnly(field, { keepMath: true });
+        for (const finding of findingsIn(proseOnly(field), withMath, options)) {
           diagnostics.push({
             context: 'prose',
+            code: finding.code ?? PROSE_NOTATION_CODE,
             severity: 'error',
             file: `${assessment.id} (${item.id ?? '?'})`,
             token: finding.token,

package/src/reference/katex-delimiters.mjs

@@ -32,8 +32,6 @@
  * increase. A course therefore either renders with engine-sized delimiters or
  * fails its build saying so — it cannot quietly get the stock behaviour.
  */
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import katex from 'katex';
 
 /** TeX's `\delimitershortfall`, in points, as KaTeX hard-codes it. */
@@ -78,12 +76,21 @@ export function rewriteBundle(source) {
 }
 
 async function loadGrownKatex() {
+  // Imported here, not at the top: should a browser graph ever reach this
+  // module (a lab island once did, through `render-lab-math.ts`; islands now
+  // import `lab-math-slot.ts`), Vite's `node:fs` stub throws on first access —
+  // which, for a static named import, is module evaluation itself, so the
+  // island would never hydrate.
+  const { readFileSync } = await import('node:fs');
+  const { createRequire } = await import('node:module');
   const require = createRequire(import.meta.url);
   const source = readFileSync(require.resolve('katex/dist/katex.mjs'), 'utf8');
   // The bundle is self-contained, so it can be re-imported from a data URL
-  // with no base to resolve relative specifiers against.
+  // with no base to resolve relative specifiers against. The URL is built at
+  // run time on purpose, so Vite has nothing to analyze here.
   const rewritten = rewriteBundle(source);
   const module = await import(
+    /* @vite-ignore */
     `data:text/javascript;base64,${Buffer.from(rewritten).toString('base64')}`
   );
   return module.default;
@@ -116,10 +123,16 @@ export function assertDelimiterGrowth(instance = katex) {
   }
 }
 
-const grown = await loadGrownKatex();
-for (const name of RENDER_EXPORTS) {
-  if (typeof grown[name] === 'function') katex[name] = grown[name];
+// Build and server rendering only. In a browser there is no KaTeX bundle on
+// disk to rewrite. No client graph should include this module (lab math is
+// rendered on the server); if one does, a client-side render falls back to
+// stock sizing rather than breaking the island.
+if (typeof window === 'undefined') {
+  const grown = await loadGrownKatex();
+  for (const name of RENDER_EXPORTS) {
+    if (typeof grown[name] === 'function') katex[name] = grown[name];
+  }
+  assertDelimiterGrowth();
 }
-assertDelimiterGrowth();
 
 export default katex;

package/src/reference/keyed-float-validate.ts

@@ -8,11 +8,18 @@
  * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
  *   `[[slug#<prefix>-key]]` points at the matching keyed float with that `id`.
  * - `<prefix>-key-unused` (info): a keyed float is never referenced.
+ * - `<prefix>-removed-prop` (error): the tag sets a prop that no longer
+ *   exists. Mostly a name prop (`<Figure title>`, `<Diagram label>`) — every
+ *   float is named by the one caption pair, `caption` (long) and `short`
+ *   (optional), and a removed prop would otherwise render nothing and escape
+ *   rule S1 — and a diagram's compaction props (`defaultOpen`,
+ *   `rememberState`), since a diagram no longer folds by itself.
  *
- * `tables-validate.ts`, `figures-validate.ts`, and `diagrams-validate.ts` are
- * thin wrappers over this so callers import a kind-specific validator with
- * narrow diagnostic-code types, while `equations-validate.ts` stays untouched
- * — equations predate this and keep their own dedicated path.
+ * `tables-validate.ts`, `figures-validate.ts`, `diagrams-validate.ts` and
+ * `examples-validate.ts` (`<CompactExamples>`, which adds its required-prop
+ * check) are thin wrappers over this so callers import a kind-specific
+ * validator with narrow diagnostic-code types, while `equations-validate.ts`
+ * stays untouched — equations predate this and keep their own dedicated path.
  */
 
 import {
@@ -28,11 +35,20 @@ export interface KeyedFloatKind {
   readonly prefix: string;
   /** Lowercase noun used in diagnostic messages, e.g. `table` or `figure`. */
   readonly noun: string;
+  /**
+   * Name props this kind no longer takes, each with the fix its diagnostic
+   * gives, e.g. `{ title: 'use \`caption\` …' }`. Omitted: none.
+   */
+  readonly removedProps?: Readonly<Record<string, string>>;
 }
 
 export interface KeyedFloatLabelRecord {
   readonly key: string;
   readonly number: string;
+  /** The float's literal `short` caption, when it has one. */
+  readonly short?: string;
+  /** The float's literal `caption`; absent when it is an expression. */
+  readonly caption?: string;
   readonly lessonId: string;
   readonly slug: string;
   readonly section: number;
@@ -69,13 +85,14 @@ export interface KeyedFloatLessonInput {
   readonly file: string;
   readonly body: string;
   /**
-   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
-   * and how many floats of this kind earlier lessons of that part already used.
-   * When set, floats are numbered `‹part›.‹offset + n›`; when omitted, the
-   * legacy `##`-section scheme. Each kind counts on its own, so the caller
-   * passes a different `offset` for `<Table>` than for `<Figure>`.
+   * `{ prefix, offset }` — the lesson's float-number prefix (`‹part›.‹chapter›`,
+   * or `‹part›` under `numbering.floats: "part"`) and how many floats of this
+   * kind precede the lesson in that scope. When set, floats are numbered
+   * `‹prefix›.‹offset + n›`; when omitted, the legacy `##`-section scheme.
+   * Each kind counts on its own, so the caller passes a different `offset`
+   * for `<Table>` than for `<Figure>`.
    */
-  readonly numbering?: { readonly prefix: number; readonly offset: number };
+  readonly numbering?: { readonly prefix: number | string; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -108,7 +125,7 @@ export function validateKeyedFloats(
   lessons: readonly KeyedFloatLessonInput[],
   kind: KeyedFloatKind,
 ): KeyedFloatValidation {
-  const { tagName, prefix, noun } = kind;
+  const { tagName, prefix, noun, removedProps = {} } = kind;
   const labels: KeyedFloatLabelRecord[] = [];
   const diagnostics: KeyedFloatDiagnostic[] = [];
   const numbersBySlug: Record<string, Record<string, string>> = {};
@@ -124,9 +141,24 @@ export function validateKeyedFloats(
     }) as {
       key: string | null;
       number: string;
+      short: string | null;
+      caption: string | null;
+      props: string[];
       section: number;
       indexInSection: number;
     }[]) {
+      for (const prop of raw.props) {
+        const fix = removedProps[prop];
+        if (fix === undefined) continue;
+        diagnostics.push({
+          code: `${prefix}-removed-prop`,
+          severity: 'error',
+          message: `${lesson.lessonId} has a <${tagName} ${prop}="…">${raw.key ? ` (id="${raw.key}")` : ''}, but <${tagName}> has no \`${prop}\` prop: ${fix}`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          ...(raw.key ? { key: raw.key } : {}),
+        });
+      }
       if (raw.key == null) continue;
       if (!KEYED_FLOAT_KEY_PATTERN.test(raw.key)) {
         diagnostics.push({
@@ -155,6 +187,8 @@ export function validateKeyedFloats(
       labels.push({
         key: raw.key,
         number: raw.number,
+        ...(raw.short ? { short: raw.short } : {}),
+        ...(raw.caption ? { caption: raw.caption } : {}),
         lessonId: lesson.lessonId,
         slug: lesson.slug,
         section: raw.section,