explico 0.13.0 → 0.14.0

package/src/reference/figure-symbols.ts

@@ -11,13 +11,22 @@
  * `figure.keyed-figure` (a lab's tools included), every letter KaTeX draws
  * must sit in a `[data-notation-key]`. Upright text is not a symbol:
  * `\text{…}`, `\mathrm{…}` (the resolver skips its body, rule N10) and a
- * named operator (`\sin`, `\max`). `compiler/astro.ts` runs it on every
- * built page, and a course's browser test can run it on a hydrated figure's
- * `outerHTML`, which also holds what an island draws only in the browser.
+ * named operator (`\sin`, `\max`). Nor is a plain base-library atom (`d`,
+ * `e`, `i`, `\pi`; `base-library.mjs`), which the resolver leaves without a
+ * card in lab math as in a lesson's, because every reader knows it — in a
+ * power too (`e^{i\pi}`). A styled one (`\mathbf{e}`), a decorated one
+ * (`\hat{e}`, rule N22) and an index (`x_i`, `e_i`, rule N23) are other
+ * symbols and still need a card; a subscript is told from a power by
+ * KaTeX's `vlist-t2`, the vertical list that has a lowered row.
+ * `compiler/astro.ts` runs it on every built page, and a course's browser
+ * test can run it on a hydrated figure's `outerHTML`, which also holds what
+ * an island draws only in the browser.
  */
 
 import { parse, type DefaultTreeAdapterMap } from 'parse5';
 
+import { isBaseLibraryGlyph } from './base-library.mjs';
+
 type HtmlNode = DefaultTreeAdapterMap['node'];
 type HtmlElement = DefaultTreeAdapterMap['element'];
 
@@ -30,6 +39,10 @@ export interface UnboundFigureSymbols {
 
 /** KaTeX classes of upright text, which is never a symbol. */
 const UPRIGHT = new Set(['text', 'mathrm', 'textrm', 'mop']);
+/** KaTeX classes of a letter in its plain italic form, `\mathit{e}` included. */
+const PLAIN = new Set(['mathnormal', 'mathit']);
+/** KaTeX class of an accent: the letter under it is not the plain atom. */
+const DECORATED = new Set(['accent']);
 const LETTER = /\p{L}/u;
 
 function isElement(node: HtmlNode): node is HtmlElement {
@@ -59,59 +72,123 @@ export function unboundFigureSymbols(html: string): UnboundFigureSymbols[] {
   if (!html.includes('keyed-figure') || !html.includes('katex-html')) return [];
   const found = new Map<string, string[]>();
 
-  const visit = (
-    node: HtmlNode,
-    figure: string | undefined,
-    inKatex: boolean,
-    covered: boolean,
-  ): void => {
+  interface Context {
+    readonly figure: string | undefined;
+    readonly inKatex: boolean;
+    readonly covered: boolean;
+    /** Under an accent or in a subscript: not the plain atom. */
+    readonly decorated: boolean;
+    /** The element that holds this text draws it in plain italic. */
+    readonly plain: boolean;
+    /** In an `msupsub` with a subscript (`vlist-t2`), whose first row it is. */
+    readonly lowered: boolean;
+  }
+
+  const visit = (node: HtmlNode, context: Context, row?: number): void => {
+    let next = context;
     if (isElement(node)) {
       const names = classes(node);
+      next = {
+        ...context,
+        // A letter's own element says how it is drawn; its ancestors do not.
+        plain: names.some((name) => PLAIN.has(name)),
+        // Only the rows of a script's own vertical list are its sub and sup.
+        lowered: names.includes('msupsub')
+          ? childrenOf(node).some((child) => isElement(child) && classes(child).includes('vlist-t2'))
+          : row === undefined
+            ? context.lowered
+            : false,
+      };
       if (node.tagName === 'figure' && names.includes('keyed-figure')) {
-        figure = attribute(node, 'id') ?? '(a figure with no id)';
+        next = { ...next, figure: attribute(node, 'id') ?? '(a figure with no id)' };
+      }
+      if (names.includes('katex-html')) next = { ...next, inKatex: true };
+      if (names.some((name) => DECORATED.has(name)) || (row === 0 && context.lowered)) {
+        next = { ...next, decorated: true };
       }
-      if (names.includes('katex-html')) inKatex = true;
       if (
         attribute(node, 'data-notation-key') !== undefined ||
-        (inKatex && names.some((name) => UPRIGHT.has(name)))
+        (next.inKatex && names.some((name) => UPRIGHT.has(name)))
       ) {
-        covered = true;
+        next = { ...next, covered: true };
       }
     } else if (
       node.nodeName === '#text' &&
-      figure !== undefined &&
-      inKatex &&
-      !covered
+      context.figure !== undefined &&
+      context.inKatex &&
+      !context.covered
     ) {
       const text = (node as DefaultTreeAdapterMap['textNode']).value.trim();
-      if (LETTER.test(text)) {
-        const symbols = found.get(figure) ?? [];
+      // KaTeX draws a run of plain letters as one text node (`iπ` of `e^{i\pi}`).
+      const library =
+        context.plain &&
+        !context.decorated &&
+        [...text].every((glyph) => !LETTER.test(glyph) || isBaseLibraryGlyph(glyph));
+      if (LETTER.test(text) && !library) {
+        const symbols = found.get(context.figure) ?? [];
         if (!symbols.includes(text)) symbols.push(text);
-        found.set(figure, symbols);
+        found.set(context.figure, symbols);
       }
     }
-    for (const child of childrenOf(node)) visit(child, figure, inKatex, covered);
+    // The rows of a `vlist` are its element children; the first of a lowered
+    // one is the subscript, the second a superscript over it.
+    const isVlist = isElement(node) && classes(node).includes('vlist');
+    let rows = 0;
+    for (const child of childrenOf(node)) {
+      const isRow = isVlist && isElement(child);
+      visit(child, next, isRow ? rows : undefined);
+      if (isRow) rows += 1;
+    }
   };
 
-  visit(parse(html), undefined, false, false);
+  visit(parse(html), {
+    figure: undefined,
+    inKatex: false,
+    covered: false,
+    decorated: false,
+    plain: false,
+    lowered: false,
+  });
   return [...found].map(([figure, symbols]) => ({ figure, symbols }));
 }
 
+/** One rendered page and the figures on it that draw a symbol with no card. */
+export interface PageUnboundFigureSymbols {
+  /** The page's path in the build output, e.g. `lecture-5/chernoff/index.html`. */
+  readonly page: string;
+  readonly figures: readonly UnboundFigureSymbols[];
+}
+
+const describeFigures = (figures: readonly UnboundFigureSymbols[]): string =>
+  figures
+    .map(({ figure, symbols }) => `#${figure} shows ${symbols.map((s) => `"${s}"`).join(', ')}`)
+    .join('; ');
+
 /**
- * Fail a build whose rendered page shows a symbol in a figure that opens no
- * card, naming the figure, the symbols, and the way to bind them.
+ * Fail a build over the pages that show a symbol in a figure that opens no
+ * card, naming every page, its figures and symbols, and the way to bind them.
+ * A build collects the whole list first (`compiler/astro.ts`), so it reports
+ * every page at once instead of one per run.
  */
-export function assertFigureSymbolsBound(page: string, html: string): void {
-  const unbound = unboundFigureSymbols(html);
-  if (unbound.length === 0) return;
+export function assertNoUnboundFigureSymbols(pages: readonly PageUnboundFigureSymbols[]): void {
+  const found = pages.filter(({ figures }) => figures.length > 0);
+  const [only] = found;
+  if (!only) return;
+  const head =
+    found.length === 1
+      ? `Explico figure symbols without a notation card on rendered page "${only.page}": ` +
+        describeFigures(only.figures)
+      : `Explico figure symbols without a notation card on ${found.length} rendered pages:\n` +
+        found.map(({ page, figures }) => `  "${page}": ${describeFigures(figures)}`).join('\n');
   throw new Error(
-    `Explico figure symbols without a notation card on rendered page "${page}": ` +
-      unbound
-        .map(({ figure, symbols }) => `#${figure} shows ${symbols.map((s) => `"${s}"`).join(', ')}`)
-        .join('; ') +
-      '. Every symbol a figure shows opens its card (rule N4): render its math ' +
+    `${head}. Every symbol a figure shows opens its card (rule N4): render its math ` +
       'with renderLabMath (`{ display: false }` for a legend, an axis title or ' +
       'a label; a `{ math }` run for the caption clause), never with katex ' +
       'directly. Write a unit as `\\text{…}`.',
   );
 }
+
+/** Fail a build whose rendered page shows a symbol in a figure that opens no card. */
+export function assertFigureSymbolsBound(page: string, html: string): void {
+  assertNoUnboundFigureSymbols([{ page, figures: unboundFigureSymbols(html) }]);
+}

package/src/reference/folds-validate.ts

@@ -2,7 +2,7 @@
  * `<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:
+ * it holds (`./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

package/src/reference/gate-indices.ts

@@ -34,6 +34,7 @@ import {
   type LessonAssessmentLink,
   type MathGateDiagnostic,
   type ScopeEntry,
+  scopeLocals,
 } from './gate-math';
 import { formulaGlyphScope, type GlyphScopeEntry, type ResolvedGloss } from './gloss';
 import { indexOfEntry } from './math-glyphs.mjs';
@@ -136,7 +137,8 @@ function message(
         `${lessonId}: the running index ${details.letter} (first in ${JSON.stringify(details.token)}) ` +
         `has no stated set. Give ${details.where} a range (range: "1, \\\\dots, n"), state it after a ` +
         `\\quad on the first display line that uses it (\\quad ${details.letter} = 1, \\dots, n), or ` +
-        `mark the card fixedIndex: true if ${details.letter} is a label there, not a running index (rule N23).`
+        `mark the card fixedIndex: true if ${details.letter} is a label there, not a running index; ` +
+        `a family indexed by ${details.letter} then explains none of its instances (rule N23).`
       );
     case 'derived-key-taken':
       return (
@@ -173,7 +175,7 @@ export function gateIndices(
     const bodyOffset = (lesson.bodyLine ?? 1) - 1;
     const scope = pageScope(lesson, entries);
     const local = new Map<string, IndexEntryFacts>(
-      lesson.localDefinitions.map((definition) => [definition.key, definition]),
+      scopeLocals(lesson).map((definition) => [definition.key, definition]),
     );
     const factsOf = (key: string | null): IndexEntryFacts | undefined =>
       key === null ? undefined : (local.get(key) ?? entries.get(key));
@@ -325,7 +327,7 @@ export function gateIndices(
     if (!lesson) continue;
     const scope = pageScope(lesson, entries);
     const local = new Map<string, IndexEntryFacts>(
-      lesson.localDefinitions.map((definition) => [definition.key, definition]),
+      scopeLocals(lesson).map((definition) => [definition.key, definition]),
     );
     const factsOf = (key: string | null): IndexEntryFacts | undefined =>
       key === null ? undefined : (local.get(key) ?? entries.get(key));

package/src/reference/gate-math.ts

@@ -1,8 +1,9 @@
 /**
  * The completeness gate, run from the CLI (`pnpm validate:content`) over every
  * rendered-math context — lesson body `$…$` / `$$…$$` (including math inside
- * component slots), each `notation.local` `formula`, and any `$…$` in an
- * assessment `prompt` / `explanation`. It reuses the one resolver the Astro
+ * component slots), a notation entry's Markdown body, each `notation.local`
+ * and shared `formula`, and any `$…$` in an assessment `prompt` /
+ * `explanation`. It reuses the one resolver the Astro
  * remark pass uses (`resolveMathGlyphs`), so there is a single glyph table and
  * a single diagnostic shape; `astro build` re-runs the same resolver on the
  * render path as a backstop.
@@ -10,7 +11,7 @@
  * Every finding names its source and the fix. N17's size-only findings are
  * warnings and include a column when the math came from lesson/assessment text.
  */
-import { resolveMathGlyphs, GlyphResolutionError } from './math-glyphs.mjs';
+import { resolveMathGlyphs, GlyphResolutionError, fixedLenderMessage, mathExcerpt } from './math-glyphs.mjs';
 import {
   EQ_LABEL_PATTERN,
   equationAnchorId,
@@ -25,6 +26,7 @@ import type {
   SharedNotationDefinitionInput,
 } from './types';
 import { blankPropStrings } from './gate-prop-text';
+import { REGISTRY_BODY_FIX, registryGlyphScope } from './registry-scope.mjs';
 
 /**
  * The equation a finding sits in, when its math carries a `\label{eq:…}`.
@@ -77,7 +79,7 @@ export interface MathGateDiagnostic {
    * one the engine ships; its severity is the course's choice, so it is the one
    * context whose severity is not fixed here.
    */
-  readonly severity: 'error' | 'warning';
+  readonly severity: 'error' | 'warning' | 'info';
   /** Owned by exactly one rule or invariant in `src/rules/catalog.ts`. */
   readonly code: string;
   readonly file: string;
@@ -192,14 +194,76 @@ export function scopeEntry(definition: {
  * assessment's math (`mixed-content.ts`), say — doesn't reconstruct it by
  * hand and risk drifting from what the completeness gate actually checks.
  */
+/**
+ * The `notation.local` entries in scope on a page: its own, and for a deck
+ * beside its chapter the chapter's, which are the lesson's
+ * (`NotationLessonInput.inheritedLocalDefinitions`).
+ */
+export function scopeLocals(
+  lesson: NotationLessonInput,
+): readonly NotationLessonInput['localDefinitions'][number][] {
+  const inherited = lesson.inheritedLocalDefinitions ?? [];
+  return inherited.length === 0 ? lesson.localDefinitions : [...lesson.localDefinitions, ...inherited];
+}
+
+const EXPLAIN_CALL = /\\explain\{([^{}]+)\}\{((?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*)\}/g;
+
+/** Every `\explain{key}{inner}` in a span, in source order, with its offset. */
+export function explainCalls(latex: string): { key: string; inner: string; index: number }[] {
+  return [...latex.matchAll(EXPLAIN_CALL)].map((match) => ({
+    key: match[1]!,
+    inner: match[2]!,
+    index: match.index ?? 0,
+  }));
+}
+
+/**
+ * The `\explain` wraps in a span that bind nothing new (rule N4): the bare
+ * inner form already resolves to the same card, with no glyph left over and
+ * no decoration left unexplained (rule N22). Such a wrap costs an author
+ * tokens on every use and the resolver nothing; `\explain` is for a compound
+ * or a colliding glyph.
+ */
+export function redundantExplainWraps(
+  latex: string,
+  scope: readonly ScopeEntry[],
+  options: { readonly suspended?: readonly string[]; readonly derive?: boolean } = {},
+): { key: string; inner: string; index: number }[] {
+  const redundant: { key: string; inner: string; index: number }[] = [];
+  for (const call of explainCalls(latex)) {
+    let bare;
+    try {
+      bare = resolveMathGlyphs(call.inner, [...scope], {
+        suspended: options.suspended ?? [],
+        derive: options.derive ?? false,
+      }) as {
+        bindings: readonly { key: string; level: string }[];
+        unresolved: readonly unknown[];
+        decorations: readonly { wholeForm: string | null; operator: string | null }[];
+      };
+    } catch {
+      continue;
+    }
+    if (
+      bare.unresolved.length === 0 &&
+      bare.bindings.length > 0 &&
+      bare.bindings.every((binding) => binding.key === call.key && binding.level !== 'explicit') &&
+      bare.decorations.every((decoration) => decoration.wholeForm !== null || decoration.operator !== null)
+    ) {
+      redundant.push(call);
+    }
+  }
+  return redundant;
+}
+
 export function pageScope(
   lesson: NotationLessonInput,
   sharedByKey: ReadonlyMap<string, ScopeEntry>,
 ): ScopeEntry[] {
-  const local = lesson.localDefinitions.map(scopeEntry);
+  const local = scopeLocals(lesson).map(scopeEntry);
   const localKeys = new Set(local.map((entry) => entry.key));
 
-  const referenced = new Set<string>();
+  const referenced = new Set<string>(lesson.inheritedKeys ?? []);
   for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
     for (const match of lesson.body.matchAll(pattern)) referenced.add(match[1]);
   }
@@ -237,6 +301,15 @@ export function suspendedOperators(lesson: NotationLessonInput): string[] {
   return (lesson.suspended ?? []).map((item) => item.operator);
 }
 
+/** A family that would explain a subscripted symbol, were its index not fixed (rule N23). */
+interface FixedLender {
+  readonly key: string;
+  /** What fixed it: the entry's own `fixedIndex`, a letter card's, or an index entry. */
+  readonly via: 'entry' | 'fixedIndex' | 'index-entry';
+  readonly card?: string;
+  readonly letter?: string;
+}
+
 function resolveInto(
   latex: string,
   scope: readonly ScopeEntry[],
@@ -300,6 +373,24 @@ function resolveInto(
     });
     return;
   }
+  // Rule N4: an `\explain` wrap whose bare symbol already resolves to the
+  // same card binds nothing new. In a formula the wrap is what puts the card
+  // in scope (`formulaGlyphScope`), so the check does not apply there.
+  if (context !== 'formula') {
+    for (const wrap of redundantExplainWraps(stripEquationLabels(latex), scope, { suspended, derive })) {
+      out.push({
+        context,
+        code: 'explain-redundant',
+        severity: 'info',
+        file,
+        line,
+        ...(column === undefined ? {} : { column }),
+        token: wrap.inner,
+        ...at,
+        message: `\\explain{${wrap.key}}{${wrap.inner}} wraps what ${wrap.inner} already resolves to on this page; write it bare — \\explain is for a compound or a colliding glyph (rule N4)`,
+      });
+    }
+  }
   for (const item of result.unresolved) {
     const { token } = item;
     if ('suspended' in item && typeof item.suspended === 'string') {
@@ -320,10 +411,23 @@ function resolveInto(
       'font' in item && typeof item.font === 'string'
         ? ` ${token} is a different symbol from the plain letter: give it its own entry (latex: ${token}) or wrap it in \\explain{key}{${token}}.`
         : '';
+    // Rule N23: a family whose index letter a card fixed would have explained
+    // this `r_2`; blaming "a bare r" for it sends the author to the wrong repair.
+    const fixedLenders: readonly FixedLender[] =
+      'fixedLenders' in item && Array.isArray(item.fixedLenders)
+        ? (item.fixedLenders as FixedLender[])
+        : [];
+    const instance = 'instance' in item && typeof item.instance === 'string' ? item.instance : token;
+    const fixedHint = fixedLenders.map((lender) => ` ${fixedLenderMessage(lender, instance)}`).join('');
     // Rule N23: an indexed entry with this base explains no bare letter.
+    const fixedKeys = new Set(fixedLenders.map((lender) => lender.key));
+    const lenders =
+      'lenders' in item && Array.isArray(item.lenders)
+        ? (item.lenders as string[]).filter((key) => !fixedKeys.has(key))
+        : [];
     const lenderHint =
-      'lenders' in item && Array.isArray(item.lenders) && item.lenders.length > 0
-        ? ` ${item.lenders.join(', ')} ${item.lenders.length === 1 ? 'has' : 'have'} ${token} with a subscript, and an indexed entry explains its own instances only, never a bare ${token} (rule N4). If ${token} is a different object, give it its own entry (latex: ${token}); if it is shorthand for that entry, wrap it in \\explain{${item.lenders[0]}}{${token}}.`
+      lenders.length > 0
+        ? ` ${lenders.join(', ')} ${lenders.length === 1 ? 'has' : 'have'} ${token} with a subscript, and an indexed entry explains its own instances only, never a bare ${token} (rule N4). If ${token} is a different object, give it its own entry (latex: ${token}); if it is shorthand for that entry, wrap it in \\explain{${lenders[0]}}{${token}}.`
         : '';
     out.push({
       context,
@@ -333,7 +437,7 @@ function resolveInto(
       line,
       token,
       ...at,
-      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math.${fontHint}${lenderHint} ${fix}`,
+      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math, in ${mathExcerpt(latex)}.${fontHint}${fixedHint}${lenderHint} ${fix}`,
     });
   }
 }
@@ -372,6 +476,31 @@ export function currencyDollars(body: string): MathSpan[] {
   return spans;
 }
 
+/** A body's `$5 to $6`: money remark-math would render as math. */
+function reportCurrencyDollars(
+  body: string,
+  file: string,
+  bodyOffset: number,
+  out: MathGateDiagnostic[],
+): void {
+  for (const span of currencyDollars(body)) {
+    const shown = span.latex.replace(/\s+$/, '');
+    out.push({
+      context: 'body',
+      code: 'currency-dollar',
+      severity: SEVERITY.body,
+      file,
+      line: span.line + bodyOffset,
+      column: span.column,
+      token: `$${span.latex}$`,
+      message:
+        `"$${span.latex}$" reads as math: remark-math pairs any two dollars on a line, so the ` +
+        `page shows "${shown}" without them. Write a currency dollar as \\$ (\\$5 to \\$6), ` +
+        'or the amount in words.',
+    });
+  }
+}
+
 const BODY_FIX =
   'Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.';
 function dedupeScope(scope: readonly GlyphScopeEntry[]): GlyphScopeEntry[] {
@@ -491,22 +620,7 @@ export function gateContentMath(input: {
       );
     }
 
-    for (const span of currencyDollars(lesson.body)) {
-      const shown = span.latex.replace(/\s+$/, '');
-      diagnostics.push({
-        context: 'body',
-        code: 'currency-dollar',
-        severity: SEVERITY.body,
-        file,
-        line: span.line + bodyOffset,
-        column: span.column,
-        token: `$${span.latex}$`,
-        message:
-          `"$${span.latex}$" reads as math: remark-math pairs any two dollars on a line, so the ` +
-          `page shows "${shown}" without them. Write a currency dollar as \\$ (\\$5 to \\$6), ` +
-          'or the amount in words.',
-      });
-    }
+    reportCurrencyDollars(lesson.body, file, bodyOffset, diagnostics);
 
     for (const definition of lesson.localDefinitions) {
       if (!definition.formula) continue;
@@ -533,6 +647,36 @@ export function gateContentMath(input: {
     }
   }
 
+  // A shared entry's Markdown body renders in the glossary through the same
+  // remark pass as a lesson, against the whole registry (`registry-scope.mjs`).
+  // A symbol it misses fails that render, and Astro's content layer only logs
+  // the failure and ships the entry without its body, so this is the check
+  // that stops the build.
+  const registryScope: ScopeEntry[] = registryGlyphScope(
+    notationInput.sharedDefinitions,
+  );
+  for (const definition of notationInput.sharedDefinitions) {
+    const file = definition.source.file;
+    const bodyOffset = (definition.bodyLine ?? 1) - 1;
+    for (const span of mathSpans(definition.body)) {
+      resolveInto(
+        span.latex,
+        registryScope,
+        'body',
+        file,
+        span.line + bodyOffset,
+        span.column,
+        REGISTRY_BODY_FIX,
+        diagnostics,
+        undefined,
+        // An entry's body suspends nothing and derives no cards.
+        [],
+        false,
+      );
+    }
+    reportCurrencyDollars(definition.body, file, bodyOffset, diagnostics);
+  }
+
   // Shared cards carry their own rigorous `formula`. It resolves against the
   // entry-scoped table (D15) — the card, its glosses, and the cards the
   // formula names with `\explain` — not the registry-wide table the card's

package/src/reference/lab-katex-validate.ts

@@ -7,9 +7,12 @@
  * Starting at each lesson's own imports, this follows every relative import
  * — the course's visuals, wherever they live — and reports each file that
  * imports `katex` as `lab-katex-direct`, with the chain of imports that
- * reaches it. A package import (`explico/…`, `react`) is not followed:
- * explico's own KaTeX use is the seam. A type-only import and the KaTeX
- * stylesheet draw nothing and are not reported.
+ * reaches it. The answer is per lesson: a helper that three lessons reach is
+ * reported three times, each with that lesson's own chain, and a lesson that
+ * reaches none is clean — so `content check <lesson>` can say so. A package
+ * import (`explico/…`, `react`) is not followed: explico's own KaTeX use is
+ * the seam. A type-only import and the KaTeX stylesheet draw nothing and are
+ * not reported.
  *
  * `figure-symbols.ts` checks the same promise on the rendered page, which
  * also catches math a lab draws some other way.
@@ -26,7 +29,7 @@ export interface LabKatexDiagnostic {
   readonly message: string;
   /** The file that imports `katex`, repository-relative. */
   readonly file: string;
-  /** The first lesson (by id) whose imports reach it. */
+  /** The lesson whose imports reach it; one diagnostic per lesson and file. */
   readonly lessonId: string;
 }
 
@@ -94,26 +97,35 @@ function resolveRelative(fromFile: string, specifier: string): string | undefine
 }
 
 /**
- * Each course file that a lesson's imports reach and that imports `katex`.
- * `root` is the repository root the lesson paths are relative to.
+ * Each course file that imports `katex`, once for every lesson whose imports
+ * reach it, by the shortest chain. `root` is the repository root the lesson
+ * paths are relative to.
  */
 export function validateLabKatexImports(
   lessons: readonly LabKatexLessonInput[],
   root: string = process.cwd(),
 ): LabKatexDiagnostic[] {
+  // A component many lessons import is read once.
+  const sources = new Map<string, string | undefined>();
   const read = (path: string): string | undefined => {
-    try {
-      return readFileSync(path, 'utf8');
-    } catch {
-      return undefined;
+    if (!sources.has(path)) {
+      try {
+        sources.set(path, readFileSync(path, 'utf8'));
+      } catch {
+        sources.set(path, undefined);
+      }
     }
+    return sources.get(path);
   };
   const repoPath = (path: string) => relative(root, path).split(sep).join('/');
 
-  const diagnostics = new Map<string, LabKatexDiagnostic>();
-  const seen = new Set<string>();
+  const diagnostics: LabKatexDiagnostic[] = [];
   for (const lesson of [...lessons].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
     const lessonPath = join(root, lesson.file);
+    // What this lesson reaches; another lesson reaching it too is not an answer
+    // for this one.
+    const reported = new Set<string>();
+    const seen = new Set<string>();
     // Breadth first, so a reported chain is the shortest one.
     const queue: { path: string; source: string; chain: readonly string[] }[] = [
       { path: lessonPath, source: stripFencedCode(lesson.body), chain: [lesson.file] },
@@ -123,8 +135,9 @@ export function validateLabKatexImports(
       for (const specifier of importSpecifiers(source)) {
         if (isKatexModule(specifier)) {
           const file = repoPath(path);
-          if (!diagnostics.has(file)) {
-            diagnostics.set(file, {
+          if (!reported.has(file)) {
+            reported.add(file);
+            diagnostics.push({
               code: 'lab-katex-direct',
               severity: 'error',
               file,
@@ -152,5 +165,7 @@ export function validateLabKatexImports(
       }
     }
   }
-  return [...diagnostics.values()].sort((a, b) => a.file.localeCompare(b.file));
+  return diagnostics.sort(
+    (a, b) => a.file.localeCompare(b.file) || a.lessonId.localeCompare(b.lessonId),
+  );
 }

package/src/reference/lab-math-scope.ts

@@ -4,6 +4,7 @@ import {
   bindScopeToPage,
   registerPageNotationDependencies,
   routeIdFromLocals,
+  scopeLessonsOf,
 } from './page-notation';
 
 interface LessonNotationFrontmatter {
@@ -37,14 +38,45 @@ export async function labMathScope(
   body = '',
   component?: { readonly locals: object; readonly context: string },
 ): Promise<LabMathScopeDefinition[]> {
-  const local = notation?.local ?? [];
+  const manifest = await loadManifest();
+  // On a deck beside its chapter (`docs/authoring/deck.md`), a lab shows its
+  // lesson's symbols: the chapter's `notation.local` and the keys it names,
+  // as the deck's own math does. On a part's deck, its chapters' symbols,
+  // the first chapter to define a key binding it.
+  const routeId = component ? routeIdFromLocals(component.locals) : undefined;
+  const deck = routeId === undefined
+    ? undefined
+    : manifest.decks?.find(
+        (entry) => entry.slug === routeId && (entry.chapter !== undefined || entry.part !== undefined),
+      );
+  const scopeLessons = deck ? scopeLessonsOf(manifest, deck.pageId) : [];
+  const lessonLocal: { key: string; latex: string; fixedIndex?: boolean }[] = [];
+  for (const lessonId of scopeLessons) {
+    for (const definition of manifest.notation.definitions) {
+      if (definition.kind !== 'local' || !definition.id.startsWith(`page:${lessonId}:`)) continue;
+      if (lessonLocal.some((known) => known.key === definition.key)) continue;
+      lessonLocal.push({
+        key: definition.key,
+        latex: definition.notation,
+        ...(definition.fixedIndex ? { fixedIndex: true } : {}),
+      });
+    }
+  }
+  const lessonKeys = scopeLessons.flatMap((lessonId) =>
+    (manifest.lessons.find((lesson) => lesson.id === lessonId)?.notation.bindings ?? []).map((binding) => binding.key),
+  );
+  const ownLocal = notation?.local ?? [];
+  const local = [
+    ...ownLocal,
+    ...lessonLocal.filter((definition) => !ownLocal.some((own) => own.key === definition.key)),
+  ];
   const scope: LabMathScopeDefinition[] = local.map((definition) => ({
     key: definition.key,
     notation: definition.latex,
     ...(definition.fixedIndex === true ? { fixedIndex: true as const } : {}),
   }));
 
-  const referenced = new Set<string>();
+  const referenced = new Set<string>(lessonKeys);
   const explicitlyExplained = new Set<string>();
   for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
     for (const match of body.matchAll(pattern)) {
@@ -54,7 +86,6 @@ export async function labMathScope(
   }
 
   const localKeys = new Set(local.map((definition) => definition.key));
-  const manifest = await loadManifest();
   const sharedByKey = new Map(
     manifest.notation.definitions
       .filter((definition) => definition.kind === 'shared')