explico 0.8.0 → 0.11.1

package/src/compiler/course-config.ts

@@ -1,3 +1,6 @@
+import type { CourseRulesConfig } from '../rules/settings';
+import type { CourseRuleDefinitions } from '../rules/course-rules';
+
 /**
  * The shape `content/course.config.ts` must satisfy (Phase F).
  *
@@ -10,14 +13,21 @@
 /**
  * One **part** — a sidebar group, holding the chapters (lessons) whose slugs
  * start with `dir`. A part's 1-based position in `CourseConfig.parts` is the
- * number before the dot in every equation, table, and figure number inside it.
- * See `docs/authoring/structure.md` for the full level taxonomy.
+ * first number in every section, equation, table, and figure number inside
+ * it. See `docs/authoring/structure.md` for the full level taxonomy.
  */
 export interface CoursePart {
   /** Lesson-slug prefix, e.g. `bonds` for `bonds/yield-to-maturity`. */
   readonly dir: string;
   /** Sidebar group heading. */
   readonly label: string;
+  /**
+   * The sidebar row that opens this part's **overview page**, when
+   * `content/docs/<dir>/index.mdx` exists. Defaults to `Overview`; the page's
+   * own title stays the part's name, which would only repeat the group
+   * heading one row below it.
+   */
+  readonly overviewLabel?: string;
 }
 
 /**
@@ -65,6 +75,21 @@ export interface CourseRomanLabels {
   readonly deny?: readonly string[];
 }
 
+/**
+ * A course's edits to the shipped accent baseline (`BASE_ACCENTS`, empty),
+ * consumed by the `accent-explained` consistency check (rule N22). A
+ * decoration a lesson uses (`\hat`, `\bar`, `'`, `*`, …) is fine when it is on
+ * the baseline plus `allow` minus `deny`, explained by an operator entry
+ * (`latex: \hat{}`), or part of a whole-form entry (`latex: \hat{\beta}`).
+ * Same shape as {@link CourseOperators}; set under `rules.N22` only.
+ */
+export interface CourseAccents {
+  /** Decorations this course treats as universal (`\dot`, `\vec`, …). */
+  readonly allow?: readonly string[];
+  /** Baseline decorations this course wants explained anyway. */
+  readonly deny?: readonly string[];
+}
+
 /**
  * A course's edits to the shipped abbreviation baseline (`BASE_ABBREVIATIONS`),
  * consumed by the `abbreviation-explained` gate (rule N14). An abbreviation-
@@ -116,43 +141,235 @@ export interface CourseAbout {
   readonly changelogHref?: string;
 }
 
+/** A heading-like block's collapse default: may it fold, and does it start open? */
+export interface CourseHeadingDisclosure {
+  /** Wrap it in a collapsible section. */
+  readonly collapsible?: boolean;
+  /** Its state for a reader with nothing saved yet; ignored when not collapsible. */
+  readonly defaultOpen?: boolean;
+}
+
+/** A block that always folds; only its first-visit state is a course choice. */
+export interface CourseOpenDefault {
+  readonly defaultOpen?: boolean;
+}
+
 /**
- * A course's chosen initial open/closed state for the engine's own built-in
- * collapsible sections — the "Page notation" panel (`NotationLayer.astro`)
- * and the generated "References" section (`remark-citation.mjs`). Each is
- * independent of `defaultCollapsible.sections`/`.subsections` (an author's
- * own `##` headings): both of these are engine-authored, not written by a
- * lesson, so they need their own default rather than inheriting the site's
- * general heading default.
+ * Every collapse default a course sets — the `disclosure` block of the course
+ * settings, in its own shape (docs/plans/titles-and-containers.md Part 4).
+ * Each kind names its default here:
  *
- * `true` starts open, `false` (or omitted) starts closed — the engine's own
- * default is closed either way, matching a long panel a reader usually
- * doesn't need open on arrival.
+ * - **Full collapse**, the section wrapper (`CollapsibleSections.astro`):
+ *   `sections` (`##`), `subsections` (`###`–`######`), `knowledgeChecks`, the
+ *   generated `references` section, `memos` (a memo is a `######`-rank
+ *   section of its own), `folds` (a `<Fold>`, the same without a memo's
+ *   marker, letter or frame) and `workedExamples` (a set is a `##`-rank
+ *   section of its own, Part 6). The notation panel (`notation`) folds the
+ *   same way.
+ * - **A float's own fold**, which keeps its picture and caption line:
+ *   `figures` sets whether a lab's tools start open
+ *   (docs/plans/figures-and-short-captions.md, decision 5); a table is
+ *   minimized by hand, and starts truncated when it has more than
+ *   `tables.truncateAfter` rows. A figure or a diagram never folds by
+ *   itself (decision 7).
+ *
+ * A heading's own marker (`[collapsible]`, `[collapsed]`, `[no-collapsible]`)
+ * and a component's `defaultOpen` prop override the kind's default at one
+ * place. Every collapsible remembers the reader's choice per page.
+ * {@link normalizeDisclosure} fills in the engine defaults — the values each
+ * kind had before they became settings.
  */
-export interface CourseDisclosureDefaults {
-  /** Initial state of the "Page notation" panel. Default: closed. */
-  readonly notation?: boolean;
-  /** Initial state of the generated "References" section. Default: closed. */
-  readonly references?: boolean;
+export interface CourseDisclosure {
+  readonly sections?: CourseHeadingDisclosure;
+  readonly subsections?: CourseHeadingDisclosure;
+  readonly knowledgeChecks?: CourseHeadingDisclosure;
+  readonly notation?: CourseOpenDefault;
+  readonly references?: CourseOpenDefault;
+  readonly memos?: CourseOpenDefault;
+  /** Whether a `<Fold>` starts open. */
+  readonly folds?: CourseOpenDefault;
+  /** Whether a lab's tools start open. */
+  readonly figures?: CourseOpenDefault;
+  readonly workedExamples?: CourseOpenDefault;
+  readonly tables?: {
+    /** A table with more rows than this starts truncated. Default `6`. */
+    readonly truncateAfter?: number;
+  };
 }
 
-/** The stable, non-optional form `NormalizedLessonExports` mirrors. */
-export interface NormalizedDisclosureDefaults {
-  readonly notation: boolean;
-  readonly references: boolean;
+/** {@link CourseDisclosure} with every default applied. */
+export interface NormalizedDisclosure {
+  readonly sections: Required<CourseHeadingDisclosure>;
+  readonly subsections: Required<CourseHeadingDisclosure>;
+  readonly knowledgeChecks: Required<CourseHeadingDisclosure>;
+  readonly notation: Required<CourseOpenDefault>;
+  readonly references: Required<CourseOpenDefault>;
+  readonly memos: Required<CourseOpenDefault>;
+  readonly folds: Required<CourseOpenDefault>;
+  readonly figures: Required<CourseOpenDefault>;
+  readonly workedExamples: Required<CourseOpenDefault>;
+  readonly tables: { readonly truncateAfter: number };
 }
 
-/** Validate and canonicalize `CourseConfig.disclosureDefaults`. Absent (or
- *  an absent sub-field) resolves to closed, the engine's own default. */
-export function normalizeDisclosureDefaults(
-  config: CourseConfig,
-): NormalizedDisclosureDefaults {
+/**
+ * The engine's defaults. Headings do not fold unless the course says so;
+ * the notation panel, References, memos, folds and worked examples start
+ * closed; a knowledge check folds and starts open; a lab's tools start open;
+ * a table over 6 rows starts truncated.
+ */
+export const DISCLOSURE_DEFAULTS: NormalizedDisclosure = {
+  sections: { collapsible: false, defaultOpen: true },
+  subsections: { collapsible: false, defaultOpen: true },
+  knowledgeChecks: { collapsible: true, defaultOpen: true },
+  notation: { defaultOpen: false },
+  references: { defaultOpen: false },
+  memos: { defaultOpen: false },
+  folds: { defaultOpen: false },
+  figures: { defaultOpen: true },
+  workedExamples: { defaultOpen: false },
+  tables: { truncateAfter: 6 },
+};
+
+/** Validate `CourseConfig.disclosure` and apply its defaults. Throws on a bad value. */
+export function normalizeDisclosure(config: CourseConfig): NormalizedDisclosure {
+  const disclosure = config.disclosure ?? {};
+  if ('diagrams' in disclosure) {
+    throw new Error(
+      'CourseConfig disclosure.diagrams is gone: a diagram no longer folds by ' +
+        'itself. Delete the key; to let a reader fold a diagram away, wrap it ' +
+        'in a <Fold> or put it in a collapsible section.',
+    );
+  }
+  const heading = (
+    key: 'sections' | 'subsections' | 'knowledgeChecks',
+  ): Required<CourseHeadingDisclosure> => ({
+    collapsible: disclosure[key]?.collapsible ?? DISCLOSURE_DEFAULTS[key].collapsible,
+    defaultOpen: disclosure[key]?.defaultOpen ?? DISCLOSURE_DEFAULTS[key].defaultOpen,
+  });
+  const open = (
+    key: 'notation' | 'references' | 'memos' | 'folds' | 'figures' | 'workedExamples',
+  ): Required<CourseOpenDefault> => ({
+    defaultOpen: disclosure[key]?.defaultOpen ?? DISCLOSURE_DEFAULTS[key].defaultOpen,
+  });
+  const truncateAfter =
+    disclosure.tables?.truncateAfter ?? DISCLOSURE_DEFAULTS.tables.truncateAfter;
+  if (!Number.isInteger(truncateAfter) || truncateAfter < 2) {
+    throw new Error(
+      `CourseConfig disclosure.tables.truncateAfter must be a whole number of ` +
+        `rows, at least 2; received ${JSON.stringify(truncateAfter)}.`,
+    );
+  }
   return {
-    notation: config.disclosureDefaults?.notation === true,
-    references: config.disclosureDefaults?.references === true,
+    sections: heading('sections'),
+    subsections: heading('subsections'),
+    knowledgeChecks: heading('knowledgeChecks'),
+    notation: open('notation'),
+    references: open('references'),
+    memos: open('memos'),
+    folds: open('folds'),
+    figures: open('figures'),
+    workedExamples: open('workedExamples'),
+    tables: { truncateAfter },
   };
 }
 
+/**
+ * How the course numbers its outline and its floats (`numbering` in the
+ * course settings; docs/authoring/structure.md § Numbering). Every field is
+ * optional; {@link normalizeNumbering} fills in the defaults.
+ */
+export interface CourseNumbering {
+  readonly sections?: {
+    /**
+     * Show section numbers: on wide screens, in print, and on a collapsed
+     * section's bar. Default `true`. Off, `[[sec-…]]` prints the title.
+     */
+    readonly show?: boolean;
+    /** The deepest heading level numbered, `2` (`##`) to `6`. Default `4`. */
+    readonly depth?: number;
+  };
+  /**
+   * The scope a float's counter runs over. `chapter` (default) restarts every
+   * kind in each chapter and prints `‹part›.‹chapter›.‹n›`; `part` runs on
+   * across the part's chapters and prints `‹part›.‹n›`. A plain `string`
+   * because the settings arrive as JSON; {@link normalizeNumbering} rejects
+   * any other value.
+   */
+  readonly floats?: string;
+  /**
+   * Resolve a number-form fragment a reader types (`#sec-1.1.2`,
+   * `#fig-2.2.1`) to the named anchor. Default `true`. The site itself only
+   * ever links and copies the named anchor.
+   */
+  readonly aliases?: boolean;
+}
+
+/** {@link CourseNumbering} with every default applied. */
+export interface NormalizedNumbering {
+  readonly sections: { readonly show: boolean; readonly depth: number };
+  readonly floats: 'chapter' | 'part';
+  readonly aliases: boolean;
+}
+
+/** Validate `CourseConfig.numbering` and apply its defaults. Throws on a bad value. */
+export function normalizeNumbering(config: CourseConfig): NormalizedNumbering {
+  const numbering = config.numbering ?? {};
+  const depth = numbering.sections?.depth ?? 4;
+  if (!Number.isInteger(depth) || depth < 2 || depth > 6) {
+    throw new Error(
+      `CourseConfig numbering.sections.depth must be a heading level from 2 ` +
+        `(##) to 6 (######); received ${JSON.stringify(depth)}.`,
+    );
+  }
+  const floats = numbering.floats ?? 'chapter';
+  if (floats !== 'chapter' && floats !== 'part') {
+    throw new Error(
+      `CourseConfig numbering.floats must be "chapter" or "part"; received ` +
+        `${JSON.stringify(floats)}.`,
+    );
+  }
+  return {
+    sections: { show: numbering.sections?.show !== false, depth },
+    floats,
+    aliases: numbering.aliases !== false,
+  };
+}
+
+/**
+ * How a knowledge check's and a worked-example set's heading names its kind
+ * (`blockLabels` in the course settings; docs/plans/titles-and-containers.md
+ * Q11). The engine draws the kind before the author's title: `icon-word`
+ * (the default) shows the kind's icon and its word, "Knowledge check" or
+ * "Example"; `icon` shows the icon alone and keeps the word for a screen
+ * reader.
+ */
+export type BlockLabels = 'icon' | 'icon-word';
+
+/** The engine default for {@link CourseConfig.blockLabels}. */
+export const BLOCK_LABELS_DEFAULT: BlockLabels = 'icon-word';
+
+/** Validate `CourseConfig.blockLabels` and apply its default. Throws on a bad value. */
+export function normalizeBlockLabels(config: CourseConfig): BlockLabels {
+  const labels = config.blockLabels ?? BLOCK_LABELS_DEFAULT;
+  if (labels !== 'icon' && labels !== 'icon-word') {
+    throw new Error(
+      `CourseConfig blockLabels must be "icon" or "icon-word"; received ` +
+        `${JSON.stringify(labels)}.`,
+    );
+  }
+  return labels;
+}
+
+/**
+ * Rule S2's word ranges (`rules.S2.bridgeMinWords` … in the course settings),
+ * in the shape `gate-part-pages.ts` takes. Built by `partPageLimits` in
+ * `src/rules/settings.ts`.
+ */
+export interface NormalizedPartPages {
+  readonly bridge: { readonly minWords: number; readonly maxWords: number };
+  readonly scope: { readonly minWords: number; readonly maxWords: number };
+}
+
 /** Optional, build-time lesson artifacts exposed to readers. */
 export interface LessonExportsConfig {
   /** Emit one self-contained, offline-capable HTML file per lesson. */
@@ -191,17 +408,39 @@ export interface CourseConfig {
   readonly conventions: CourseConventions;
   /** Reader-facing identity + knowledge version (the `[?]` About panel). */
   readonly about: CourseAbout;
-  /** Edits to the shipped named-operator baseline (rule N8). Optional. */
+  /**
+   * Per-rule switches and settings, flat by rule ID — only what differs from
+   * the defaults (`{ "P5": { "enabled": false }, "S1": { "maxLength": 72 } }`).
+   * Resolved and validated by `resolveRules` (`src/rules/settings.ts`); the
+   * closed list of IDs and settings is `src/rules/catalog.ts`.
+   */
+  readonly rules?: CourseRulesConfig;
+  /**
+   * The course's *own* rules, on top of the engine's — `X1`…`X99`, each with
+   * its own text, elements, severity and optional `forbid` patterns. A list,
+   * not a map, so the settings form can add and remove one. Resolved and
+   * validated by `resolveCourseRules` (`src/rules/course-rules.ts`).
+   */
+  readonly courseRules?: CourseRuleDefinitions;
+  /** @deprecated Moved to `rules.N8` (same shape). Honoured for now; removed in a later MINOR. */
   readonly operators?: CourseOperators;
-  /** Edits to the shipped roman-label baseline (rule N10). Optional. */
+  /** @deprecated Moved to `rules.N10` (same shape). Honoured for now; removed in a later MINOR. */
   readonly romanLabels?: CourseRomanLabels;
-  /** Edits to the shipped abbreviation baseline (rule N14). Optional. */
+  /** @deprecated Moved to `rules.N14` (same shape). Honoured for now; removed in a later MINOR. */
   readonly abbreviations?: CourseAbbreviations;
   /** Per-lesson export actions and downloadable artifacts. Disabled when omitted. */
   readonly lessonExports?: LessonExportsConfig;
-  /** Initial open/closed state for the engine's own built-in collapsible
-   *  sections ("Page notation", "References"). Closed when omitted. */
-  readonly disclosureDefaults?: CourseDisclosureDefaults;
+  /** Every collapse default: headings, checks, memos, floats, tables. */
+  readonly disclosure?: CourseDisclosure;
+  /** Outline and float numbering. The defaults apply when omitted. */
+  readonly numbering?: CourseNumbering;
+  /**
+   * How a check's and an example set's heading names its kind: `icon-word`
+   * (default) or `icon` ({@link BlockLabels}). A plain `string` because the
+   * settings arrive as JSON; {@link normalizeBlockLabels} rejects any other
+   * value.
+   */
+  readonly blockLabels?: string;
 }
 
 /** Validate and canonicalize the build-facing lesson-export configuration. */

package/src/compiler/knowledge-version.ts

@@ -141,7 +141,7 @@ export function resolveKnowledgeVersion(options: {
   if (!latest) {
     warn(
       'knowledge-changelog-missing',
-      `${file} has no released \`## [x.y.z]\` entry — only \`## [Unreleased]\`. Cut a release: move it to \`## [${declaredVersion}] - <date>\` (rule C4).`,
+      `${file} has no released \`## [x.y.z]\` entry — only \`## [Unreleased]\`. Cut a release: move it to \`## [${declaredVersion}] - <date>\` (rule C3).`,
     );
     return { version: declaredVersion, diagnostics };
   }

package/src/compiler/lesson-derivation.ts

@@ -136,27 +136,48 @@ export function mergeTrackOrder(tracks: readonly TrackLike[]): string[] {
 export interface SidebarSection {
   readonly dir: string;
   readonly label: string;
+  readonly overviewLabel?: string;
+  /**
+   * Href of this part's overview page (`/<dir>/`), set only when the part has
+   * one. It becomes the group's first item, so the page a part directory
+   * resolves to is reachable from the navigation that names the part.
+   */
+  readonly overviewLink?: string;
 }
 
-export type SidebarGroup =
-  | { readonly label: string; readonly items: readonly string[] }
+/**
+ * One sidebar entry: a lesson slug, or an explicit link. `attrs` is Starlight's
+ * own passthrough onto the rendered `<a>` — the engine uses it to mark a part's
+ * overview row so CSS can give it its own icon.
+ */
+export type SidebarItem =
+  | string
   | {
       readonly label: string;
-      readonly items: readonly {
-        readonly label: string;
-        readonly link: string;
-      }[];
+      readonly link: string;
+      readonly attrs?: Readonly<Record<string, string>>;
     };
 
+export interface SidebarGroup {
+  readonly label: string;
+  readonly items: readonly SidebarItem[];
+}
+
+/** Marks the overview row so `global.css` can give it its own icon. */
+export const PART_OVERVIEW_CLASS = 'explico-part-overview';
+
 /**
  * The Starlight `sidebar` config: one group per section, lessons ordered by the
  * merged track order (ties broken by slug), then the static Reference group.
  * Replaces seven `autogenerate` blocks that read an authored `sidebar.order`.
+ * `floatIndex`: the course has a top-level "Figures and tables" page
+ * (`figures-and-tables.mdx`, `FloatIndex.astro`), listed in Reference.
  */
 export function buildSidebar(
   tracks: readonly TrackLike[],
   lessonSlugs: readonly string[],
   parts: readonly SidebarSection[],
+  { floatIndex = false }: { readonly floatIndex?: boolean } = {},
 ): SidebarGroup[] {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index]),
@@ -164,21 +185,39 @@ export function buildSidebar(
   const positionOf = (slug: string) =>
     rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
 
-  const groups: SidebarGroup[] = parts.map(({ dir, label }) => ({
-    label,
-    items: lessonSlugs
-      .filter((slug) => slug.startsWith(`${dir}/`))
-      .sort(
-        (left, right) =>
-          positionOf(left) - positionOf(right) || left.localeCompare(right),
-      ),
-  }));
+  const groups: SidebarGroup[] = parts.map(
+    ({ dir, label, overviewLabel, overviewLink }) => {
+      const chapters = lessonSlugs
+        .filter((slug) => slug.startsWith(`${dir}/`))
+        .sort(
+          (left, right) =>
+            positionOf(left) - positionOf(right) || left.localeCompare(right),
+        );
+      // The overview leads the group: it is the part's own page, so it reads
+      // as the chapter list's heading rather than an appendix to it, and in
+      // compact mode it is the first icon instead of the last.
+      return {
+        label,
+        items: overviewLink
+          ? [
+              {
+                label: overviewLabel ?? 'Overview',
+                link: overviewLink,
+                attrs: { class: PART_OVERVIEW_CLASS },
+              },
+              ...chapters,
+            ]
+          : chapters,
+      };
+    },
+  );
 
   groups.push({
     label: 'Reference',
     items: [
       { label: 'Curriculum map', link: '/curriculum-map/' },
       { label: 'Notation glossary', link: '/glossary/' },
+      ...(floatIndex ? [{ label: 'Figures and tables', link: '/figures-and-tables/' }] : []),
     ],
   });
 

package/src/compiler/logging.ts

@@ -42,6 +42,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { join, relative } from 'node:path';
+import { ruleIdOf } from '../rules/catalog';
 
 const REPOSITORY_ROOT = process.cwd();
 /** Sits beside `build/manifest.json` and `build/resolution/` (Phase F). */
@@ -163,14 +164,19 @@ export interface RunLog {
  * `[code] file:line:column: message`, matching what the console has always
  * printed, with ` (eq:<key> -> <href>)` appended when the finding belongs to a
  * keyed equation — so a size-only finding inside a long `aligned` block names
- * the result it is about, not just its coordinates.
+ * the result it is about, not just its coordinates. A code owned by a lettered
+ * rule is prefixed with that rule's ID (`[N9 prose-notation]`), so the line
+ * names the rule page to read; an invariant's code stands alone, and a course
+ * rule's code *is* its ID (`[X1]`), so it is not repeated.
  */
 export function diagnosticLine(diagnostic: AnyDiagnostic): string {
   const code = diagnostic.code ?? diagnostic.kind;
   const at = [diagnostic.file, diagnostic.line, diagnostic.column]
     .filter((part) => part !== undefined)
     .join(':');
-  const prefix = code === undefined ? '' : `[${code}] `;
+  const owner = code === undefined ? undefined : ruleIdOf(code);
+  const rule = owner === undefined || owner === code ? '' : `${owner} `;
+  const prefix = code === undefined ? '' : `[${rule}${code}] `;
   const equation =
     diagnostic.equation === undefined
       ? ''