explico 0.8.0 → 0.11.0

package/dist/reference/examples-validate.d.ts

@@ -0,0 +1,31 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/**
+ * `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.
+ */
+
+type ExampleDiagnosticCode = 'ex-invalid-key' | 'ex-duplicate-key' | 'ex-ref-resolves' | 'ex-key-unused' | 'ex-removed-prop' | 'ex-missing-prop';
+interface ExampleDiagnostic {
+    readonly code: ExampleDiagnosticCode;
+    readonly severity: 'error' | 'warning' | 'info';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type ExampleLabelRecord = KeyedFloatLabelRecord;
+type ExampleLessonInput = KeyedFloatLessonInput;
+interface ExampleValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly ExampleDiagnostic[];
+}
+declare function validateExamples(lessons: readonly ExampleLessonInput[]): ExampleValidation;
+
+export { type ExampleDiagnostic, type ExampleDiagnosticCode, type ExampleLabelRecord, type ExampleLessonInput, type ExampleValidation, validateExamples };

package/dist/reference/examples-validate.js

@@ -0,0 +1,48 @@
+import {
+  validateKeyedFloats
+} from "./keyed-float-validate.js";
+import { scanKeyedJsxFloats } from "./keyed-jsx-floats.mjs";
+const REQUIRED_PROPS = {
+  id: "give it an `id` (lowercase letters, digits and hyphens): the set is anchored `#ex-\u2039id\u203A` and cited with `[[ex-\u2039id\u203A]]`.",
+  short: 'give it a `short` title naming the topic, e.g. "Converting between coordinate systems"; the engine draws "Example" and the number before it.'
+};
+function validateExamples(lessons) {
+  const shared = validateKeyedFloats(lessons, {
+    tagName: "CompactExamples",
+    prefix: "ex",
+    noun: "worked-example set",
+    removedProps: {
+      summary: 'rename it `short`: the set\u2019s topical title, shown after the engine\u2019s "Example" badge.'
+    }
+  });
+  const missing = [];
+  for (const lesson of lessons) {
+    const sets = scanKeyedJsxFloats(lesson.body, {
+      tagName: "CompactExamples",
+      numbering: lesson.numbering
+    });
+    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,
+    ...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 };
+}
+export {
+  validateExamples
+};

package/dist/reference/figures-validate.d.ts

@@ -2,7 +2,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 
 /** `validateKeyedFloats` for `<Figure>` — see `keyed-float-validate.ts`. */
 
-type FigureDiagnosticCode = 'fig-invalid-key' | 'fig-duplicate-key' | 'fig-ref-resolves' | 'fig-key-unused';
+type FigureDiagnosticCode = 'fig-invalid-key' | 'fig-duplicate-key' | 'fig-ref-resolves' | 'fig-key-unused' | 'fig-removed-prop';
 interface FigureDiagnostic {
     readonly code: FigureDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/figures-validate.js

@@ -5,7 +5,10 @@ function validateFigures(lessons) {
   return validateKeyedFloats(lessons, {
     tagName: "Figure",
     prefix: "fig",
-    noun: "figure"
+    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`."
+    }
   });
 }
 export {

package/dist/reference/folds-validate.d.ts

@@ -0,0 +1,33 @@
+import { KeyedFloatLessonInput } from './keyed-float-validate.js';
+
+/**
+ * `<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.
+ */
+
+type FoldDiagnosticCode = 'fold-unnamed';
+interface FoldDiagnostic {
+    readonly code: FoldDiagnosticCode;
+    readonly severity: 'error';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+}
+interface FoldValidation {
+    readonly diagnostics: readonly FoldDiagnostic[];
+}
+declare function validateFolds(lessons: readonly KeyedFloatLessonInput[]): FoldValidation;
+
+export { type FoldDiagnostic, type FoldDiagnosticCode, type FoldValidation, validateFolds };

package/dist/reference/folds-validate.js

@@ -0,0 +1,32 @@
+import { stripFencedCode } from "./equations.mjs";
+import { scanKeyedJsxFloats } from "./keyed-jsx-floats.mjs";
+const ATTRIBUTES = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const FOLD = new RegExp(`<Fold\\b(${ATTRIBUTES})>([\\s\\S]*?)<\\/Fold\\s*>`, "g");
+const NUMBERED_FLOATS = ["Figure", "Table", "Diagram"];
+function validateFolds(lessons) {
+  const diagnostics = [];
+  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: void 0 }).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 };
+}
+export {
+  validateFolds
+};

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

@@ -1,6 +1,8 @@
 import { MathGateDiagnostic } from './gate-math.js';
 import { NotationRegistryInput, AbbreviationDefinitionInput } from './types.js';
-import { CourseAbbreviations } from '../compiler/course-config.js';
+import { a as CourseAbbreviations } from '../course-config-Dsnri9Tk.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
 
 /**
  * Scan every lesson body for an abbreviation-shaped token outside `$…$` that

package/dist/reference/gate-abbreviations.js

@@ -49,6 +49,7 @@ function gateAbbreviations(input) {
       reported.add(token);
       diagnostics.push({
         context: "abbreviation",
+        code: "abbreviation-unexplained",
         severity: "error",
         file: lesson.source.file,
         line: lessonLine(lesson, index),

package/dist/reference/gate-course-rules.d.ts

@@ -0,0 +1,32 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+import { CourseRule } from '../rules/course-rules.js';
+import '../rules/catalog.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function gateCourseRules(lessons: readonly NotationLessonInput[], rules: readonly CourseRule[]): MathGateDiagnostic[];
+
+export { gateCourseRules };

package/dist/reference/gate-course-rules.js

@@ -0,0 +1,85 @@
+import { lessonLine, proseOnly } from "./gate-prose-notation.js";
+const HEADING = /^[ \t]{0,3}(#{1,6})[ \t]+(.*)$/;
+function paragraphs(text) {
+  const units = [];
+  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 !== "");
+}
+function headings(text) {
+  const units = [];
+  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, prose) {
+  switch (scope) {
+    case "prose":
+      return [{ text: prose, index: 0 }];
+    case "heading":
+      return headings(prose);
+    case "paragraph":
+      return paragraphs(prose);
+  }
+}
+function* matches(pattern, unit) {
+  const regex = new RegExp(pattern.pattern, `${pattern.flags}g`);
+  let match;
+  while ((match = regex.exec(unit.text)) !== null) {
+    yield [unit.index + match.index, match[0]];
+    if (match.index === regex.lastIndex) regex.lastIndex += 1;
+  }
+}
+function gateCourseRules(lessons, rules) {
+  const active = rules.filter((rule) => rule.enabled && rule.forbid.length > 0);
+  if (active.length === 0) return [];
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    const prose = proseOnly(lesson.body);
+    const cache = /* @__PURE__ */ new Map();
+    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;
+}
+export {
+  gateCourseRules
+};

package/dist/reference/gate-heading-length.d.ts

@@ -1,12 +1,15 @@
 import { MathGateDiagnostic } from './gate-math.js';
 import { NotationLessonInput } from './types.js';
 
+/** Rule S1's default; a course sets its own with `rules.S1.maxLength`. */
 declare const HEADING_LENGTH_LIMIT = 65;
 /**
- * Scan every lesson body for a heading or a keyed float's title running past
+ * Scan every lesson body for a heading or a short caption running past
  * `HEADING_LENGTH_LIMIT` characters. Returns one `MathGateDiagnostic`
  * (context `'structure'`, always an error) per finding.
  */
-declare function gateHeadingLength(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+declare function gateHeadingLength(lessons: readonly NotationLessonInput[], options?: {
+    readonly maxLength?: number;
+}): MathGateDiagnostic[];
 
 export { HEADING_LENGTH_LIMIT, gateHeadingLength };

package/dist/reference/gate-heading-length.js

@@ -1,68 +1,92 @@
-import { stripFencedCode } from "./equations.mjs";
+import { EQ_CAPTION_PATTERN, stripFencedCode } from "./equations.mjs";
+import { stripHeadingMarker } from "./rehype-heading-anchors.mjs";
 import { lessonLine } from "./gate-prose-notation.js";
 const HEADING_LENGTH_LIMIT = 65;
 const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
-const TITLE_ATTRIBUTE_BY_TAG = {
-  Figure: "title",
-  Diagram: "label",
-  Memo: "title",
+const SHORT_ATTRIBUTE_BY_TAG = {
+  Figure: "short",
+  Diagram: "short",
+  Table: "short",
+  Memo: "short",
+  CompactExamples: "short",
   ShortNote: "title"
 };
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
 function readAttribute(attributesSource, name) {
   const pattern = new RegExp(`\\b${name}\\s*=\\s*(["'])([^"']*)\\1`);
   const match = pattern.exec(attributesSource);
   return match ? match[2] : void 0;
 }
-function overLimitMessage(kind, text) {
-  return `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ${HEADING_LENGTH_LIMIT}-character limit (rule S1). Shorten it and move the rest into the paragraph or caption that follows.`;
+function overLimitMessage(kind, text, limit) {
+  return `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ${limit}-character limit (rule S1, rules.S1.maxLength in the course settings). Shorten it and move the rest into the paragraph or caption that follows.`;
 }
-function headingFindings(text) {
+function headingFindings(text, limit) {
   const out = [];
   const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
   let match;
   while (match = re.exec(text)) {
     const level = match[1]?.length ?? 1;
-    const title = (match[2] ?? "").trim();
-    if (title.length > HEADING_LENGTH_LIMIT) {
+    const title = stripHeadingMarker(match[2] ?? "").trim();
+    if (title.length > limit) {
       out.push({
         index: match.index,
         token: title,
-        message: overLimitMessage(`${"#".repeat(level)} heading`, title)
+        message: overLimitMessage(`${"#".repeat(level)} heading`, title, limit)
       });
     }
   }
   return out;
 }
-function floatTitleFindings(text) {
+function floatTitleFindings(text, limit) {
   const out = [];
-  for (const [tagName, attribute] of Object.entries(TITLE_ATTRIBUTE_BY_TAG)) {
+  for (const [tagName, attribute] of Object.entries(SHORT_ATTRIBUTE_BY_TAG)) {
     const opening = new RegExp(`<${tagName}\\b([^>]*)>`, "g");
     let match;
     while (match = opening.exec(text)) {
       const value = readAttribute(match[1] ?? "", attribute)?.trim();
-      if (value && value.length > HEADING_LENGTH_LIMIT) {
+      if (value && value.length > limit) {
         out.push({
           index: match.index,
           token: value,
-          message: overLimitMessage(`<${tagName} ${attribute}>`, value)
+          message: overLimitMessage(`<${tagName} ${attribute}>`, value, limit)
         });
       }
     }
   }
   return out;
 }
-function findingsIn(text) {
-  return [...headingFindings(text), ...floatTitleFindings(text)].sort(
-    (a, b) => a.index - b.index
-  );
+function equationCaptionFindings(text, limit) {
+  const out = [];
+  for (const display of text.matchAll(DISPLAY_MATH)) {
+    for (const caption of (display[1] ?? "").matchAll(EQ_CAPTION_PATTERN)) {
+      const value = (caption[1] ?? "").replace(/\s+/g, " ").trim();
+      if (value.length > limit) {
+        out.push({
+          index: (display.index ?? 0) + 2 + (caption.index ?? 0),
+          token: value,
+          message: overLimitMessage("Equation \\caption{}", value, limit)
+        });
+      }
+    }
+  }
+  return out;
+}
+function findingsIn(text, limit) {
+  return [
+    ...headingFindings(text, limit),
+    ...floatTitleFindings(text, limit),
+    ...equationCaptionFindings(text, limit)
+  ].sort((a, b) => a.index - b.index);
 }
-function gateHeadingLength(lessons) {
+function gateHeadingLength(lessons, options = {}) {
   const diagnostics = [];
+  const limit = options.maxLength ?? HEADING_LENGTH_LIMIT;
   for (const lesson of lessons) {
     const text = stripFencedCode(lesson.body);
-    for (const finding of findingsIn(text)) {
+    for (const finding of findingsIn(text, limit)) {
       diagnostics.push({
         context: "structure",
+        code: "title-length",
         severity: "error",
         file: lesson.source.file,
         line: lessonLine(lesson, finding.index),

package/dist/reference/gate-heading-structure.d.ts

@@ -0,0 +1,41 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+
+/**
+ * The heading-structure gate: rules S6 and S7, over a lesson's outline — the
+ * top-level headings `sections.mjs` numbers, read by the same
+ * `scanOutlineBlocks`, so the rules and the section numbers can never
+ * disagree about which headings a page has. A heading inside a component
+ * (`<Memo>`, `<CompactExample>`, …) belongs to that component and is in
+ * neither. See docs/authoring/structure-rules.md#s6 and #s7.
+ *
+ * - **S6 (`heading-skip`)** — headings descend one level at a time. The page
+ *   title (`frontmatter.title`) is the lesson's one `#`, so the body starts at
+ *   `##`, a `#` in the body is an error, and a heading is at most one level
+ *   deeper than the one before it. Going back up any number of levels is fine.
+ * - **S7 (`heading-adjacent`)** — a heading is followed by body content,
+ *   never directly by another heading, whatever the two levels.
+ *
+ * Both also see the headings a component draws where its tag stands
+ * ({@link TITLED_COMPONENTS}): a knowledge check's and a worked-example set's
+ * `<h2>` (`BlockHeading.astro`) read as a `##`, so a heading written directly
+ * above either is two headings in a row, and the next heading steps from
+ * `##`.
+ *
+ * Ships straight as an error, same as S1: every playground violation was fixed
+ * or waived in the same change.
+ */
+
+/**
+ * Scan every lesson body's outline for rule S6 (`heading-skip`) and rule S7
+ * (`heading-adjacent`) findings. `levels` / `adjacency` switch each rule's
+ * half off, the way `rules.S6.enabled` / `rules.S7.enabled` do. Returns one
+ * `MathGateDiagnostic` (context `'structure'`, always an error) per finding,
+ * located at the heading that breaks the rule.
+ */
+declare function gateHeadingStructure(lessons: readonly NotationLessonInput[], options?: {
+    readonly levels?: boolean;
+    readonly adjacency?: boolean;
+}): MathGateDiagnostic[];
+
+export { gateHeadingStructure };

package/dist/reference/gate-heading-structure.js

@@ -0,0 +1,113 @@
+import { lessonLine } from "./gate-prose-notation.js";
+import { scanOutlineBlocks } from "./sections.mjs";
+const TITLED_COMPONENTS = {
+  AssessmentSet: {
+    level: 2,
+    what: "which renders its own `<h2>`: the \u201CKnowledge check\u201D badge, its number and the check\u2019s title"
+  },
+  CompactExamples: {
+    level: 2,
+    what: "which renders its own `<h2>`: the \u201CExample\u201D badge, its number and the set\u2019s `short` title"
+  }
+};
+function blocksOf(body) {
+  return scanOutlineBlocks(body).map((block) => {
+    if (block.kind === "heading") {
+      const hashes = "#".repeat(block.level);
+      return {
+        kind: "heading",
+        level: block.level,
+        label: `\`${hashes} ${block.text}\``,
+        token: block.text,
+        index: block.index
+      };
+    }
+    if (block.kind === "element") {
+      const titled = TITLED_COMPONENTS[block.name];
+      if (titled) {
+        return {
+          kind: "titled",
+          name: block.name,
+          index: block.index,
+          ...titled.level === void 0 ? {} : { level: titled.level }
+        };
+      }
+    }
+    return { kind: "content" };
+  });
+}
+function skipFindings(blocks) {
+  const out = [];
+  let previous = { level: 1, label: "the page title (`#`)" };
+  for (const block of blocks) {
+    if (block.kind === "content") continue;
+    if (block.kind === "titled") {
+      if (block.level !== void 0) {
+        previous = { level: block.level, label: `the \`<h${block.level}>\` of \`<${block.name} />\`` };
+      }
+      continue;
+    }
+    if (block.level === 1) {
+      out.push({
+        code: "heading-skip",
+        index: block.index,
+        token: block.token,
+        message: `${block.label} is a \`#\` in the lesson body, but the page title (\`frontmatter.title\`) is the lesson\u2019s one \`#\`: the body\u2019s headings start at \`##\` (rule S6). Make it \`##\`, or move the text into the title.`
+      });
+    } else if (block.level > previous.level + 1) {
+      const expected = "#".repeat(previous.level + 1);
+      out.push({
+        code: "heading-skip",
+        index: block.index,
+        token: block.token,
+        message: `${block.label} follows ${previous.label}, skipping a level: headings descend one level at a time (rule S6). Make it \`${expected}\`, or add the \`${expected}\` section it belongs under.`
+      });
+    }
+    previous = { level: block.level, label: block.label };
+  }
+  return out;
+}
+function adjacentFindings(blocks, lesson) {
+  const out = [];
+  blocks.forEach((block, position) => {
+    if (block.kind !== "heading") return;
+    const next = blocks[position + 1];
+    if (next === void 0 || next.kind === "content") return;
+    const line = lessonLine(lesson, next.index);
+    const followedBy = next.kind === "heading" ? `${next.label} (line ${line})` : `\`<${next.name}>\` (line ${line}), ${TITLED_COMPONENTS[next.name].what}`;
+    out.push({
+      code: "heading-adjacent",
+      index: block.index,
+      token: block.token,
+      message: `${block.label} is followed directly by ${followedBy}: a heading is followed by body content, never by another heading (rule S7). Write what the section is about before it goes on, or drop the heading that says nothing of its own.`
+    });
+  });
+  return out;
+}
+function gateHeadingStructure(lessons, options = {}) {
+  const { levels = true, adjacency = true } = options;
+  const diagnostics = [];
+  if (!levels && !adjacency) return diagnostics;
+  for (const lesson of lessons) {
+    const blocks = blocksOf(lesson.body);
+    const findings = [
+      ...levels ? skipFindings(blocks) : [],
+      ...adjacency ? adjacentFindings(blocks, lesson) : []
+    ].sort((a, b) => a.index - b.index);
+    for (const finding of findings) {
+      diagnostics.push({
+        context: "structure",
+        code: finding.code,
+        severity: "error",
+        file: lesson.source.file,
+        line: lessonLine(lesson, finding.index),
+        token: finding.token,
+        message: finding.message
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  gateHeadingStructure
+};

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

@@ -0,0 +1,71 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+
+/**
+ * The trailing-punctuation gate (rule N12): math never ends in the sentence's
+ * own `.`, `,`, `;` or `:`. It runs from the CLI alongside the completeness
+ * gate (`gate-math.ts`) over the same spans (`mathSpans`: every `$…$` /
+ * `$$…$$` in a lesson body, including table cells and component slots, and in
+ * an assessment item's `prompt` / `explanation`), and shares its
+ * `MathGateDiagnostic` shape and output array.
+ *
+ * "Ends" is read the way a reader sees it, not the raw source: trailing
+ * spacing (`\,`, `\quad`), `\label{…}` / `\caption{…}` / `\tag{…}`, a row break `\\`, an
+ * `\end{…}`, and the invisible delimiter `\right.` are looked through, and a
+ * closing `\text{…}` / `\mathrm{…}` is looked into — so `5\ \text{m,}` and
+ * `c &= d. \end{aligned}` are both caught. Every row of a multi-line block
+ * (the text before each `\\`) is checked the same way.
+ *
+ * Two shapes are called out by name because they look like notation: a
+ * trailing decimal point (`5.`) — a precision marker that cannot be told
+ * apart from the full stop, so it is never allowed — and a typed `...`
+ * (write `\ldots`). The one exception is a dotted abbreviation set upright
+ * that is itself notation (`+ \text{h.c.}`, `X_n \to X\ \text{a.s.}`): the
+ * shipped {@link MATH_END_ABBREVIATIONS}, edited per course with
+ * `rules.N12.allow` / `deny`.
+ */
+
+interface AssessmentItemLike {
+    readonly id?: string;
+    readonly prompt?: string;
+    readonly explanation?: string;
+}
+interface AssessmentLike {
+    readonly id: string;
+    readonly items?: readonly AssessmentItemLike[];
+}
+/** Dotted abbreviations that are notation, so they may end math (`\text{h.c.}`). */
+declare const MATH_END_ABBREVIATIONS: readonly string[];
+interface MathPunctuationOptions {
+    /** Abbreviations allowed in addition to {@link MATH_END_ABBREVIATIONS}. */
+    readonly allow?: readonly string[];
+    /** Shipped abbreviations this course does not accept. */
+    readonly deny?: readonly string[];
+}
+interface PunctuationFinding {
+    /** Index of the mark in the LaTeX. */
+    readonly index: number;
+    readonly mark: string;
+    readonly kind: 'sentence' | 'decimal' | 'ellipsis' | 'abbreviation';
+    /** True when the mark ends a row (text before a `\\`), not the whole span. */
+    readonly rowEnd: boolean;
+    /** The upright dotted word the mark closes (`etc.`), for `abbreviation`. */
+    readonly word?: string;
+}
+/** Every N12 finding in one span of LaTeX (the text between the `$` delimiters). */
+declare function trailingPunctuation(latex: string, options?: MathPunctuationOptions): PunctuationFinding[];
+/**
+ * Scan every lesson body's math for the sentence's own trailing punctuation.
+ * One error per mark, located at the mark itself, so a per-place waiver
+ * (`{/* explico-allow N12: reason *\/}`) can cover it.
+ */
+declare function gateMathPunctuation(lessons: readonly NotationLessonInput[], options?: MathPunctuationOptions): MathGateDiagnostic[];
+/**
+ * The same check over every assessment item's `prompt` / `explanation`, which
+ * render through the same KaTeX pipeline as lesson math. No line number: the
+ * item is one JSON string field, so `file` names the item, the same
+ * `"<assessmentId> (<itemId>)"` shape `gate-math.ts` uses.
+ */
+declare function gateMathPunctuationInAssessments(assessments: readonly AssessmentLike[], options?: MathPunctuationOptions): MathGateDiagnostic[];
+
+export { MATH_END_ABBREVIATIONS, type MathPunctuationOptions, type PunctuationFinding, gateMathPunctuation, gateMathPunctuationInAssessments, trailingPunctuation };