explico 0.14.0 → 0.15.0

package/dist/compiler/cli-verify.js

@@ -0,0 +1,151 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+const VERIFY_DIR = join("node_modules", ".cache", "explico", "verify");
+const RECORD = "last-pass.json";
+const TAIL_LINES = 20;
+function verifyTreeHash(cwd) {
+  try {
+    const git = (args) => execFileSync("git", args, { cwd, maxBuffer: 1 << 30, stdio: ["ignore", "pipe", "ignore"] });
+    const hash = createHash("sha1");
+    hash.update(git(["rev-parse", "HEAD"]));
+    hash.update(git(["diff", "HEAD", "--binary"]));
+    const untracked = git(["ls-files", "--others", "--exclude-standard", "-z"]).toString("utf8").split("\0").filter(Boolean).sort();
+    for (const file of untracked) {
+      hash.update(`\0${file}\0`);
+      if (existsSync(join(cwd, file))) hash.update(readFileSync(join(cwd, file)));
+    }
+    return hash.digest("hex");
+  } catch {
+    return null;
+  }
+}
+function scriptCommand(script, args) {
+  const execpath = process.env.npm_execpath ?? "";
+  const manager = /pnpm/.test(execpath) ? "pnpm" : /yarn/.test(execpath) ? "yarn" : /npm/.test(execpath) ? "npm" : "pnpm";
+  const tail = manager === "npm" && args.length > 0 ? ["run", script, "--", ...args] : ["run", script, ...args];
+  const display = `${manager} ${tail.join(" ")}`;
+  if (execpath === "" || !execpath.includes(manager)) return { file: manager, argv: tail, display };
+  return /\.[cm]?js$/.test(execpath) ? { file: process.execPath, argv: [execpath, ...tail], display } : { file: execpath, argv: tail, display };
+}
+function binCommand(cwd, bin, args) {
+  return { file: join(cwd, "node_modules", ".bin", process.platform === "win32" ? `${bin}.cmd` : bin), argv: [...args], display: [bin, ...args].join(" ") };
+}
+function slug(name) {
+  return name.replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function tailOf(file) {
+  const lines = readFileSync(file, "utf8").split("\n").map((line) => line.trimEnd()).filter((line) => line !== "");
+  return lines.slice(-TAIL_LINES);
+}
+function runVerify(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const e2e = options.e2e ?? false;
+  const dir = join(cwd, VERIFY_DIR);
+  const recordFile = join(dir, RECORD);
+  if (!options.force && existsSync(recordFile)) {
+    try {
+      const record = JSON.parse(readFileSync(recordFile, "utf8"));
+      const tree2 = verifyTreeHash(cwd);
+      if (tree2 !== null && record.tree === tree2 && (record.e2e || !e2e)) {
+        return { ok: true, cached: true, since: record.when, tree: tree2, e2e: record.e2e, steps: record.steps };
+      }
+    } catch {
+    }
+  }
+  mkdirSync(dir, { recursive: true });
+  const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+  const scripts = pkg.scripts ?? {};
+  const has = (path) => existsSync(join(cwd, path));
+  const playwrightConfig = ["playwright.config.ts", "playwright.config.mts", "playwright.config.js", "playwright.config.mjs"].some(has);
+  const plans = [
+    scripts["validate:content"] === void 0 ? { name: "validate:content", reason: "package.json has no validate:content script", fail: true } : { name: "validate:content", command: scriptCommand("validate:content", []) },
+    scripts.content === void 0 ? { name: "check --changed", reason: "package.json has no content script", fail: true } : { name: "check --changed", command: scriptCommand("content", ["check", "--changed"]) },
+    // Without @astrojs/check, `astro check` stops to ask whether to install it.
+    has(join("node_modules", "@astrojs", "check", "package.json")) ? { name: "astro check", command: binCommand(cwd, "astro", ["check"]) } : { name: "astro check", reason: "@astrojs/check is not installed (pnpm add -D @astrojs/check typescript)" },
+    scripts.test === void 0 ? { name: "tests", reason: "package.json has no test script" } : { name: "tests", command: scriptCommand("test", []) },
+    { name: "astro build", command: binCommand(cwd, "astro", ["build"]) }
+  ];
+  if (e2e) {
+    plans.push(
+      scripts["test:e2e"] !== void 0 ? { name: "e2e", command: scriptCommand("test:e2e", []) } : playwrightConfig ? { name: "e2e", command: binCommand(cwd, "playwright", ["test"]) } : { name: "e2e", reason: "no test:e2e script and no playwright.config" }
+    );
+  }
+  const steps = [];
+  for (const plan of plans) {
+    options.onStep?.({ phase: "start", name: plan.name });
+    let step;
+    if (plan.command === void 0) {
+      step = { name: plan.name, status: plan.fail ? "fail" : "skipped", reason: plan.reason };
+    } else {
+      const log = join(dir, `${slug(plan.name)}.log`);
+      const fd = openSync(log, "w");
+      const started = Date.now();
+      let result;
+      try {
+        result = spawnSync(plan.command.file, plan.command.argv, {
+          cwd,
+          stdio: ["ignore", fd, fd],
+          shell: process.platform === "win32",
+          env: process.env
+        });
+      } finally {
+        closeSync(fd);
+      }
+      const seconds = Math.round((Date.now() - started) / 100) / 10;
+      const passed = result.error === void 0 && result.status === 0;
+      step = {
+        name: plan.name,
+        status: passed ? "pass" : "fail",
+        command: plan.command.display,
+        seconds,
+        log: relative(cwd, log),
+        ...result.error === void 0 ? {} : { reason: result.error.message },
+        ...passed ? {} : { tail: tailOf(log) }
+      };
+    }
+    steps.push(step);
+    options.onStep?.({ phase: "end", step });
+  }
+  const ok = steps.every((step) => step.status !== "fail");
+  const tree = verifyTreeHash(cwd);
+  if (ok && tree !== null) {
+    const record = { tree, e2e, when: (/* @__PURE__ */ new Date()).toISOString(), steps };
+    writeFileSync(recordFile, `${JSON.stringify(record, null, 2)}
+`);
+  }
+  return { ok, cached: false, tree, e2e, steps };
+}
+function formatVerifyReport(report) {
+  if (report.cached) {
+    return `verify: PASS, unchanged since ${report.since} (${report.e2e ? "with" : "without"} e2e); --force reruns
+`;
+  }
+  const out = [];
+  for (const step of report.steps) {
+    if (step.status !== "fail") continue;
+    out.push("", `${step.name} failed${step.reason === void 0 ? "" : `: ${step.reason}`}${step.log === void 0 ? "" : ` \u2014 last lines of ${step.log}:`}`);
+    for (const line of step.tail ?? []) out.push(`  ${line}`);
+  }
+  const failed = report.steps.filter((step) => step.status === "fail").map((step) => step.name);
+  out.push(
+    "",
+    failed.length === 0 ? `verify: PASS${report.tree === null ? " (not a git repository: nothing recorded)" : ""}` : `verify: FAIL \u2014 ${failed.join(", ")}; whole output under ${VERIFY_DIR}/`
+  );
+  return `${out.join("\n").replace(/^\n/, "")}
+`;
+}
+function formatVerifyStep(step) {
+  const verdict = step.status === "pass" ? "ok" : step.status === "fail" ? "FAIL" : "skipped";
+  const detail = step.seconds !== void 0 ? `${step.seconds.toFixed(1)}s` : step.reason ?? "";
+  return `  ${step.name.padEnd(18)} ${verdict.padEnd(7)} ${detail}
+`;
+}
+export {
+  VERIFY_DIR,
+  formatVerifyReport,
+  formatVerifyStep,
+  runVerify,
+  verifyTreeHash
+};

package/dist/compiler/cli.d.ts

@@ -1,9 +1,9 @@
 import { DiagnosticSeverity } from '../reference/types.js';
 import { EquationLink, ScopeEntry } from '../reference/gate-math.js';
-import { ManifestLesson, Manifest } from './manifest.js';
+import { ManifestLesson, ManifestLessonFloat, Manifest } from './manifest.js';
 import { RenderDiagnostic } from './render-diagnostics.js';
 import { RetiredRule } from '../rules/catalog.js';
-import { RuleInEffect, RulesFilter } from '../rules/in-effect.js';
+import { RulesFilter, RuleInEffect } from '../rules/in-effect.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
 import '../course-config-BLtIdkei.js';
@@ -64,7 +64,7 @@ import './lesson-derivation.js';
  *     under the `render:` source.
  */
 
-type ContentCliCode = 'unknown-command' | 'usage' | 'unknown-lesson' | 'unknown-kind' | 'invalid-id' | 'exists' | 'not-a-lesson' | 'no-git' | 'unknown-version' | 'migration-gap' | 'unknown-key';
+type ContentCliCode = 'unknown-command' | 'usage' | 'unknown-lesson' | 'unknown-kind' | 'invalid-id' | 'exists' | 'not-a-lesson' | 'no-git' | 'unknown-version' | 'migration-gap' | 'unknown-key' | 'no-changelog';
 /** A user-facing failure with a stable code and no stack in `--json` output. */
 declare class ContentCliError extends Error {
     readonly code: ContentCliCode;
@@ -312,22 +312,10 @@ interface ContextReport {
         units?: string;
         formula?: string;
     }[];
-    readonly equations: readonly {
-        key: string;
-        number: string;
-    }[];
-    readonly tables: readonly {
-        key: string;
-        number: string;
-    }[];
-    readonly figures: readonly {
-        key: string;
-        number: string;
-    }[];
-    readonly diagrams: readonly {
-        key: string;
-        number: string;
-    }[];
+    readonly equations: readonly ManifestLessonFloat[];
+    readonly tables: readonly ManifestLessonFloat[];
+    readonly figures: readonly ManifestLessonFloat[];
+    readonly diagrams: readonly ManifestLessonFloat[];
     /** Worked-example sets: `short` is the title `[[ex-key]]` names. */
     readonly examples: readonly {
         key: string;
@@ -357,13 +345,6 @@ interface ContextReport {
     readonly diagnostics: readonly CliDiagnostic[];
     readonly tokens: TokenCounts;
 }
-/**
- * The migration guide, cut to the sections an upgrade needs: from the
- * version a course pins to the version it has installed, oldest first. The
- * guide is one newest-first file of every release; an upgrade reads one or
- * two sections of it, and the heading grammar `## <from> → <to>` (a `0.4.x`
- * range on the left, `Unreleased` allowed on the right) says which.
- */
 interface MigrationSection {
     readonly from: string;
     readonly to: string;
@@ -401,14 +382,6 @@ declare function contentMigrate(options?: {
 }): MigrateReport;
 /** The sections, oldest first, under one line that says how much is coming. */
 declare function formatMigrateReport(report: MigrateReport): string;
-/**
- * What a lesson's math binds, span by span, before a build says so: each
- * glyph and the card it resolves to, how (`canonical`, `family`, `derived`,
- * `base`, `operator`, or an explicit `\explain` wrap), the wraps the bare
- * symbol would have resolved without, and every unresolved glyph with where
- * `content symbol` finds it defined. The same resolver and scope the
- * completeness gate uses, so what it prints is what the build will do.
- */
 interface SpanBinding {
     readonly token: string;
     readonly key: string;
@@ -503,11 +476,6 @@ declare function contentEquation(manifest: Manifest, latex: string, options?: {
     readonly lesson?: string;
 }): EquationReport;
 declare function formatEquationReport(report: EquationReport): string;
-/**
- * The refactors a model gets wrong most and reads most for, as deterministic
- * edits: every one is planned first (`FileEdit`s with the whole text before
- * and after), shown as a unified diff, and written only on `--write`.
- */
 interface FileEdit {
     /** Course-relative path. */
     readonly file: string;
@@ -537,10 +505,17 @@ declare function removeLocalItem(text: string, key: string): {
     text: string;
     removed: boolean;
 };
-/** A shared card's file from a page-local entry's fields, nothing invented. */
+/**
+ * A shared card's file from a page-local entry's fields, nothing invented: no
+ * body (the glossary shows the meaning; what a reader needs beyond it is the
+ * author's to write, and a placeholder would publish), and the label only
+ * when the entry has one. `domain` is the caller's pick, else the key's
+ * prefix, else `general`.
+ */
 declare function sharedCardFromLocal(local: Record<string, unknown>, options: {
     readonly key: string;
     readonly fromLesson: string;
+    readonly domain?: string;
 }): string;
 /**
  * `content move <lesson>:<key> [--to <key>]`: a page-local entry becomes a
@@ -559,6 +534,8 @@ declare function planRename(manifest: Manifest, oldKey: string, newKey: string):
  * becomes `inner`.
  */
 declare function planFix(manifest: Manifest, lessonId: string): EditPlan;
+/** `content fix` over several lessons (or every one, `--all`) as one plan: the lessons with nothing to fix are counted, not listed. */
+declare function planFixMany(manifest: Manifest, lessonIds: readonly string[]): EditPlan;
 /** The plan as a unified diff (git's), file by file, under its summary lines. */
 declare function renderEditPlan(plan: EditPlan): string;
 /** Write a plan's edits. Returns the files touched. */
@@ -614,15 +591,7 @@ declare function contentRule(manifest: Manifest, rawId: string): RuleReport;
 /** The text form of a rule report: the entry's facts, then the page section. */
 declare function formatRuleReport(report: RuleReport): string;
 declare function contentContext(manifest: Manifest, rawId: string): ContextReport;
-/**
- * Where a symbol is already defined, asked before an author declares it
- * again. Reads the registry the manifest holds: shared cards, page-local
- * entries (`notation.local`) and glosses (a card's `glosses:`), matched on
- * the latex as written, a shared card's `aliases`, or the key. A `contains`
- * list follows for a letter that sits inside a longer notation (`v` in
- * `v_0`), so a near miss is visible too. Read-only; every list is sorted,
- * so two runs print the same report.
- */
+/** Where a hit is defined: a shared card, a lesson's `notation.local`, or a card's gloss. */
 type SymbolTier = 'shared' | 'local' | 'gloss';
 interface SymbolHit {
     readonly tier: SymbolTier;
@@ -716,4 +685,4 @@ declare function scaffoldLesson(rawId: string): Scaffold;
 declare function scaffoldDeck(rawId: string): Scaffold;
 declare function scaffoldTerm(rawKey: string): Scaffold;
 
-export { type BindingsReport, type BindingsSpan, type CheckLessonResult, type CheckReport, type CheckTarget, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DiagnosticsSummary, type DomainFileSignatures, type EditPlan, type EquationReport, type ExplicitWrap, type FileEdit, type MigrateReport, type MigrationSection, type RenderResult, type RuleReport, type RulesReport, type Scaffold, type SpanBinding, type SpanBindings, type StatusReport, type SymbolHit, type SymbolReport, type SymbolTier, type TokenCounts, type UnresolvedGlyph, type WarningsReport, applyEditPlan, authoringDocsDir, changedLessonIds, contentBindings, contentCheck, contentContext, contentDiagnostics, contentEquation, contentMigrate, contentRule, contentRules, contentStatus, contentSymbol, contentWarnings, courseAgentDir, estimateTokens, filterDiagnostics, findCheckTarget, findLesson, formatBindingsReport, formatCliDiagnostic, formatDiagnosticsSummary, formatEquationReport, formatMigrateReport, formatRuleReport, formatSymbolReport, installedEngineVersion, lessonDiagnostics, lessonSource, normalizeLessonId, ownerTag, parseMigrationSections, parseRulesFilter, pinnedEngineVersion, planFix, planInitAgent, planMove, planRename, removeLocalItem, renderEditPlan, renderLesson, rewriteKeyReferences, ruleSection, scaffoldDeck, scaffoldLesson, scaffoldTerm, selectMigrationPath, sharedCardFromLocal, spanBindings, summarizeDiagnostics };
+export { type BindingsReport, type BindingsSpan, type CheckLessonResult, type CheckReport, type CheckTarget, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DiagnosticsSummary, type DomainFileSignatures, type EditPlan, type EquationReport, type ExplicitWrap, type FileEdit, type MigrateReport, type MigrationSection, type RenderResult, type RuleReport, type RulesReport, type Scaffold, type SpanBinding, type SpanBindings, type StatusReport, type SymbolHit, type SymbolReport, type SymbolTier, type TokenCounts, type UnresolvedGlyph, type WarningsReport, applyEditPlan, authoringDocsDir, changedLessonIds, contentBindings, contentCheck, contentContext, contentDiagnostics, contentEquation, contentMigrate, contentRule, contentRules, contentStatus, contentSymbol, contentWarnings, courseAgentDir, estimateTokens, filterDiagnostics, findCheckTarget, findLesson, formatBindingsReport, formatCliDiagnostic, formatDiagnosticsSummary, formatEquationReport, formatMigrateReport, formatRuleReport, formatSymbolReport, installedEngineVersion, lessonDiagnostics, lessonSource, normalizeLessonId, ownerTag, parseMigrationSections, parseRulesFilter, pinnedEngineVersion, planFix, planFixMany, planInitAgent, planMove, planRename, removeLocalItem, renderEditPlan, renderLesson, rewriteKeyReferences, ruleSection, scaffoldDeck, scaffoldLesson, scaffoldTerm, selectMigrationPath, sharedCardFromLocal, spanBindings, summarizeDiagnostics };

package/dist/compiler/cli.js

@@ -1121,7 +1121,7 @@ function yamlBlock(value, indent) {
 }
 function sharedCardFromLocal(local, options) {
   const key = options.key;
-  const domain = key.includes(".") ? key.slice(0, key.indexOf(".")) : "general";
+  const domain = options.domain ?? (key.includes(".") ? key.slice(0, key.indexOf(".")) : "general");
   const front = {
     key,
     latex: local.latex,
@@ -1143,10 +1143,22 @@ function sharedCardFromLocal(local, options) {
   return `---
 ${yamlBlock(front, 0).join("\n")}
 ---
-
-Promoted from \`${options.fromLesson}\`'s \`notation.local\`; the meaning above is what that page said. Extend this body with what a glossary reader needs.
 `;
 }
+function promotedDomain(manifest, lesson, key) {
+  const shared = manifest.notation.definitions.filter((definition) => definition.kind === "shared");
+  const prefix = key.includes(".") ? key.slice(0, key.indexOf(".")) : void 0;
+  if (prefix !== void 0 && shared.some((definition) => definition.domain === prefix)) return prefix;
+  const mostCommon = (definitions) => {
+    const counts = /* @__PURE__ */ new Map();
+    for (const definition of definitions) {
+      if (definition.domain) counts.set(definition.domain, (counts.get(definition.domain) ?? 0) + 1);
+    }
+    return [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+  };
+  const bound = new Set(lesson.notation.definitionIds);
+  return mostCommon(shared.filter((definition) => bound.has(definition.id))) ?? mostCommon(shared) ?? prefix ?? "general";
+}
 function courseTextFiles() {
   const out = [];
   const walk = (dir) => {
@@ -1195,8 +1207,20 @@ function planMove(manifest, lessonId, key, options = {}) {
   }
   const summary = [];
   const edits = [];
-  edits.push({ file: target, before: null, after: sharedCardFromLocal(source, { key: newKey, fromLesson: lesson.id }) });
-  summary.push(`${target}: new shared card from ${lesson.id}'s entry${newKey === key ? "" : ` (key ${key} \u2192 ${newKey})`}`);
+  const domain = promotedDomain(manifest, lesson, newKey);
+  const glyph = typeof source.latex === "string" ? source.latex.trim() : "";
+  const owner = manifest.notation.definitions.find(
+    (definition) => definition.kind === "shared" && definition.key !== newKey && definition.notation.trim() === glyph
+  );
+  if (owner !== void 0) {
+    summary.push(
+      `CAUTION: ${glyph} is already shared card ${owner.key}'s \u2014 a second shared card on one glyph is a glyph-unique-in-corpus finding; a reused letter stays local (rule N4). Write this only if the two cards are meant to share the glyph, and acknowledge the pair.`
+    );
+  }
+  edits.push({ file: target, before: null, after: sharedCardFromLocal(source, { key: newKey, fromLesson: lesson.id, domain }) });
+  summary.push(
+    `${target}: new shared card from ${lesson.id}'s entry${newKey === key ? "" : ` (key ${key} \u2192 ${newKey})`}, domain ${domain}; no body yet \u2014 add what a glossary reader needs beyond the meaning` + (source.label === void 0 ? "; no label in the entry \u2014 the card shows one made from the key until you add `label:`" : "")
+  );
   const touched = /* @__PURE__ */ new Set();
   for (const other of manifest.lessons) {
     const copy = local(other);
@@ -1285,6 +1309,20 @@ function planFix(manifest, lessonId) {
     next: [`pnpm content check ${lesson.id}`]
   };
 }
+function planFixMany(manifest, lessonIds) {
+  if (lessonIds.length === 1) return planFix(manifest, lessonIds[0]);
+  const plans = lessonIds.map((id) => planFix(manifest, id));
+  const fixing = plans.filter((plan) => plan.edits.length > 0);
+  const clean = plans.length - fixing.length;
+  return {
+    summary: [
+      ...fixing.flatMap((plan) => plan.summary),
+      ...clean > 0 ? [`${clean} lesson(s) with nothing to fix`] : []
+    ],
+    edits: fixing.flatMap((plan) => plan.edits),
+    next: ["pnpm content check --changed"]
+  };
+}
 function renderEditPlan(plan) {
   const lines = plan.summary.map((line) => `  ${line}`);
   const scratch = join(REPOSITORY_ROOT, ".agent", "content-edits");
@@ -1354,7 +1392,7 @@ function planInitAgent() {
     const before = existsSync(target) ? readFileSync(target, "utf8") : null;
     if (before === after) return;
     edits.push({ file: to, before, after });
-    summary.push(`${to}: ${before === null ? "installed" : "refreshed from the engine"}`);
+    summary.push(`${to}: ${before === null ? "new" : "differs from the engine's copy"}`);
   };
   for (const file of filesUnder(join(source, "skills"))) install(`skills/${file}`, `.claude/skills/${file}`);
   for (const file of filesUnder(join(source, "agents"))) install(`agents/${file}`, `.claude/agents/${file}`);
@@ -2079,6 +2117,7 @@ export {
   parseRulesFilter,
   pinnedEngineVersion,
   planFix,
+  planFixMany,
   planInitAgent,
   planMove,
   planRename,

package/dist/compiler/content-release.d.ts

@@ -0,0 +1,49 @@
+import { EditPlan } from './cli.js';
+import '../reference/types.js';
+import '../reference/gate-math.js';
+import './manifest.js';
+import '../curriculum/validation.js';
+import '../reference/consistency.js';
+import '../course-config-BLtIdkei.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
+import './collections.js';
+import '../reference/gate-retired-keys.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/diagrams-validate.js';
+import '../reference/examples-validate.js';
+import '../reference/folds-validate.js';
+import '../reference/knowledge-checks-validate.js';
+import '../reference/raw-floats-validate.js';
+import '../reference/lab-katex-validate.js';
+import '../reference/mixed-content.js';
+import '../reference/gloss.js';
+import '../rules/waivers.js';
+import './knowledge-version.js';
+import './page-versions.js';
+import './decks.js';
+import '../reference/decks-validate.js';
+import '../reference/deck-source.js';
+import './lesson-derivation.js';
+import './render-diagnostics.js';
+import '../rules/in-effect.js';
+
+type ReleaseBump = 'major' | 'minor' | 'patch';
+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. */
+declare function releaseEdit(changelog: string, config: string, date: string, requested?: ReleaseBump): ReleaseEdit | null;
+declare function planContentRelease(requested?: string, date?: string): EditPlan;
+
+export { type ReleaseBump, type ReleaseEdit, planContentRelease, releaseEdit };

package/dist/compiler/content-release.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ContentCliError } from "./cli.js";
+const CHANGELOG = "content/CHANGELOG.md";
+const CONFIG = "content/course.config.ts";
+function releaseEdit(changelog, config, date, requested) {
+  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);
+  const implied = /^### (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 === void 0,
+    changelog: `${changelog.slice(0, bodyStart)}
+
+## [${to}] - ${date}${body}${changelog.slice(bodyEnd)}`,
+    config: config.replace(version[0], `${version[1]}${to}${version[5]}`)
+  };
+}
+function localDate(now = /* @__PURE__ */ new Date()) {
+  return [now.getFullYear(), now.getMonth() + 1, now.getDate()].map((n, i) => String(n).padStart(i === 0 ? 4 : 2, "0")).join("-");
+}
+function planContentRelease(requested, date = localDate()) {
+  if (requested !== void 0 && 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} \u2192 ${edit.to} (${edit.bump}${edit.inferred ? ", from the section's headings" : ""})`,
+      `${CHANGELOG}: ## [Unreleased] \u2192 ## [${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"]
+  };
+}
+export {
+  planContentRelease,
+  releaseEdit
+};

package/dist/compiler/content-schemas.d.ts

@@ -178,9 +178,9 @@ declare const trackSchema: z.ZodObject<{
 declare const sourceSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
+        paper: "paper";
         primary: "primary";
         "official-guidance": "official-guidance";
-        paper: "paper";
         book: "book";
         secondary: "secondary";
     }>;
@@ -359,9 +359,9 @@ declare const CONTENT_SCHEMAS: {
     readonly sources: z.ZodObject<{
         id: z.ZodString;
         type: z.ZodEnum<{
+            paper: "paper";
             primary: "primary";
             "official-guidance": "official-guidance";
-            paper: "paper";
             book: "book";
             secondary: "secondary";
         }>;

package/dist/compiler/manifest.js

@@ -112,6 +112,7 @@ import {
   resolveKnowledgeVersion
 } from "./knowledge-version.js";
 import {
+  deckStaleDiagnostics,
   nextPageVersions,
   PAGE_VERSIONS_FILE,
   pageSourceDigest,
@@ -1170,6 +1171,32 @@ async function compileManifest(courseConfig) {
     disclaimer: courseConfig.about.disclaimer,
     ...courseConfig.about.changelogHref === void 0 ? {} : { changelogHref: courseConfig.about.changelogHref }
   };
+  const lessonsWithSince = lessons.map((lesson) => ({ ...lesson, since: sinceOfPage(lesson.slug) }));
+  const decksWithSince = deckModel.decks.map((deck) => {
+    const page = pageInputById.get(deck.pageId);
+    return {
+      ...deck,
+      since: sinceOfPage(deck.slug),
+      notation: lessonNotationBundle(
+        bundlesByLesson.get(deck.pageId),
+        definitionsById,
+        page === void 0 ? [] : lessonNotationResolution(page, definitionsById, availableDefinitionIds),
+        cardsByKey,
+        // A deck shows its lessons' symbols: the derived cards (rule N23)
+        // its chapters' bodies and checks use ship with it, as its bundle
+        // holds the chapters' entries.
+        [
+          ...indexGate.derivedByLesson.get(deck.pageId) ?? [],
+          ...(page?.scopeLessonIds ?? []).flatMap((lessonId) => [
+            ...indexGate.derivedByLesson.get(lessonId) ?? [],
+            ...assessmentDerived.get(lessonId)?.values() ?? []
+          ])
+        ].filter((use, index, all) => all.findIndex((other) => other.key === use.key) === index)
+      )
+    };
+  });
+  const chapterSince = new Map(lessonsWithSince.map((lesson) => [lesson.slug, lesson.since]));
+  mathIssues.push(...deckStaleDiagnostics(decksWithSince, chapterSince));
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
@@ -1182,29 +1209,7 @@ async function compileManifest(courseConfig) {
     readingMemory: normalizeReadingMemory(courseConfig),
     appearance: normalizeAppearance(courseConfig),
     deck: deckSettings,
-    decks: deckModel.decks.map((deck) => {
-      const page = pageInputById.get(deck.pageId);
-      return {
-        ...deck,
-        since: sinceOfPage(deck.slug),
-        notation: lessonNotationBundle(
-          bundlesByLesson.get(deck.pageId),
-          definitionsById,
-          page === void 0 ? [] : lessonNotationResolution(page, definitionsById, availableDefinitionIds),
-          cardsByKey,
-          // A deck shows its lessons' symbols: the derived cards (rule N23)
-          // its chapters' bodies and checks use ship with it, as its bundle
-          // holds the chapters' entries.
-          [
-            ...indexGate.derivedByLesson.get(deck.pageId) ?? [],
-            ...(page?.scopeLessonIds ?? []).flatMap((lessonId) => [
-              ...indexGate.derivedByLesson.get(lessonId) ?? [],
-              ...assessmentDerived.get(lessonId)?.values() ?? []
-            ])
-          ].filter((use, index, all) => all.findIndex((other) => other.key === use.key) === index)
-        )
-      };
-    }),
+    decks: decksWithSince,
     about,
     notation: {
       definitions: registry.definitions,
@@ -1221,7 +1226,7 @@ async function compileManifest(courseConfig) {
     parts: manifestParts.map(
       ({ overview, ...part }) => overview ? { ...part, overview: { ...overview, since: sinceOfPage(`${part.dir}/index`) } } : part
     ),
-    lessons: lessons.map((lesson) => ({ ...lesson, since: sinceOfPage(lesson.slug) })),
+    lessons: lessonsWithSince,
     pageVersions,
     pages,
     prereqEdges,

package/dist/compiler/page-versions.d.ts

@@ -156,5 +156,29 @@ declare function syncPageVersions(manifest: {
     readonly frozen?: boolean;
     readonly root?: string;
 }): PageVersionsSync;
+/**
+ * Rule D11, shaped like a `MathGateDiagnostic` (`src/reference/gate-math.ts`)
+ * so it can join `diagnostics.math` beside D1–D10's frame codes, without
+ * this module importing from `src/reference/`.
+ */
+interface DeckStaleDiagnostic {
+    readonly context: 'structure';
+    readonly severity: 'info';
+    readonly code: 'deck-stale';
+    readonly file: string;
+    readonly message: string;
+}
+/**
+ * Rule D11: nothing else would notice a lesson's chapter and deck drifting
+ * apart, since two files keep each edition readable at the cost of that one
+ * check. Flags a deck whose chapter's `since` (rule C5) is newer than the
+ * deck's own. A part's deck has no one chapter to compare against, so a
+ * deck without a `chapter` (its `BuiltDeck.chapter`) is skipped.
+ */
+declare function deckStaleDiagnostics(decks: readonly {
+    readonly file: string;
+    readonly chapter?: string;
+    readonly since: string | null;
+}[], chapterSince: ReadonlyMap<string, string | null>): DeckStaleDiagnostic[];
 
-export { type ManifestPageVersions, type NextPageVersionsInput, PAGE_VERSIONS_FILE, PAGE_VERSIONS_FORMAT, PAGE_VERSIONS_GENERATED_BY, type PageVersionEntry, type PageVersionsRecord, type PageVersionsStaleDiagnostic, type PageVersionsSync, compareKnowledgeVersions, newestSince, nextPageVersions, pageSourceDigest, pageVersionsFrozen, readPageVersions, serializePageVersions, sinceOf, syncPageVersions, versionPhrase };
+export { type DeckStaleDiagnostic, type ManifestPageVersions, type NextPageVersionsInput, PAGE_VERSIONS_FILE, PAGE_VERSIONS_FORMAT, PAGE_VERSIONS_GENERATED_BY, type PageVersionEntry, type PageVersionsRecord, type PageVersionsStaleDiagnostic, type PageVersionsSync, compareKnowledgeVersions, deckStaleDiagnostics, newestSince, nextPageVersions, pageSourceDigest, pageVersionsFrozen, readPageVersions, serializePageVersions, sinceOf, syncPageVersions, versionPhrase };