explico 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to the **`explico` engine** are recorded here. The installed
+`package.json` `version` is the single source of truth for what you have; this
+file says what changed between versions and [`docs/VERSIONING.md`](docs/VERSIONING.md)
+says what a version bump means.
+
+A course built on explico keeps its **own** knowledge version — see the course's
+`content/CHANGELOG.md` and [`docs/authoring/versioning.md`](docs/authoring/versioning.md).
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project is pre-1.0: a MINOR bump may carry a breaking change, always listed
+under **Breaking** below; a PATCH never breaks.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-09-05
+
+### Breaking
+
+- `CourseConfig` now requires an `about` block (`materialName?`, `summary?`,
+  `version`, `authors`, `disclaimer`, `changelogHref?`). It carries the course's
+  reader-facing identity and its **knowledge version**. Add one to
+  `content/course.config.ts`.
+- Manifest gains `manifest.about` (engine identity + the course `about` block +
+  the knowledge version resolved from `content/CHANGELOG.md`) and
+  `manifest.diagnostics.knowledge`; `schemaVersion` bumped. Additive — existing
+  fields are unchanged.
+- `EquationRefLayer` / `EquationEnhancer` are replaced by `FloatRefLayer` +
+  `KeyedFloatEnhancer`, one hover/pin/jump engine shared by equation, table, and
+  figure references. Update the wiring in your Starlight `Footer` override.
+
+### Added
+
+- **Figures and tables as first-class keyed floats.** New `Figure` and `Table`
+  components with appearance-order numbering, `#fig-<id>` / `#tab-<id>` anchors,
+  and `[[fig-<id>]]` / `[[tab-<id>]]` cross-references that highlight the target
+  when it is on screen and preview it when it is not — the same model equations
+  already had. New build gates `reference/figures-validate.ts`,
+  `reference/tables-validate.ts`, `reference/keyed-float-validate.ts`, and the
+  `reference/keyed-jsx-floats.mjs` remark pass.
+- **About `[?]` panel.** `components/starlight/AboutPanel.astro` +
+  `LayoutSocialIcons.astro` render a header control, on every route, showing the
+  material name and summary, the knowledge version and date, the engine version,
+  the authors and contact, the disclaimer, and a link to the content changelog.
+  Wire it with `components: { SocialIcons: 'explico/components/starlight/LayoutSocialIcons.astro' }`.
+- **Knowledge versioning.** `compiler/knowledge-version.ts` parses
+  `content/CHANGELOG.md` and checks it against `about.version`; drift is a Tier-3
+  `knowledge-version-mismatch` / `knowledge-changelog-missing` /
+  `knowledge-version-invalid` warning (never fails the build). Governed by new
+  authoring area **C** (`docs/authoring/versioning.md`, rules C1–C4).
+- `Diagram` component (Dagre + build-time KaTeX), with an `LR` direction and an
+  optional hand-written `description` for the text fallback.
+- Notation engine: a base **operator** library (`reference/base-operators.mjs`)
+  alongside the base glyph library, wider automatic glyph resolution in
+  `reference/math-glyphs.mjs`, and `\explain{key}{latex}` support inside notation
+  `formula:` fields and `Diagram` node formulas.
+- `content status` now reports the course's knowledge version.
+- Course-author docs in the published package: `docs/authoring/agents.md`
+  (working on a course repo with an AI agent) and `docs/authoring/migrating.md`
+  (per-version upgrade steps). The published `files` are `dist`, `src`,
+  `README.md`, `CHANGELOG.md`, `docs/VERSIONING.md`, `docs/authoring/` — the
+  repo's own `AGENTS.md` is engine-development guidance and is **no longer
+  shipped** (it described `src/` internals a consumer does not have).
+- `compileManifest` throws a named error, pointing at `migrating.md`, when a
+  course upgrading from 0.2.x has no `about` block — instead of a bare
+  `Cannot read properties of undefined`.
+- `scripts/agent/` (`verify`, `fresh`, `shot`) and a generated, staleness-gated
+  repo map in the repo's `AGENTS.md` (`scripts/agent/gen-map.mjs`) — repo tooling,
+  not part of the package.
+
+### Changed
+
+- Deep-linkable heading anchors (`rehype-heading-anchors` +
+  `HeadingAnchorEnhancer`) and numbered lesson equations are on by default.
+- `remark-notation` and `consistency` gained substantial coverage for the
+  keyed-float syntax, operator resolution, and `\explain` handling.
+
+## [0.2.0] - 2026-09-04
+
+- Two-tier notation vocabulary: named operators (rule N8) are a Tier-3
+  `operator-explained` warning against a shipped baseline plus a per-course
+  `operators.allow` / `operators.deny` list, softer than the identifier gate.
+- Heading deep links: `rehype-heading-anchors` + `HeadingAnchorEnhancer.astro`.
+- `popup-stack.ts` — nested, independently positioned notation popups.
+
+## [0.1.1] - 2026-09-03
+
+- Make the published build load under Node ESM (`.mjs` extension fixups, `dist/`
+  resolution).
+
+## [0.1.0] - 2026-09-03
+
+- Initial import of the explico engine, extracted from the `equations` project:
+  the one manifest compiler, the notation / citation / equation reference
+  system with its completeness gate, the curriculum-graph validator, the
+  Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
+
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/danieltuzes/explico/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/danieltuzes/explico/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/danieltuzes/explico/releases/tag/v0.1.0

package/README.md

@@ -14,7 +14,10 @@ What it gives a course:
   meaning; a **completeness gate** fails the build if any identifier in any
   rendered-math context (lesson body, `notation.formula`, `checks.yml`,
   assessment prompts, component slots) does not resolve to a key. One meaning
-  per glyph per page, enforced corpus-wide.
+  per glyph per page, enforced corpus-wide. Named operators get the same
+  treatment one tier softer: a lesson's `\operatorname{Var}` is a warning
+  (`operator-explained`) until it carries an entry or the course lists it in
+  `operators.allow`; a shipped baseline (`\exp`, `\int`, trig, …) is exempt.
 - **Inline citations** — `[@source-id; locator]` → numbered marker + generated
   reference list, resolved against a schema-checked source collection.
 - **Equation identity** — `\label{eq:key}` gives a display equation a stable
@@ -28,6 +31,14 @@ What it gives a course:
 - **Shared Astro/Starlight UI** — a hover-panel primitive shared by the
   notation and citation layers, a glossary, a curriculum map, compact examples,
   layout overrides.
+- **Interactive figures, with room to grow** — a `labMathScope`/`renderLabMath`
+  seam compiles a `\slot{}`-templated formula against the page's real notation
+  at build time, so a client-side island only ever patches numbers into
+  pre-rendered KaTeX. Hand-rolled SVG is the default chart (zero dependency,
+  covers a single custom figure); reach for D3 once a figure needs real
+  tick-labeled axes, log scales, or several series sharing a scale; Observable
+  Plot pays off once a course is authoring many charts per lecture. Pick per
+  figure — nothing in the engine assumes one plotting approach.
 - **LMS / analytics / identity seams** — framework-free interfaces shipped as
   no-ops; a host supplies real implementations without touching a component.
 - **A `content` CLI** — `status`, `context <lesson>`, `check <lesson>` (compiles
@@ -67,7 +78,8 @@ import { courseConfig } from './content/course.config.ts';
 
 const manifest = await loadManifest(courseConfig);
 // … starlight({ customCss: ['explico/styles/global.css'],
-//               components: { Footer: 'explico/components/starlight/LessonFooter.astro', … } })
+//               components: { Footer: 'explico/components/starlight/LessonFooter.astro',
+//                             SocialIcons: 'explico/components/starlight/LayoutSocialIcons.astro', … } })
 // … markdown.remarkPlugins / rehypePlugins from the manifest
 ```
 
@@ -92,6 +104,19 @@ discounting → bonds → credit/CDS → derivatives and options.
 | `src/content-config.ts`                           | the Zod collection schemas (Astro re-exports them)                                                                                          |
 | `src/styles/`                                     | `global.css` (notation panel, keyed-equation flash, KaTeX)                                                                                  |
 
+## Authoring
+
+Course content follows the rules in [`docs/authoring/`](docs/authoring/) —
+strong recommendations for human and AI authors covering notation spelling
+(`\mathcal{N}` for the normal, `\mathbb{P}` for probability, upright `\mathrm{d}`
+for the differential, …), which library draws a diagram or
+chart (`Diagram` for graphs; SVG → D3 → Observable Plot for charts), how
+randomised interactive figures pick their axes, and how the course's knowledge
+version and `content/CHANGELOG.md` move with a content change (area `C`,
+surfaced to readers in the About `[?]` panel).
+[`docs/authoring/README.md`](docs/authoring/README.md) is the governance: rule
+IDs, enforcement levels, and how to amend.
+
 ## Build
 
 ```bash
@@ -102,7 +127,23 @@ pnpm build   # tsup → dist/ (ESM + .d.ts) for the .ts core; .astro / .tsx / .c
 Published `exports` resolve to `dist/` for the typed core and to `src/` for the
 Astro components and styles (see `publishConfig` in `package.json`).
 
-## Status
+## Versioning
+
+The engine follows [semver](https://semver.org). The **golden source** for the
+version is the installed `package.json` (`explico`'s own `version`); the About
+`[?]` panel reads it at build time and the docs never repeat a number.
+
+- [`CHANGELOG.md`](CHANGELOG.md) — what changed between engine versions.
+- [`docs/VERSIONING.md`](docs/VERSIONING.md) — what a MAJOR / MINOR / PATCH bump
+  means here, the public surface it is measured against, and the pre-1.0 clause.
+
+A course built on explico carries an **independent knowledge version** over its
+content — `about.version` in `content/course.config.ts`, tracked in the course's
+`content/CHANGELOG.md`, surfaced to readers in the same `[?]` panel. See
+[`docs/authoring/versioning.md`](docs/authoring/versioning.md).
+
+For AI authors: [`AGENTS.md`](AGENTS.md) says which changelog and which version a
+given change updates.
 
-`0.1.x` — extracted from the `equations` project. API not yet stable; the
-license is undecided (`UNLICENSED` until chosen).
+Status: extracted from the `equations` project; API not yet stable (pre-1.0);
+the license is undecided (`UNLICENSED` until chosen).

package/dist/compiler/cli.d.ts

@@ -6,7 +6,12 @@ import './collections.js';
 import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
+import '../reference/tables-validate.js';
+import '../reference/keyed-float-validate.js';
+import '../reference/figures-validate.js';
 import '../reference/gate-math.js';
+import '../reference/gloss.js';
+import './knowledge-version.js';
 import './lesson-derivation.js';
 
 /**
@@ -90,6 +95,8 @@ interface DomainFileSignatures {
     readonly signatures: readonly string[];
 }
 interface StatusReport {
+    /** The course's published knowledge version (`about.version`). */
+    readonly knowledgeVersion: string;
     readonly counts: {
         readonly lessons: number;
         readonly competencies: number;
@@ -98,6 +105,8 @@ interface StatusReport {
         readonly tracks: number;
         readonly notationDefinitions: number;
         readonly keyedEquations: number;
+        readonly keyedTables: number;
+        readonly keyedFigures: number;
     };
     readonly draftDebt: {
         readonly lessons: readonly string[];
@@ -144,6 +153,14 @@ interface ContextReport {
         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;

package/dist/compiler/cli.js

@@ -8,6 +8,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";
 import remarkCitation from "../reference/remark-citation.mjs";
@@ -81,6 +82,20 @@ function lessonDiagnostics(manifest, lesson) {
       ...withFile(diagnostic.file)
     });
   }
+  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({
@@ -100,12 +115,19 @@ function processorFor(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
+          equations: manifest.equations.numbersBySlug,
+          tables: manifest.tables.numbersBySlug,
+          figures: manifest.figures.numbersBySlug
         }
       ],
       [remarkCitation, { sources: manifest.sources }]
@@ -279,16 +301,28 @@ function contentStatus(manifest) {
     ...manifest.diagnostics.alignment.map((d) => d.severity),
     ...manifest.diagnostics.math.map((d) => d.severity),
     ...manifest.diagnostics.equations.map((d) => d.severity),
-    ...manifest.diagnostics.consistency.map(() => "warning")
+    ...manifest.diagnostics.tables.map((d) => d.severity),
+    ...manifest.diagnostics.figures.map((d) => d.severity),
+    ...manifest.diagnostics.consistency.map(() => "warning"),
+    ...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,
@@ -296,7 +330,9 @@ function contentStatus(manifest) {
       sources: manifest.sources.length,
       tracks: manifest.tracks.length,
       notationDefinitions: manifest.notation.definitions.length,
-      keyedEquations
+      keyedEquations,
+      keyedTables,
+      keyedFigures
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -350,6 +386,8 @@ function contentContext(manifest, rawId) {
       ...definition.formula === void 0 ? {} : { 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);
       return {

package/dist/compiler/collections.js

@@ -3,7 +3,9 @@ import { basename, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
 import { isSubstantiveMeaning } from "../reference/prose.js";
 import { parseEquationRef } from "../reference/equations.mjs";
+import { parseKeyedFloatRef } from "../reference/keyed-jsx-floats.mjs";
 import { resolveLabel } from "../reference/label.js";
+import { resolveGlosses } from "../reference/gloss.js";
 import {
   deriveRequires,
   deriveSources,
@@ -135,7 +137,9 @@ function extractNotationReferences(text, file, kind) {
   for (const [pattern, referenceKind] of patterns) {
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? "").trim();
-      if (parseEquationRef(key)) continue;
+      if (parseEquationRef(key) || parseKeyedFloatRef(key, { prefix: "tab" }) || parseKeyedFloatRef(key, { prefix: "fig" })) {
+        continue;
+      }
       references.push({
         key,
         kind: referenceKind,
@@ -206,6 +210,30 @@ async function loadCurriculumCatalog() {
     tracks: jsonEntries(join(CONTENT_ROOT, "tracks"))
   };
 }
+function glossEntries(raw, ownerKey, at) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) throw new Error(`${at} must be an array`);
+  const authored = raw.map((value, index) => {
+    const data = record(value, `${at}[${index}]`);
+    const units = optionalString(data.units, `${at}[${index}].units`);
+    return {
+      latex: string(data.latex, `${at}[${index}].latex`),
+      name: string(data.name, `${at}[${index}].name`),
+      ...units === void 0 ? {} : { units }
+    };
+  });
+  const glosses = resolveGlosses(ownerKey, authored);
+  const seen = /* @__PURE__ */ new Set();
+  for (const gloss of glosses) {
+    if (seen.has(gloss.key)) {
+      throw new Error(
+        `${at} declares two glosses named ${JSON.stringify(gloss.label)}`
+      );
+    }
+    seen.add(gloss.key);
+  }
+  return glosses;
+}
 function localDefinition(raw, file, index) {
   const at = `${file} notation.local[${index}]`;
   const data = record(raw, at);
@@ -224,6 +252,7 @@ function localDefinition(raw, file, index) {
     seeAlso: strings(data.seeAlso, `${at}.seeAlso`),
     alignment: data.alignment === void 0 ? { kind: "general", rationale: "Lesson-local symbol." } : alignment(data.alignment, `${at}.alignment`),
     references: extractNotationReferences(definitionText, file, "definition"),
+    glosses: glossEntries(data.glosses, key, `${at}.glosses`),
     source: { file },
     ...formula === void 0 ? {} : { formula },
     ...units === void 0 ? {} : { units }
@@ -255,6 +284,7 @@ function sharedNotationEntries() {
       aiAssisted: boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
       references: extractNotationReferences(body, file, void 0),
+      glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
       ...formula === void 0 ? {} : { formula },
       ...units === void 0 ? {} : { units }

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

@@ -18,6 +18,53 @@ interface CourseConventions {
     /** 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;
@@ -26,6 +73,10 @@ interface CourseConfig {
     /** 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;
 }
 
-export type { CourseConfig, CourseConventions, CourseSection };
+export type { CourseAbout, CourseAuthor, CourseConfig, CourseConventions, CourseOperators, CourseSection };

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
+};