explico 0.3.0 → 0.5.0

package/src/compiler/cli.ts

@@ -40,7 +40,11 @@ import remarkMdx from 'remark-mdx';
 import { createNotationKatexOptions } from '../reference/katex-options.mjs';
 import rehypeFailKatexErrors from '../reference/rehype-fail-katex-errors.mjs';
 import remarkCitation from '../reference/remark-citation.mjs';
-import remarkNotation from '../reference/remark-notation.mjs';
+import remarkMemo from '../reference/remark-memo.mjs';
+import remarkNotation, {
+  createRemarkNotationOptions,
+} from '../reference/remark-notation.mjs';
+import remarkShortNote from '../reference/remark-short-note.mjs';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
 
@@ -173,6 +177,9 @@ export function lessonDiagnostics(
   for (const diagnostic of [
     ...manifest.diagnostics.tables,
     ...manifest.diagnostics.figures,
+    ...manifest.diagnostics.diagrams,
+    ...manifest.diagnostics.checks,
+    ...manifest.diagnostics.rawFloats,
   ]) {
     if (
       diagnostic.lessonId !== id &&
@@ -221,15 +228,18 @@ function processorFor(manifest: Manifest) {
       // shape here that it does there (D7/F-tables-figures parity).
       remarkMdx,
       remarkMath,
-      [
-        remarkNotation,
-        {
-          definitions: manifest.notation.raw,
-          equations: manifest.equations.numbersBySlug,
-          tables: manifest.tables.numbersBySlug,
-          figures: manifest.figures.numbersBySlug,
-        },
-      ],
+      remarkShortNote,
+      remarkMemo,
+      // `manifest` carries the number tables *and* the part/offset placement
+      // together, so this check numbers a page exactly as the Astro build
+      // does. Passing the tables alone silently numbered pages by `##` section
+      // here while cross-page references read the part-scheme manifest.
+      // No `strict: true` here: `renderLesson()` below is also called
+      // directly with a synthetic path/body that has no manifest entry at all
+      // (fixture renderability checks — see its own doc comment), which
+      // strict mode would reject as "catalogued lesson with no numbering",
+      // even though it was never meant to be catalogued in the first place.
+      [remarkNotation, createRemarkNotationOptions(manifest)],
       [remarkCitation, { sources: manifest.sources }],
     ],
     rehypePlugins: [
@@ -480,6 +490,7 @@ export interface StatusReport {
     readonly keyedEquations: number;
     readonly keyedTables: number;
     readonly keyedFigures: number;
+    readonly keyedDiagrams: number;
   };
   readonly draftDebt: {
     readonly lessons: readonly string[];
@@ -525,6 +536,9 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.equations.map((d) => d.severity),
     ...manifest.diagnostics.tables.map((d) => d.severity),
     ...manifest.diagnostics.figures.map((d) => d.severity),
+    ...manifest.diagnostics.diagrams.map((d) => d.severity),
+    ...manifest.diagnostics.checks.map((d) => d.severity),
+    ...manifest.diagnostics.rawFloats.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map(() => 'warning' as const),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
   ];
@@ -541,6 +555,10 @@ export function contentStatus(manifest: Manifest): StatusReport {
     (count, lesson) => count + lesson.figures.length,
     0,
   );
+  const keyedDiagrams = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.diagrams.length,
+    0,
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
@@ -557,6 +575,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
       keyedEquations,
       keyedTables,
       keyedFigures,
+      keyedDiagrams,
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -597,6 +616,8 @@ export interface ContextReport {
   readonly equations: readonly { key: string; number: string }[];
   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 }[];
   readonly sources: readonly {
     id: string;
     title: string;
@@ -667,6 +688,8 @@ export function contentContext(
     equations: lesson.equations.map((equation) => ({ ...equation })),
     tables: lesson.tables.map((table) => ({ ...table })),
     figures: lesson.figures.map((figure) => ({ ...figure })),
+    diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
+    knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id) as Record<string, unknown> | undefined;
       return {

package/src/compiler/collections.ts

@@ -24,6 +24,7 @@ import type {
   TrackDefinition,
 } from '../curriculum/validation';
 import type {
+  AbbreviationDefinitionInput,
   EditorialStatus,
   LocalNotationDefinitionInput,
   NotationAlignment,
@@ -37,6 +38,8 @@ import type {
 import { isSubstantiveMeaning } from '../reference/prose';
 import { parseEquationRef } from '../reference/equations.mjs';
 import { parseKeyedFloatRef } from '../reference/keyed-jsx-floats.mjs';
+import { parseKnowledgeCheckRef } from '../reference/knowledge-checks.mjs';
+import { parseMemoRef } from '../reference/remark-memo.mjs';
 import { resolveLabel } from '../reference/label';
 import { resolveGlosses } from '../reference/gloss';
 import {
@@ -231,13 +234,17 @@ 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]]` (and their cross-page forms) are
-      // `<Table>`/`<Figure>` references (F-tables-figures) — all resolved by
-      // the remark pass and the manifest, not notation keys.
+      // `[[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.
       if (
         parseEquationRef(key) ||
         parseKeyedFloatRef(key, { prefix: 'tab' }) ||
-        parseKeyedFloatRef(key, { prefix: 'fig' })
+        parseKeyedFloatRef(key, { prefix: 'fig' }) ||
+        parseKeyedFloatRef(key, { prefix: 'dia' }) ||
+        parseKnowledgeCheckRef(key) ||
+        parseMemoRef(key)
       ) {
         continue;
       }
@@ -438,6 +445,40 @@ function sharedNotationEntries(): SharedNotationDefinitionInput[] {
   });
 }
 
+/**
+ * Abbreviations table (rule N14) — a lighter tier than a notation card, read
+ * straight off disk the same way `sharedNotationEntries` reads `notation/`.
+ * The directory is optional: a course that never uses this feature need not
+ * create an empty `content/abbreviations/`.
+ */
+function abbreviationEntries(): AbbreviationDefinitionInput[] {
+  const directory = join(CONTENT_ROOT, 'abbreviations');
+  if (!existsSync(directory)) return [];
+  return filesBelow(directory, ['.md']).map((path) => {
+    const { file, data } = parseDocument(path);
+    const key = string(data.key, `${file} key`);
+    const filenameKey = basename(path, '.md');
+    if (key !== filenameKey) {
+      throw new Error(`${file} declares key ${key}; expected ${filenameKey}`);
+    }
+    const domain = optionalString(data.domain, `${file} domain`);
+    return {
+      key,
+      abbr: string(data.abbr, `${file} abbr`),
+      expansion: meaningText(data.expansion, `${file} expansion`),
+      aliases: strings(data.aliases, `${file} aliases`),
+      source: { file },
+      ...(domain === undefined ? {} : { domain }),
+    };
+  });
+}
+
+export async function loadAbbreviationRegistryInput(): Promise<
+  readonly AbbreviationDefinitionInput[]
+> {
+  return abbreviationEntries();
+}
+
 function notationLessonEntries(): NotationLessonInput[] {
   const lessons: NotationLessonInput[] = [];
   for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {

package/src/compiler/course-config.ts

@@ -7,13 +7,25 @@
  * supplies its own value of this shape.
  */
 
-export interface CourseSection {
+/**
+ * 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.
+ */
+export 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.
+ */
+export type CourseSection = CoursePart;
+
 export interface CourseConventions {
   /** Notation key a lesson's stated sign convention must resolve to. */
   readonly signConventionKey: string;
@@ -37,6 +49,39 @@ export interface CourseOperators {
   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.
+ */
+export 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}.
+ */
+export 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. */
 export interface CourseAuthor {
   readonly name: string;
@@ -71,11 +116,39 @@ export interface CourseAbout {
   readonly changelogHref?: string;
 }
 
+/** Optional, build-time lesson artifacts exposed to readers. */
+export 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. */
+export interface NormalizedLessonExports {
+  readonly standaloneHtml: boolean;
+  readonly print: boolean;
+  readonly canonicalBaseUrl?: string;
+}
+
 export interface CourseConfig {
   readonly title: string;
   readonly description: string;
-  /** Sidebar section groups, in order. */
-  readonly sections: readonly CourseSection[];
+  /**
+   * 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;
@@ -83,4 +156,59 @@ export interface CourseConfig {
   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;
+}
+
+/** Validate and canonicalize the build-facing lesson-export configuration. */
+export function normalizeLessonExports(
+  config: CourseConfig,
+): NormalizedLessonExports {
+  const standaloneHtml = config.lessonExports?.standaloneHtml === true;
+  const print = config.lessonExports?.print === true;
+  const rawBase = config.lessonExports?.canonicalBaseUrl;
+  if (rawBase === undefined) return { standaloneHtml, print };
+
+  let parsed: URL;
+  try {
+    parsed = new URL(rawBase);
+  } catch {
+    throw new Error(
+      `CourseConfig lessonExports.canonicalBaseUrl must be an absolute ` +
+        `http(s) URL; received ${JSON.stringify(rawBase)}.`,
+    );
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(
+      `CourseConfig lessonExports.canonicalBaseUrl must use http(s); ` +
+        `received ${JSON.stringify(rawBase)}.`,
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw new Error(
+      'CourseConfig lessonExports.canonicalBaseUrl cannot contain a query or fragment.',
+    );
+  }
+  if (!parsed.pathname.endsWith('/')) parsed.pathname += '/';
+  return { standaloneHtml, print, canonicalBaseUrl: parsed.toString() };
+}
+
+/**
+ * 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.
+ */
+export function coursePartsOf(config: CourseConfig): readonly CoursePart[] {
+  const parts = config.parts ?? config.sections;
+  if (!parts || parts.length === 0) {
+    throw new Error(
+      'CourseConfig needs at least one entry in `parts` (a sidebar group: ' +
+        '{ dir, label }). The old name `sections` is still accepted.',
+    );
+  }
+  return parts;
 }