explico 0.2.0 → 0.4.0

package/src/reference/base-operators.mjs

@@ -0,0 +1,103 @@
+/**
+ * The base operator library: the named mathematical operators every reader is
+ * assumed to know, so a lesson never has to introduce them with a notation
+ * entry.
+ *
+ * Rationale (parallel to `base-library.mjs`): the completeness gate has no
+ * opinion about operators — KaTeX parses `\exp`, `\int`, `\sin`, … as operator
+ * nodes, and `\operatorname{Var}` as an `operatorname` node, none of which the
+ * glyph resolver treats as a bindable symbol. The `operator-explained`
+ * consistency check (rule N8) fills that gap: an operator a lesson uses is
+ * either on this list (or the course's additions to it) or it carries a
+ * notation entry the reader can hover. This set is the "everyone knows these"
+ * baseline — trig, the exponential and logarithms, limits, extrema, and the
+ * big operators — kept greppable and small like the base library.
+ *
+ * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
+ * written `\operatorname{…}` and is NOT here: it earns a card, a
+ * `notation.local` entry, or an explicit line in `course.config.ts`
+ * (`operators.allow`).
+ *
+ * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
+ * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).
+ * Matching is case-sensitive.
+ */
+export const BASE_OPERATORS = Object.freeze(
+  new Set([
+    // exponential / logarithms
+    'exp',
+    'log',
+    'ln',
+    'lg',
+    // trigonometric
+    'sin',
+    'cos',
+    'tan',
+    'cot',
+    'sec',
+    'csc',
+    // inverse trigonometric
+    'arcsin',
+    'arccos',
+    'arctan',
+    // hyperbolic
+    'sinh',
+    'cosh',
+    'tanh',
+    'coth',
+    // limits
+    'lim',
+    'limsup',
+    'liminf',
+    'injlim',
+    'projlim',
+    'varlimsup',
+    'varliminf',
+    'varinjlim',
+    'varprojlim',
+    // extrema
+    'max',
+    'min',
+    'sup',
+    'inf',
+    // linear algebra / number theory / misc
+    'arg',
+    'deg',
+    'det',
+    'dim',
+    'gcd',
+    'hom',
+    'ker',
+    'Pr',
+    'mod',
+    // big operators
+    'sum',
+    'prod',
+    'coprod',
+    'int',
+    'iint',
+    'iiint',
+    'oint',
+  ]),
+);
+
+/**
+ * The operators a course treats as common, given its `course.config.ts`
+ * `operators` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} operators
+ * @returns {Set<string>}
+ */
+export function effectiveOperatorAllowlist(operators) {
+  const allow = operators?.allow ?? [];
+  const deny = new Set(operators?.deny ?? []);
+  const effective = new Set(BASE_OPERATORS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+
+/** True when `name` needs no notation entry for this course. */
+export function isBaseOperator(name, operators) {
+  return effectiveOperatorAllowlist(operators).has(name);
+}

package/src/reference/consistency.ts

@@ -19,15 +19,23 @@
  *   (f) weak-local                   a `notation.local` symbol used only in its
  *                                     own defining equation and prose
  *   (g) notation-source-locator      every notation `sources` entry has a locator
+ *   (h) operator-explained           a named operator a lesson uses is on the
+ *                                     shipped/course operator allowlist or
+ *                                     carries a notation entry (rule N8)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
-import type { CourseConventions } from '../compiler/course-config';
+import type {
+  CourseConventions,
+  CourseOperators,
+} 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 { offVocabularyTokens } from './units-vocab';
 import type {
   NotationDefinitionRecord,
@@ -45,7 +53,8 @@ export type ConsistencyCode =
   | 'notation-source-locator'
   | 'gloss-wants-promoting'
   | 'card-wants-demoting'
-  | 'gloss-name-shape';
+  | 'gloss-name-shape'
+  | 'operator-explained';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -68,6 +77,8 @@ export interface ConsistencyInput {
   readonly lintIgnore: LintIgnore;
   /** Convention keys this course anchors on (from `content/course.config.ts`). */
   readonly conventions: CourseConventions;
+  /** This course's edits to the named-operator baseline (rule N8). */
+  readonly operators?: CourseOperators;
 }
 
 const CONVENTION_RE =
@@ -472,6 +483,74 @@ function checkGlossNameShape(
   }
 }
 
+/**
+ * A named operator a lesson uses is either universal — on the shipped
+ * `BASE_OPERATORS` baseline plus this course's `operators.allow`, minus its
+ * `operators.deny` — or it is explained: a notation card or `notation.local`
+ * entry the lesson binds with `[[key]]` whose `latex` is that operator, so the
+ * reader can hover it. Anything else (`\operatorname{Var}` with no entry, or a
+ * baseline operator the course chose to `deny`) is a finding. Rule N8.
+ *
+ * The glyph resolver skips operator bodies whole, so this is the only check
+ * that looks at them; it reads `collectOperators`, which parses with the same
+ * pinned KaTeX as the completeness gate.
+ */
+function checkOperatorExplained(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveOperatorAllowlist(input.operators);
+  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) {
+    // Operators 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 noteEntryOperators = (latex: string): void => {
+      for (const operator of collectOperators(latex)) {
+        explained.add(operator.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryOperators(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryOperators(definition.notation);
+    }
+
+    const reported = new Set<string>();
+    for (const span of mathSpans(lesson.body)) {
+      for (const operator of collectOperators(span.latex)) {
+        if (allowlist.has(operator.name)) continue;
+        if (explained.has(operator.name)) continue;
+        if (reported.has(operator.name)) continue;
+        reported.add(operator.name);
+        if (input.lintIgnore.matches('operator-explained', operator.name)) {
+          continue;
+        }
+        const display =
+          operator.source === 'operatorname'
+            ? `\\operatorname{${operator.name}}`
+            : `\\${operator.name}`;
+        out.push({
+          code: 'operator-explained',
+          severity: 'warning',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: operator.name,
+          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to operators.allow in course.config.ts`,
+        });
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -485,6 +564,7 @@ const CHECKS: ((
   checkGlossWantsPromoting,
   checkCardWantsDemoting,
   checkGlossNameShape,
+  checkOperatorExplained,
 ];
 
 /**
@@ -522,6 +602,7 @@ export function consistencyCounts(
     'gloss-wants-promoting': 0,
     'card-wants-demoting': 0,
     'gloss-name-shape': 0,
+    'operator-explained': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/diagram-layout.ts

@@ -0,0 +1,246 @@
+/**
+ * Build-time graph layout for the `Diagram` component.
+ *
+ * Wraps `@dagrejs/dagre` — a pure layout algorithm, no DOM — so node
+ * positions and edge routes are computed once at build time, the same way
+ * `renderLabMath` and the notation formulas are: static output, no runtime
+ * layout library shipped to the reader. `Diagram.astro` turns the result into
+ * SVG; this module only computes geometry and is deliberately framework-free
+ * so it is unit-testable without KaTeX, Astro, or a browser.
+ *
+ * Box sizes are not measured from a real render (there is no DOM at build
+ * time) — `estimateBoxSize` is a deliberately generous character-count
+ * heuristic. It is meant to avoid overlap and clipping in the common case,
+ * not to be pixel-accurate; a diagram author can always pass an explicit
+ * `width`/`height` on a node for a wide equation.
+ */
+import dagre from '@dagrejs/dagre';
+import type {
+  EdgeLabel as DagreEdgeLabel,
+  GraphLabel as DagreGraphLabel,
+  NodeLabel as DagreNodeLabel,
+} from '@dagrejs/dagre';
+
+export interface DiagramNodeInput {
+  readonly id: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface DiagramEdgeInput {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface DiagramLayoutOptions {
+  /** Top-to-bottom (default) or left-to-right. */
+  readonly direction?: 'TB' | 'LR';
+  readonly nodeSeparation?: number;
+  readonly rankSeparation?: number;
+  /** Uniform padding added around the computed bounding box. */
+  readonly padding?: number;
+}
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface LaidOutNode {
+  readonly id: string;
+  /** Top-left corner, not the center dagre itself works in. */
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface LaidOutEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly points: readonly Point[];
+}
+
+export interface DiagramLayout {
+  readonly nodes: readonly LaidOutNode[];
+  readonly edges: readonly LaidOutEdge[];
+  /** The SVG canvas size a caller should use as the `viewBox`. */
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Lay out a small directed graph. Node ids must be unique; an edge naming an
+ * undeclared node fails loudly rather than silently dropping it (dagre itself
+ * would otherwise create a phantom zero-size node).
+ */
+export function layoutDiagram(
+  nodes: readonly DiagramNodeInput[],
+  edges: readonly DiagramEdgeInput[],
+  options: DiagramLayoutOptions = {},
+): DiagramLayout {
+  const ids = new Set<string>();
+  for (const node of nodes) {
+    if (ids.has(node.id)) {
+      throw new Error(`Diagram declares node "${node.id}" more than once.`);
+    }
+    if (!(node.width > 0) || !(node.height > 0)) {
+      throw new Error(
+        `Diagram node "${node.id}" must have a positive width and height.`,
+      );
+    }
+    ids.add(node.id);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) {
+      throw new Error(`Diagram edge references unknown node "${edge.from}".`);
+    }
+    if (!ids.has(edge.to)) {
+      throw new Error(`Diagram edge references unknown node "${edge.to}".`);
+    }
+  }
+
+  const graph = new dagre.graphlib.Graph<
+    DagreGraphLabel,
+    DagreNodeLabel,
+    DagreEdgeLabel
+  >();
+  graph.setGraph({
+    rankdir: options.direction ?? 'TB',
+    nodesep: options.nodeSeparation ?? 24,
+    ranksep: options.rankSeparation ?? 48,
+    marginx: 0,
+    marginy: 0,
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of nodes) {
+    graph.setNode(node.id, { width: node.width, height: node.height });
+  }
+  for (const edge of edges) {
+    graph.setEdge(edge.from, edge.to);
+  }
+
+  dagre.layout(graph);
+
+  const centeredNodes = nodes.map((node) => {
+    const label = graph.node(node.id);
+    const cx = label.x ?? 0;
+    const cy = label.y ?? 0;
+    return {
+      id: node.id,
+      x: cx - node.width / 2,
+      y: cy - node.height / 2,
+      width: node.width,
+      height: node.height,
+    };
+  });
+
+  const rawEdges = edges.map((edge) => {
+    const label = graph.edge(edge.from, edge.to) ?? {};
+    return {
+      from: edge.from,
+      to: edge.to,
+      points: (label.points ?? []).map((point) => ({
+        x: point.x,
+        y: point.y,
+      })),
+    };
+  });
+
+  // dagre does not guarantee the layout starts at (0, 0); compute the real
+  // bounding box from node boxes and edge routing points, then shift
+  // everything so the canvas starts at `padding`.
+  const padding = options.padding ?? 12;
+  const xs = [
+    ...centeredNodes.flatMap((node) => [node.x, node.x + node.width]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.x)),
+  ];
+  const ys = [
+    ...centeredNodes.flatMap((node) => [node.y, node.y + node.height]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.y)),
+  ];
+  const minX = xs.length > 0 ? Math.min(...xs) : 0;
+  const minY = ys.length > 0 ? Math.min(...ys) : 0;
+  const maxX = xs.length > 0 ? Math.max(...xs) : 0;
+  const maxY = ys.length > 0 ? Math.max(...ys) : 0;
+  const shiftX = padding - minX;
+  const shiftY = padding - minY;
+
+  return {
+    nodes: centeredNodes.map((node) => ({
+      ...node,
+      x: node.x + shiftX,
+      y: node.y + shiftY,
+    })),
+    edges: rawEdges.map((edge) => ({
+      ...edge,
+      points: edge.points.map((point) => ({
+        x: point.x + shiftX,
+        y: point.y + shiftY,
+      })),
+    })),
+    width: maxX - minX + padding * 2,
+    height: maxY - minY + padding * 2,
+  };
+}
+
+// --- box-size estimation (no DOM at build time) --------------------------
+
+export interface BoxSizeEstimate {
+  readonly width: number;
+  readonly height: number;
+}
+
+const DEFAULT_MAX_WIDTH = 220;
+const MIN_WIDTH = 90;
+const PADDING_X = 20;
+const PADDING_Y = 16;
+const LINE_HEIGHT = 22;
+/** Generous per-visible-character width estimates, in px, at diagram scale. */
+const CHAR_WIDTH: Record<'text' | 'formula', number> = {
+  text: 7.2,
+  formula: 11,
+};
+
+/**
+ * A LaTeX command name (`\theta`, `\cdot`, …) renders as roughly one glyph,
+ * not one character per letter of its name; braces are structural, not
+ * visible. Collapsing both keeps the estimate from reading a formula as far
+ * wider than it will actually render.
+ */
+function formulaVisibleLength(latex: string): number {
+  const collapsed = latex
+    .replace(/\\[a-zA-Z]+/g, 'x')
+    .replace(/[{}$]/g, '')
+    .trim();
+  return Math.max(1, collapsed.length);
+}
+
+/**
+ * Estimate a diagram node's box from its label text (or raw, pre-resolution
+ * LaTeX for a formula node). Deliberately generous: it is meant to avoid
+ * clipping, not to match a real render pixel-for-pixel. Pass an explicit
+ * `width`/`height` on the node to override for a label this estimate gets
+ * badly wrong.
+ */
+export function estimateBoxSize(
+  content: string,
+  kind: 'text' | 'formula',
+  options: { readonly maxWidth?: number } = {},
+): BoxSizeEstimate {
+  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
+  const visibleLength =
+    kind === 'formula' ? formulaVisibleLength(content) : content.trim().length || 1;
+  const charWidth = CHAR_WIDTH[kind];
+
+  const naturalWidth = visibleLength * charWidth + PADDING_X * 2;
+  const width = Math.min(maxWidth, Math.max(MIN_WIDTH, naturalWidth));
+
+  const usableWidth = width - PADDING_X * 2;
+  const charsPerLine = Math.max(1, Math.floor(usableWidth / charWidth));
+  const lines = Math.max(1, Math.ceil(visibleLength / charsPerLine));
+  const height = lines * LINE_HEIGHT + PADDING_Y * 2;
+
+  return { width: Math.round(width), height: Math.round(height) };
+}

package/src/reference/equations-validate.ts

@@ -53,6 +53,13 @@ export interface EquationLessonInput {
   readonly slug: string;
   readonly file: string;
   readonly body: string;
+  /**
+   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+   * and how many display equations earlier lessons of that part already used.
+   * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
+   * legacy `##`-section scheme. See `docs/authoring/structure.md`.
+   */
+  readonly numbering?: { readonly prefix: number; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -90,7 +97,7 @@ export function validateEquations(
   )) {
     const seen = new Set<string>();
     const table: Record<string, string> = {};
-    for (const raw of scanEquationLabels(lesson.body) as {
+    for (const raw of scanEquationLabels(lesson.body, lesson.numbering) as {
       key: string;
       number: string;
       section: number;