explico 0.5.0 → 0.7.0

package/src/reference/delimiter-size.ts

@@ -0,0 +1,301 @@
+/**
+ * Rule N17: nested scalable delimiters must make their hierarchy visible.
+ *
+ * This deliberately parses only sizing syntax. It does not decide whether a
+ * parenthesis, bracket, or brace is semantic, and it never recommends changing
+ * one delimiter shape into another. N16's alternating-shape preference remains
+ * a review-only authoring concern.
+ */
+
+export const DELIMITER_SIZE_DIAGNOSTIC_CODE =
+  'delimiter-size-hierarchy' as const;
+
+export type DelimiterSizeName =
+  | 'automatic'
+  | 'big'
+  | 'Big'
+  | 'bigg'
+  | 'Bigg';
+
+export interface DelimiterSizeSuggestion {
+  readonly size: Exclude<DelimiterSizeName, 'automatic' | 'big'>;
+  readonly open: string;
+  readonly close: string;
+  readonly latex: string;
+}
+
+export interface DelimiterSizeDiagnostic {
+  readonly code: typeof DELIMITER_SIZE_DIAGNOSTIC_CODE;
+  readonly severity: 'warning';
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+  readonly outerSize: DelimiterSizeName;
+  readonly nestedSize: DelimiterSizeName;
+  readonly suggestion?: DelimiterSizeSuggestion;
+  readonly message: string;
+}
+
+type TokenKind = 'open' | 'close';
+type PairKind = 'automatic' | 'manual';
+
+interface SizeSpec {
+  readonly name: DelimiterSizeName;
+  /** `\left` and `\big` can be visually equivalent, so share level 1. */
+  readonly rank: number;
+  readonly openCommand: string;
+  readonly closeCommand: string;
+  readonly kind: PairKind;
+}
+
+interface DelimiterToken {
+  readonly kind: TokenKind;
+  readonly pairKind: PairKind;
+  readonly rank: number;
+  readonly size: DelimiterSizeName;
+  readonly delimiter: string;
+  readonly offset: number;
+  readonly end: number;
+}
+
+interface DelimiterPair {
+  readonly open: DelimiterToken;
+  close?: DelimiterToken;
+  readonly children: DelimiterPair[];
+  requiredRank?: number;
+}
+
+const SIZE_SPECS: readonly SizeSpec[] = [
+  {
+    name: 'automatic',
+    rank: 1,
+    openCommand: '\\left',
+    closeCommand: '\\right',
+    kind: 'automatic',
+  },
+  {
+    name: 'big',
+    rank: 1,
+    openCommand: '\\bigl',
+    closeCommand: '\\bigr',
+    kind: 'manual',
+  },
+  {
+    name: 'Big',
+    rank: 2,
+    openCommand: '\\Bigl',
+    closeCommand: '\\Bigr',
+    kind: 'manual',
+  },
+  {
+    name: 'bigg',
+    rank: 3,
+    openCommand: '\\biggl',
+    closeCommand: '\\biggr',
+    kind: 'manual',
+  },
+  {
+    name: 'Bigg',
+    rank: 4,
+    openCommand: '\\Biggl',
+    closeCommand: '\\Biggr',
+    kind: 'manual',
+  },
+];
+
+interface CommandSpec extends SizeSpec {
+  readonly command: string;
+  readonly tokenKind: TokenKind;
+}
+
+// Longest first prevents `\Biggl` from being considered as `\Bigl`.
+const COMMAND_SPECS: readonly CommandSpec[] = SIZE_SPECS.flatMap((spec) => [
+  { ...spec, command: spec.openCommand, tokenKind: 'open' as const },
+  { ...spec, command: spec.closeCommand, tokenKind: 'close' as const },
+]).sort((left, right) => right.command.length - left.command.length);
+
+const SUGGESTION_BY_RANK = new Map(
+  SIZE_SPECS.filter((spec) => spec.rank >= 2).map((spec) => [spec.rank, spec]),
+);
+
+function delimiterAt(
+  latex: string,
+  offset: number,
+  kind: TokenKind,
+): { delimiter: string; end: number } | undefined {
+  const candidates =
+    kind === 'open'
+      ? (['\\{', '(', '['] as const)
+      : (['\\}', ')', ']'] as const);
+  for (const delimiter of candidates) {
+    if (latex.startsWith(delimiter, offset)) {
+      return { delimiter, end: offset + delimiter.length };
+    }
+  }
+  return undefined;
+}
+
+function tokenAt(latex: string, offset: number): DelimiterToken | undefined {
+  if (latex[offset] !== '\\') return undefined;
+  for (const spec of COMMAND_SPECS) {
+    if (!latex.startsWith(spec.command, offset)) continue;
+    const afterCommand = offset + spec.command.length;
+    // A longer control word such as `\leftarrow` is not `\left`.
+    if (/[A-Za-z]/.test(latex[afterCommand] ?? '')) continue;
+    let delimiterOffset = afterCommand;
+    while (/\s/.test(latex[delimiterOffset] ?? '')) delimiterOffset += 1;
+    const delimiter = delimiterAt(latex, delimiterOffset, spec.tokenKind);
+    if (!delimiter) continue;
+    return {
+      kind: spec.tokenKind,
+      pairKind: spec.kind,
+      rank: spec.rank,
+      size: spec.name,
+      delimiter: delimiter.delimiter,
+      offset,
+      end: delimiter.end,
+    };
+  }
+  return undefined;
+}
+
+function pairMatches(open: DelimiterToken, close: DelimiterToken): boolean {
+  return (
+    open.kind === 'open' &&
+    close.kind === 'close' &&
+    open.pairKind === close.pairKind &&
+    open.rank === close.rank
+  );
+}
+
+function isEscaped(latex: string, offset: number): boolean {
+  let slashes = 0;
+  for (let index = offset - 1; index >= 0 && latex[index] === '\\'; index -= 1) {
+    slashes += 1;
+  }
+  return slashes % 2 === 1;
+}
+
+/**
+ * Build a real nesting tree using an explicit stack. Malformed input is left
+ * to KaTeX's syntax diagnostics; this linter emits no potentially misleading
+ * size advice for a source whose pairs cannot be matched reliably.
+ */
+function parseDelimiterPairs(latex: string): DelimiterPair[] | undefined {
+  const roots: DelimiterPair[] = [];
+  const stack: DelimiterPair[] = [];
+
+  for (let offset = 0; offset < latex.length; offset += 1) {
+    if (latex[offset] === '%' && !isEscaped(latex, offset)) {
+      const newline = latex.indexOf('\n', offset + 1);
+      if (newline === -1) break;
+      offset = newline;
+      continue;
+    }
+    const token = isEscaped(latex, offset) ? undefined : tokenAt(latex, offset);
+    if (!token) continue;
+    offset = token.end - 1;
+
+    if (token.kind === 'open') {
+      const pair: DelimiterPair = { open: token, children: [] };
+      const parent = stack[stack.length - 1];
+      if (parent) parent.children.push(pair);
+      else roots.push(pair);
+      stack.push(pair);
+      continue;
+    }
+
+    const pair = stack[stack.length - 1];
+    if (!pair || !pairMatches(pair.open, token)) return undefined;
+    pair.close = token;
+    stack.pop();
+  }
+
+  return stack.length === 0 ? roots : undefined;
+}
+
+function lineAndColumn(
+  source: string,
+  offset: number,
+): { line: number; column: number } {
+  const before = source.slice(0, offset);
+  const lastNewline = before.lastIndexOf('\n');
+  return {
+    line: before.split('\n').length,
+    column: offset - lastNewline,
+  };
+}
+
+function sizeName(rank: number): DelimiterSizeName {
+  return SUGGESTION_BY_RANK.get(rank)?.name ?? 'Bigg';
+}
+
+function suggestionFor(
+  pair: DelimiterPair,
+  requiredRank: number,
+): DelimiterSizeSuggestion | undefined {
+  const close = pair.close;
+  const spec = SUGGESTION_BY_RANK.get(requiredRank);
+  if (!close || !spec || spec.name === 'automatic' || spec.name === 'big') {
+    return undefined;
+  }
+  return {
+    size: spec.name,
+    open: `${spec.openCommand}${pair.open.delimiter}`,
+    close: `${spec.closeCommand}${close.delimiter}`,
+    latex: `${spec.openCommand}${pair.open.delimiter} ... ${spec.closeCommand}${close.delimiter}`,
+  };
+}
+
+/**
+ * Warn when a scalable outer pair is not at least one manual size level above
+ * everything nested inside it. `\left` and `\big` form the baseline level;
+ * progressively larger levels are `\Big`, `\bigg`, and `\Bigg`.
+ *
+ * Only `()`, `[]`, and `\{\}` are parsed. Bare delimiters are intentionally
+ * ignored: N15 owns that separate error, while ordinary semantic notation
+ * such as `f(x)` and `\mathbb{E}[X]` must not trigger this size-only linter.
+ */
+export function lintDelimiterSizes(latex: string): DelimiterSizeDiagnostic[] {
+  const roots = parseDelimiterPairs(latex);
+  if (!roots) return [];
+  const diagnostics: DelimiterSizeDiagnostic[] = [];
+
+  const assess = (pair: DelimiterPair): number => {
+    let largestNestedRequirement = 0;
+    let representativeNestedSize: DelimiterSizeName = 'automatic';
+    for (const child of pair.children) {
+      const childRequired = assess(child);
+      if (childRequired > largestNestedRequirement) {
+        largestNestedRequirement = childRequired;
+        representativeNestedSize = sizeName(childRequired);
+      }
+    }
+
+    const requiredRank =
+      largestNestedRequirement === 0
+        ? pair.open.rank
+        : largestNestedRequirement + 1;
+    pair.requiredRank = Math.max(pair.open.rank, requiredRank);
+    if (largestNestedRequirement > 0 && pair.open.rank < requiredRank) {
+      const location = lineAndColumn(latex, pair.open.offset);
+      const suggestion = suggestionFor(pair, requiredRank);
+      diagnostics.push({
+        code: DELIMITER_SIZE_DIAGNOSTIC_CODE,
+        severity: 'warning',
+        offset: pair.open.offset,
+        ...location,
+        outerSize: pair.open.size,
+        nestedSize: representativeNestedSize,
+        ...(suggestion ? { suggestion } : {}),
+        message: suggestion
+          ? `Outer delimiters are not larger than their nested pair. Use ${suggestion.latex}; preserve the original opening and closing delimiter shapes (rule N17).`
+          : `Outer delimiters are not larger than their nested pair, and no larger standard manual delimiter size remains. Preserve the original opening and closing shapes and restructure the expression if necessary (rule N17).`,
+      });
+    }
+    return pair.requiredRank;
+  };
+
+  for (const root of roots) assess(root);
+  return diagnostics.sort((left, right) => left.offset - right.offset);
+}

package/src/reference/diagrams-validate.ts

@@ -15,7 +15,7 @@ export type DiagramDiagnosticCode =
 
 export interface DiagramDiagnostic {
   readonly code: DiagramDiagnosticCode;
-  readonly severity: 'error' | 'warning';
+  readonly severity: 'error' | 'warning' | 'info';
   readonly message: string;
   readonly file?: string;
   readonly lessonId?: string;

package/src/reference/equations-validate.ts

@@ -4,7 +4,7 @@
  * - `eq-duplicate-key` (Tier 1, error): an `eq:` key is unique per lesson.
  * - `eq-ref-resolves` (Tier 1, error): every `[[eq-key]]` / `[[slug#eq-key]]`
  *   points at a display equation that carries `\label{eq:key}`.
- * - `eq-key-unused` (Tier 3, warning): a labelled equation never referenced.
+ * - `eq-key-unused` (info): a labelled equation is never referenced.
  *
  * The remark pass enforces the same rules on the render path; this gives the
  * fast `pnpm validate:content` the same coverage and feeds the manifest.
@@ -33,7 +33,7 @@ export type EquationDiagnosticCode =
 
 export interface EquationDiagnostic {
   readonly code: EquationDiagnosticCode;
-  readonly severity: 'error' | 'warning';
+  readonly severity: 'error' | 'warning' | 'info';
   readonly message: string;
   readonly file?: string;
   readonly lessonId?: string;
@@ -154,7 +154,7 @@ export function validateEquations(
     if (referenced.has(`${label.slug}#${label.key}`)) continue;
     diagnostics.push({
       code: 'eq-key-unused',
-      severity: 'warning',
+      severity: 'info',
       message: `${label.lessonId} labels eq:${label.key} (${label.number}) but nothing references it with [[eq-${label.key}]]`,
       file: label.slug,
       lessonId: label.lessonId,

package/src/reference/figures-validate.ts

@@ -15,7 +15,7 @@ export type FigureDiagnosticCode =
 
 export interface FigureDiagnostic {
   readonly code: FigureDiagnosticCode;
-  readonly severity: 'error' | 'warning';
+  readonly severity: 'error' | 'warning' | 'info';
   readonly message: string;
   readonly file?: string;
   readonly lessonId?: string;

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

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ *
+ * `<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.
+ *
+ * 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
+ * build-time gate, which only scans body text, cannot see it.
+ *
+ * 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 type { MathGateDiagnostic } from './gate-math';
+import { lineOf } from './gate-prose-notation';
+import type { NotationLessonInput } from './types';
+
+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',
+  ShortNote: 'title',
+};
+
+interface Finding {
+  readonly index: number;
+  readonly token: string;
+  readonly message: string;
+}
+
+function readAttribute(attributesSource: string, name: string): string | undefined {
+  const pattern = new RegExp(`\\b${name}\\s*=\\s*(["'])([^"']*)\\1`);
+  const match = pattern.exec(attributesSource);
+  return match ? match[2] : undefined;
+}
+
+function overLimitMessage(kind: string, text: string): 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.'
+  );
+}
+
+function headingFindings(text: string): 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) {
+      out.push({
+        index: match.index,
+        token: title,
+        message: overLimitMessage(`${'#'.repeat(level)} heading`, title),
+      });
+    }
+  }
+  return out;
+}
+
+function floatTitleFindings(text: string): Finding[] {
+  const out: Finding[] = [];
+  for (const [tagName, attribute] of Object.entries(TITLE_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) {
+        out.push({
+          index: match.index,
+          token: value,
+          message: overLimitMessage(`<${tagName} ${attribute}>`, value),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/** 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,
+  );
+}
+
+/**
+ * Scan every lesson body for a heading or a keyed float's title running past
+ * `HEADING_LENGTH_LIMIT` characters. Returns one `MathGateDiagnostic`
+ * (context `'structure'`, always an error) per finding.
+ */
+export function gateHeadingLength(
+  lessons: readonly NotationLessonInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const lesson of lessons) {
+    const text = stripFencedCode(lesson.body);
+    for (const finding of findingsIn(text)) {
+      diagnostics.push({
+        context: 'structure',
+        severity: 'error',
+        file: lesson.source.file,
+        line: lineOf(lesson.body, finding.index),
+        token: finding.token,
+        message: finding.message,
+      });
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/gate-math.ts

@@ -7,10 +7,12 @@
  * a single diagnostic shape; `astro build` re-runs the same resolver on the
  * render path as a backstop.
  *
- * Every failure names `file:line: "token"` and the fix.
+ * 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 { stripEquationLabels } from './equations.mjs';
+import { lintDelimiterSizes } from './delimiter-size';
 import { formulaGlyphScope, unknownFormulaScopeKeys } from './gloss';
 import type { GlyphScopeEntry } from './gloss';
 import type {
@@ -20,7 +22,7 @@ import type {
 } from './types';
 
 export interface MathGateDiagnostic {
-  readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation';
+  readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
   /**
    * Body / component-slot math blocks the build (the render path needs every
    * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
@@ -38,11 +40,17 @@ export interface MathGateDiagnostic {
    * same change that introduced the check. `abbreviation` (N14,
    * `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.
+   * 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
+   * diagnostic shape and the one `manifest.diagnostics.math` array rather
+   * than adding a second array the CLI has to know about.
    */
   readonly severity: 'error' | 'warning';
+  readonly code?: string;
   readonly file: string;
   readonly line?: number;
+  readonly column?: number;
   readonly token?: string;
   readonly message: string;
 }
@@ -53,6 +61,7 @@ const SEVERITY: Record<MathGateDiagnostic['context'], 'error' | 'warning'> = {
   assessment: 'error',
   prose: 'error',
   abbreviation: 'error',
+  structure: 'error',
 };
 
 interface AssessmentItemLike {
@@ -87,6 +96,7 @@ function lineOf(text: string, index: number): number {
 interface MathSpan {
   readonly latex: string;
   readonly line: number;
+  readonly column: number;
 }
 
 function mathSpans(body: string): MathSpan[] {
@@ -96,10 +106,14 @@ function mathSpans(body: string): MathSpan[] {
     pattern.lastIndex = 0;
     let match: RegExpExecArray | null;
     while ((match = pattern.exec(searchable))) {
+      const latex = match[1] ?? '';
+      const latexOffset = match.index + match[0].indexOf(latex);
+      const before = body.slice(0, latexOffset);
+      const lastNewline = before.lastIndexOf('\n');
       spans.push({
-        // D7: `\label{eq:…}` is an identity marker, not math KaTeX parses.
-        latex: stripEquationLabels(match[1] ?? ''),
-        line: lineOf(body, match.index),
+        latex,
+        line: lineOf(body, latexOffset),
+        column: latexOffset - lastNewline,
       });
     }
   }
@@ -145,12 +159,34 @@ function resolveInto(
   context: MathGateDiagnostic['context'],
   file: string,
   line: number | undefined,
+  column: number | undefined,
   fix: string,
   out: MathGateDiagnostic[],
 ): void {
+  for (const diagnostic of lintDelimiterSizes(latex)) {
+    const locatedLine =
+      line === undefined ? undefined : line + diagnostic.line - 1;
+    const locatedColumn =
+      column === undefined
+        ? undefined
+        : diagnostic.line === 1
+          ? column + diagnostic.column - 1
+          : diagnostic.column;
+    out.push({
+      context,
+      code: diagnostic.code,
+      severity: 'warning',
+      file,
+      ...(locatedLine === undefined ? {} : { line: locatedLine }),
+      ...(locatedColumn === undefined ? {} : { column: locatedColumn }),
+      message: diagnostic.message,
+    });
+  }
+
   let result;
   try {
-    result = resolveMathGlyphs(latex, [...scope]);
+    // D7: `\label{eq:…}` is an identity marker, not math KaTeX parses.
+    result = resolveMathGlyphs(stripEquationLabels(latex), [...scope]);
   } catch (error) {
     out.push({
       context,
@@ -278,6 +314,7 @@ export function gateContentMath(input: {
         'body',
         file,
         span.line,
+        span.column,
         BODY_FIX,
         diagnostics,
       );
@@ -300,6 +337,7 @@ export function gateContentMath(input: {
         'formula',
         file,
         undefined,
+        undefined,
         FORMULA_FIX,
         diagnostics,
       );
@@ -325,6 +363,7 @@ export function gateContentMath(input: {
       'formula',
       definition.source.file,
       undefined,
+      undefined,
       SHARED_FORMULA_FIX,
       diagnostics,
     );
@@ -353,7 +392,8 @@ export function gateContentMath(input: {
               scope,
               'assessment',
               `${assessmentId} (${item.id ?? '?'})`,
-              undefined,
+              span.line,
+              span.column,
               ASSESSMENT_FIX,
               diagnostics,
             );

package/src/reference/keyed-float-validate.ts

@@ -7,7 +7,7 @@
  * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
  * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
  *   `[[slug#<prefix>-key]]` points at the matching keyed float with that `id`.
- * - `<prefix>-key-unused` (warning): a keyed float never referenced.
+ * - `<prefix>-key-unused` (info): a keyed float is never referenced.
  *
  * `tables-validate.ts`, `figures-validate.ts`, and `diagrams-validate.ts` are
  * thin wrappers over this so callers import a kind-specific validator with
@@ -48,7 +48,7 @@ export interface KeyedFloatRefRecord {
 
 export interface KeyedFloatDiagnostic {
   readonly code: string;
-  readonly severity: 'error' | 'warning';
+  readonly severity: 'error' | 'warning' | 'info';
   readonly message: string;
   readonly file?: string;
   readonly lessonId?: string;
@@ -190,7 +190,7 @@ export function validateKeyedFloats(
     if (referenced.has(`${label.slug}#${label.key}`)) continue;
     diagnostics.push({
       code: `${prefix}-key-unused`,
-      severity: 'warning',
+      severity: 'info',
       message: `${label.lessonId} has a ${noun} id="${label.key}" (${label.number}) but nothing references it with [[${prefix}-${label.key}]]`,
       file: label.slug,
       lessonId: label.lessonId,