explico 0.7.0 → 0.11.0

package/src/compiler/cli.ts

@@ -49,8 +49,16 @@ import remarkNotation, {
 } from '../reference/remark-notation.mjs';
 import remarkShortNote from '../reference/remark-short-note.mjs';
 import type { DiagnosticSeverity } from '../reference/types';
+import type { EquationLink } from '../reference/gate-math';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
+import { isCourseRuleId, ownerOf, ELEMENTS, type Element, type Enforcement } from '../rules/catalog';
+import {
+  renderRulesInEffect,
+  rulesInEffect,
+  type RuleInEffect,
+  type RulesFilter,
+} from '../rules/in-effect';
 
 const REPOSITORY_ROOT = process.cwd();
 // Content and its course math are the top-level `content/` folder (Phase F).
@@ -85,17 +93,45 @@ export class ContentCliError extends Error {
 /** One normalized diagnostic. `code` is `<source>:<kind>` and always stable. */
 export interface CliDiagnostic {
   readonly code: string;
+  /**
+   * The catalog entry that owns the code — a rule ID (`N9`) or an invariant
+   * slug (`keyed-floats`). Absent only for a code the catalog does not know,
+   * which `tests/rules/catalog.test.ts` treats as a bug.
+   */
+  readonly rule?: string;
   readonly severity: DiagnosticSeverity;
   readonly message: string;
   readonly file?: string;
   readonly line?: number;
   readonly column?: number;
+  /**
+   * The keyed equation the finding sits in, when the math carries a
+   * `\label{eq:…}` — `{ key, href }`, the href being the anchor on the
+   * rendered page. A size-only finding inside a long `aligned` block is
+   * otherwise anonymous.
+   */
+  readonly equation?: EquationLink;
 }
 
 function diagnosticSeverity(value: unknown): DiagnosticSeverity {
   return value === 'info' || value === 'warning' ? value : 'error';
 }
 
+/**
+ * `{ rule }` for a `<source>:<code>` (or bare) code the catalog owns — or for a
+ * course rule, whose code is its own ID (`X1`).
+ */
+function ownerFields(code: string): { readonly rule?: string } {
+  const bare = code.slice(code.indexOf(':') + 1);
+  const owner = ownerOf(bare);
+  if (owner !== undefined) return { rule: owner.id };
+  return isCourseRuleId(bare) ? { rule: bare } : {};
+}
+
+function withOwner(diagnostic: CliDiagnostic): CliDiagnostic {
+  return { ...diagnostic, ...ownerFields(diagnostic.code) };
+}
+
 function mentions(message: string, lessonId: string, file: string): boolean {
   return (
     message.includes(lessonId) ||
@@ -159,12 +195,15 @@ export function lessonDiagnostics(
         ));
     if (!forLesson) continue;
     out.push({
-      code: `math:${diagnostic.code ?? diagnostic.context}`,
+      code: `math:${diagnostic.code}`,
       severity: diagnostic.severity,
       message: diagnostic.message,
       file: diagnostic.file,
       ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
       ...(diagnostic.column === undefined ? {} : { column: diagnostic.column }),
+      ...(diagnostic.equation === undefined
+        ? {}
+        : { equation: diagnostic.equation }),
     });
   }
 
@@ -189,6 +228,8 @@ export function lessonDiagnostics(
     ...manifest.diagnostics.figures,
     ...manifest.diagnostics.diagrams,
     ...manifest.diagnostics.checks,
+    ...manifest.diagnostics.examples,
+    ...manifest.diagnostics.folds,
     ...manifest.diagnostics.rawFloats,
   ]) {
     if (
@@ -216,10 +257,12 @@ export function lessonDiagnostics(
     });
   }
 
-  return out.sort(
-    (a, b) =>
-      a.code.localeCompare(b.code) || a.message.localeCompare(b.message),
-  );
+  return out
+    .map(withOwner)
+    .sort(
+      (a, b) =>
+        a.code.localeCompare(b.code) || a.message.localeCompare(b.message),
+    );
 }
 
 // --- renderability -------------------------------------------------------
@@ -501,6 +544,7 @@ export interface StatusReport {
     readonly keyedTables: number;
     readonly keyedFigures: number;
     readonly keyedDiagrams: number;
+    readonly keyedExamples: number;
   };
   readonly draftDebt: {
     readonly lessons: readonly string[];
@@ -528,6 +572,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
     .filter((diagnostic) => diagnostic.code === 'unused-definition')
     .map((diagnostic) => ({
       code: `notation:${diagnostic.code}`,
+      ...ownerFields(diagnostic.code),
       severity: diagnosticSeverity(diagnostic.severity),
       message: diagnostic.message,
       ...(diagnostic.source?.file === undefined
@@ -546,9 +591,13 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.figures.map((d) => d.severity),
     ...manifest.diagnostics.diagrams.map((d) => d.severity),
     ...manifest.diagnostics.checks.map((d) => d.severity),
+    ...manifest.diagnostics.examples.map((d) => d.severity),
+    ...manifest.diagnostics.folds.map((d) => d.severity),
     ...manifest.diagnostics.rawFloats.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map((d) => d.severity),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
+    ...manifest.diagnostics.config.map((d) => d.severity),
+    ...manifest.diagnostics.waivers.map((d) => d.severity),
   ];
 
   const keyedEquations = manifest.lessons.reduce(
@@ -567,6 +616,10 @@ export function contentStatus(manifest: Manifest): StatusReport {
     (count, lesson) => count + lesson.diagrams.length,
     0,
   );
+  const keyedExamples = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.examples.length,
+    0,
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
@@ -584,6 +637,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
       keyedTables,
       keyedFigures,
       keyedDiagrams,
+      keyedExamples,
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -621,8 +675,18 @@ type DiagnosticRecord = Record<string, unknown> & {
   readonly line?: unknown;
   readonly column?: unknown;
   readonly source?: unknown;
+  readonly equation?: unknown;
 };
 
+/** `{ key, href }` as it survives the untyped manifest walk above. */
+function equationLink(value: unknown): EquationLink | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const { key, href } = value as Record<string, unknown>;
+  return typeof key === 'string' && typeof href === 'string'
+    ? { key, href }
+    : undefined;
+}
+
 function numericLocation(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isInteger(value) && value > 0
     ? value
@@ -685,13 +749,16 @@ export function contentDiagnostics(
           : typeof diagnostic.kind === 'string'
             ? diagnostic.kind
             : 'diagnostic';
+      const equation = equationLink(diagnostic.equation);
       diagnostics.push({
         code: `${group}:${detail}`,
+        ...ownerFields(detail),
         severity,
         message: String(diagnostic.message ?? detail),
         ...(file === undefined ? {} : { file }),
         ...(line === undefined ? {} : { line }),
         ...(column === undefined ? {} : { column }),
+        ...(equation === undefined ? {} : { equation }),
       });
     }
   }
@@ -719,6 +786,61 @@ export function contentWarnings(manifest: Manifest): WarningsReport {
   return { count: warnings.length, warnings };
 }
 
+// --- content rules -------------------------------------------------------
+
+export interface RulesReport {
+  readonly filter: RulesFilter;
+  readonly count: number;
+  readonly rules: readonly RuleInEffect[];
+  /** The same selection as the page `validate:content` writes. */
+  readonly markdown: string;
+}
+
+/**
+ * Parse `--element a,b` / `--enforcement script` into a filter, throwing a
+ * usage error on a value outside the vocabulary.
+ */
+export function parseRulesFilter(input: {
+  readonly element?: string;
+  readonly enforcement?: string;
+}): RulesFilter {
+  const filter: { elements?: Element[]; enforcement?: Enforcement | 'locked' } = {};
+  if (input.element !== undefined) {
+    const elements = input.element.split(',').map((e) => e.trim()).filter(Boolean);
+    for (const element of elements) {
+      if (!(ELEMENTS as readonly string[]).includes(element)) {
+        throw new ContentCliError(
+          'usage',
+          `--element ${element}: not an element. One of: ${ELEMENTS.join(', ')}.`,
+        );
+      }
+    }
+    filter.elements = elements as Element[];
+  }
+  if (input.enforcement !== undefined) {
+    const kinds = ['script', 'partial', 'guide', 'locked'];
+    if (!kinds.includes(input.enforcement)) {
+      throw new ContentCliError(
+        'usage',
+        `--enforcement ${input.enforcement}: one of ${kinds.join(', ')}.`,
+      );
+    }
+    filter.enforcement = input.enforcement as Enforcement | 'locked';
+  }
+  return filter;
+}
+
+/** The rules this course has in effect, optionally narrowed. */
+export function contentRules(manifest: Manifest, filter: RulesFilter = {}): RulesReport {
+  const rules = rulesInEffect(manifest, filter);
+  return {
+    filter,
+    count: rules.length,
+    rules,
+    markdown: renderRulesInEffect(manifest, filter),
+  };
+}
+
 // --- content context ---------------------------------------------------
 
 export interface ContextReport {
@@ -749,7 +871,16 @@ export interface ContextReport {
   readonly tables: readonly { key: string; number: string }[];
   readonly figures: readonly { key: string; number: string }[];
   readonly diagrams: readonly { key: string; number: string }[];
-  readonly knowledgeChecks: readonly { key: string; number: string }[];
+  /** Worked-example sets: `short` is the title `[[ex-key]]` names. */
+  readonly examples: readonly { key: string; number: string; short?: string }[];
+  readonly knowledgeChecks: readonly { key: string; number: string; title?: string }[];
+  /** The top-level headings: `slug` is what `[[sec-slug]]` names. */
+  readonly sections: readonly {
+    slug: string;
+    text: string;
+    level: number;
+    number?: string;
+  }[];
   readonly sources: readonly {
     id: string;
     title: string;
@@ -821,7 +952,9 @@ export function contentContext(
     tables: lesson.tables.map((table) => ({ ...table })),
     figures: lesson.figures.map((figure) => ({ ...figure })),
     diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
+    examples: lesson.examples.map((example) => ({ ...example })),
     knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
+    sections: lesson.headings.map((heading) => ({ ...heading })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id) as Record<string, unknown> | undefined;
       return {

package/src/compiler/collections.ts

@@ -31,15 +31,21 @@ import type {
   NotationLessonInput,
   NotationReferenceInput,
   NotationRegistryInput,
+  NotationSuspension,
   SharedNotationDefinitionInput,
   SourceSpan,
   NotationGlossEntry,
 } from '../reference/types';
 import { isSubstantiveMeaning } from '../reference/prose';
 import { parseEquationRef } from '../reference/equations.mjs';
+import {
+  DECORATION_NAMES,
+  decorationOfEntry,
+} from '../reference/math-glyphs.mjs';
 import { parseKeyedFloatRef } from '../reference/keyed-jsx-floats.mjs';
 import { parseKnowledgeCheckRef } from '../reference/knowledge-checks.mjs';
 import { parseMemoRef } from '../reference/remark-memo.mjs';
+import { parseSectionRef } from '../reference/sections.mjs';
 import { resolveLabel } from '../reference/label';
 import { resolveGlosses } from '../reference/gloss';
 import {
@@ -80,6 +86,32 @@ interface ParsedDocument {
   readonly data: Record<string, unknown>;
   /** Markdown body, byte-identical to the previous `gray-matter` output. */
   readonly body: string;
+  /**
+   * 1-based line *in the file* where {@link body} starts — the frontmatter
+   * block's height plus one. Every gate scans the body, so a finding's index
+   * is body-relative while the `file` it is reported against is not; without
+   * this offset a `file:line:column` diagnostic points at the wrong line (by
+   * the height of the frontmatter) and no editor can jump to it.
+   */
+  readonly bodyLine: number;
+}
+
+/**
+ * The line `body` starts on in `raw`. `parseFrontmatter` returns the body as a
+ * suffix of the file, so the offset is what precedes it; the `indexOf` branch
+ * is a guard for a future parser that normalizes the text rather than slicing.
+ */
+function bodyStartLine(raw: string, body: string): number {
+  const offset = raw.endsWith(body)
+    ? raw.length - body.length
+    : raw.indexOf(body);
+  if (offset <= 0) return 1;
+
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (raw.charCodeAt(index) === 10) line += 1;
+  }
+  return line;
 }
 
 /**
@@ -87,11 +119,14 @@ interface ParsedDocument {
  * did not; strip it so body offsets in diagnostics are unchanged.
  */
 function parseDocument(path: string): ParsedDocument {
-  const parsed = parseFrontmatter(readFileSync(path, 'utf8'));
+  const raw = readFileSync(path, 'utf8');
+  const parsed = parseFrontmatter(raw);
+  const body = parsed.content.replace(/^\n/, '');
   return {
     file: relative(REPOSITORY_ROOT, path),
     data: (parsed.frontmatter ?? {}) as Record<string, unknown>,
-    body: parsed.content.replace(/^\n/, ''),
+    body,
+    bodyLine: bodyStartLine(raw, body),
   };
 }
 
@@ -234,16 +269,19 @@ export function extractNotationReferences(
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? '').trim();
       // `[[eq-key]]` / `[[slug#eq-key]]` are equation references (D7), and
-      // `[[tab-key]]`/`[[fig-key]]`/`[[dia-key]]` (and their cross-page forms)
-      // are keyed-float references, `[[check-key]]` targets a lesson's
-      // assessment list, and `[[memo-key]]` is a page-local memo reference —
-      // all resolved by the remark pass and the manifest, not notation keys.
+      // `[[tab-key]]`/`[[fig-key]]`/`[[dia-key]]`/`[[ex-key]]` (and their
+      // cross-page forms) are keyed-float references, `[[check-key]]`
+      // targets a lesson's assessment list, `[[sec-slug]]` a heading, and
+      // `[[memo-key]]` is a page-local memo reference — all resolved by the
+      // remark pass and the manifest, not notation keys.
       if (
         parseEquationRef(key) ||
         parseKeyedFloatRef(key, { prefix: 'tab' }) ||
         parseKeyedFloatRef(key, { prefix: 'fig' }) ||
         parseKeyedFloatRef(key, { prefix: 'dia' }) ||
+        parseKeyedFloatRef(key, { prefix: 'ex' }) ||
         parseKnowledgeCheckRef(key) ||
+        parseSectionRef(key) ||
         parseMemoRef(key)
       ) {
         continue;
@@ -294,6 +332,57 @@ function lessonCheckIds(lessonPath: string): string[] {
     : [];
 }
 
+/**
+ * One part's **overview page** — `content/docs/<dir>/index.mdx`, the page the
+ * part's own directory URL resolves to. `isLessonSlug` already excludes any
+ * `<dir>/index`, so this page is not a chapter: it carries no competencies, no
+ * knowledge check, and no float numbers, and nothing in the curriculum graph
+ * changes when a course adds one.
+ */
+export interface PartOverviewPage {
+  readonly dir: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly title: string;
+  readonly description?: string;
+  /** MDX after the frontmatter — what the S2 gate (`gate-part-pages.ts`) reads. */
+  readonly body: string;
+  /** 1-based file line `body` starts on, for diagnostic locations. */
+  readonly bodyLine: number;
+}
+
+/**
+ * The overview page of every part that has one, keyed by the part's directory.
+ * A part without one is simply absent — overview pages are opt-in, one part at
+ * a time.
+ */
+export function loadPartOverviews(
+  parts: readonly { readonly dir: string }[],
+): PartOverviewPage[] {
+  const pages: PartOverviewPage[] = [];
+  for (const { dir } of parts) {
+    for (const extension of ['.mdx', '.md']) {
+      const path = join(CONTENT_ROOT, 'docs', dir, `index${extension}`);
+      if (!existsSync(path)) continue;
+      const { data, file, body, bodyLine } = parseDocument(path);
+      const title = typeof data.title === 'string' ? data.title : dir;
+      const description =
+        typeof data.description === 'string' ? data.description : undefined;
+      pages.push({
+        dir,
+        slug: `${dir}/index`,
+        file,
+        title,
+        ...(description === undefined ? {} : { description }),
+        body,
+        bodyLine,
+      });
+      break;
+    }
+  }
+  return pages;
+}
+
 function lessonEntries(
   prerequisitesById: ReadonlyMap<string, readonly string[]>,
 ): LessonDefinition[] {
@@ -479,22 +568,67 @@ export async function loadAbbreviationRegistryInput(): Promise<
   return abbreviationEntries();
 }
 
+/**
+ * A lesson's `notation.suspend` (rule N22): decorations that are not
+ * operators on this page. A name outside `DECORATION_NAMES`, a decoration
+ * suspended twice, and a `notation.local` operator entry for a suspended
+ * decoration (the page would contradict itself) each fail the load.
+ */
+export function notationSuspensions(
+  raw: unknown,
+  localDefinitions: readonly LocalNotationDefinitionInput[],
+  file: string,
+): NotationSuspension[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    throw new TypeError(`${file} notation.suspend must be an array`);
+  }
+  const seen = new Set<string>();
+  return raw.map((item, index) => {
+    const at = `${file} notation.suspend[${index}]`;
+    const data = record(item, at);
+    const operator = string(data.operator, `${at}.operator`).trim();
+    if (!DECORATION_NAMES.has(operator)) {
+      throw new Error(
+        `${at}.operator ${JSON.stringify(operator)} is not a decoration; use one of ${[...DECORATION_NAMES].join(', ')}`,
+      );
+    }
+    if (seen.has(operator)) {
+      throw new Error(`${at} suspends ${JSON.stringify(operator)} a second time`);
+    }
+    seen.add(operator);
+    const local = localDefinitions.find(
+      (definition) => decorationOfEntry(definition.notation) === operator,
+    );
+    if (local) {
+      throw new Error(
+        `${at} suspends ${JSON.stringify(operator)}, but notation.local entry ${local.key} explains it as an operator (latex ${JSON.stringify(local.notation)}); drop one of them`,
+      );
+    }
+    const reason = optionalString(data.reason, `${at}.reason`);
+    return reason === undefined ? { operator } : { operator, reason: reason.trim() };
+  });
+}
+
 function notationLessonEntries(): NotationLessonInput[] {
   const lessons: NotationLessonInput[] = [];
   for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
     const slug = docSlug(path);
     if (!isLessonSlug(slug)) continue;
-    const { file, data, body } = parseDocument(path);
+    const { file, data, body, bodyLine } = parseDocument(path);
     const notation = record(data.notation ?? {}, `${file} notation`);
     const local = Array.isArray(notation.local) ? notation.local : [];
+    const localDefinitions = local.map((entry, index) =>
+      localDefinition(entry, file, index),
+    );
     lessons.push({
       lessonId: lessonIdFromSlug(slug),
       status: status(data.editorialStatus, `${file} editorialStatus`),
-      localDefinitions: local.map((entry, index) =>
-        localDefinition(entry, file, index),
-      ),
+      localDefinitions,
+      suspended: notationSuspensions(notation.suspend, localDefinitions, file),
       references: extractNotationReferences(body, file, undefined),
       body,
+      bodyLine,
       source: { file },
     });
   }