explico 0.7.0 → 0.11.0

package/src/reference/equations.mjs

@@ -4,23 +4,24 @@
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
  * from appearance order. When the caller supplies `numbering`
  * (`{ prefix, offset }` — see `resolveNumbering`), the number is
- * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
- * groups, `n` counts every display equation in the lesson, and `offset` carries
- * the count from earlier lessons of the same part so the sequence runs
- * continuously across a part rather than restarting on every page. `##` and
- * `###` headings never affect it — `(2.4)` is the fourth display equation of
- * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
- * the level names. With no `numbering` the number falls back to the
- * `##`-section scheme `‹section›.‹indexInSection›` (used by hand-built test
- * trees and non-lesson pages). An author additionally
+ * `‹prefix›.‹offset + n›`: `n` counts every display equation in the lesson,
+ * and the course's `numbering.floats` scope decides the rest — `chapter` (the
+ * default) makes the prefix `‹part›.‹chapter›` with no offset, so `(2.2.4)` is
+ * the fourth display equation of part 2's second chapter; `part` makes it the
+ * part's ordinal alone, with `offset` carrying the count from earlier lessons
+ * of the part so the sequence runs on across it. `##` and `###` headings never
+ * affect it. See `docs/authoring/structure.md` for the level names. With no
+ * `numbering` the number falls back to the `##`-section scheme
+ * `‹section›.‹indexInSection›` (used by hand-built test trees and non-lesson
+ * pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:
  *
- *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
+ *   [[eq-discount-factor-def]]           same page  → "(2.2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
- * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * An unkeyed equation still gets a positional anchor (`#eq-2-2-4`) so it can be
  * deep-linked, but only a keyed equation is referenceable by name.
  *
  * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
@@ -37,6 +38,28 @@ export const EQ_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export const EQ_LABEL_PATTERN =
   /\\label\{\s*eq:([a-z0-9]+(?:-[a-z0-9]+)*)\s*\}/g;
 
+/**
+ * A `\caption{<short caption>}` anywhere in a math source — the equation's
+ * short caption, plain text with no nested braces. Global; the text in group
+ * 1. An equation takes only a short caption: it names the equation in the
+ * `[[eq-…]]` preview card and in the "Copy LaTeX — ‹caption›" tooltip, and is
+ * stripped before KaTeX exactly like `\label{}`.
+ */
+export const EQ_CAPTION_PATTERN = /\\caption\{([^{}]*)\}/g;
+
+/**
+ * The short caption a display equation carries, trimmed, or `null` when it
+ * has none. Only the first `\caption{}` counts; `remark-notation.mjs` fails a
+ * page that gives one equation two, or an empty one.
+ */
+export function equationCaption(latex) {
+  EQ_CAPTION_PATTERN.lastIndex = 0;
+  const match = EQ_CAPTION_PATTERN.exec(String(latex ?? ''));
+  EQ_CAPTION_PATTERN.lastIndex = 0;
+  const text = match?.[1]?.replace(/\s+/g, ' ').trim();
+  return text ? text : null;
+}
+
 /**
  * A `[[ … ]]` payload that targets an equation: `eq-<key>` on the current page,
  * or `<lesson-slug>#eq-<key>` across pages. `lesson` (group 1) is a `/`-slug.
@@ -52,10 +75,14 @@ export function parseEquationRef(raw) {
   return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
 }
 
-/** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
+/**
+ * Remove every `\label{eq:…}` and `\caption{…}` (and the whitespace they
+ * leave) from a math source: both are identity markers, not math KaTeX parses.
+ */
 export function stripEquationLabels(latex) {
   return String(latex)
     .replace(EQ_LABEL_PATTERN, '')
+    .replace(EQ_CAPTION_PATTERN, '')
     .replace(/[ \t]+\n/g, '\n')
     .replace(/\n{3,}/g, '\n\n')
     .replace(/[ \t]{2,}/g, ' ')
@@ -70,13 +97,14 @@ function equationNumber(section, index) {
 /**
  * Normalise the numbering input to `{ prefix, offset }`.
  *
- * `prefix` is the number before the dot — the **part**'s ordinal (its position
- * among the sidebar groups). `offset` is how many display equations already
- * appeared in earlier lessons of that same part, so `n` runs continuously
- * across a part instead of restarting on every page. A bare number is the
- * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
- * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
- * `##`-section fallback for non-lesson pages.
+ * `prefix` is everything before the last dot — `‹part›.‹chapter›` under the
+ * default `numbering.floats: "chapter"`, the part's ordinal under `"part"`.
+ * `offset` is how many items of the kind precede the lesson in that scope: 0
+ * for a chapter, the earlier chapters' count for a part, so `n` runs on
+ * across it. A bare number is the legacy per-lesson form (`prefix = n`,
+ * `offset = 0`) and is still accepted so hand-built trees and unit tests keep
+ * working. `undefined`/`null`/`0`/`''` ⇒ the `##`-section fallback for
+ * non-lesson pages.
  */
 export function resolveNumbering(input) {
   if (input == null) return { prefix: undefined, offset: 0 };
@@ -90,9 +118,9 @@ export function resolveNumbering(input) {
 }
 
 /**
- * The visible number for one display equation. With a `prefix` (the part's
- * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
- * are ignored; without it, the legacy `##`-section scheme.
+ * The visible number for one display equation. With a `prefix` the scheme is
+ * `‹prefix›.‹offset + indexInLesson›` and `##` headings are ignored; without
+ * it, the legacy `##`-section scheme.
  */
 export function displayEquationNumber({
   prefix,
@@ -106,7 +134,13 @@ export function displayEquationNumber({
     : `${prefix}.${offset + indexInLesson}`;
 }
 
-/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+/**
+ * A display equation's anchor id: `eq-<key>` when it carries a
+ * `\label{eq:…}`, else the positional form, e.g. `2.4` → `eq-2-4`.
+ *
+ * @param {{ key?: string, number?: string | number }} equation - `number` is
+ *   read only when there is no `key`, so a keyed caller may omit it.
+ */
 export function equationAnchorId({ key, number }) {
   return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
 }
@@ -130,10 +164,8 @@ export function stripFencedCode(markdown) {
  * 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
+ * tags and exposes their body to the later blanking pass. The
+ * {@link TRANSPARENT_COMPONENTS} are the intentional uses. Section headings in
  * a transparent body do not change the surrounding page's section counter.
  */
 export function stripJsxComponents(markdown, keep, transparent = []) {
@@ -163,23 +195,35 @@ export function stripJsxComponents(markdown, keep, transparent = []) {
   );
 }
 
+/**
+ * The components whose bodies stay in the lesson's reading order: `<Memo>`,
+ * `<ShortNote>` and `<Fold>`. Unlike a worked-example/presentation wrapper,
+ * their bodies are details or folded stretches of the lesson itself, so a
+ * numbered equation or float in one stays in the official sequence. Every
+ * scan and tree walk that numbers equations or floats reads this list.
+ */
+export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold']);
+
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
- * with its assigned number. `$$…$$` blocks only. With `numbering`
- * (`{ prefix, offset }`, the part's ordinal and the count of display equations
- * in earlier lessons of that part) the number is `‹part›.‹offset + n›`, `n`
- * sequential over every display block in the lesson; without it, `##` headings
- * advance a section counter and the number is `‹section›.‹indexInSection›`.
+ * with its assigned number and its `\caption{}` short caption (`short`, or
+ * `null`). `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the lesson's float-number prefix and the count of
+ * display equations before it in that scope) the number is
+ * `‹prefix›.‹offset + n›`, `n` sequential over every display block in the
+ * lesson; without it, `##` headings advance a section counter and the number
+ * is `‹section›.‹indexInSection›`.
  * Either way every display block advances the index, so a keyed equation's
  * number reflects its position among *all* display equations, not only the
  * keyed ones.
  */
 export function scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown), undefined, [
-    'Memo',
-    'ShortNote',
-  ]);
+  const text = stripJsxComponents(
+    stripFencedCode(markdown),
+    undefined,
+    TRANSPARENT_COMPONENTS,
+  );
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -193,6 +237,7 @@ export function scanDisplayEquations(markdown, numbering) {
       kind: 'equation',
       index: match.index,
       key: label ? label[1] : null,
+      short: equationCaption(match[1]),
     });
   }
   tokens.sort((a, b) => a.index - b.index);
@@ -218,6 +263,7 @@ export function scanDisplayEquations(markdown, numbering) {
         indexInSection,
         indexInLesson,
       }),
+      short: token.short,
       section,
       indexInSection,
     });
@@ -255,11 +301,11 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // 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.
+  // Top-level blocks plus the bodies of the `TRANSPARENT_COMPONENTS`: other
+  // MDX components (a `<CompactExample>` worked example, an `<Aside>`) remain
+  // illustrative and outside the lesson's official equation sequence. The
+  // transparent ones 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') {
@@ -269,6 +315,7 @@ export function collectDisplayEquations(tree, numbering) {
       const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
       equations.push({
         key: label ? label[1] : null,
+        short: equationCaption(node.value),
         number: displayEquationNumber({
           prefix,
           offset,
@@ -284,8 +331,7 @@ export function collectDisplayEquations(tree, numbering) {
     }
     if (
       node.type === 'mdxJsxFlowElement' &&
-      node.name !== 'Memo' &&
-      node.name !== 'ShortNote'
+      !TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       return;
     }
@@ -304,7 +350,7 @@ export function collectDisplayEquations(tree, numbering) {
     if (node.type === 'math') collectFromDetail(node);
     else if (
       node.type === 'mdxJsxFlowElement' &&
-      (node.name === 'Memo' || node.name === 'ShortNote')
+      TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       collectFromDetail(node);
     }

package/src/reference/examples-validate.ts

@@ -0,0 +1,97 @@
+/**
+ * `validateKeyedFloats` for `<CompactExamples>` — see
+ * `keyed-float-validate.ts`. A worked-example set is a numbered kind of its
+ * own, like a knowledge check (docs/plans/titles-and-containers.md Part 6,
+ * Q11): `Example ‹prefix›.‹n›`, anchored `#ex-‹id›`, cited with `[[ex-‹id›]]`.
+ *
+ * On top of the shared checks, both of the set's names are required
+ * (`ex-missing-prop`): the `id` its anchor and references need, and the
+ * `short` title its heading shows after the engine's "Example" badge. There is
+ * no default title to fall back on.
+ */
+
+import {
+  validateKeyedFloats,
+  type KeyedFloatLabelRecord,
+  type KeyedFloatLessonInput,
+  type KeyedFloatValidation,
+} from './keyed-float-validate';
+import { scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
+
+export type ExampleDiagnosticCode =
+  | 'ex-invalid-key'
+  | 'ex-duplicate-key'
+  | 'ex-ref-resolves'
+  | 'ex-key-unused'
+  | 'ex-removed-prop'
+  | 'ex-missing-prop';
+
+export interface ExampleDiagnostic {
+  readonly code: ExampleDiagnosticCode;
+  readonly severity: 'error' | 'warning' | 'info';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export type ExampleLabelRecord = KeyedFloatLabelRecord;
+export type ExampleLessonInput = KeyedFloatLessonInput;
+
+export interface ExampleValidation extends KeyedFloatValidation {
+  readonly diagnostics: readonly ExampleDiagnostic[];
+}
+
+/** The props a set cannot do without, each with the fix its diagnostic gives. */
+const REQUIRED_PROPS: Readonly<Record<string, string>> = {
+  id: 'give it an `id` (lowercase letters, digits and hyphens): the set is anchored `#ex-‹id›` and cited with `[[ex-‹id›]]`.',
+  short:
+    'give it a `short` title naming the topic, e.g. "Converting between coordinate systems"; the engine draws "Example" and the number before it.',
+};
+
+export function validateExamples(
+  lessons: readonly ExampleLessonInput[],
+): ExampleValidation {
+  const shared = validateKeyedFloats(lessons, {
+    tagName: 'CompactExamples',
+    prefix: 'ex',
+    noun: 'worked-example set',
+    removedProps: {
+      summary:
+        'rename it `short`: the set’s topical title, shown after the engine’s "Example" badge.',
+    },
+  });
+
+  const missing: ExampleDiagnostic[] = [];
+  for (const lesson of lessons) {
+    const sets = scanKeyedJsxFloats(lesson.body, {
+      tagName: 'CompactExamples',
+      numbering: lesson.numbering,
+    }) as { key: string | null; props: string[] }[];
+    for (const set of sets) {
+      for (const [prop, fix] of Object.entries(REQUIRED_PROPS)) {
+        if (set.props.includes(prop)) continue;
+        missing.push({
+          code: 'ex-missing-prop',
+          severity: 'error',
+          message: `${lesson.lessonId} has a <CompactExamples>${set.key ? ` (id="${set.key}")` : ''} with no \`${prop}\`: ${fix}`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          ...(set.key ? { key: set.key } : {}),
+        });
+      }
+    }
+  }
+
+  const diagnostics = [
+    ...(shared.diagnostics as readonly ExampleDiagnostic[]),
+    ...missing,
+  ].sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) ||
+      (a.lessonId ?? '').localeCompare(b.lessonId ?? '') ||
+      (a.key ?? '').localeCompare(b.key ?? '') ||
+      a.message.localeCompare(b.message),
+  );
+  return { ...shared, diagnostics };
+}

package/src/reference/figures-validate.ts

@@ -11,7 +11,8 @@ export type FigureDiagnosticCode =
   | 'fig-invalid-key'
   | 'fig-duplicate-key'
   | 'fig-ref-resolves'
-  | 'fig-key-unused';
+  | 'fig-key-unused'
+  | 'fig-removed-prop';
 
 export interface FigureDiagnostic {
   readonly code: FigureDiagnosticCode;
@@ -36,5 +37,9 @@ export function validateFigures(
     tagName: 'Figure',
     prefix: 'fig',
     noun: 'figure',
+    removedProps: {
+      title:
+        'a figure is named by its `caption` (the long caption, shown below it with its number) and an optional `short` caption; move a short title to `short`.',
+    },
   }) as FigureValidation;
 }

package/src/reference/folds-validate.ts

@@ -0,0 +1,65 @@
+/**
+ * `<Fold>` validation, run inside `compileManifest()`
+ * (docs/plans/figures-and-short-captions.md, decision 11). A fold's bar is
+ * its `label` or, without one, the numbers and short captions of the floats
+ * it holds (`../components/float-name.ts`), so a fold needs one or the other:
+ *
+ * - `fold-unnamed` (error): a `<Fold>` with no `label` and no `<Figure>`,
+ *   `<Table>` or `<Diagram>` that takes a number inside it — its bar would
+ *   have nothing to show.
+ *
+ * `Fold.astro` throws on the same fold when it renders; this reports it
+ * earlier, at `validate:content`, with the lesson it is in. A float that a
+ * wrapper component renders counts when the lesson writes it under a float's
+ * tag name (`<Diagram id="…" />` for a wrapper imported as `Diagram`), the
+ * way the numbering scan sees it.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
+import type { KeyedFloatLessonInput } from './keyed-float-validate';
+
+export type FoldDiagnosticCode = 'fold-unnamed';
+
+export interface FoldDiagnostic {
+  readonly code: FoldDiagnosticCode;
+  readonly severity: 'error';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+}
+
+export interface FoldValidation {
+  readonly diagnostics: readonly FoldDiagnostic[];
+}
+
+const ATTRIBUTES = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const FOLD = new RegExp(`<Fold\\b(${ATTRIBUTES})>([\\s\\S]*?)<\\/Fold\\s*>`, 'g');
+const NUMBERED_FLOATS = ['Figure', 'Table', 'Diagram'] as const;
+
+export function validateFolds(
+  lessons: readonly KeyedFloatLessonInput[],
+): FoldValidation {
+  const diagnostics: FoldDiagnostic[] = [];
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    for (const [, attributes = '', body = ''] of stripFencedCode(lesson.body).matchAll(
+      FOLD,
+    )) {
+      if (/(?:^|\s)label\s*=/.test(attributes)) continue;
+      const named = NUMBERED_FLOATS.some(
+        (tagName) => scanKeyedJsxFloats(body, { tagName, numbering: undefined }).length > 0,
+      );
+      if (named) continue;
+      diagnostics.push({
+        code: 'fold-unnamed',
+        severity: 'error',
+        message: `${lesson.lessonId} has a <Fold> with no \`label\` and no numbered <Figure>, <Table> or <Diagram> inside it, so its bar has nothing to name it by: give it a \`label\`, or fold a numbered float with it.`,
+        file: lesson.file,
+        lessonId: lesson.lessonId,
+      });
+    }
+  }
+  return { diagnostics };
+}

package/src/reference/gate-abbreviations.ts

@@ -25,7 +25,7 @@ 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 { lessonLine, proseOnly } from './gate-prose-notation';
 import type {
   AbbreviationDefinitionInput,
   NotationRegistryInput,
@@ -115,9 +115,10 @@ export function gateAbbreviations(input: {
       reported.add(token);
       diagnostics.push({
         context: 'abbreviation',
+        code: 'abbreviation-unexplained',
         severity: 'error',
         file: lesson.source.file,
-        line: lineOf(lesson.body, index),
+        line: lessonLine(lesson, index),
         token,
         message: `Unexplained abbreviation ${JSON.stringify(token)} outside math. ${FIX}`,
       });

package/src/reference/gate-course-rules.ts

@@ -0,0 +1,134 @@
+/**
+ * The gate for a course's own rules (`courseRules` in `course.settings.json`,
+ * resolved by `src/rules/course-rules.ts`).
+ *
+ * One loop over every enabled course rule's `forbid` patterns, matched against
+ * the same "is this really prose" surface rule N9 uses — `proseOnly` blanks
+ * code fences, inline code, `$…$` / `$$…$$`, `[[key]]` references, `import`
+ * lines, JSX tags and MDX comments to spaces, so offsets still point at the
+ * source. A match becomes a `MathGateDiagnostic` with the rule's own ID as its
+ * code and a lesson `file` + `line`, which is what lets `{/* explico-allow X1:
+ * reason *\/}` waive one place.
+ *
+ * Nothing here knows what a rule *means*: the patterns come from the course,
+ * already validated (they compile, and none matches the empty string). The
+ * three scopes are the three units an author can reason about — a paragraph, a
+ * whole lesson's prose, a heading.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import { lessonLine, proseOnly } from './gate-prose-notation';
+import type { NotationLessonInput } from './types';
+import type { CourseRule, CourseRulePattern } from '../rules/course-rules';
+
+/** A stretch of text to match, with its offset in the (blanked) body. */
+interface Unit {
+  readonly text: string;
+  readonly index: number;
+}
+
+const HEADING = /^[ \t]{0,3}(#{1,6})[ \t]+(.*)$/;
+
+/**
+ * Consecutive non-blank lines, as one unit each, right-trimmed so `$` means
+ * "end of the paragraph" — a paragraph whose last visible thing is math or a
+ * JSX tag ends in the spaces `proseOnly` left behind, and the author means the
+ * prose before it.
+ */
+function paragraphs(text: string): Unit[] {
+  const units: Unit[] = [];
+  let index = 0;
+  let start = -1;
+  const lines = text.split('\n');
+  lines.forEach((line, i) => {
+    const blank = line.trim() === '';
+    if (!blank && start === -1) start = index;
+    if ((blank || i === lines.length - 1) && start !== -1) {
+      const end = blank ? index : index + line.length;
+      units.push({ text: text.slice(start, end).replace(/\s+$/, ''), index: start });
+      start = -1;
+    }
+    index += line.length + 1;
+  });
+  return units.filter((unit) => unit.text !== '');
+}
+
+/** The text of each Markdown heading, without its `#`s. */
+function headings(text: string): Unit[] {
+  const units: Unit[] = [];
+  let index = 0;
+  for (const line of text.split('\n')) {
+    const match = HEADING.exec(line);
+    if (match !== null) {
+      const body = match[2]!.replace(/\s+#*\s*$/, '');
+      if (body !== '') {
+        units.push({ text: body, index: index + line.indexOf(body) });
+      }
+    }
+    index += line.length + 1;
+  }
+  return units;
+}
+
+function unitsFor(scope: CourseRulePattern['scope'], prose: string): Unit[] {
+  switch (scope) {
+    case 'prose':
+      return [{ text: prose, index: 0 }];
+    case 'heading':
+      return headings(prose);
+    case 'paragraph':
+      return paragraphs(prose);
+  }
+}
+
+/** Every match of `pattern` in `unit`, as `[offset in the body, matched text]`. */
+function* matches(pattern: CourseRulePattern, unit: Unit): Generator<[number, string]> {
+  const regex = new RegExp(pattern.pattern, `${pattern.flags}g`);
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(unit.text)) !== null) {
+    yield [unit.index + match.index, match[0]];
+    // A zero-length match cannot happen (the pattern is rejected at resolve
+    // time if it matches the empty string), but a group could still make one.
+    if (match.index === regex.lastIndex) regex.lastIndex += 1;
+  }
+}
+
+/**
+ * Scan every lesson body for what the course's own rules forbid. Only enabled
+ * rules with at least one pattern do anything; a guide rule is not this gate's
+ * business. Findings carry the rule ID as `code`, so `ownerOf` / `ruleIdOf`
+ * name the rule and a waiver can target it.
+ */
+export function gateCourseRules(
+  lessons: readonly NotationLessonInput[],
+  rules: readonly CourseRule[],
+): MathGateDiagnostic[] {
+  const active = rules.filter((rule) => rule.enabled && rule.forbid.length > 0);
+  if (active.length === 0) return [];
+
+  const diagnostics: MathGateDiagnostic[] = [];
+  for (const lesson of lessons) {
+    const prose = proseOnly(lesson.body);
+    const cache = new Map<CourseRulePattern['scope'], Unit[]>();
+    for (const rule of active) {
+      for (const pattern of rule.forbid) {
+        if (!cache.has(pattern.scope)) cache.set(pattern.scope, unitsFor(pattern.scope, prose));
+        for (const unit of cache.get(pattern.scope)!) {
+          for (const [index, token] of matches(pattern, unit)) {
+            diagnostics.push({
+              context: 'course',
+              code: rule.id,
+              severity: rule.severity,
+              file: lesson.source.file,
+              line: lessonLine(lesson, index),
+              // The matched text, trimmed — unless the pattern deliberately
+              // matched whitespace, in which case there is nothing else to show.
+              token: token.trim() || token,
+              message: `${pattern.message} (course rule ${rule.id})`,
+            });
+          }
+        }
+      }
+    }
+  }
+  return diagnostics;
+}