explico 0.8.0 → 0.11.1

package/dist/compiler/course-config.d.ts

@@ -1,194 +1,3 @@
-/**
- * The shape `content/course.config.ts` must satisfy (Phase F).
- *
- * The engine never imports the course's config file; the wiring layer
- * (`astro.config.mjs`, `scripts/*`, `src/content.config.ts`) imports the plain
- * data value and passes it here, typed against `CourseConfig`. A second course
- * supplies its own value of this shape.
- */
-/**
- * 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.
- */
-interface CoursePart {
-    /** Lesson-slug prefix, e.g. `bonds` for `bonds/yield-to-maturity`. */
-    readonly dir: string;
-    /** Sidebar group heading. */
-    readonly label: string;
-}
-/**
- * @deprecated Renamed to {@link CoursePart}. "Section" now only ever means an
- * `##` heading inside a lesson. Removed in the next MINOR release.
- */
-type CourseSection = CoursePart;
-interface CourseConventions {
-    /** Notation key a lesson's stated sign convention must resolve to. */
-    readonly signConventionKey: string;
-    /** Competency id that also counts as declaring the cash-flow perspective. */
-    readonly cashFlowPerspectiveCompetency: string;
-}
-/**
- * A course's edits to the shipped named-operator baseline (`BASE_OPERATORS`),
- * consumed by the `operator-explained` consistency check (rule N8). An operator
- * a lesson uses is fine when it is on the baseline plus `allow` minus `deny`;
- * otherwise it needs a notation entry the reader can hover.
- *
- * Names are the KaTeX command without its backslash (`erf`, not `\erf`) for a
- * built-in, and the verbatim body for an `\operatorname{…}` operator (`Var`).
- */
-interface CourseOperators {
-    /** Operators this course also treats as universal (`Var`, `Cov`, `sgn`, …). */
-    readonly allow?: readonly string[];
-    /** Baseline operators this course wants explained anyway. */
-    readonly deny?: readonly string[];
-}
-/**
- * A course's edits to the shipped roman-label baseline (`BASE_ROMAN_LABELS`),
- * consumed by the `roman-label-explained` consistency check (rule N10). A
- * `\mathrm{…}` multi-letter label a lesson uses is fine when it is on the
- * baseline plus `allow` minus `deny`; otherwise it needs a notation entry the
- * reader can hover. Same shape as {@link CourseOperators}, one level down:
- * this governs `\mathrm{KE}`-style labels, not `\operatorname{Var}`-style
- * operators.
- */
-interface CourseRomanLabels {
-    /** Labels this course also treats as universal qualifiers (`eff`, `net`, …). */
-    readonly allow?: readonly string[];
-    /** Baseline labels 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-
- * shaped token — an all-caps acronym or a dotted form like `w.r.t.` — a
- * lesson uses in prose is fine when it is on the baseline plus `allow` minus
- * `deny`; otherwise it needs an entry in the `abbreviations` content
- * collection, or — if it also names a math quantity — a notation entry the
- * reader can hover. Same shape as {@link CourseOperators} / {@link
- * CourseRomanLabels}.
- */
-interface CourseAbbreviations {
-    /** Abbreviations this course also treats as universal (`GDP`, `CPU`, …). */
-    readonly allow?: readonly string[];
-    /** Baseline abbreviations this course wants explained anyway. */
-    readonly deny?: readonly string[];
-}
-/** One person or team credited for the study material. */
-interface CourseAuthor {
-    readonly name: string;
-    /**
-     * Email, URL, or handle. Rendered in the About panel as a link when it looks
-     * like a `mailto:` or `https:` target, plain text otherwise.
-     */
-    readonly contact?: string;
-}
-/**
- * The reader-facing "about this material" block, surfaced by the `[?]` panel in
- * the header (`components/starlight/AboutPanel.astro`) on every page.
- *
- * `version` is the course's **knowledge version** — semver over the
- * learning-facing content, independent of the `explico` engine's own version.
- * It must equal the newest entry in `content/CHANGELOG.md`; a mismatch is a
- * Tier-3 `knowledge-version-mismatch` warning (rule C3, `docs/authoring/versioning.md`).
- */
-interface CourseAbout {
-    /** Display name of the material. Defaults to {@link CourseConfig.title}. */
-    readonly materialName?: string;
-    /** One or two sentences on what the material covers. Defaults to {@link CourseConfig.description}. */
-    readonly summary?: string;
-    /** Knowledge version — semver; equals the latest `content/CHANGELOG.md` heading. */
-    readonly version: string;
-    /** Who authored / maintains the material. At least one entry. */
-    readonly authors: readonly CourseAuthor[];
-    /** Shown verbatim in the About panel — scope, warranty, AI-assistance note. */
-    readonly disclaimer: string;
-    /** Link to the published content changelog (repo blob, docs page, …). */
-    readonly changelogHref?: string;
-}
-/**
- * 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.
- *
- * `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.
- */
-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;
-}
-/** The stable, non-optional form `NormalizedLessonExports` mirrors. */
-interface NormalizedDisclosureDefaults {
-    readonly notation: boolean;
-    readonly references: boolean;
-}
-/** Validate and canonicalize `CourseConfig.disclosureDefaults`. Absent (or
- *  an absent sub-field) resolves to closed, the engine's own default. */
-declare function normalizeDisclosureDefaults(config: CourseConfig): NormalizedDisclosureDefaults;
-/** Optional, build-time lesson artifacts exposed to readers. */
-interface LessonExportsConfig {
-    /** Emit one self-contained, offline-capable HTML file per lesson. */
-    readonly standaloneHtml?: boolean;
-    /** Offer the browser's native print dialog with explico's lesson print layout. */
-    readonly print?: boolean;
-    /**
-     * Published course root used for links that intentionally leave the exported
-     * lesson. Required at export time when such a link is present.
-     */
-    readonly canonicalBaseUrl?: string;
-}
-/** The stable, non-optional export settings carried by the manifest. */
-interface NormalizedLessonExports {
-    readonly standaloneHtml: boolean;
-    readonly print: boolean;
-    readonly canonicalBaseUrl?: string;
-}
-interface CourseConfig {
-    readonly title: string;
-    readonly description: string;
-    /**
-     * The course's parts (sidebar groups), in order. Exactly one of `parts` or
-     * the deprecated `sections` must be given.
-     */
-    readonly parts?: readonly CoursePart[];
-    /**
-     * @deprecated Renamed to {@link CourseConfig.parts}. Still honoured, so a
-     * course on the old name keeps building; removed in the next MINOR release.
-     */
-    readonly sections?: readonly CoursePart[];
-    /** Namespaces used by competency / notation `domain` fields. */
-    readonly domains: readonly string[];
-    readonly conventions: CourseConventions;
-    /** Reader-facing identity + knowledge version (the `[?]` About panel). */
-    readonly about: CourseAbout;
-    /** Edits to the shipped named-operator baseline (rule N8). Optional. */
-    readonly operators?: CourseOperators;
-    /** Edits to the shipped roman-label baseline (rule N10). Optional. */
-    readonly romanLabels?: CourseRomanLabels;
-    /** Edits to the shipped abbreviation baseline (rule N14). Optional. */
-    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;
-}
-/** Validate and canonicalize the build-facing lesson-export configuration. */
-declare function normalizeLessonExports(config: CourseConfig): NormalizedLessonExports;
-/**
- * The course's parts, from whichever field the config uses. Throws rather than
- * silently producing a course with no sidebar groups — a config with neither
- * field would otherwise number every float by the `##`-section fallback.
- */
-declare function coursePartsOf(config: CourseConfig): readonly CoursePart[];
-
-export { type CourseAbbreviations, type CourseAbout, type CourseAuthor, type CourseConfig, type CourseConventions, type CourseDisclosureDefaults, type CourseOperators, type CoursePart, type CourseRomanLabels, type CourseSection, type LessonExportsConfig, type NormalizedDisclosureDefaults, type NormalizedLessonExports, coursePartsOf, normalizeDisclosureDefaults, normalizeLessonExports };
+export { s as BLOCK_LABELS_DEFAULT, B as BlockLabels, a as CourseAbbreviations, t as CourseAbout, i as CourseAccents, u as CourseAuthor, C as CourseConfig, f as CourseConventions, v as CourseDisclosure, w as CourseHeadingDisclosure, x as CourseNumbering, y as CourseOpenDefault, g as CourseOperators, z as CoursePart, h as CourseRomanLabels, A as CourseSection, D as DISCLOSURE_DEFAULTS, L as LessonExportsConfig, c as NormalizedDisclosure, b as NormalizedLessonExports, d as NormalizedNumbering, N as NormalizedPartPages, E as coursePartsOf, F as normalizeBlockLabels, G as normalizeDisclosure, H as normalizeLessonExports, I as normalizeNumbering } from '../course-config-Dsnri9Tk.js';
+import '../rules/course-rules.js';
+import '../rules/catalog.js';

package/dist/compiler/course-config.js

@@ -1,9 +1,78 @@
-function normalizeDisclosureDefaults(config) {
+const DISCLOSURE_DEFAULTS = {
+  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 }
+};
+function normalizeDisclosure(config) {
+  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) => ({
+    collapsible: disclosure[key]?.collapsible ?? DISCLOSURE_DEFAULTS[key].collapsible,
+    defaultOpen: disclosure[key]?.defaultOpen ?? DISCLOSURE_DEFAULTS[key].defaultOpen
+  });
+  const open = (key) => ({
+    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 {
+    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 }
+  };
+}
+function normalizeNumbering(config) {
+  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 {
-    notation: config.disclosureDefaults?.notation === true,
-    references: config.disclosureDefaults?.references === true
+    sections: { show: numbering.sections?.show !== false, depth },
+    floats,
+    aliases: numbering.aliases !== false
   };
 }
+const BLOCK_LABELS_DEFAULT = "icon-word";
+function normalizeBlockLabels(config) {
+  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;
+}
 function normalizeLessonExports(config) {
   const standaloneHtml = config.lessonExports?.standaloneHtml === true;
   const print = config.lessonExports?.print === true;
@@ -40,7 +109,11 @@ function coursePartsOf(config) {
   return parts;
 }
 export {
+  BLOCK_LABELS_DEFAULT,
+  DISCLOSURE_DEFAULTS,
   coursePartsOf,
-  normalizeDisclosureDefaults,
-  normalizeLessonExports
+  normalizeBlockLabels,
+  normalizeDisclosure,
+  normalizeLessonExports,
+  normalizeNumbering
 };

package/dist/compiler/exports/standalone-html.d.ts

@@ -1,7 +1,9 @@
 import { Manifest } from '../manifest.js';
 import '../../curriculum/validation.js';
 import '../../reference/consistency.js';
-import '../course-config.js';
+import '../../course-config-Dsnri9Tk.js';
+import '../../rules/catalog.js';
+import '../../rules/course-rules.js';
 import '../collections.js';
 import '../../reference/types.js';
 import '../../reference/lint-ignore.js';
@@ -10,11 +12,14 @@ import '../../reference/tables-validate.js';
 import '../../reference/keyed-float-validate.js';
 import '../../reference/figures-validate.js';
 import '../../reference/diagrams-validate.js';
+import '../../reference/examples-validate.js';
+import '../../reference/folds-validate.js';
 import '../../reference/knowledge-checks-validate.js';
 import '../../reference/raw-floats-validate.js';
 import '../../reference/gate-math.js';
 import '../../reference/mixed-content.js';
 import '../../reference/gloss.js';
+import '../../rules/waivers.js';
 import '../knowledge-version.js';
 import '../lesson-derivation.js';
 

package/dist/compiler/knowledge-version.js

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

package/dist/compiler/lesson-derivation.d.ts

@@ -68,22 +68,39 @@ declare function mergeTrackOrder(tracks: readonly TrackLike[]): string[];
 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;
 }
-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.
+ */
+type SidebarItem = string | {
     readonly label: string;
-    readonly items: readonly {
-        readonly label: string;
-        readonly link: string;
-    }[];
+    readonly link: string;
+    readonly attrs?: Readonly<Record<string, string>>;
 };
+interface SidebarGroup {
+    readonly label: string;
+    readonly items: readonly SidebarItem[];
+}
+/** Marks the overview row so `global.css` can give it its own icon. */
+declare 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.
  */
-declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], parts: readonly SidebarSection[]): SidebarGroup[];
+declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], parts: readonly SidebarSection[], { floatIndex }?: {
+    readonly floatIndex?: boolean;
+}): SidebarGroup[];
 
-export { type SidebarGroup, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };
+export { PART_OVERVIEW_CLASS, type SidebarGroup, type SidebarItem, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };

package/dist/compiler/lesson-derivation.js

@@ -59,27 +59,42 @@ function mergeTrackOrder(tracks) {
   }
   return ordered;
 }
-function buildSidebar(tracks, lessonSlugs, parts) {
+const PART_OVERVIEW_CLASS = "explico-part-overview";
+function buildSidebar(tracks, lessonSlugs, parts, { floatIndex = false } = {}) {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index])
   );
   const positionOf = (slug) => rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
-  const groups = parts.map(({ dir, label }) => ({
-    label,
-    items: lessonSlugs.filter((slug) => slug.startsWith(`${dir}/`)).sort(
-      (left, right) => positionOf(left) - positionOf(right) || left.localeCompare(right)
-    )
-  }));
+  const groups = parts.map(
+    ({ dir, label, overviewLabel, overviewLink }) => {
+      const chapters = lessonSlugs.filter((slug) => slug.startsWith(`${dir}/`)).sort(
+        (left, right) => positionOf(left) - positionOf(right) || left.localeCompare(right)
+      );
+      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/" }
+      { label: "Notation glossary", link: "/glossary/" },
+      ...floatIndex ? [{ label: "Figures and tables", link: "/figures-and-tables/" }] : []
     ]
   });
   return groups;
 }
 export {
+  PART_OVERVIEW_CLASS,
   buildSidebar,
   citedSourceIds,
   deriveRequires,

package/dist/compiler/logging.d.ts

@@ -98,7 +98,10 @@ 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.
  */
 declare function diagnosticLine(diagnostic: AnyDiagnostic): string;
 interface RunLogOptions {

package/dist/compiler/logging.js

@@ -7,6 +7,7 @@ import {
   writeFileSync
 } from "node:fs";
 import { join, relative } from "node:path";
+import { ruleIdOf } from "../rules/catalog.js";
 const REPOSITORY_ROOT = process.cwd();
 const LOGS_DIR = join(REPOSITORY_ROOT, "build", "logs");
 const LEVELS = ["ERROR", "WARNING", "INFO"];
@@ -37,7 +38,9 @@ function formatRecord(level, source, message, date) {
 function diagnosticLine(diagnostic) {
   const code = diagnostic.code ?? diagnostic.kind;
   const at = [diagnostic.file, diagnostic.line, diagnostic.column].filter((part) => part !== void 0).join(":");
-  const prefix = code === void 0 ? "" : `[${code}] `;
+  const owner = code === void 0 ? void 0 : ruleIdOf(code);
+  const rule = owner === void 0 || owner === code ? "" : `${owner} `;
+  const prefix = code === void 0 ? "" : `[${rule}${code}] `;
   const equation = diagnostic.equation === void 0 ? "" : ` (eq:${diagnostic.equation.key} -> ${diagnostic.equation.href})`;
   return at === "" ? `${prefix}${diagnostic.message}${equation}` : `${prefix}${at}: ${diagnostic.message}${equation}`;
 }