explico 0.12.0 → 0.13.1

package/src/compiler/content-schemas.ts

@@ -0,0 +1,391 @@
+/**
+ * The content collections' schemas, one definition for both readers of
+ * `content/`: Astro's collections (`src/content-config.ts`, which wraps each
+ * in `defineCollection`) and the manifest walk, which checks every record
+ * against the same schema (`content-schema.ts`, `validateContentSchemas`) so
+ * `pnpm validate:content` rejects what `astro build` would.
+ *
+ * Plain zod only — no `astro:content` — so the manifest can import it outside
+ * Vite.
+ */
+import { z } from 'astro/zod';
+import { isSubstantiveMeaning } from '../reference/prose';
+import { glossKeySegment } from '../reference/gloss';
+import { BASE_PLACEHOLDER } from '../reference/derived-notation.mjs';
+
+export const contentId = z.string().regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/);
+const id = contentId;
+
+/**
+ * Notation `meaning` / `summary`: plain prose (no `$`, `\`, backticks), and —
+ * the C1b safeguard — substantive, not a placeholder. A short or blocklisted
+ * phrase fails the build so a local symbol cannot get a glossary-style panel
+ * for a throwaway definition.
+ */
+export const notationProse = z
+  .string()
+  .min(1)
+  .refine((value) => !/[\\$`]/.test(value), {
+    message:
+      'Notation meaning/summary must be plain prose: no `$`, `\\` or backtick. Put a symbol or formula in its own field (`latex`, `formula`), and write an amount of money in words or with its currency code ("USD 5").',
+  })
+  .refine(isSubstantiveMeaning, {
+    message:
+      'Notation meaning must be substantive prose (at least four words, not a placeholder).',
+  });
+
+const notationAlignment = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('competency'),
+    introducedByCompetency: id,
+    introducedInLesson: id,
+  }),
+  z.object({
+    kind: z.literal('general'),
+    rationale: z.string().min(1),
+  }),
+]);
+const notationAlignmentDefault = notationAlignment.default({
+  kind: 'general',
+  rationale: 'General notation.',
+});
+
+/**
+ * A citation on a notation definition: a bare id (locator pending, see D6/g) or
+ * `{id, locator}` — a per-claim locator verified against the cited text.
+ */
+const notationSource = z.union([
+  id,
+  z.object({ id, locator: z.string().min(1) }),
+]);
+
+/**
+ * A **gloss** on a notation card: a symbol the card's own `formula` needs in
+ * order to be written down, carrying a name and nothing else (D15).
+ *
+ * A gloss is deliberately cheaper than a card. It has no description, no
+ * sources, no curriculum alignment, no review state, and no glossary card of
+ * its own; it is not a node in the curriculum graph and never creates a
+ * reference edge. Its key is derived, not authored — `<card key>.<slug(name)>`
+ * — so a gloss is scoped to the card that declares it and two cards may each
+ * gloss `T`. Because a formula spells LaTeX and never a key, **promoting** a
+ * gloss is exactly: delete this line, add `content/notation/<key>.md`.
+ *
+ * `units` is optional and stays a bare unit string: "T — time" is ambiguous in
+ * a corpus with several `T`s, "T — time, years from valuation" is not, and it
+ * is still one line. Prose belongs on a card.
+ */
+const notationGloss = z.object({
+  latex: z.string().min(1),
+  name: z
+    .string()
+    .min(1)
+    .refine((value) => glossKeySegment(value) !== undefined, {
+      message:
+        'A gloss name must contain letters or digits so a key can be derived from it.',
+    })
+    // The symbol goes in `latex`, the name names it. A name carrying LaTeX is
+    // the one unambiguous way to get this field wrong, so it blocks; a name
+    // that is merely long is a Tier-3 `gloss-name-shape` warning instead,
+    // because a complicated quantity may honestly need several words.
+    .refine((value) => !/[\\$`\n]/.test(value), {
+      message:
+        'A gloss name is a plain noun phrase; put the symbol in `latex`, not in the name.',
+    }),
+  units: z.string().min(1).optional(),
+});
+
+/** An index entry's latex: a subscript on an empty group, `{}_0`. */
+export function isIndexEntryLatex(latex: string): boolean {
+  return /^\s*\{\s*\}\s*_/.test(latex);
+}
+
+/**
+ * One notation entry shape (Phase C1b), shared by page-local `notation.local`
+ * and the standalone `notation` collection.
+ *
+ * Authored: `key`, `latex`, `meaning`, optional `formula`, optional `units`
+ * (or `dimensionless: true`), `seeAlso`, `sources` (`{id, locator}`),
+ * optional `alignment` (defaults to `general`), optional `label`; and for
+ * rule N23, `reads` on an index entry, `range` and `fixedIndex` on a letter.
+ *
+ * The display label defaults to the humanized `key` (see `reference/label.ts`);
+ * `label` is authored only where that reads wrong. The `notationProse`
+ * refinement rejects an under-specified `meaning`.
+ */
+const notationEntryObject = z.object({
+  key: id,
+  latex: z.string().min(1),
+  meaning: notationProse,
+  formula: z.string().min(1).optional(),
+  units: z.string().min(1).optional(),
+  dimensionless: z.literal(true).optional(),
+  seeAlso: z.array(id).default([]),
+  sources: z.array(notationSource).default([]),
+  alignment: notationAlignmentDefault,
+  label: z.string().min(1).optional(),
+  glosses: z.array(notationGloss).default([]),
+  /**
+   * An index entry's title for the symbol it indexes (rule N23):
+   * `"{base} evaluated at t = 0"`. Defaults to `"<label> of {base}"`.
+   */
+  reads: z
+    .string()
+    .min(1)
+    .refine((value) => value.includes(BASE_PLACEHOLDER), {
+      message: `reads names the indexed symbol with ${BASE_PLACEHOLDER}, e.g. "${BASE_PLACEHOLDER} evaluated at t = 0".`,
+    })
+    .refine((value) => !/[\\$`]/.test(value), {
+      message: 'reads is plain prose: no `$`, `\\` or backtick.',
+    })
+    .optional(),
+  /** The set a running index letter runs over (rule N23): `1, \dots, n`. */
+  range: z.string().min(1).optional(),
+  /** As an index, this letter (or this entry's own index) is a fixed label. */
+  fixedIndex: z.literal(true).optional(),
+});
+
+/**
+ * Rule N23's fields belong to one kind of entry each: `reads` to an index
+ * entry (`{}_0`), and `range`, `fixedIndex` and units to anything else — a
+ * subscript has no unit, and a derived card takes the indexed symbol's.
+ */
+function refineIndexFields(
+  entry: z.infer<typeof notationEntryObject>,
+  context: z.RefinementCtx,
+): void {
+  const index = isIndexEntryLatex(entry.latex);
+  if (entry.reads !== undefined && !index) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['reads'],
+      message:
+        'reads belongs on an index entry, whose latex is a subscript on an empty group ({}_0).',
+    });
+  }
+  for (const field of ['range', 'fixedIndex', 'units', 'dimensionless'] as const) {
+    if (index && entry[field] !== undefined) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: [field],
+        message: `An index entry ({}_…) takes no ${field}: a derived card takes its units from the symbol it indexes, and the index it names is fixed already.`,
+      });
+    }
+  }
+}
+
+export const notationEntryShape = notationEntryObject.superRefine(refineIndexFields);
+
+/**
+ * One `notation.suspend` item (rule N22): a decoration (`'`, `\hat`, …) that
+ * is not an operator on this page. The loader (`collections.ts`) checks the
+ * name against the decorations the resolver knows.
+ */
+const notationSuspension = z.object({
+  operator: z.string().min(1),
+  reason: z.string().min(1).optional(),
+});
+
+const lessonNotation = z
+  .object({
+    // `notation.uses` is retired (D3): a lesson pulls a shared key into scope
+    // by referencing it in prose (`[[key]]`) or math (`\explain`).
+    local: z.array(notationEntryShape).default([]),
+    suspend: z.array(notationSuspension).default([]),
+  })
+  .default({ local: [], suspend: [] });
+
+/**
+ * How long this chapter takes to study: `40`, or a `[low, high]` range in
+ * minutes. It is a reader-facing estimate the author makes, aggregated by
+ * `<PartOverview>` and `<CourseContents>` into a part and course total — not
+ * the provenance field `estimatedMinutes` used to be, and nothing derives it.
+ *
+ * A part only reports a total when every one of its chapters states one, so a
+ * half-annotated course shows the chapters it knows about and no misleading
+ * sum.
+ */
+const studyMinutes = z
+  .union([
+    z.number().int().positive(),
+    z.tuple([z.number().int().positive(), z.number().int().positive()]),
+  ])
+  .refine((value) => !Array.isArray(value) || value[0] <= value[1], {
+    message:
+      'studyMinutes as a range is [low, high]; the low end cannot exceed the high end.',
+  });
+
+/**
+ * Lesson frontmatter — reduced shape (Phase C1 schema, C2 codemod applied):
+ * the fields explico adds to Starlight's own (`title`, `description`, …).
+ *
+ * Authored:  `teaches` (ordered — the curriculum contract, never derived),
+ *            `assumptions`, `studyMinutes` (optional reader-facing estimate),
+ *            `notation.local` (page-local symbols only).
+ * Derived (in `compiler/collections.ts` + `compiler/lesson-derivation.ts`,
+ *            never authored): `lessonId` (doc slug), `requires` (direct
+ *            competency-DAG prerequisites of `teaches`, minus `teaches`),
+ *            `sources` (`[@…]` occurrences), `assessments` (colocated
+ *            `<lesson>.checks.yml`), `sidebar` order (track order).
+ * Dropped:   `aiAssisted`, `lastReviewed`, `riskTier` (git history carries
+ *            provenance); `editorialStatus`, the draft / in-review / reviewed
+ *            flag, because lessons are reviewed continuously and never earn a
+ *            one-time stamp (a file that still sets it fails the build, see
+ *            `reference/gate-retired-keys.ts`); `estimatedMinutes`, whose
+ *            reader-facing half returned as the optional `studyMinutes` once
+ *            part pages had somewhere to total it; `notation.uses` (D3 — a
+ *            shared symbol is imported by using it).
+ */
+export const lessonFrontmatterSchema = z.object({
+  teaches: z.array(id).default([]),
+  assumptions: z.array(z.string().min(1)).default([]),
+  studyMinutes: studyMinutes.optional(),
+  notation: lessonNotation,
+});
+
+export const competencySchema = z.object({
+  id,
+  title: z.string().min(1),
+  domain: id,
+  facet: z.enum([
+    'knowledge',
+    'calculation',
+    'interpretation',
+    'convention',
+    'risk',
+  ]),
+  outcome: z.string().min(1),
+  prerequisites: z.array(id).default([]),
+  evidence: z.object({
+    minimumIndependentItems: z.number().int().min(1),
+    requiresTransfer: z.boolean(),
+    requiresUnassistedPass: z.boolean(),
+  }),
+  misconceptions: z.array(z.string().min(1)).default([]),
+});
+
+const assessmentItemBase = z.object({
+  id,
+  competencyId: id,
+  evidenceKind: z.enum(['direct', 'transfer']),
+  prompt: z.string().min(1),
+  explanation: z.string().min(1),
+});
+
+/**
+ * `AssessmentSet.astro` renders the numbered heading itself — `<h2>Knowledge
+ * check {number} — {title}</h2>` — so `title` must be just the topic. A title
+ * that repeats the "Knowledge check" label duplicates it on every page that
+ * uses `AssessmentSet` (the standalone `AssessmentRunner` heading fallback
+ * reads fine either way, so this only bites the common path).
+ */
+const assessmentTitle = z
+  .string()
+  .min(1)
+  .refine((value) => !/^knowledge check\b/i.test(value), {
+    message:
+      'Assessment title must not start with "Knowledge check" — AssessmentSet already renders "Knowledge check {number} — {title}", so a title with the same prefix duplicates it. Use just the topic, e.g. "AIC and KL risk".',
+  });
+
+export const assessmentSchema = z.object({
+  id,
+  title: assessmentTitle,
+  items: z
+    .array(
+      z.discriminatedUnion('type', [
+        assessmentItemBase.extend({
+          type: z.literal('numeric'),
+          answer: z.object({
+            value: z.number(),
+            tolerance: z.number().positive(),
+          }),
+        }),
+        assessmentItemBase.extend({
+          type: z.literal('single-choice'),
+          options: z
+            .array(
+              z.object({
+                id,
+                label: z.string().min(1),
+              }),
+            )
+            .min(2),
+          correctOptionId: id,
+        }),
+      ]),
+    )
+    .min(1),
+});
+
+export const trackSchema = z.object({
+  id,
+  title: z.string().min(1),
+  description: z.string().min(1),
+  audience: z.string().min(1),
+  entryAssumptions: z.array(z.string().min(1)),
+  lessons: z.array(id).min(1),
+});
+
+export const sourceSchema = z.object({
+  id,
+  type: z.enum([
+    'primary',
+    'official-guidance',
+    'paper',
+    'book',
+    'secondary',
+  ]),
+  title: z.string().min(1),
+  authors: z.array(z.string().min(1)).optional(),
+  organization: z.string().min(1).optional(),
+  edition: z.string().optional(),
+  publisher: z.string().optional(),
+  year: z.number().int().optional(),
+  isbn: z.string().optional(),
+  url: z.url().optional(),
+  locator: z.string().optional(),
+  accessed: z.coerce.date().optional(),
+  licenseNotes: z.string().optional(),
+});
+
+/**
+ * Standalone notation collection — the one `notationEntry` shape plus the
+ * shared-only extras: `domain`, `aliases`, and a Markdown body.
+ */
+export const notationSchema = notationEntryObject
+  .extend({
+    domain: id,
+    aliases: z.array(z.string().min(1)).default([]),
+    aiAssisted: z.boolean().default(false),
+  })
+  .superRefine(refineIndexFields);
+
+/**
+ * Abbreviations table (rule N14) — deliberately a lighter tier than a
+ * `notation` card: just a name resolution, no `formula`, `units`, or
+ * curriculum `alignment`. `abbr` is the canonical written form (`OLS`);
+ * `aliases` are other written forms of the same abbreviation that should
+ * resolve the same way (`w.r.t.` might alias `wrt`).
+ */
+export const abbreviationSchema = z.object({
+  key: id,
+  abbr: z.string().min(1),
+  expansion: notationProse,
+  aliases: z.array(z.string().min(1)).default([]),
+  domain: id.optional(),
+});
+
+/**
+ * Each collection's directory under `content/` and the schema a record there
+ * must satisfy. `docs` checks only the fields explico adds; Starlight's own
+ * (`title`, `description`, …) are Starlight's schema's to judge.
+ */
+export const CONTENT_SCHEMAS = {
+  docs: lessonFrontmatterSchema,
+  competencies: competencySchema,
+  assessments: assessmentSchema,
+  tracks: trackSchema,
+  sources: sourceSchema,
+  notation: notationSchema,
+  abbreviations: abbreviationSchema,
+} as const;

package/src/compiler/course-config.ts

@@ -36,13 +36,6 @@ export interface CoursePart {
  */
 export type CourseSection = CoursePart;
 
-export interface CourseConventions {
-  /** Notation key a lesson's stated sign convention must resolve to. */
-  readonly signConventionKey: string;
-  /** Competency id that also counts as declaring the cash-flow perspective. */
-  readonly cashFlowPerspectiveCompetency: string;
-}
-
 /**
  * A course's edits to the shipped named-operator baseline (`BASE_OPERATORS`),
  * consumed by the `operator-explained` consistency check (rule N8). An operator
@@ -360,6 +353,39 @@ export function normalizeBlockLabels(config: CourseConfig): BlockLabels {
   return labels;
 }
 
+/**
+ * How a course's explanation cards start for a reader who has not chosen
+ * yet (`cards` in the course settings). Every field is optional;
+ * {@link normalizeCards} fills in the defaults.
+ */
+export interface CourseCards {
+  /**
+   * Whether "Carry cards" starts on (rule K1, `card-carry.ts`): a kept card
+   * stays on screen as the page scrolls and comes along to every page of the
+   * course. A reader's own choice always wins. Default `false`.
+   */
+  readonly carry?: boolean;
+}
+
+/** {@link CourseCards} with every default applied. */
+export interface NormalizedCards {
+  readonly carry: boolean;
+}
+
+/** The engine's defaults: a reader turns carrying on (D8). */
+export const CARDS_DEFAULTS: NormalizedCards = { carry: false };
+
+/** Validate `CourseConfig.cards` and apply its defaults. Throws on a bad value. */
+export function normalizeCards(config: CourseConfig): NormalizedCards {
+  const carry: unknown = config.cards?.carry ?? CARDS_DEFAULTS.carry;
+  if (typeof carry !== 'boolean') {
+    throw new Error(
+      `CourseConfig cards.carry must be true or false; received ${JSON.stringify(carry)}.`,
+    );
+  }
+  return { carry };
+}
+
 /**
  * Rule S2's word ranges (`rules.S2.bridgeMinWords` … in the course settings),
  * in the shape `gate-part-pages.ts` takes. Built by `partPageLimits` in
@@ -370,15 +396,33 @@ export interface NormalizedPartPages {
   readonly scope: { readonly minWords: number; readonly maxWords: number };
 }
 
-/** Optional, build-time lesson artifacts exposed to readers. */
+/**
+ * Optional, build-time downloads and print actions: each chapter, each part and
+ * the course download; every page prints.
+ */
 export interface LessonExportsConfig {
-  /** Emit one self-contained, offline-capable HTML file per lesson. */
+  /** Emit one self-contained, offline-capable HTML file per page. */
   readonly standaloneHtml?: boolean;
-  /** Offer the browser's native print dialog with explico's lesson print layout. */
+  /** Offer the browser's native print dialog with explico's print layout. */
   readonly print?: boolean;
+  /**
+   * Emit each chapter's LaTeX source — a zipped folder with explico's class,
+   * the chapter and its figures — and the PDF compiled from that folder.
+   */
+  readonly latex?: boolean;
+  /**
+   * Paper size of the LaTeX documents: `letter` (default, LaTeX's own) or
+   * `a4`. A plain `string` because the settings arrive as JSON.
+   */
+  readonly latexPaper?: string;
+  /**
+   * Emit each chapter, each part and the course as Markdown — GitHub's
+   * flavour with `$…$` math, its figures as PNG — zipped with its assets.
+   */
+  readonly markdown?: boolean;
   /**
    * Published course root used for links that intentionally leave the exported
-   * lesson. Required at export time when such a link is present.
+   * page. Required at export time when such a link is present.
    */
   readonly canonicalBaseUrl?: string;
 }
@@ -387,6 +431,9 @@ export interface LessonExportsConfig {
 export interface NormalizedLessonExports {
   readonly standaloneHtml: boolean;
   readonly print: boolean;
+  readonly latex: boolean;
+  readonly latexPaper: 'letter' | 'a4';
+  readonly markdown: boolean;
   readonly canonicalBaseUrl?: string;
 }
 
@@ -405,7 +452,12 @@ export interface CourseConfig {
   readonly sections?: readonly CoursePart[];
   /** Namespaces used by competency / notation `domain` fields. */
   readonly domains: readonly string[];
-  readonly conventions: CourseConventions;
+  /**
+   * @deprecated No longer read: rule S5, the only reader, was retired. A
+   * course that still sets it gets a `config-deprecated-key` warning; delete
+   * the block. Removed from the type in the next MINOR release.
+   */
+  readonly conventions?: unknown;
   /** Reader-facing identity + knowledge version (the `[?]` About panel). */
   readonly about: CourseAbout;
   /**
@@ -428,12 +480,14 @@ export interface CourseConfig {
   readonly romanLabels?: CourseRomanLabels;
   /** @deprecated Moved to `rules.N14` (same shape). Honoured for now; removed in a later MINOR. */
   readonly abbreviations?: CourseAbbreviations;
-  /** Per-lesson export actions and downloadable artifacts. Disabled when omitted. */
+  /** Per-page export actions and downloadable artifacts. Disabled when omitted. */
   readonly lessonExports?: LessonExportsConfig;
   /** Every collapse default: headings, checks, memos, floats, tables. */
   readonly disclosure?: CourseDisclosure;
   /** Outline and float numbering. The defaults apply when omitted. */
   readonly numbering?: CourseNumbering;
+  /** How explanation cards start for a reader: "Carry cards" on or off. */
+  readonly cards?: CourseCards;
   /**
    * How a check's and an example set's heading names its kind: `icon-word`
    * (default) or `icon` ({@link BlockLabels}). A plain `string` because the
@@ -449,8 +503,18 @@ export function normalizeLessonExports(
 ): NormalizedLessonExports {
   const standaloneHtml = config.lessonExports?.standaloneHtml === true;
   const print = config.lessonExports?.print === true;
+  const latex = config.lessonExports?.latex === true;
+  const rawPaper = config.lessonExports?.latexPaper ?? 'letter';
+  if (rawPaper !== 'letter' && rawPaper !== 'a4') {
+    throw new Error(
+      `CourseConfig lessonExports.latexPaper must be "letter" or "a4"; ` +
+        `received ${JSON.stringify(rawPaper)}.`,
+    );
+  }
+  const latexPaper: 'letter' | 'a4' = rawPaper;
+  const markdown = config.lessonExports?.markdown === true;
   const rawBase = config.lessonExports?.canonicalBaseUrl;
-  if (rawBase === undefined) return { standaloneHtml, print };
+  if (rawBase === undefined) return { standaloneHtml, print, latex, latexPaper, markdown };
 
   let parsed: URL;
   try {
@@ -473,7 +537,14 @@ export function normalizeLessonExports(
     );
   }
   if (!parsed.pathname.endsWith('/')) parsed.pathname += '/';
-  return { standaloneHtml, print, canonicalBaseUrl: parsed.toString() };
+  return {
+    standaloneHtml,
+    print,
+    latex,
+    latexPaper,
+    markdown,
+    canonicalBaseUrl: parsed.toString(),
+  };
 }
 
 /**