explico 0.8.0 → 0.11.0

package/src/reference/gate-heading-length.ts

@@ -1,16 +1,16 @@
 /**
- * The heading/title-length gate (rule S1): no Markdown heading (`##`
- * through `######`) and no `<Figure title>`, `<Diagram label>`, `<Memo
- * title>`, or `<ShortNote title>` may run past `HEADING_LENGTH_LIMIT`
- * characters. A long heading or float title is usually a full sentence that
- * belongs in the body paragraph (for a heading) or the `caption` (for a
- * float) instead — see docs/authoring/structure-rules.md#s1.
+ * The heading/short-caption-length gate (rule S1): no Markdown heading (`##`
+ * through `######`), no `short` caption (`<Figure>`, `<Diagram>`, `<Table>`,
+ * `<Memo>`, `<CompactExamples>`), no display equation's `\caption{…}` and no
+ * `<ShortNote title>` may run past `HEADING_LENGTH_LIMIT` characters. A long
+ * heading or short caption is usually a full sentence that belongs in the
+ * body paragraph (for a heading) or the long `caption` (for a float) instead
+ * — see docs/authoring/structure-rules.md#s1.
  *
- * `<Table>` is deliberately not covered: it has only a `caption`, no
- * separate `title`, and that caption is the LaTeX-convention full sentence
- * shown above the table — capping it would fight the rule that puts it
- * there. `<Figure>`'s `caption` is the same full sentence; only its short
- * `title` (the text on the collapsible title bar) is in scope.
+ * The long `caption` is deliberately never measured: it is the LaTeX
+ * convention's full sentence, shown with the float's number, and capping it
+ * would fight the rule that puts it there. Only the short name a float goes
+ * by away from itself is in scope — the `\caption[short]{…}` half.
  *
  * A lesson's own `#` (its `frontmatter.title`, rendered as the page H1 by
  * Starlight) is Review-only — it never appears in `lesson.body`, so this
@@ -19,26 +19,33 @@
  * Ships straight as an error, same as N9/N14: no partial corpus to absorb,
  * no `lint-ignore.yml` entry.
  */
-import { stripFencedCode } from './equations.mjs';
+import { EQ_CAPTION_PATTERN, stripFencedCode } from './equations.mjs';
+import { stripHeadingMarker } from './rehype-heading-anchors.mjs';
 import type { MathGateDiagnostic } from './gate-math';
 import { lessonLine } from './gate-prose-notation';
 import type { NotationLessonInput } from './types';
 
+/** Rule S1's default; a course sets its own with `rules.S1.maxLength`. */
 export const HEADING_LENGTH_LIMIT = 65;
 
 // ATX heading: 1-6 `#`, then the text, with any trailing closing `#`s
 // trimmed off (the `# text #` form CommonMark also allows).
 const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
 
-// The JSX attribute that reads as a float's own short title, per component.
-// `Table` has no entry — see the module doc comment.
-const TITLE_ATTRIBUTE_BY_TAG: Record<string, string> = {
-  Figure: 'title',
-  Diagram: 'label',
-  Memo: 'title',
+// The JSX attribute that holds a component's short name, per component: the
+// `short` caption of the caption pair, and a short note's inline link text.
+const SHORT_ATTRIBUTE_BY_TAG: Record<string, string> = {
+  Figure: 'short',
+  Diagram: 'short',
+  Table: 'short',
+  Memo: 'short',
+  CompactExamples: 'short',
   ShortNote: 'title',
 };
 
+// A display equation's `\caption{…}` (its short caption).
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
+
 interface Finding {
   readonly index: number;
   readonly token: string;
@@ -51,44 +58,63 @@ function readAttribute(attributesSource: string, name: string): string | undefin
   return match ? match[2] : undefined;
 }
 
-function overLimitMessage(kind: string, text: string): string {
+function overLimitMessage(kind: string, text: string, limit: number): string {
   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.'
+    `${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: string): Finding[] {
+function headingFindings(text: string, limit: number): Finding[] {
   const out: Finding[] = [];
   const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
   let match: RegExpExecArray | null;
   while ((match = re.exec(text))) {
     const level = match[1]?.length ?? 1;
-    const title = (match[2] ?? '').trim();
-    if (title.length > HEADING_LENGTH_LIMIT) {
+    // What the reader sees: `[collapsed]`, `[card]` and the like never render.
+    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: string): Finding[] {
+function floatTitleFindings(text: string, limit: number): Finding[] {
   const out: Finding[] = [];
-  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: RegExpExecArray | null;
     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 equationCaptionFindings(text: string, limit: number): Finding[] {
+  const out: Finding[] = [];
+  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),
         });
       }
     }
@@ -97,27 +123,32 @@ function floatTitleFindings(text: string): Finding[] {
 }
 
 /** Every S1 finding in one lesson body, in source order. */
-function findingsIn(text: string): Finding[] {
-  return [...headingFindings(text), ...floatTitleFindings(text)].sort(
-    (a, b) => a.index - b.index,
-  );
+function findingsIn(text: string, limit: number): Finding[] {
+  return [
+    ...headingFindings(text, limit),
+    ...floatTitleFindings(text, limit),
+    ...equationCaptionFindings(text, limit),
+  ].sort((a, b) => a.index - b.index);
 }
 
 /**
- * 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.
  */
 export function gateHeadingLength(
   lessons: readonly NotationLessonInput[],
+  options: { readonly maxLength?: number } = {},
 ): MathGateDiagnostic[] {
   const diagnostics: MathGateDiagnostic[] = [];
+  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/src/reference/gate-heading-structure.ts

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import { lessonLine } from './gate-prose-notation';
+import { scanOutlineBlocks } from './sections.mjs';
+import type { NotationLessonInput } from './types';
+
+/**
+ * Components that open with a title of their own, drawn where the tag stands.
+ * `level` is the `<hN>` a component renders, when it renders a real heading
+ * (rule S6 steps from it); `what` finishes a rule S7 message.
+ */
+const TITLED_COMPONENTS: Readonly<Record<string, { readonly level?: number; readonly what: string }>> = {
+  AssessmentSet: {
+    level: 2,
+    what: 'which renders its own `<h2>`: the “Knowledge check” badge, its number and the check’s title',
+  },
+  CompactExamples: {
+    level: 2,
+    what: 'which renders its own `<h2>`: the “Example” badge, its number and the set’s `short` title',
+  },
+};
+
+type Block =
+  | {
+      readonly kind: 'heading';
+      readonly level: number;
+      /** How a message names it: `` `## Title` ``. */
+      readonly label: string;
+      readonly token: string;
+      readonly index: number;
+    }
+  | { readonly kind: 'titled'; readonly name: string; readonly index: number; readonly level?: number }
+  | { readonly kind: 'content' };
+
+function blocksOf(body: string): Block[] {
+  return scanOutlineBlocks(body).map((block): 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 === undefined ? {} : { level: titled.level }),
+        };
+      }
+    }
+    return { kind: 'content' };
+  });
+}
+
+interface Finding {
+  readonly code: 'heading-skip' | 'heading-adjacent';
+  readonly index: number;
+  readonly token: string;
+  readonly message: string;
+}
+
+/** Rule S6: every heading steps down at most one level from the one before. */
+function skipFindings(blocks: readonly Block[]): Finding[] {
+  const out: Finding[] = [];
+  // The page title is the `<h1>` above the body.
+  let previous: { level: number; label: string } = { level: 1, label: 'the page title (`#`)' };
+  for (const block of blocks) {
+    if (block.kind === 'content') continue;
+    if (block.kind === 'titled') {
+      if (block.level !== undefined) {
+        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’s one `#`: the body’s 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;
+}
+
+/** Rule S7: a heading is followed by body content before the next heading. */
+function adjacentFindings(blocks: readonly Block[], lesson: NotationLessonInput): Finding[] {
+  const out: Finding[] = [];
+  blocks.forEach((block, position) => {
+    if (block.kind !== 'heading') return;
+    const next = blocks[position + 1];
+    if (next === undefined || 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;
+}
+
+/**
+ * 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.
+ */
+export function gateHeadingStructure(
+  lessons: readonly NotationLessonInput[],
+  options: { readonly levels?: boolean; readonly adjacency?: boolean } = {},
+): MathGateDiagnostic[] {
+  const { levels = true, adjacency = true } = options;
+  const diagnostics: MathGateDiagnostic[] = [];
+  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;
+}