explico 0.13.1 → 0.15.0

package/src/compiler/collections.ts

@@ -51,11 +51,19 @@ import { indexEntryFormula } from '../reference/derived-notation.mjs';
 import { isIndexEntryLatex } from './content-schemas';
 import type { ContentRecord } from '../reference/gate-retired-keys';
 import {
+  deckLessonSlug,
+  deckPageId,
+  deckRouteSlug,
   deriveRequires,
   deriveSources,
+  isDeckSlug,
   isLessonSlug,
+  isPartDeckSlug,
   lessonIdFromSlug,
   parseCheckList,
+  partDeckDir,
+  partDeckPageId,
+  partDeckRouteSlug,
 } from './lesson-derivation';
 
 // Every invocation — the CLI, `astro build`/`check`, and vitest — runs with the
@@ -325,14 +333,166 @@ function docSlug(path: string): string {
   return relative(join(CONTENT_ROOT, 'docs'), path).replace(/\\/g, '/');
 }
 
-/** Assessment ids from a lesson's colocated `<name>.checks.yml`, or `[]`. */
+/**
+ * Assessment ids from a lesson's colocated `<name>.checks.yml`, or `[]`. A
+ * deck file (`<name>.deck.mdx`) reads the same file as its chapter: the checks
+ * belong to the lesson, whichever edition shows them.
+ */
 function lessonCheckIds(lessonPath: string): string[] {
-  const checksPath = lessonPath.replace(/\.mdx?$/, '.checks.yml');
+  const checksPath = lessonPath.replace(/(?:\.deck)?\.mdx?$/, '.checks.yml');
   return existsSync(checksPath)
     ? parseCheckList(readFileSync(checksPath, 'utf8'))
     : [];
 }
 
+/** Every `.md` / `.mdx` file under `content/docs/`, sorted. */
+function docsFiles(): string[] {
+  const root = join(CONTENT_ROOT, 'docs');
+  return existsSync(root) ? filesBelow(root, ['.md', '.mdx']) : [];
+}
+
+/** What every deck file is, whichever it belongs to ({@link DeckFile}). */
+interface DeckFileBase {
+  /** Absolute path of the deck file. */
+  readonly path: string;
+  /** Repository-relative path, the `file` of its diagnostics. */
+  readonly file: string;
+  /** Docs slug of the deck file, extension included: `motion/range.deck.mdx`. */
+  readonly slug: string;
+  /** Where the deck is served: `motion/range/slides`, `motion/range` alone, or a part's `motion/slides`. */
+  readonly route: string;
+  /** The id of the deck's page: `motion.range.slides`, the lesson's id alone, or a part's `motion.slides`. */
+  readonly pageId: string;
+  /** The part directory the deck sits in: `motion`; empty for a deck outside one. */
+  readonly partDir: string;
+  /** True when the deck sits in a part's directory, as a lesson does. */
+  readonly inPart: boolean;
+  /** The deck file's frontmatter. */
+  readonly data: Record<string, unknown>;
+  readonly body: string;
+  /** 1-based file line {@link body} starts on. */
+  readonly bodyLine: number;
+}
+
+/**
+ * A lesson's deck (`<lesson>.deck.mdx`): its slide edition, beside the
+ * lesson's chapter or, for a lesson that is only slides, alone. See
+ * `docs/authoring/deck.md`.
+ */
+export interface LessonDeckFile extends DeckFileBase {
+  readonly scope: 'lesson';
+  /** The lesson's slug: `motion/range`. */
+  readonly lessonSlug: string;
+  readonly lessonId: string;
+  /** The lesson's chapter file, when it has one. */
+  readonly chapterPath?: string;
+}
+
+/**
+ * A part's deck (`<part>/index.deck.mdx`, beside the part's page): the
+ * slides of the part, whose sections may name the chapters they cover. It
+ * belongs to no lesson.
+ */
+export interface PartDeckFile extends DeckFileBase {
+  readonly scope: 'part';
+}
+
+/** A deck file: a lesson's slide edition, or a part's deck. */
+export type DeckFile = LessonDeckFile | PartDeckFile;
+
+/** A lesson's chapter file, `.mdx` before `.md`, if it has one. */
+function chapterPathOf(lessonSlug: string): string | undefined {
+  for (const extension of ['.mdx', '.md']) {
+    const path = join(CONTENT_ROOT, 'docs', `${lessonSlug}${extension}`);
+    if (existsSync(path)) return path;
+  }
+  return undefined;
+}
+
+/**
+ * Every deck file, by slug: each lesson's, and each part's. A part's deck
+ * (`<part>/index.deck.mdx`) is never read as the deck of a lesson
+ * `<part>/index` whose chapter is the part's page.
+ */
+export function loadDeckFiles(): DeckFile[] {
+  const decks: DeckFile[] = [];
+  for (const path of docsFiles()) {
+    const slug = docSlug(path);
+    if (!isDeckSlug(slug)) continue;
+    const { file, data, body, bodyLine } = parseDocument(path);
+    if (isPartDeckSlug(slug)) {
+      const partDir = partDeckDir(slug);
+      decks.push({
+        scope: 'part',
+        path,
+        file,
+        slug,
+        route: partDeckRouteSlug(partDir),
+        pageId: partDeckPageId(partDir),
+        partDir,
+        inPart: true,
+        data,
+        body,
+        bodyLine,
+      });
+      continue;
+    }
+    const lessonSlug = deckLessonSlug(slug);
+    const lessonId = lessonIdFromSlug(lessonSlug);
+    const chapterPath = chapterPathOf(lessonSlug);
+    const hasChapter = chapterPath !== undefined;
+    decks.push({
+      scope: 'lesson',
+      path,
+      file,
+      slug,
+      lessonSlug,
+      lessonId,
+      ...(chapterPath === undefined ? {} : { chapterPath }),
+      route: deckRouteSlug(lessonSlug, hasChapter),
+      pageId: deckPageId(lessonId, hasChapter),
+      partDir: lessonSlug.includes('/') ? lessonSlug.slice(0, lessonSlug.indexOf('/')) : '',
+      inPart: lessonSlug.includes('/') && !lessonSlug.endsWith('/index'),
+      data,
+      body,
+      bodyLine,
+    });
+  }
+  return decks;
+}
+
+/**
+ * A file that defines a lesson: every chapter, and every deck whose lesson has
+ * no chapter (a slides-first lesson). Its frontmatter is the lesson's —
+ * `teaches`, `assumptions`, `studyMinutes`, `notation` — and its body is what
+ * the lesson's numbering and curriculum passes read.
+ */
+export interface LessonFile {
+  readonly path: string;
+  /** Docs slug of the file, extension included. */
+  readonly slug: string;
+  readonly lessonSlug: string;
+  readonly lessonId: string;
+  readonly edition: 'chapter' | 'deck';
+}
+
+/** Every lesson's defining file, sorted by lesson slug. */
+export function loadLessonFiles(): LessonFile[] {
+  const lessons: LessonFile[] = [];
+  for (const path of docsFiles()) {
+    const slug = docSlug(path);
+    if (isLessonSlug(slug)) {
+      const lessonSlug = slug.replace(/\.(md|mdx)$/, '');
+      lessons.push({ path, slug, lessonSlug, lessonId: lessonIdFromSlug(slug), edition: 'chapter' });
+    } else if (isDeckSlug(slug) && slug.includes('/') && !isPartDeckSlug(slug)) {
+      const lessonSlug = deckLessonSlug(slug);
+      if (chapterPathOf(lessonSlug) !== undefined) continue;
+      lessons.push({ path, slug, lessonSlug, lessonId: lessonIdFromSlug(lessonSlug), edition: 'deck' });
+    }
+  }
+  return lessons.sort((left, right) => left.lessonSlug.localeCompare(right.lessonSlug));
+}
+
 /**
  * One part's **overview page** — `content/docs/<dir>/index.mdx`, the page the
  * part's own directory URL resolves to. `isLessonSlug` already excludes any
@@ -388,17 +548,26 @@ function lessonEntries(
   prerequisitesById: ReadonlyMap<string, readonly string[]>,
 ): LessonDefinition[] {
   const lessons: LessonDefinition[] = [];
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
-    const slug = docSlug(path);
-    if (!isLessonSlug(slug)) continue;
+  // A deck beside its chapter cites what its chapter does not need to: its
+  // sources count for the lesson too.
+  const deckBodies = new Map(
+    loadDeckFiles()
+      .filter((deck): deck is LessonDeckFile => deck.scope === 'lesson' && deck.chapterPath !== undefined)
+      .map((deck) => [deck.lessonId, parseDocument(deck.path).body]),
+  );
+  for (const { path, lessonId } of loadLessonFiles()) {
     const { data, body } = parseDocument(path);
     const teaches = (data.teaches as string[] | undefined) ?? [];
+    const deckBody = deckBodies.get(lessonId);
     lessons.push({
-      id: lessonIdFromSlug(slug),
+      id: lessonId,
       requires: deriveRequires(teaches, prerequisitesById),
       teaches,
       assessments: lessonCheckIds(path),
-      sources: deriveSources(body),
+      sources:
+        deckBody === undefined
+          ? deriveSources(body)
+          : [...new Set([...deriveSources(body), ...deriveSources(deckBody)])].sort(),
       assumptions: (data.assumptions as string[] | undefined) ?? [],
       body,
     });
@@ -538,7 +707,7 @@ function localDefinition(
 function sharedNotationEntries(): SharedNotationDefinitionInput[] {
   const directory = join(CONTENT_ROOT, 'notation');
   return filesBelow(directory, ['.md']).map((path) => {
-    const { file, data, body } = parseDocument(path);
+    const { file, data, body, bodyLine } = parseDocument(path);
     const key = string(data.key, `${file} key`);
     const filenameKey = basename(path, '.md');
     if (key !== filenameKey) {
@@ -566,6 +735,7 @@ function sharedNotationEntries(): SharedNotationDefinitionInput[] {
           ? false
           : boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
+      bodyLine,
       references: extractNotationReferences(body, file, undefined),
       glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
@@ -652,21 +822,31 @@ export function notationSuspensions(
   });
 }
 
+/** A lesson file's `notation.local` entries and `notation.suspend` list, parsed. */
+function lessonNotationOf(
+  file: string,
+  data: Record<string, unknown>,
+): { localDefinitions: LocalNotationDefinitionInput[]; suspended: NotationSuspension[] } {
+  const notation = record(data.notation ?? {}, `${file} notation`);
+  const local = Array.isArray(notation.local) ? notation.local : [];
+  const localDefinitions = local.map((entry, index) =>
+    localDefinition(entry, file, index),
+  );
+  return {
+    localDefinitions,
+    suspended: notationSuspensions(notation.suspend, localDefinitions, file),
+  };
+}
+
 function notationLessonEntries(): NotationLessonInput[] {
   const lessons: NotationLessonInput[] = [];
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
-    const slug = docSlug(path);
-    if (!isLessonSlug(slug)) continue;
+  for (const { path, lessonId } of loadLessonFiles()) {
     const { file, data, body, bodyLine } = parseDocument(path);
-    const notation = record(data.notation ?? {}, `${file} notation`);
-    const local = Array.isArray(notation.local) ? notation.local : [];
-    const localDefinitions = local.map((entry, index) =>
-      localDefinition(entry, file, index),
-    );
+    const { localDefinitions, suspended } = lessonNotationOf(file, data);
     lessons.push({
-      lessonId: lessonIdFromSlug(slug),
+      lessonId,
       localDefinitions,
-      suspended: notationSuspensions(notation.suspend, localDefinitions, file),
+      suspended,
       references: extractNotationReferences(body, file, undefined),
       body,
       bodyLine,
@@ -676,6 +856,87 @@ function notationLessonEntries(): NotationLessonInput[] {
   return lessons;
 }
 
+/**
+ * A deck beside its chapter, as a page of the notation registry: its own id
+ * (`<lessonId>.slides`), no entries of its own, and its chapter's scope — the
+ * chapter's `notation.local` entries are the lesson's, so a deck names them
+ * as the chapter does, and it suspends what the chapter suspends. A part's
+ * deck (`<part>.slides`) has its part's scope: every chapter of the part, in
+ * the order the tracks read them, a key one chapter defines locally binding
+ * to the first that does; it suspends what any of them suspends. A deck that
+ * is a lesson's only edition is not here: it is that lesson's page
+ * (`loadNotationRegistryInput`).
+ */
+export interface DeckNotationPage {
+  readonly deck: DeckFile;
+  readonly data: Record<string, unknown>;
+  readonly notation: NotationLessonInput;
+}
+
+export function loadDeckNotationPages(
+  decks: readonly DeckFile[] = loadDeckFiles(),
+  {
+    order = (lessonIds) => lessonIds,
+  }: {
+    /** The lessons of a part in reading order (the tracks'); by slug without it. */
+    readonly order?: (lessonIds: readonly string[]) => readonly string[];
+  } = {},
+): DeckNotationPage[] {
+  const pages: DeckNotationPage[] = [];
+  const chapterFiles = loadLessonFiles().filter((lesson) => lesson.edition === 'chapter');
+  for (const deck of decks) {
+    let chapters: { readonly lessonId: string; readonly path: string }[];
+    if (deck.scope === 'part') {
+      const inPart = chapterFiles.filter((lesson) => lesson.lessonSlug.startsWith(`${deck.partDir}/`));
+      const pathById = new Map(inPart.map((lesson) => [lesson.lessonId, lesson.path]));
+      chapters = order(inPart.map((lesson) => lesson.lessonId)).flatMap((lessonId) => {
+        const path = pathById.get(lessonId);
+        return path === undefined ? [] : [{ lessonId, path }];
+      });
+    } else if (deck.chapterPath !== undefined) {
+      chapters = [{ lessonId: deck.lessonId, path: deck.chapterPath }];
+    } else {
+      continue;
+    }
+    const inheritedLocalDefinitions: LocalNotationDefinitionInput[] = [];
+    const suspended: NotationSuspension[] = [];
+    const inheritedKeys = new Set<string>();
+    for (const { path } of chapters) {
+      const chapter = parseDocument(path);
+      const notation = lessonNotationOf(chapter.file, chapter.data);
+      for (const definition of notation.localDefinitions) {
+        if (!inheritedLocalDefinitions.some((known) => known.key === definition.key)) {
+          inheritedLocalDefinitions.push(definition);
+        }
+      }
+      for (const suspension of notation.suspended) {
+        if (!suspended.some((known) => known.operator === suspension.operator)) suspended.push(suspension);
+      }
+      for (const reference of extractNotationReferences(chapter.body, chapter.file, undefined)) {
+        inheritedKeys.add(reference.key);
+      }
+    }
+    const { file, data, body, bodyLine } = deck;
+    pages.push({
+      deck,
+      data,
+      notation: {
+        lessonId: deck.pageId,
+        localDefinitions: [],
+        suspended,
+        scopeLessonIds: chapters.map((chapter) => chapter.lessonId),
+        inheritedLocalDefinitions,
+        inheritedKeys: [...inheritedKeys].sort(),
+        references: extractNotationReferences(body, file, undefined),
+        body,
+        bodyLine,
+        source: { file },
+      },
+    });
+  }
+  return pages;
+}
+
 /**
  * A docs page that is **not a chapter** (rule S10): the landing page, a part's
  * overview page, and any other page outside a part directory — every slug
@@ -701,9 +962,10 @@ export interface NonChapterPage {
 
 export function loadNonChapterPages(): NonChapterPage[] {
   const pages: NonChapterPage[] = [];
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
+  for (const path of docsFiles()) {
     const slug = docSlug(path);
-    if (isLessonSlug(slug)) continue;
+    // A deck is an edition of a lesson (`loadDeckFiles`), not a page of its own kind.
+    if (isLessonSlug(slug) || isDeckSlug(slug)) continue;
     const { file, data, body, bodyLine } = parseDocument(path);
     const id = lessonIdFromSlug(slug);
     pages.push({
@@ -799,7 +1061,7 @@ export function loadSourceRecords(): Record<string, unknown>[] {
  */
 export function loadLessonChecks(lessonId: string): string[] {
   const slug = lessonId.replace(/\./g, '/');
-  for (const extension of ['.mdx', '.md']) {
+  for (const extension of ['.mdx', '.md', '.deck.mdx', '.deck.md']) {
     const lessonPath = join(CONTENT_ROOT, 'docs', `${slug}${extension}`);
     if (existsSync(lessonPath)) return lessonCheckIds(lessonPath);
   }
@@ -861,11 +1123,8 @@ export function loadNotationSpecs(): NotationSpec[] {
     });
   }
 
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
-    const slug = docSlug(path);
-    if (!isLessonSlug(slug)) continue;
+  for (const { path, lessonId } of loadLessonFiles()) {
     const { file, data } = parseDocument(path);
-    const lessonId = lessonIdFromSlug(slug);
     const local = (data as { notation?: { local?: unknown } }).notation?.local;
     if (!Array.isArray(local)) continue;
     for (const raw of local) {

package/src/compiler/content-release.ts

@@ -0,0 +1,91 @@
+/**
+ * `content release [major|minor|patch]` — cut a course content release (rule
+ * C3): `## [Unreleased]` in `content/CHANGELOG.md` becomes a dated
+ * `## [x.y.z]` heading and `content/course.config.ts` `about.version` becomes
+ * `x.y.z`, in one plan, shown as a diff and written only on `--write`, like
+ * the other edit verbs. The bump defaults to what the section's own headings
+ * imply (rule C2): `### Breaking` or `### Removed` a MAJOR, `### Added` a
+ * MINOR, anything else a PATCH.
+ *
+ * Each page's own version (rule C5) follows on the next `validate:content`,
+ * which records the release in `content/versions.json`; the release commit
+ * carries that file too.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ContentCliError, type EditPlan } from './cli';
+
+export type ReleaseBump = 'major' | 'minor' | 'patch';
+
+const CHANGELOG = 'content/CHANGELOG.md';
+const CONFIG = 'content/course.config.ts';
+
+export interface ReleaseEdit {
+  readonly from: string;
+  readonly to: string;
+  readonly bump: ReleaseBump;
+  /** True when the bump was read from the section's headings, not asked for. */
+  readonly inferred: boolean;
+  readonly changelog: string;
+  readonly config: string;
+}
+
+/** The release of these two files' text on `date` (`YYYY-MM-DD`); `null` when `[Unreleased]` has no entry. */
+export function releaseEdit(changelog: string, config: string, date: string, requested?: ReleaseBump): ReleaseEdit | null {
+  const unreleased = /^## \[Unreleased\]\r?$/m.exec(changelog);
+  if (!unreleased) throw new ContentCliError('no-changelog', `${CHANGELOG} has no "## [Unreleased]" heading.`);
+  const bodyStart = unreleased.index + unreleased[0].length;
+  const released = /^## \[\d+\.\d+\.\d+\](?: - .*?)?\r?$/m.exec(changelog.slice(bodyStart));
+  if (!released) throw new ContentCliError('no-changelog', `${CHANGELOG} has no released "## [x.y.z]" heading below "## [Unreleased]".`);
+  const bodyEnd = bodyStart + released.index;
+  const body = changelog.slice(bodyStart, bodyEnd);
+  if (!/^-\s+/m.test(body)) return null;
+
+  const version = /(about:\s*\{[\s\S]*?\bversion:\s*['"])(\d+)\.(\d+)\.(\d+)(['"])/.exec(config);
+  if (!version) throw new ContentCliError('unknown-version', `No about.version "x.y.z" in ${CONFIG}.`);
+  const [major, minor, patch] = version.slice(2, 5).map(Number) as [number, number, number];
+  const implied: ReleaseBump = /^### (Breaking|Removed)\s*$/m.test(body) ? 'major' : /^### Added\s*$/m.test(body) ? 'minor' : 'patch';
+  const bump = requested ?? implied;
+  const to = bump === 'major' ? `${major + 1}.0.0` : bump === 'minor' ? `${major}.${minor + 1}.0` : `${major}.${minor}.${patch + 1}`;
+  return {
+    from: `${major}.${minor}.${patch}`,
+    to,
+    bump,
+    inferred: requested === undefined,
+    changelog: `${changelog.slice(0, bodyStart)}\n\n## [${to}] - ${date}${body}${changelog.slice(bodyEnd)}`,
+    config: config.replace(version[0], `${version[1]}${to}${version[5]}`),
+  };
+}
+
+/** The release as an edit plan over the course in the working directory. */
+/** Today where the release is cut, `YYYY-MM-DD`: a release at 9 pm is dated that day, not the next one in UTC. */
+function localDate(now = new Date()): string {
+  return [now.getFullYear(), now.getMonth() + 1, now.getDate()].map((n, i) => String(n).padStart(i === 0 ? 4 : 2, '0')).join('-');
+}
+
+export function planContentRelease(requested?: string, date = localDate()): EditPlan {
+  if (requested !== undefined && requested !== 'major' && requested !== 'minor' && requested !== 'patch') {
+    throw new ContentCliError('usage', `content release takes major, minor or patch; got ${requested}.`);
+  }
+  for (const file of [CHANGELOG, CONFIG]) {
+    if (!existsSync(join(process.cwd(), file))) throw new ContentCliError('no-changelog', `No ${file} in this course.`);
+  }
+  const changelog = readFileSync(join(process.cwd(), CHANGELOG), 'utf8');
+  const config = readFileSync(join(process.cwd(), CONFIG), 'utf8');
+  const edit = releaseEdit(changelog, config, date, requested);
+  if (edit === null) {
+    return { summary: ['## [Unreleased] has no entries: nothing to release'], edits: [], next: [] };
+  }
+  return {
+    summary: [
+      `about.version ${edit.from} → ${edit.to} (${edit.bump}${edit.inferred ? ", from the section's headings" : ''})`,
+      `${CHANGELOG}: ## [Unreleased] → ## [${edit.to}] - ${date}, a fresh ## [Unreleased] above it`,
+    ],
+    edits: [
+      { file: CHANGELOG, before: changelog, after: edit.changelog },
+      { file: CONFIG, before: config, after: edit.config },
+    ],
+    next: ['pnpm validate:content (records the release in content/versions.json)', 'commit the changelog, the config and content/versions.json together'],
+  };
+}