explico 0.2.0 → 0.4.0

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

@@ -6,26 +6,102 @@
  * data value and passes it here, typed against `CourseConfig`. A second course
  * supplies its own value of this shape.
  */
-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.
+ */
+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[];
+}
+/** 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;
+}
 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.
+ */
+declare function coursePartsOf(config: CourseConfig): readonly CoursePart[];
 
-export type { CourseConfig, CourseConventions, CourseSection };
+export { type CourseAbout, type CourseAuthor, type CourseConfig, type CourseConventions, type CourseOperators, type CoursePart, type CourseSection, coursePartsOf };

package/dist/compiler/course-config.js

@@ -0,0 +1,12 @@
+function coursePartsOf(config) {
+  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;
+}
+export {
+  coursePartsOf
+};

package/dist/compiler/knowledge-version.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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. */
+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[];
+}
+type KnowledgeVersionCode = 'knowledge-changelog-missing' | 'knowledge-version-invalid' | 'knowledge-version-mismatch';
+interface KnowledgeVersionDiagnostic {
+    readonly code: KnowledgeVersionCode;
+    /** Tier 3 — a knowledge-version drift never fails the build. */
+    readonly severity: 'warning';
+    readonly message: string;
+    readonly file?: string;
+}
+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[];
+}
+declare function isKnowledgeSemver(value: string): boolean;
+/**
+ * Every released entry in a `content/CHANGELOG.md` body, in file order (newest
+ * first, by Keep a Changelog convention). `## [Unreleased]` is skipped.
+ */
+declare function parseKnowledgeChangelog(text: string): KnowledgeChangelogEntry[];
+/**
+ * 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
+ */
+declare function resolveKnowledgeVersion(options: {
+    readonly changelogText: string | undefined;
+    readonly declaredVersion: string;
+    readonly file?: string;
+}): KnowledgeVersion;
+
+export { type KnowledgeChangelogEntry, type KnowledgeVersion, type KnowledgeVersionCode, type KnowledgeVersionDiagnostic, isKnowledgeSemver, parseKnowledgeChangelog, resolveKnowledgeVersion };

package/dist/compiler/knowledge-version.js

@@ -0,0 +1,80 @@
+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*$/;
+function isKnowledgeSemver(value) {
+  return SEMVER_RE.test(value.trim());
+}
+function parseKnowledgeChangelog(text) {
+  const lines = text.split(/\r?\n/);
+  const entries = [];
+  let current = 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;
+    }
+    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 === void 0 ? {} : { date: entry.date },
+    notes: [...entry.notes]
+  }));
+}
+function resolveKnowledgeVersion(options) {
+  const { changelogText, declaredVersion } = options;
+  const file = options.file ?? "content/CHANGELOG.md";
+  const diagnostics = [];
+  const warn = (code, message) => {
+    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 === void 0) {
+    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 \u2014 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 };
+}
+export {
+  isKnowledgeSemver,
+  parseKnowledgeChangelog,
+  resolveKnowledgeVersion
+};

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

@@ -84,6 +84,6 @@ type SidebarGroup = {
  * merged track order (ties broken by slug), then the static Reference group.
  * Replaces seven `autogenerate` blocks that read an authored `sidebar.order`.
  */
-declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], sections: readonly SidebarSection[]): SidebarGroup[];
+declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], parts: readonly SidebarSection[]): SidebarGroup[];
 
 export { type SidebarGroup, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };

package/dist/compiler/lesson-derivation.js

@@ -59,12 +59,12 @@ function mergeTrackOrder(tracks) {
   }
   return ordered;
 }
-function buildSidebar(tracks, lessonSlugs, sections) {
+function buildSidebar(tracks, lessonSlugs, parts) {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index])
   );
   const positionOf = (slug) => rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
-  const groups = sections.map(({ dir, label }) => ({
+  const groups = parts.map(({ dir, label }) => ({
     label,
     items: lessonSlugs.filter((slug) => slug.startsWith(`${dir}/`)).sort(
       (left, right) => positionOf(left) - positionOf(right) || left.localeCompare(right)

package/dist/compiler/manifest.d.ts

@@ -1,13 +1,17 @@
 import { CurriculumIssue } from '../curriculum/validation.js';
 import { ConsistencyDiagnostic } from '../reference/consistency.js';
 import { EquationLabelRecord, EquationDiagnostic } from '../reference/equations-validate.js';
+import { TableLabelRecord, TableDiagnostic } from '../reference/tables-validate.js';
+import { FigureLabelRecord, FigureDiagnostic } from '../reference/figures-validate.js';
 import { MathGateDiagnostic } from '../reference/gate-math.js';
 import { GlyphScopeEntry } from '../reference/gloss.js';
 import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus, NotationGlossEntry } from '../reference/types.js';
 import { CourseConfig } from './course-config.js';
+import { KnowledgeVersionDiagnostic } from './knowledge-version.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
 import '../reference/lint-ignore.js';
+import '../reference/keyed-float-validate.js';
 
 /**
  * The one compiler manifest (Phase D5).
@@ -45,8 +49,20 @@ import '../reference/lint-ignore.js';
  * `diagnostics.consistency` (Tier-3 corpus checks).
  * v3 (D7): `equations` (labelled display equations + cross-page number table),
  * `lessons[].equations`, and `diagnostics.equations`.
+ * v4 (F-tables-figures): `tables`/`figures` (same shape as `equations`, for
+ * `<Table>`/`<Figure>`), `lessons[].tables`/`lessons[].figures`, and
+ * `diagnostics.tables`/`diagnostics.figures`.
+ * v5 (about): `about` (engine identity from `explico`'s `package.json`, the
+ * course's reader-facing `about` block, and the knowledge version resolved
+ * against `content/CHANGELOG.md`) and `diagnostics.knowledge`.
+ * v6 (chapter numbering): `lessons[].chapter` — the lesson's 1-based course
+ * ordinal, the chapter in every equation/table/figure number (`(2.1)`).
+ * v7 (part numbering): `lessons[].part` (the sidebar group's 1-based ordinal,
+ * now the number before the dot), `lessons[].chapter` redefined as the
+ * lesson's ordinal *within its part*, and `lessons[].numbering` — the
+ * per-kind offsets that make `n` run continuously across a part.
  */
-declare const MANIFEST_SCHEMA_VERSION = 3;
+declare const MANIFEST_SCHEMA_VERSION = 7;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -95,6 +111,29 @@ interface ManifestLesson {
     readonly id: string;
     /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
     readonly slug: string;
+    /**
+     * The 1-based ordinal of the **part** this lesson sits in — its sidebar
+     * group's position in `courseConfig.parts`. It is the number before the dot
+     * in every equation, table, and figure number on the page: `(2.1)` is the
+     * first equation of part 2. See `docs/authoring/structure.md`.
+     */
+    readonly part: number;
+    /**
+     * The lesson's 1-based ordinal **within its part** (merged track order, then
+     * any unranked lessons by slug) — its chapter number. This orders the
+     * sidebar and the reading path; it does not appear in a float's number.
+     */
+    readonly chapter: number;
+    /**
+     * How many floats of each kind the earlier lessons of this part already
+     * used. The lesson's own floats continue from here, so a part's sequence
+     * runs unbroken across its chapters instead of restarting on every page.
+     */
+    readonly numbering: {
+        readonly equations: number;
+        readonly tables: number;
+        readonly figures: number;
+    };
     readonly file: string;
     readonly title: string;
     readonly description: string;
@@ -113,6 +152,16 @@ interface ManifestLesson {
         readonly key: string;
         readonly number: string;
     }[];
+    /** Keyed `<Table>` elements in appearance order. */
+    readonly tables: readonly {
+        readonly key: string;
+        readonly number: string;
+    }[];
+    /** Keyed `<Figure>` elements in appearance order. */
+    readonly figures: readonly {
+        readonly key: string;
+        readonly number: string;
+    }[];
     readonly notation: {
         readonly bindings: readonly {
             readonly key: string;
@@ -124,8 +173,39 @@ interface ManifestLesson {
         readonly resolution: readonly ManifestNotationResolution[];
     };
 }
+/** The reader-facing "about this material" bundle — the `[?]` panel's data. */
+interface ManifestAbout {
+    /** `explico`'s own identity, from its `package.json` (the version's golden source). */
+    readonly engine: {
+        readonly name: string;
+        readonly version: string;
+        readonly homepage?: string;
+    };
+    readonly material: {
+        readonly name: string;
+        readonly summary: string;
+    };
+    /** The course's knowledge version — semver over the content, engine-independent. */
+    readonly knowledge: {
+        readonly version: string;
+        /** Date of the newest `content/CHANGELOG.md` entry, if it has one. */
+        readonly date?: string;
+        /** Bullet notes from that entry. */
+        readonly notes: readonly string[];
+        /** Content fingerprint at compile time — ties the shown version to a build. */
+        readonly contentTree: string;
+    };
+    readonly authors: readonly {
+        readonly name: string;
+        readonly contact?: string;
+    }[];
+    readonly disclaimer: string;
+    readonly changelogHref?: string;
+}
 interface Manifest {
     readonly schemaVersion: number;
+    /** Reader-facing identity + versions (the `[?]` About panel). */
+    readonly about: ManifestAbout;
     readonly notation: {
         readonly definitions: readonly NotationDefinitionRecord[];
         readonly bundles: readonly NotationPageBundle[];
@@ -147,6 +227,16 @@ interface Manifest {
         /** `slug -> { eqKey: number }` — passed to `remarkNotation` for `[[slug#eq:key]]`. */
         readonly numbersBySlug: Record<string, Record<string, string>>;
     };
+    /** Keyed-float identity for `<Table>` — same shape as `equations`. */
+    readonly tables: {
+        readonly labels: readonly TableLabelRecord[];
+        readonly numbersBySlug: Record<string, Record<string, string>>;
+    };
+    /** Keyed-float identity for `<Figure>` — same shape as `equations`. */
+    readonly figures: {
+        readonly labels: readonly FigureLabelRecord[];
+        readonly numbersBySlug: Record<string, Record<string, string>>;
+    };
     readonly diagnostics: {
         readonly curriculum: readonly CurriculumIssue[];
         readonly notation: readonly NotationDiagnostic[];
@@ -154,8 +244,14 @@ interface Manifest {
         readonly math: readonly MathGateDiagnostic[];
         /** Tier-3 corpus consistency checks (D6). Warnings only. */
         readonly consistency: readonly ConsistencyDiagnostic[];
+        /** Knowledge-version checks (C3): `about.version` vs `content/CHANGELOG.md`. Warnings only. */
+        readonly knowledge: readonly KnowledgeVersionDiagnostic[];
         /** Equation-identity checks (D7): `eq-duplicate-key`, `eq-ref-resolves` (error); `eq-key-unused` (warning). */
         readonly equations: readonly EquationDiagnostic[];
+        /** `<Table>` identity checks (F-tables-figures) — same codes, `tab-` prefixed. */
+        readonly tables: readonly TableDiagnostic[];
+        /** `<Figure>` identity checks (F-tables-figures) — same codes, `fig-` prefixed. */
+        readonly figures: readonly FigureDiagnostic[];
     };
     readonly hashes: {
         /** `sha256` of every content source file, keyed by repo-relative path. */
@@ -184,4 +280,4 @@ declare function readManifestSync(): Manifest;
  */
 declare function loadManifest(courseConfig?: CourseConfig): Promise<Manifest>;
 
-export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestCitation, type ManifestLesson, type ManifestLessonNotation, type ManifestNotationResolution, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };
+export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestCitation, type ManifestLesson, type ManifestLessonNotation, type ManifestNotationResolution, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };