explico 0.2.0 → 0.3.0

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/manifest.ts

@@ -34,6 +34,7 @@ import {
   readdirSync,
   writeFileSync,
 } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join, relative } from 'node:path';
 import { parseFrontmatter } from '@astrojs/markdown-remark';
 
@@ -51,6 +52,16 @@ import {
   type EquationDiagnostic,
   type EquationLabelRecord,
 } from '../reference/equations-validate';
+import {
+  validateTables,
+  type TableDiagnostic,
+  type TableLabelRecord,
+} from '../reference/tables-validate';
+import {
+  validateFigures,
+  type FigureDiagnostic,
+  type FigureLabelRecord,
+} from '../reference/figures-validate';
 import {
   gateContentMath,
   type MathGateDiagnostic,
@@ -70,6 +81,10 @@ import type {
   NotationPageBundle,
 } from '../reference/types';
 import type { CourseConfig } from './course-config';
+import {
+  resolveKnowledgeVersion,
+  type KnowledgeVersionDiagnostic,
+} from './knowledge-version';
 import {
   loadCurriculumCatalog,
   loadNotationDefinitions,
@@ -81,6 +96,7 @@ import {
   buildSidebar,
   deriveSources,
   isLessonSlug,
+  lessonIdFromSlug,
   type SidebarGroup,
 } from './lesson-derivation';
 
@@ -92,8 +108,16 @@ import {
  * `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)`).
  */
-export const MANIFEST_SCHEMA_VERSION = 3;
+export const MANIFEST_SCHEMA_VERSION = 6;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -101,6 +125,33 @@ const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, 'content');
 export const MANIFEST_PATH = join(REPOSITORY_ROOT, 'build', 'manifest.json');
 
+interface EnginePackage {
+  readonly name: string;
+  readonly version: string;
+  readonly homepage?: string;
+}
+
+/**
+ * `explico`'s own identity — the golden source for the engine version the About
+ * panel shows (the README points here, not a literal).
+ *
+ * Resolved as the bare specifier `explico/package.json` (a published `exports`
+ * entry, and a package self-reference inside this repo) through `createRequire`,
+ * so it survives being re-bundled by a course's Astro build — a relative
+ * `../../package.json` would follow the *bundle* location, not the source's.
+ * Lazy + cached: importing this module for `readManifestSync` must stay free of
+ * filesystem side effects; only `compileManifest` needs the value.
+ */
+let enginePackage: EnginePackage | undefined;
+function readEnginePackage(): EnginePackage {
+  if (!enginePackage) {
+    enginePackage = createRequire(import.meta.url)(
+      'explico/package.json',
+    ) as EnginePackage;
+  }
+  return enginePackage;
+}
+
 // --- shape ------------------------------------------------------------
 
 export interface ManifestCitation {
@@ -154,6 +205,12 @@ export interface ManifestLesson {
   readonly id: string;
   /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
   readonly slug: string;
+  /**
+   * The lesson's 1-based ordinal in the course (merged track order, then any
+   * unranked lessons by slug). It is the chapter in every equation, table, and
+   * figure number on the page — `(2.1)` is the first equation of chapter 2.
+   */
+  readonly chapter: number;
   readonly file: string;
   readonly title: string;
   readonly description: string;
@@ -172,6 +229,16 @@ export 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;
@@ -184,8 +251,37 @@ export interface ManifestLesson {
   };
 }
 
+/** The reader-facing "about this material" bundle — the `[?]` panel's data. */
+export 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;
+}
+
 export 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[];
@@ -207,6 +303,16 @@ export 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[];
@@ -214,8 +320,14 @@ export 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. */
@@ -395,6 +507,22 @@ function lessonFrontmatterById(): Map<
 export async function compileManifest(
   courseConfig: CourseConfig,
 ): Promise<Manifest> {
+  // `about` became required in explico 0.3.0. A course upgrading from 0.2.x
+  // hits this before the raw `Cannot read properties of undefined` further
+  // down; the message names the fix and the guide.
+  if (
+    courseConfig.about === undefined ||
+    courseConfig.about.version === undefined ||
+    courseConfig.about.authors === undefined ||
+    courseConfig.about.disclaimer === undefined
+  ) {
+    throw new Error(
+      "course.config.ts is missing a complete `about` block (required since explico 0.3.0): " +
+        "`about: { version, authors: [{ name }], disclaimer, materialName?, summary?, changelogHref? }`. " +
+        'See docs/authoring/migrating.md (§ 0.2.x → 0.3.0) in the installed package.',
+    );
+  }
+
   const [catalog, notationInput] = await Promise.all([
     loadCurriculumCatalog(),
     loadNotationRegistryInput(),
@@ -452,20 +580,57 @@ export async function compileManifest(
   );
   const frontmatterById = lessonFrontmatterById();
 
-  const equationValidation = validateEquations(
-    notationInput.lessons.map((lesson) => ({
-      lessonId: lesson.lessonId,
-      slug: lesson.lessonId.replace(/\./g, '/'),
-      file: lesson.source.file,
-      body: lesson.body,
-    })),
+  const lessonSlugs = [...notationInput.lessons]
+    .map((lesson) => lesson.lessonId.replace(/\./g, '/'))
+    .sort();
+  const sidebar = buildSidebar(
+    catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
+    lessonSlugs,
+    courseConfig.sections,
   );
+
+  // A lesson's chapter is its position when the sidebar is read top to bottom
+  // (sections in config order, lessons within a section by merged track order
+  // then slug). It prefixes every equation / table / figure number on the page
+  // (`(2.1)` = first equation of chapter 2). Derived from `sidebar` so there is
+  // one lesson-ordering source, not two.
+  const chapterByLessonId = new Map<string, number>();
+  let chapterCursor = 0;
+  for (const group of sidebar) {
+    for (const item of group.items) {
+      if (typeof item !== 'string') continue; // the static Reference group
+      chapterByLessonId.set(lessonIdFromSlug(item), ++chapterCursor);
+    }
+  }
+
+  const keyedFloatLessonInputs = notationInput.lessons.map((lesson) => ({
+    lessonId: lesson.lessonId,
+    slug: lesson.lessonId.replace(/\./g, '/'),
+    file: lesson.source.file,
+    body: lesson.body,
+    chapter: chapterByLessonId.get(lesson.lessonId),
+  }));
+  const equationValidation = validateEquations(keyedFloatLessonInputs);
   const equationsBySlug = new Map(
     Object.entries(equationValidation.numbersBySlug).map(([slug, table]) => [
       slug,
       Object.entries(table).map(([key, number]) => ({ key, number })),
     ]),
   );
+  const tableValidation = validateTables(keyedFloatLessonInputs);
+  const tablesBySlug = new Map(
+    Object.entries(tableValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number })),
+    ]),
+  );
+  const figureValidation = validateFigures(keyedFloatLessonInputs);
+  const figuresBySlug = new Map(
+    Object.entries(figureValidation.numbersBySlug).map(([slug, table]) => [
+      slug,
+      Object.entries(table).map(([key, number]) => ({ key, number })),
+    ]),
+  );
 
   const lessons: ManifestLesson[] = [];
   for (const notationLesson of notationInput.lessons) {
@@ -480,6 +645,10 @@ export async function compileManifest(
     lessons.push({
       id,
       slug: id.replace(/\./g, '/'),
+      // 0 = the lesson is not placed in any configured section; a curriculum
+      // diagnostic covers that separately, and both numbering paths then fall
+      // back to the legacy `##`-section scheme.
+      chapter: chapterByLessonId.get(id) ?? 0,
       file: notationLesson.source.file,
       title: frontmatter.title,
       description: frontmatter.description,
@@ -491,6 +660,8 @@ export async function compileManifest(
       sources: deriveSources(notationLesson.body),
       citations: lessonCitations(notationLesson.body),
       equations: equationsBySlug.get(id.replace(/\./g, '/')) ?? [],
+      tables: tablesBySlug.get(id.replace(/\./g, '/')) ?? [],
+      figures: figuresBySlug.get(id.replace(/\./g, '/')) ?? [],
       prereqEdges: sortEdges(
         teaches.flatMap((to) =>
           (prerequisitesById.get(to) ?? [])
@@ -519,6 +690,9 @@ export async function compileManifest(
     catalog,
     lintIgnore: loadLintIgnore(),
     conventions: courseConfig.conventions,
+    ...(courseConfig.operators === undefined
+      ? {}
+      : { operators: courseConfig.operators }),
   });
 
   const rawNotation = [...loadNotationDefinitions()].sort((a, b) =>
@@ -530,17 +704,54 @@ export async function compileManifest(
   const sources = [...loadSourceRecords()].sort(byId);
   const tracks = catalog.tracks.map((entry) => ({ ...entry })).sort(byId);
 
-  const lessonSlugs = [...notationInput.lessons]
-    .map((lesson) => lesson.lessonId.replace(/\./g, '/'))
-    .sort();
-  const sidebar = buildSidebar(
-    catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
-    lessonSlugs,
-    courseConfig.sections,
-  );
+  const hashes = contentHashes();
+
+  // Knowledge version (C3): `about.version` vs the newest `content/CHANGELOG.md`
+  // entry. Every finding is a Tier-3 warning; the resolved entry feeds the
+  // `[?]` About panel.
+  const knowledgeChangelogPath = join(CONTENT_ROOT, 'CHANGELOG.md');
+  const knowledge = resolveKnowledgeVersion({
+    changelogText: existsSync(knowledgeChangelogPath)
+      ? readFileSync(knowledgeChangelogPath, 'utf8')
+      : undefined,
+    declaredVersion: courseConfig.about.version,
+    file: relative(REPOSITORY_ROOT, knowledgeChangelogPath).replace(/\\/g, '/'),
+  });
+
+  const enginePkg = readEnginePackage();
+  const about: ManifestAbout = {
+    engine: {
+      name: enginePkg.name,
+      version: enginePkg.version,
+      ...(enginePkg.homepage === undefined
+        ? {}
+        : { homepage: enginePkg.homepage }),
+    },
+    material: {
+      name: courseConfig.about.materialName ?? courseConfig.title,
+      summary: courseConfig.about.summary ?? courseConfig.description,
+    },
+    knowledge: {
+      version: knowledge.version,
+      ...(knowledge.latest?.date === undefined
+        ? {}
+        : { date: knowledge.latest.date }),
+      notes: knowledge.latest?.notes ?? [],
+      contentTree: hashes.contentTree,
+    },
+    authors: courseConfig.about.authors.map((author) => ({
+      name: author.name,
+      ...(author.contact === undefined ? {} : { contact: author.contact }),
+    })),
+    disclaimer: courseConfig.about.disclaimer,
+    ...(courseConfig.about.changelogHref === undefined
+      ? {}
+      : { changelogHref: courseConfig.about.changelogHref }),
+  };
 
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
+    about,
     notation: {
       definitions: registry.definitions,
       bundles: registry.bundles,
@@ -558,6 +769,14 @@ export async function compileManifest(
       labels: equationValidation.labels,
       numbersBySlug: equationValidation.numbersBySlug,
     },
+    tables: {
+      labels: tableValidation.labels,
+      numbersBySlug: tableValidation.numbersBySlug,
+    },
+    figures: {
+      labels: figureValidation.labels,
+      numbersBySlug: figureValidation.numbersBySlug,
+    },
     diagnostics: {
       curriculum: curriculumIssues,
       notation: registry.diagnostics,
@@ -565,8 +784,11 @@ export async function compileManifest(
       math: mathIssues,
       consistency: consistencyIssues,
       equations: equationValidation.diagnostics,
+      tables: tableValidation.diagnostics,
+      figures: figureValidation.diagnostics,
+      knowledge: knowledge.diagnostics,
     },
-    hashes: contentHashes(),
+    hashes,
   };
 }
 

package/src/components/CurriculumMap.astro

@@ -2,6 +2,7 @@
 import { getCollection } from 'astro:content';
 import { loadManifest } from '../compiler/manifest';
 import { isLessonSlug, lessonIdFromSlug } from '../compiler/lesson-derivation';
+import Diagram, { type DiagramEdge, type DiagramNode } from './diagram/Diagram.astro';
 
 const [tracks, docs, competencies, manifest] = await Promise.all([
   getCollection('tracks'),
@@ -22,6 +23,20 @@ const lessonById = new Map(
 const competencyById = new Map(
   competencies.map((entry) => [entry.data.id, entry.data]),
 );
+
+// The dependency graph is read straight off the authored `prerequisites`
+// lists — no separate content to keep in sync, and the same data the build's
+// DAG/cycle validator already checks.
+const competencyNodes: DiagramNode[] = competencies.map(({ data }) => ({
+  id: data.id,
+  text: data.title,
+}));
+const competencyEdges: DiagramEdge[] = competencies.flatMap(({ data }) =>
+  data.prerequisites.map((prerequisiteId) => ({
+    from: prerequisiteId,
+    to: data.id,
+  })),
+);
 ---
 
 {
@@ -110,6 +125,18 @@ const competencyById = new Map(
     The build rejects unknown references, cycles, invalid lesson ordering, and
     insufficient assessment coverage.
   </p>
+
+  {
+    competencyNodes.length > 0 && (
+      <Diagram
+        id="competency-graph"
+        label="Competency dependency graph"
+        nodes={competencyNodes}
+        edges={competencyEdges}
+      />
+    )
+  }
+
   <ol class="competency-map">
     {
       competencies