explico 0.7.0 → 0.11.0

package/dist/reference/gate-math.d.ts

@@ -1,7 +1,21 @@
 import { NotationRegistryInput, NotationLessonInput } from './types.js';
 
+/**
+ * The equation a finding sits in, when its math carries a `\label{eq:…}`.
+ *
+ * A location tells you where to edit; this tells you *what you are looking
+ * at*. A size-only N17 finding inside a six-line `aligned` block is otherwise
+ * anonymous — the message names delimiters, not the result they belong to —
+ * so the key and the rendered page's anchor both travel with the diagnostic.
+ */
+interface EquationLink {
+    /** The label's key, without the `eq:` prefix. */
+    readonly key: string;
+    /** Where the reader sees it, e.g. `/l1-ar/ar1-basics/#eq-ar1-variance`. */
+    readonly href: string;
+}
 interface MathGateDiagnostic {
-    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
+    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure' | 'course';
     /**
      * Body / component-slot math blocks the build (the render path needs every
      * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
@@ -20,17 +34,24 @@ interface MathGateDiagnostic {
      * `gate-abbreviations.ts`) is the same "ships straight as an error" story
      * for a different shape of plain-text token — an unexplained acronym or
      * dotted abbreviation, rather than a mis-typed quantity/unit. `structure`
-     * (S1, `gate-heading-length.ts`) is unrelated to notation — it caps how
-     * long a heading or a keyed float's title may run — but reuses this same
+     * (S1, `gate-heading-length.ts`; S2, `gate-part-pages.ts`) is unrelated to
+     * notation — it caps how long a heading or a keyed float's title may run,
+     * and requires a part page's bridge and scope paragraphs — but reuses this same
      * diagnostic shape and the one `manifest.diagnostics.math` array rather
-     * than adding a second array the CLI has to know about.
+     * than adding a second array the CLI has to know about. `course`
+     * (`gate-course-rules.ts`) is a rule the *course* wrote in `courseRules`, not
+     * 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 code?: string;
+    /** Owned by exactly one rule or invariant in `src/rules/catalog.ts`. */
+    readonly code: string;
     readonly file: string;
     readonly line?: number;
     readonly column?: number;
     readonly token?: string;
+    /** Present when the offending math carries a `\label{eq:…}`. */
+    readonly equation?: EquationLink;
     readonly message: string;
 }
 interface AssessmentItemLike {
@@ -46,6 +67,15 @@ interface LessonAssessmentLink {
     readonly lessonId: string;
     readonly assessmentIds: readonly string[];
 }
+interface MathSpan {
+    readonly latex: string;
+    readonly line: number;
+    readonly column: number;
+    /** Index of `latex` in the text it was cut from. */
+    readonly offset: number;
+}
+/** Every `$$…$$` then `$…$` span in `body`, outside code, with its position. */
+declare function mathSpans(body: string): MathSpan[];
 type ScopeEntry = {
     key: string;
     notation: string;
@@ -58,6 +88,14 @@ type ScopeEntry = {
  * hand and risk drifting from what the completeness gate actually checks.
  */
 declare function pageScope(lesson: NotationLessonInput, sharedByKey: ReadonlyMap<string, ScopeEntry>): ScopeEntry[];
+/**
+ * The `\label{eq:…}` a math source carries, as a key plus the anchor the
+ * rendered page gives it. `EQ_LABEL_PATTERN` is global, so its `lastIndex` is
+ * reset before use — a stale one would skip the first label of the next span.
+ */
+declare function equationLinkFor(lessonId: string, latex: string): EquationLink | undefined;
+/** Decorations a lesson suspends (`notation.suspend`, rule N22), by name. */
+declare function suspendedOperators(lesson: NotationLessonInput): string[];
 /**
  * Resolve every rendered-math context against the page glyph table. Returns one
  * diagnostic per unresolved token; an empty array means the gate passed.
@@ -68,4 +106,4 @@ declare function gateContentMath(input: {
     readonly lessonAssessments: readonly LessonAssessmentLink[];
 }): MathGateDiagnostic[];
 
-export { type MathGateDiagnostic, type ScopeEntry, gateContentMath, pageScope };
+export { type EquationLink, type MathGateDiagnostic, type MathSpan, type ScopeEntry, equationLinkFor, gateContentMath, mathSpans, pageScope, suspendedOperators };

package/dist/reference/gate-math.js

@@ -1,5 +1,9 @@
 import { resolveMathGlyphs, GlyphResolutionError } from "./math-glyphs.mjs";
-import { stripEquationLabels } from "./equations.mjs";
+import {
+  EQ_LABEL_PATTERN,
+  equationAnchorId,
+  stripEquationLabels
+} from "./equations.mjs";
 import { lintDelimiterSizes } from "./delimiter-size.js";
 import { formulaGlyphScope, unknownFormulaScopeKeys } from "./gloss.js";
 const SEVERITY = {
@@ -8,7 +12,9 @@ const SEVERITY = {
   assessment: "error",
   prose: "error",
   abbreviation: "error",
-  structure: "error"
+  structure: "error",
+  // Never read: `gateCourseRules` sets the severity the course chose.
+  course: "error"
 };
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
@@ -34,7 +40,8 @@ function mathSpans(body) {
       spans.push({
         latex,
         line: lineOf(body, latexOffset),
-        column: latexOffset - lastNewline
+        column: latexOffset - lastNewline,
+        offset: latexOffset
       });
     }
   }
@@ -58,7 +65,20 @@ function pageScope(lesson, sharedByKey) {
   }
   return scope;
 }
-function resolveInto(latex, scope, context, file, line, column, fix, out) {
+function equationLinkFor(lessonId, latex) {
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  const match = EQ_LABEL_PATTERN.exec(latex);
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  if (!match) return void 0;
+  const key = match[1];
+  const slug = lessonId.replace(/\./g, "/");
+  return { key, href: `/${slug}/#${equationAnchorId({ key })}` };
+}
+function suspendedOperators(lesson) {
+  return (lesson.suspended ?? []).map((item) => item.operator);
+}
+function resolveInto(latex, scope, context, file, line, column, fix, out, equation, suspended = []) {
+  const at = equation === void 0 ? {} : { equation };
   for (const diagnostic of lintDelimiterSizes(latex)) {
     const locatedLine = line === void 0 ? void 0 : line + diagnostic.line - 1;
     const locatedColumn = column === void 0 ? void 0 : diagnostic.line === 1 ? column + diagnostic.column - 1 : diagnostic.column;
@@ -69,15 +89,21 @@ function resolveInto(latex, scope, context, file, line, column, fix, out) {
       file,
       ...locatedLine === void 0 ? {} : { line: locatedLine },
       ...locatedColumn === void 0 ? {} : { column: locatedColumn },
+      ...at,
       message: diagnostic.message
     });
   }
   let result;
   try {
-    result = resolveMathGlyphs(stripEquationLabels(latex), [...scope]);
+    result = resolveMathGlyphs(stripEquationLabels(latex), [...scope], {
+      suspended
+    });
   } catch (error) {
     out.push({
       context,
+      // The resolver's own code (`unparenthesized-function`, `invalid-latex`,
+      // …) is what the rule catalog keys on; anything else is a KaTeX crash.
+      code: error instanceof GlyphResolutionError && typeof error.code === "string" ? error.code : "math-compile-error",
       severity: SEVERITY[context],
       file,
       line,
@@ -85,14 +111,31 @@ function resolveInto(latex, scope, context, file, line, column, fix, out) {
     });
     return;
   }
-  for (const { token } of result.unresolved) {
+  for (const item of result.unresolved) {
+    const { token } = item;
+    if ("suspended" in item && typeof item.suspended === "string") {
+      out.push({
+        context,
+        code: "suspended-operator-unresolved",
+        severity: SEVERITY[context],
+        file,
+        line,
+        token,
+        ...at,
+        message: `On this page ${JSON.stringify(item.suspended)} is suspended (notation.suspend), so ${JSON.stringify(token)} is not ${JSON.stringify(item.suspended)} applied to a symbol: it needs its own notation entry (latex: ${token}) or an \\explain{key}{${token}} wrap.`
+      });
+      continue;
+    }
+    const fontHint = "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}}.` : "";
     out.push({
       context,
+      code: "unresolved-glyph",
       severity: SEVERITY[context],
       file,
       line,
       token,
-      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math. ${fix}`
+      ...at,
+      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math.${fontHint} ${fix}`
     });
   }
 }
@@ -116,6 +159,9 @@ function reportUnknownScopeKeys(definition, cardKeys, file, out) {
   )) {
     out.push({
       context: "formula",
+      // Same failure the resolver reports for a body `\explain{key}` that
+      // names nothing — one code, one owner (`notation-references`).
+      code: "unknown-explicit-key",
       severity: SEVERITY.formula,
       file,
       token: key,
@@ -156,16 +202,20 @@ function gateContentMath(input) {
   for (const lesson of notationInput.lessons) {
     const scope = pageScope(lesson, sharedByKey);
     const file = lesson.source.file;
+    const suspended = suspendedOperators(lesson);
+    const bodyOffset = (lesson.bodyLine ?? 1) - 1;
     for (const span of mathSpans(lesson.body)) {
       resolveInto(
         span.latex,
         scope,
         "body",
         file,
-        span.line,
+        span.line + bodyOffset,
         span.column,
         BODY_FIX,
-        diagnostics
+        diagnostics,
+        equationLinkFor(lesson.lessonId, span.latex),
+        suspended
       );
     }
     for (const definition of lesson.localDefinitions) {
@@ -243,6 +293,9 @@ function gateContentMath(input) {
   return diagnostics;
 }
 export {
+  equationLinkFor,
   gateContentMath,
-  pageScope
+  mathSpans,
+  pageScope,
+  suspendedOperators
 };

package/dist/reference/gate-part-pages.d.ts

@@ -0,0 +1,50 @@
+import { N as NormalizedPartPages } from '../course-config-Dsnri9Tk.js';
+import { MathGateDiagnostic } from './gate-math.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
+import './types.js';
+
+/**
+ * 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.
+ */
+
+/** One part overview page, as the manifest compiler loads it. */
+interface PartPageInput {
+    readonly dir: string;
+    /** 1-based position in `courseConfig.parts`. */
+    readonly ordinal: number;
+    readonly file: string;
+    readonly body: string;
+    readonly bodyLine: number;
+}
+/**
+ * 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.
+ */
+declare function proseWordCount(markdown: string): number;
+/**
+ * Check every part overview page for its S2 paragraphs. Returns one
+ * `MathGateDiagnostic` (context `'structure'`, code `part-page-paragraph`,
+ * always an error) per finding.
+ */
+declare function gatePartPages(pages: readonly PartPageInput[], limits: NormalizedPartPages): MathGateDiagnostic[];
+
+export { type PartPageInput, gatePartPages, proseWordCount };

package/dist/reference/gate-part-pages.js

@@ -0,0 +1,118 @@
+import { stripFencedCode } from "./equations.mjs";
+import { lessonLine } from "./gate-prose-notation.js";
+const TAG_BY_SLOT = {
+  bridge: "PartBridge",
+  scope: "PartScope"
+};
+const SUBJECT_BY_SLOT = {
+  bridge: "how the earlier parts lead into this one",
+  scope: "what this part covers"
+};
+function scannable(body) {
+  return stripFencedCode(body).replace(
+    /\{\/\*[\s\S]*?\*\/\}/g,
+    (comment) => comment.replace(/[^\n]/g, " ")
+  );
+}
+function occurrencesOf(text, tag) {
+  const pattern = new RegExp(
+    `<${tag}\\b[^>]*?(?:\\/>|>([\\s\\S]*?)<\\/${tag}\\s*>)`,
+    "g"
+  );
+  return [...text.matchAll(pattern)].map((match) => ({
+    index: match.index ?? 0,
+    content: match[1]
+  }));
+}
+function paragraphsOf(content) {
+  return content.trim().split(/\n[ \t]*\n/).filter((block) => block.trim().length > 0);
+}
+function proseWordCount(markdown) {
+  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, text, slot, limits) {
+  const tag = TAG_BY_SLOT[slot];
+  const found = occurrencesOf(text, tag);
+  const required = slot === "scope" || page.ordinal > 1;
+  const out = [];
+  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}>\u2026</${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}\u2013${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;
+}
+function gatePartPages(pages, limits) {
+  const diagnostics = [];
+  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;
+}
+export {
+  gatePartPages,
+  proseWordCount
+};

package/dist/reference/gate-prose-notation.d.ts

@@ -6,7 +6,8 @@ import { NotationLessonInput } from './types.js';
  * 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.
@@ -31,20 +32,40 @@ interface AssessmentLike {
     readonly items?: readonly AssessmentItemLike[];
 }
 /**
- * Blank code, math, reference, and JSX-tag spans so offsets don't shift.
- * Exported so `gate-abbreviations.ts` (N14) scans exactly the same "is this
- * really prose" surface as N9, instead of drifting with a second copy of
- * these regexes.
+ * `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`.
  */
-declare function proseOnly(body: string): string;
+declare function proseOnly(body: string, options?: {
+    readonly keepMath?: boolean;
+}): string;
 /** Exported for the same reason as {@link proseOnly}. */
 declare function lineOf(text: string, index: number): number;
+/**
+ * {@link lineOf} corrected to the file the lesson came from. A gate scans
+ * `lesson.body`, which starts *after* the frontmatter, so a raw body line is
+ * short by the frontmatter's height and points at the wrong source line —
+ * silently, because the number is still plausible. Every gate that reports a
+ * `line` against `lesson.source.file` must go through this.
+ */
+declare function lessonLine(lesson: {
+    readonly body: string;
+    readonly bodyLine?: number;
+}, index: number): number;
+/** Rule N9's settings the gate reads (`rules.N9` in the course settings). */
+interface ProseNotationOptions {
+    /** Unit words this course lets prose spell out (`rules.N9.allow`), singular or plural. */
+    readonly allowSpelledUnits?: readonly string[];
+}
 /**
  * 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.
  */
-declare function gateProseNotation(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+declare function gateProseNotation(lessons: readonly NotationLessonInput[], options?: ProseNotationOptions): MathGateDiagnostic[];
 /**
  * Scan every assessment `prompt` / `explanation` for the same plain-text
  * notation N9 forbids in a lesson body — `AssessmentRunner` renders both
@@ -55,6 +76,6 @@ declare function gateProseNotation(lessons: readonly NotationLessonInput[]): Mat
  * same `"<assessmentId> (<itemId>)"` shape `gate-math.ts` already uses for
  * this context.
  */
-declare function gateProseNotationInAssessments(assessments: readonly AssessmentLike[]): MathGateDiagnostic[];
+declare function gateProseNotationInAssessments(assessments: readonly AssessmentLike[], options?: ProseNotationOptions): MathGateDiagnostic[];
 
-export { gateProseNotation, gateProseNotationInAssessments, lineOf, proseOnly };
+export { type ProseNotationOptions, gateProseNotation, gateProseNotationInAssessments, lessonLine, lineOf, proseOnly };

package/dist/reference/gate-prose-notation.js

@@ -1,3 +1,4 @@
+import { findSpelledUnits } from "./unit-words.js";
 const CODE_FENCE = /```[\s\S]*?```/g;
 const INLINE_CODE = /(^|[^`])`[^`\n]*`/g;
 const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
@@ -5,13 +6,19 @@ const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
 const IMPORT_LINE = /^[ \t]*import\b[^\n]*$/gm;
 const KEY_REFERENCE = /\[\[[^\]\n]*\]\]/g;
 const JSX_TAG = /<\/?[A-Za-z][^<>]*>/g;
-function proseOnly(body) {
+const MDX_COMMENT = /\{\/\*[\s\S]*?\*\/\}/g;
+function proseOnly(body, options = {}) {
   const blank = (match) => match.replace(/[^\n]/g, " ");
-  return body.replace(CODE_FENCE, blank).replace(INLINE_CODE, (match, lead) => lead + blank(match.slice(lead.length))).replace(DISPLAY_MATH, blank).replace(INLINE_MATH, blank).replace(IMPORT_LINE, blank).replace(KEY_REFERENCE, blank).replace(JSX_TAG, blank);
+  const code = body.replace(MDX_COMMENT, blank).replace(CODE_FENCE, blank).replace(INLINE_CODE, (match, lead) => 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);
 }
 function lineOf(text, index) {
   return text.slice(0, index).split("\n").length;
 }
+function lessonLine(lesson, index) {
+  return lineOf(lesson.body, index) + (lesson.bodyLine ?? 1) - 1;
+}
 const UNIT = String.raw`m/s²|m/s|km/h|rad/s|m²/s²|J/kg|m²|s⁻¹|kg|N|J|W|Hz|deg|°|rad|m|s`;
 const NUMERAL_UNIT = new RegExp(
   String.raw`(?<![\w.])-?\d+(?:\.\d+)?\s?(?:${UNIT})(?![A-Za-z])`,
@@ -37,6 +44,7 @@ const SLASH_IDIOMS = /* @__PURE__ */ new Set([
 ]);
 const SLASH_TOKENS = /\b([A-Za-z]{1,6})\/([A-Za-z]{1,6})\b/g;
 const FAKE_SCRIPT = /[A-Za-z0-9][_^][A-Za-z0-9{]/g;
+const PROSE_NOTATION_CODE = "prose-notation";
 function findAll(text, pattern, toFinding) {
   const out = [];
   const re = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
@@ -48,8 +56,17 @@ function findAll(text, pattern, toFinding) {
   return out;
 }
 const FIX = "Wrap it in $\u2026$ (or $$\u2026$$) instead \u2014 see docs/authoring/notation.md#n9.";
-function findingsIn(text) {
+function findingsIn(text, withMath, options) {
+  const spelled = findSpelledUnits(text, withMath, options.allowSpelledUnits).map(
+    (unit) => ({
+      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 $\u2026$, even in flowing prose. Where the sentence defines or names the unit itself, waive the block with {/* explico-allow N9: reason */} \u2014 see docs/authoring/notation.md#n9.`
+    })
+  );
   return [
+    ...spelled,
     ...findAll(text, /\\\|/g, (m) => ({
       index: m.index,
       token: m[0],
@@ -80,16 +97,18 @@ function findingsIn(text) {
     }).filter(Boolean)
   ];
 }
-function gateProseNotation(lessons) {
+function gateProseNotation(lessons, options = {}) {
   const diagnostics = [];
   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: lineOf(lesson.body, finding.index),
+        line: lessonLine(lesson, finding.index),
         token: finding.token,
         message: finding.message
       });
@@ -97,15 +116,17 @@ function gateProseNotation(lessons) {
   }
   return diagnostics;
 }
-function gateProseNotationInAssessments(assessments) {
+function gateProseNotationInAssessments(assessments, options = {}) {
   const diagnostics = [];
   for (const assessment of assessments) {
     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,
@@ -120,6 +141,7 @@ function gateProseNotationInAssessments(assessments) {
 export {
   gateProseNotation,
   gateProseNotationInAssessments,
+  lessonLine,
   lineOf,
   proseOnly
 };

package/dist/reference/katex-delimiters.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Exported for the test that pins both failure messages — a KaTeX upgrade that
+ * moves the constant, and a leftover `patches/` file, are the two ways this
+ * stops being able to install itself.
+ */
+export function rewriteBundle(source: any): any;
+/**
+ * Render a known nest and confirm the outer pair really is larger than the
+ * inner one. Cheap, and it turns every way this could go wrong — an upstream
+ * refactor, a frozen export, an import that beat us to it — into one loud
+ * failure at the point of installation.
+ */
+export function assertDelimiterGrowth(instance?: typeof katex): void;
+export default katex;
+import katex from 'katex';