explico 0.2.0 → 0.4.0

package/src/compiler/cli.ts

@@ -35,6 +35,7 @@ import {
 } from '@astrojs/markdown-remark';
 import rehypeKatex from 'rehype-katex';
 import remarkMath from 'remark-math';
+import remarkMdx from 'remark-mdx';
 
 import { createNotationKatexOptions } from '../reference/katex-options.mjs';
 import rehypeFailKatexErrors from '../reference/rehype-fail-katex-errors.mjs';
@@ -169,6 +170,25 @@ export function lessonDiagnostics(
     });
   }
 
+  for (const diagnostic of [
+    ...manifest.diagnostics.tables,
+    ...manifest.diagnostics.figures,
+  ]) {
+    if (
+      diagnostic.lessonId !== id &&
+      diagnostic.file !== file &&
+      !mentions(diagnostic.message, id, file)
+    ) {
+      continue;
+    }
+    out.push({
+      code: diagnostic.code,
+      severity: diagnostic.severity === 'warning' ? 'warning' : 'error',
+      message: diagnostic.message,
+      ...withFile(diagnostic.file),
+    });
+  }
+
   for (const diagnostic of manifest.diagnostics.consistency) {
     if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
     out.push({
@@ -195,14 +215,17 @@ function processorFor(manifest: Manifest) {
     syntaxHighlight: false,
     smartypants: false,
     remarkPlugins: [
+      // Syntax only (no JSX evaluation) — teaches the parser `<Table>` /
+      // `<Figure>` / `<CompactExample>` are `mdxJsxFlowElement` nodes, same
+      // as the real Astro/MDX build, so `remarkNotation` sees the same tree
+      // shape here that it does there (D7/F-tables-figures parity).
+      remarkMdx,
       remarkMath,
-      [
-        remarkNotation,
-        {
-          definitions: manifest.notation.raw,
-          equations: manifest.equations.numbersBySlug,
-        },
-      ],
+      // `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.
+      [remarkNotation, { definitions: manifest.notation.raw, manifest }],
       [remarkCitation, { sources: manifest.sources }],
     ],
     rehypePlugins: [
@@ -441,6 +464,8 @@ function domainSignaturesForSection(section: string): DomainFileSignatures[] {
 // --- content status ------------------------------------------------------
 
 export interface StatusReport {
+  /** The course's published knowledge version (`about.version`). */
+  readonly knowledgeVersion: string;
   readonly counts: {
     readonly lessons: number;
     readonly competencies: number;
@@ -449,6 +474,8 @@ export interface StatusReport {
     readonly tracks: number;
     readonly notationDefinitions: number;
     readonly keyedEquations: number;
+    readonly keyedTables: number;
+    readonly keyedFigures: number;
   };
   readonly draftDebt: {
     readonly lessons: readonly string[];
@@ -492,18 +519,30 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.alignment.map((d) => d.severity),
     ...manifest.diagnostics.math.map((d) => d.severity),
     ...manifest.diagnostics.equations.map((d) => d.severity),
+    ...manifest.diagnostics.tables.map((d) => d.severity),
+    ...manifest.diagnostics.figures.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map(() => 'warning' as const),
+    ...manifest.diagnostics.knowledge.map((d) => d.severity),
   ];
 
   const keyedEquations = manifest.lessons.reduce(
     (count, lesson) => count + lesson.equations.length,
     0,
   );
+  const keyedTables = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.tables.length,
+    0,
+  );
+  const keyedFigures = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.figures.length,
+    0,
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
 
   return {
+    knowledgeVersion: manifest.about.knowledge.version,
     counts: {
       lessons: manifest.lessons.length,
       competencies: manifest.competencies.length,
@@ -512,6 +551,8 @@ export function contentStatus(manifest: Manifest): StatusReport {
       tracks: manifest.tracks.length,
       notationDefinitions: manifest.notation.definitions.length,
       keyedEquations,
+      keyedTables,
+      keyedFigures,
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -550,6 +591,8 @@ export interface ContextReport {
     formula?: string;
   }[];
   readonly equations: readonly { key: string; number: string }[];
+  readonly tables: readonly { key: string; number: string }[];
+  readonly figures: readonly { key: string; number: string }[];
   readonly sources: readonly {
     id: string;
     title: string;
@@ -618,6 +661,8 @@ export function contentContext(
         : { formula: definition.formula }),
     })),
     equations: lesson.equations.map((equation) => ({ ...equation })),
+    tables: lesson.tables.map((table) => ({ ...table })),
+    figures: lesson.figures.map((figure) => ({ ...figure })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id) as Record<string, unknown> | undefined;
       return {

package/src/compiler/collections.ts

@@ -36,6 +36,7 @@ import type {
 } from '../reference/types';
 import { isSubstantiveMeaning } from '../reference/prose';
 import { parseEquationRef } from '../reference/equations.mjs';
+import { parseKeyedFloatRef } from '../reference/keyed-jsx-floats.mjs';
 import { resolveLabel } from '../reference/label';
 import { resolveGlosses } from '../reference/gloss';
 import {
@@ -229,9 +230,17 @@ export function extractNotationReferences(
   for (const [pattern, referenceKind] of patterns) {
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? '').trim();
-      // `[[eq:key]]` / `[[slug#eq:key]]` are equation references (D7), resolved
-      // by the remark pass and the manifest, not notation keys.
-      if (parseEquationRef(key)) continue;
+      // `[[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.
+      if (
+        parseEquationRef(key) ||
+        parseKeyedFloatRef(key, { prefix: 'tab' }) ||
+        parseKeyedFloatRef(key, { prefix: 'fig' })
+      ) {
+        continue;
+      }
       references.push({
         key,
         kind: referenceKind,

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;
@@ -21,12 +33,90 @@ export interface CourseConventions {
   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`).
+ */
+export 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[];
+}
+
+/** One person or team credited for the study material. */
+export 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`).
+ */
+export 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;
+}
+
 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;
+  /** Reader-facing identity + knowledge version (the `[?]` About panel). */
+  readonly about: CourseAbout;
+  /** Edits to the shipped named-operator baseline (rule N8). Optional. */
+  readonly operators?: CourseOperators;
+}
+
+/**
+ * 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;
 }

package/src/compiler/knowledge-version.ts

@@ -0,0 +1,157 @@
+/**
+ * The course's **knowledge version** — semver over the learning-facing content,
+ * independent of the `explico` engine's own package version.
+ *
+ * The declared value lives in `content/course.config.ts` (`about.version`); the
+ * history and the human-readable notes live in `content/CHANGELOG.md`
+ * (Keep a Changelog shape). This module parses that file and checks the two
+ * agree — rule C3 in `docs/authoring/versioning.md`. Every finding is a Tier-3
+ * warning: `pnpm validate:content` prints it, `manifest.diagnostics.knowledge`
+ * records it, and the build still passes. The resolved entry is what the `[?]`
+ * About panel publishes to readers (`manifest.about.knowledge`).
+ *
+ * Pure: `parseKnowledgeChangelog` takes text, `resolveKnowledgeVersion` takes
+ * text + the declared version. The caller (`compileManifest`) does the file IO.
+ */
+
+/** A released entry from `content/CHANGELOG.md`, newest first in file order. */
+export interface KnowledgeChangelogEntry {
+  readonly version: string;
+  /** The `- YYYY-MM-DD` part of the heading, if present. */
+  readonly date?: string;
+  /** Bullet lines under the heading, marker stripped, in file order. */
+  readonly notes: readonly string[];
+}
+
+export type KnowledgeVersionCode =
+  | 'knowledge-changelog-missing'
+  | 'knowledge-version-invalid'
+  | 'knowledge-version-mismatch';
+
+export interface KnowledgeVersionDiagnostic {
+  readonly code: KnowledgeVersionCode;
+  /** Tier 3 — a knowledge-version drift never fails the build. */
+  readonly severity: 'warning';
+  readonly message: string;
+  readonly file?: string;
+}
+
+export interface KnowledgeVersion {
+  /** The declared `about.version`, echoed for consumers. */
+  readonly version: string;
+  /** The newest released `## [x.y.z]` entry, when the changelog has one. */
+  readonly latest?: KnowledgeChangelogEntry;
+  readonly diagnostics: readonly KnowledgeVersionDiagnostic[];
+}
+
+// `1.2.3`, optionally `-rc.1` / `+build.5` — the shape `about.version` and a
+// `## [x.y.z]` heading must both take.
+const SEMVER_RE =
+  /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const HEADING_RE = /^##\s+\[([^\]]+)\]\s*(?:[-–—]\s*(\S.*?))?\s*$/;
+const BULLET_RE = /^[-*]\s+(.*\S)\s*$/;
+
+export function isKnowledgeSemver(value: string): boolean {
+  return SEMVER_RE.test(value.trim());
+}
+
+/**
+ * Every released entry in a `content/CHANGELOG.md` body, in file order (newest
+ * first, by Keep a Changelog convention). `## [Unreleased]` is skipped.
+ */
+export function parseKnowledgeChangelog(
+  text: string,
+): KnowledgeChangelogEntry[] {
+  const lines = text.split(/\r?\n/);
+  const entries: {
+    version: string;
+    date?: string;
+    notes: string[];
+  }[] = [];
+  let current: { version: string; date?: string; notes: string[] } | null =
+    null;
+
+  for (const line of lines) {
+    const heading = HEADING_RE.exec(line);
+    if (heading) {
+      const token = (heading[1] ?? '').trim();
+      if (/^unreleased$/i.test(token)) {
+        current = null;
+        continue;
+      }
+      current = { version: token, notes: [] };
+      const date = (heading[2] ?? '').trim();
+      if (date) current.date = date;
+      entries.push(current);
+      continue;
+    }
+    // A top-level `#` or a deeper `###` heading ends the current entry's notes.
+    if (/^#{1,3}\s/.test(line) && !line.startsWith('## [')) {
+      current = null;
+      continue;
+    }
+    if (!current) continue;
+    const bullet = BULLET_RE.exec(line);
+    if (bullet) current.notes.push(bullet[1] ?? '');
+  }
+
+  return entries.map((entry) => ({
+    version: entry.version,
+    ...(entry.date === undefined ? {} : { date: entry.date }),
+    notes: [...entry.notes],
+  }));
+}
+
+/**
+ * Check the declared knowledge version against `content/CHANGELOG.md`.
+ *
+ * @param options.changelogText  the file body, or `undefined` when it is absent
+ * @param options.declaredVersion  `courseConfig.about.version`
+ * @param options.file  repo-relative path, for diagnostic messages
+ */
+export function resolveKnowledgeVersion(options: {
+  readonly changelogText: string | undefined;
+  readonly declaredVersion: string;
+  readonly file?: string;
+}): KnowledgeVersion {
+  const { changelogText, declaredVersion } = options;
+  const file = options.file ?? 'content/CHANGELOG.md';
+  const diagnostics: KnowledgeVersionDiagnostic[] = [];
+  const warn = (code: KnowledgeVersionCode, message: string): void => {
+    diagnostics.push({ code, severity: 'warning', message, file });
+  };
+
+  if (!isKnowledgeSemver(declaredVersion)) {
+    warn(
+      'knowledge-version-invalid',
+      `about.version ${JSON.stringify(declaredVersion)} in content/course.config.ts is not a semver \`x.y.z\` string.`,
+    );
+  }
+
+  if (changelogText === undefined) {
+    warn(
+      'knowledge-changelog-missing',
+      `No ${file}. Add a Keep a Changelog file whose newest \`## [x.y.z]\` heading is ${JSON.stringify(declaredVersion)} (rule C1).`,
+    );
+    return { version: declaredVersion, diagnostics };
+  }
+
+  const entries = parseKnowledgeChangelog(changelogText);
+  const latest = entries[0];
+  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).`,
+    );
+    return { version: declaredVersion, diagnostics };
+  }
+
+  if (isKnowledgeSemver(declaredVersion) && latest.version !== declaredVersion) {
+    warn(
+      'knowledge-version-mismatch',
+      `about.version is ${JSON.stringify(declaredVersion)} but the newest ${file} entry is ${JSON.stringify(latest.version)}. Bump one to match the other (rule C3).`,
+    );
+  }
+
+  return { version: declaredVersion, latest, diagnostics };
+}

package/src/compiler/lesson-derivation.ts

@@ -156,7 +156,7 @@ export type SidebarGroup =
 export function buildSidebar(
   tracks: readonly TrackLike[],
   lessonSlugs: readonly string[],
-  sections: readonly SidebarSection[],
+  parts: readonly SidebarSection[],
 ): SidebarGroup[] {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index]),
@@ -164,7 +164,7 @@ export function buildSidebar(
   const positionOf = (slug: string) =>
     rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
 
-  const groups: SidebarGroup[] = sections.map(({ dir, label }) => ({
+  const groups: SidebarGroup[] = parts.map(({ dir, label }) => ({
     label,
     items: lessonSlugs
       .filter((slug) => slug.startsWith(`${dir}/`))