explico 0.7.0 → 0.11.0

package/dist/compiler/manifest.d.ts

@@ -4,18 +4,23 @@ import { EquationLabelRecord, EquationDiagnostic } from '../reference/equations-
 import { TableLabelRecord, TableDiagnostic } from '../reference/tables-validate.js';
 import { FigureLabelRecord, FigureDiagnostic } from '../reference/figures-validate.js';
 import { DiagramLabelRecord, DiagramDiagnostic } from '../reference/diagrams-validate.js';
+import { ExampleLabelRecord, ExampleDiagnostic } from '../reference/examples-validate.js';
+import { FoldDiagnostic } from '../reference/folds-validate.js';
 import { KnowledgeCheckLabelRecord, KnowledgeCheckDiagnostic } from '../reference/knowledge-checks-validate.js';
 import { RawFloatDiagnostic } from '../reference/raw-floats-validate.js';
 import { MathGateDiagnostic } from '../reference/gate-math.js';
 import { ContentSegment } from '../reference/mixed-content.js';
 import { GlyphScopeEntry } from '../reference/gloss.js';
 import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus, NotationGlossEntry } from '../reference/types.js';
-import { NormalizedLessonExports, NormalizedDisclosureDefaults, CourseConfig } from './course-config.js';
+import { b as NormalizedLessonExports, c as NormalizedDisclosure, d as NormalizedNumbering, B as BlockLabels, M as ManifestRules, e as ConfigDiagnostic, C as CourseConfig } from '../course-config-Dsnri9Tk.js';
+import { WaiverDiagnostic } from '../rules/waivers.js';
 import { KnowledgeVersionDiagnostic } from './knowledge-version.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
 import '../reference/lint-ignore.js';
 import '../reference/keyed-float-validate.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
 
 /**
  * The one compiler manifest (Phase D5).
@@ -100,8 +105,70 @@ import '../reference/keyed-float-validate.js';
  * optional advice. Unused keys/definitions and restructuring candidates move
  * from `warning` to `info`; their diagnostic codes and container fields stay
  * unchanged.
+ * v17 (part pages, additive): `parts` — every part with its chapters in
+ * reading order and, where the course authored one, its overview page. A part
+ * with an overview page also gains a leading `Overview` item in its
+ * `sidebar` group, so `sidebar[].items` is now a mixed list of lesson slugs
+ * and `{ label, link, attrs? }` entries rather than one kind per group.
+ * Also `lessons[].studyMinutes` from the optional frontmatter field, and
+ * `parts[].studyMinutes` totalling it across a part whose chapters all
+ * state one.
+ *
+ * v18 (rule settings, additive): `rules` — the course's rule switches
+ * (`disabled`) and every rule's effective settings; `diagnostics.config` —
+ * findings about the course settings themselves (a deprecated top-level
+ * `operators` / `romanLabels` / `abbreviations` block, a block for a retired
+ * rule), from `resolveRules`. A diagnostic owned by a disabled rule is not
+ * published at all; one covered by a per-place waiver
+ * (`{/* explico-allow N9: reason *\/}`) is dropped too, and
+ * `diagnostics.waivers` reports the waivers themselves (malformed, invalid,
+ * unused). Every math-gate finding now carries a `code`
+ * (`prose-notation`, `abbreviation-unexplained`, `title-length`,
+ * `unresolved-glyph`, `math-compile-error`, or the resolver's own).
+ *
+ * v19 (course rules, additive): `rules.course` — the course's own `X` rules
+ * from `courseRules` in the settings, validated, in file order, so
+ * `build/rules-in-effect.md` and `content rules` list them beside the engine's.
+ * A finding from one is in `diagnostics.math` with the rule's ID as its `code`.
+ *
+ * v20 (outline numbering): `numbering` — the course's resolved
+ * `numbering` settings; `lessons[].headings` — every top-level heading with
+ * its anchor, text, level and, down to `numbering.sections.depth`, its
+ * `‹part›.‹chapter›.‹section›…` number; `lessons[].numbering.prefix` — the
+ * float-number prefix. Under the default `numbering.floats: "chapter"` that
+ * prefix is `‹part›.‹chapter›` and every per-kind offset is 0, so a float
+ * number is `2.2.1` where it used to be `2.1`. A `[[sec-…]]` that names no
+ * heading is a `sec-ref-resolves` error in `diagnostics.math`.
+ *
+ * v21 (one caption pair): `lessons[].equations` / `.tables` / `.figures` /
+ * `.diagrams` entries, and the `labels` of `equations` / `tables` / `figures`
+ * / `diagrams`, carry the float's `short` caption (an equation's
+ * `\caption{…}`, or the `short` prop) and, for a JSX float, its long
+ * `caption`, each when stated as a literal. `diagnostics.figures` /
+ * `diagnostics.diagrams` gain `fig-removed-prop` / `dia-removed-prop`.
+ *
+ * v22 (one collapse model): `disclosure` replaces `disclosureDefaults` — the
+ * course's whole `disclosure` settings block with the engine defaults applied
+ * (`NormalizedDisclosure`): `sections` / `subsections` / `knowledgeChecks`
+ * as `{ collapsible, defaultOpen }`, `notation` / `references` / `memos` /
+ * `figures` / `diagrams` / `workedExamples` as `{ defaultOpen }`, and
+ * `tables.truncateAfter`.
+ *
+ * v23 (kind badges): a worked-example set is a numbered kind of its own —
+ * `examples` (same shape as `figures`), `lessons[].examples`,
+ * `lessons[].numbering.examples` and `diagnostics.examples` (`ex-…` codes,
+ * `ex-missing-prop` among them). `lessons[].knowledgeChecks` entries carry
+ * the check's `title`; `lessons[].titledBlocks` lists every check and example
+ * set with the anchor and title of the `<h2>` it draws and the heading it
+ * follows; `blockLabels` is the course's resolved badge form.
+ *
+ * v24 (figures stop compacting; `<Fold>`): `disclosure` loses `diagrams` —
+ * a diagram no longer folds by itself — and gains `folds`, the first-visit
+ * state of a `<Fold>`; `disclosure.figures` now says whether a lab's tools
+ * start open; `diagnostics.folds` holds `fold-unnamed`
+ * (docs/plans/figures-and-short-captions.md, Parts 1–2).
  */
-declare const MANIFEST_SCHEMA_VERSION = 15;
+declare const MANIFEST_SCHEMA_VERSION = 24;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -146,74 +213,122 @@ interface ManifestLessonNotation {
      */
     readonly formulaScope: readonly GlyphScopeEntry[];
 }
+/**
+ * One keyed float of a lesson (v21): its key and number, and its caption pair
+ * — `short` (an equation's `\caption{…}`, or the `short` prop) and, for a
+ * `<Table>` / `<Figure>` / `<Diagram>`, the long `caption`. Each is present
+ * only when the source states it as a literal.
+ */
+interface ManifestLessonFloat {
+    readonly key: string;
+    readonly number: string;
+    readonly short?: string;
+    readonly caption?: string;
+}
+/**
+ * A block that draws a heading of its own where its tag stands (v23): a
+ * knowledge check (`<AssessmentSet />`) or a worked-example set
+ * (`<CompactExamples>`). `anchor` is the heading's id, `title` the author's
+ * topical title, `after` the slug of the top-level heading it follows.
+ */
+interface ManifestTitledBlock {
+    readonly kind: 'check' | 'example';
+    readonly key: string;
+    readonly anchor: string;
+    readonly title: string;
+    readonly after?: string;
+}
 interface ManifestLesson {
     readonly id: string;
     /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
     readonly slug: string;
     /**
      * The 1-based ordinal of the **part** this lesson sits in — its sidebar
-     * group's position in `courseConfig.parts`. It is the number before the dot
-     * in every equation, table, figure, diagram, and knowledge-check number on
-     * the page: `(2.1)` is the first equation of part 2. See
-     * `docs/authoring/structure.md`.
+     * group's position in `courseConfig.parts`. It is the first number of every
+     * section, equation, table, figure, diagram, and knowledge-check number on
+     * the page. See `docs/authoring/structure.md`.
      */
     readonly part: number;
     /**
      * The lesson's 1-based ordinal **within its part** (merged track order, then
-     * any unranked lessons by slug) — its chapter number. This orders the
-     * sidebar and the reading path; it does not appear in a float's number.
+     * any unranked lessons by slug) — its chapter number, the second number of
+     * every section number (`1.2.3`) and, under the default
+     * `numbering.floats: "chapter"`, of every float number (`(1.2.1)`).
      */
     readonly chapter: number;
     /**
-     * How many floats of each kind the earlier lessons of this part already
-     * used. The lesson's own floats continue from here, so a part's sequence
-     * runs unbroken across its chapters instead of restarting on every page.
+     * The float numbers' `prefix` — `‹part›.‹chapter›` under
+     * `numbering.floats: "chapter"`, `‹part›` under `"part"` — and, per kind,
+     * how many floats of that kind precede this lesson in that scope: always 0
+     * for `chapter`, the earlier chapters' count for `part`, whose sequence
+     * runs unbroken across the part. A float is `‹prefix›.‹offset + n›`.
      */
     readonly numbering: {
+        readonly prefix: string;
         readonly equations: number;
         readonly tables: number;
         readonly figures: number;
         readonly diagrams: number;
         readonly checks: number;
+        readonly examples: number;
     };
+    /**
+     * Every top-level heading in document order (`sections.mjs`): its anchor
+     * (`slug`, which the page's heading is given, and which `[[sec-slug]]`
+     * names), its text and level, and — for a `##` to the course's
+     * `numbering.sections.depth` — its outline number, `‹part›.‹chapter›.‹s›…`.
+     */
+    readonly headings: readonly {
+        readonly slug: string;
+        readonly text: string;
+        readonly level: number;
+        readonly number?: string;
+    }[];
     readonly file: string;
     readonly title: string;
     readonly description: string;
+    /** Authored reader-facing estimate; `40` and `[30, 40]` both land here. */
+    readonly studyMinutes?: {
+        readonly min: number;
+        readonly max: number;
+    };
     readonly status: EditorialStatus;
     /** Ordered — the curriculum contract. */
     readonly teaches: readonly string[];
     readonly requires: readonly string[];
     readonly assumptions: readonly string[];
     readonly assessments: readonly string[];
-    /** Numbered knowledge checks from `assessments`, in `.checks.yml` order. */
+    /**
+     * Numbered knowledge checks from `assessments`, in `.checks.yml` order,
+     * each with the `title` its assessment file gives it (v23) — the topic its
+     * heading shows after the engine's badge.
+     */
     readonly knowledgeChecks: readonly {
         readonly key: string;
         readonly number: string;
+        readonly title?: string;
     }[];
+    /**
+     * The blocks that draw an `<h2>` of their own (v23): each knowledge check
+     * and worked-example set, in document order, with that heading's `anchor`
+     * and `title` and `after`, the slug of the top-level heading it follows
+     * (absent before the first) — where "On this page" lists it.
+     */
+    readonly titledBlocks: readonly ManifestTitledBlock[];
     readonly sources: readonly string[];
     readonly citations: readonly ManifestCitation[];
     /** Competency prerequisite edges this lesson introduces. */
     readonly prereqEdges: readonly PrereqEdge[];
     /** Labelled display equations in appearance order (D7). */
-    readonly equations: readonly {
-        readonly key: string;
-        readonly number: string;
-    }[];
+    readonly equations: readonly ManifestLessonFloat[];
     /** Keyed `<Table>` elements in appearance order. */
-    readonly tables: readonly {
-        readonly key: string;
-        readonly number: string;
-    }[];
+    readonly tables: readonly ManifestLessonFloat[];
     /** Keyed `<Figure>` elements in appearance order. */
-    readonly figures: readonly {
-        readonly key: string;
-        readonly number: string;
-    }[];
+    readonly figures: readonly ManifestLessonFloat[];
     /** Keyed `<Diagram>` elements in appearance order. */
-    readonly diagrams: readonly {
-        readonly key: string;
-        readonly number: string;
-    }[];
+    readonly diagrams: readonly ManifestLessonFloat[];
+    /** Keyed `<CompactExamples>` sets in appearance order; `short` is the set's title (v23). */
+    readonly examples: readonly ManifestLessonFloat[];
     readonly notation: {
         readonly bindings: readonly {
             readonly key: string;
@@ -262,12 +377,48 @@ interface ManifestAssessmentItemContent {
     readonly promptSegments: readonly ContentSegment[];
     readonly explanationSegments: readonly ContentSegment[];
 }
+/**
+ * One **part** (v17) — a sidebar group and the directory its chapters live in,
+ * with its chapters in reading order and its overview page when the course
+ * authored one at `content/docs/<dir>/index.mdx`.
+ *
+ * `link` is where the directory URL resolves; without an `overview` that URL
+ * has no page behind it, which is exactly the 404 a part-level page removes.
+ */
+interface ManifestPart {
+    readonly dir: string;
+    readonly label: string;
+    /** 1-based position in `courseConfig.parts` — the float-number prefix. */
+    readonly ordinal: number;
+    /** Base-relative href of the part's own page, `/<dir>/`. */
+    readonly link: string;
+    /** Lesson ids in chapter order. */
+    readonly lessons: readonly string[];
+    /**
+     * The part's total study time — present only when **every** chapter in it
+     * states one, so a half-annotated part reports the chapters it knows and no
+     * misleading sum.
+     */
+    readonly studyMinutes?: {
+        readonly min: number;
+        readonly max: number;
+    };
+    readonly overview?: {
+        readonly title: string;
+        readonly file: string;
+        readonly description?: string;
+    };
+}
 interface Manifest {
     readonly schemaVersion: number;
     /** Normalized build/UI settings for opt-in per-lesson exports. */
     readonly lessonExports: NormalizedLessonExports;
-    /** Initial open/closed state for "Page notation" and "References". */
-    readonly disclosureDefaults: NormalizedDisclosureDefaults;
+    /** Every collapse default, engine defaults applied (`CourseConfig.disclosure`). */
+    readonly disclosure: NormalizedDisclosure;
+    /** Outline and float numbering, defaults applied (`CourseConfig.numbering`). */
+    readonly numbering: NormalizedNumbering;
+    /** How a check's and an example set's heading names its kind (`CourseConfig.blockLabels`). */
+    readonly blockLabels: BlockLabels;
     /** Reader-facing identity + versions (the `[?]` About panel). */
     readonly about: ManifestAbout;
     readonly notation: {
@@ -284,6 +435,8 @@ interface Manifest {
     /** Abbreviations table (N14), for `remarkAbbreviations`. Ordered by key. */
     readonly abbreviations: readonly Record<string, unknown>[];
     readonly sidebar: readonly SidebarGroup[];
+    /** The course's parts in config order, with their chapters and overview pages. */
+    readonly parts: readonly ManifestPart[];
     readonly lessons: readonly ManifestLesson[];
     /** Full competency prerequisite graph. */
     readonly prereqEdges: readonly PrereqEdge[];
@@ -313,6 +466,11 @@ interface Manifest {
         readonly labels: readonly KnowledgeCheckLabelRecord[];
         readonly numbersBySlug: Record<string, Record<string, string>>;
     };
+    /** Keyed-float identity for `<CompactExamples>` — same shape as `figures` (v23). */
+    readonly examples: {
+        readonly labels: readonly ExampleLabelRecord[];
+        readonly numbersBySlug: Record<string, Record<string, string>>;
+    };
     /**
      * Every assessment item's `prompt` / `explanation`, pre-split into
      * text/math segments (v8). `AssessmentSet.astro` filters this by
@@ -323,6 +481,13 @@ interface Manifest {
      * lesson's scope can resolve its glyphs differently.
      */
     readonly assessmentContent: readonly ManifestAssessmentItemContent[];
+    /**
+     * The course's rule switches and settings (`CourseConfig.rules`, resolved
+     * against `src/rules/catalog.ts`). `disabled` names the rules whose
+     * diagnostics are withheld below; `settings` is every rule's effective
+     * values, defaults applied.
+     */
+    readonly rules: ManifestRules;
     readonly diagnostics: {
         readonly curriculum: readonly CurriculumIssue[];
         readonly notation: readonly NotationDiagnostic[];
@@ -342,12 +507,20 @@ interface Manifest {
         readonly diagrams: readonly DiagramDiagnostic[];
         /** Knowledge-check identity and `[[check-…]]` reference checks. */
         readonly checks: readonly KnowledgeCheckDiagnostic[];
+        /** `<CompactExamples>` identity checks — the keyed-float codes, `ex-` prefixed, plus `ex-missing-prop`. */
+        readonly examples: readonly ExampleDiagnostic[];
+        /** `<Fold>` checks: `fold-unnamed`, a fold with no `label` and no numbered float to name its bar by. */
+        readonly folds: readonly FoldDiagnostic[];
         /**
          * A raw Markdown table, a raw HTML `<table>`, or an Explico `<Diagram>`
          * that is unkeyed or nested outside `<Table>`/`<Figure>` — invisible to
          * keyed-float validation above. Warnings only.
          */
         readonly rawFloats: readonly RawFloatDiagnostic[];
+        /** Findings about `CourseConfig.rules` and the deprecated blocks it replaces. Warnings only. */
+        readonly config: readonly ConfigDiagnostic[];
+        /** Per-place waivers that are malformed, name an unwaivable rule, or silenced nothing. */
+        readonly waivers: readonly WaiverDiagnostic[];
     };
     readonly hashes: {
         /** `sha256` of every content source file, keyed by repo-relative path. */
@@ -376,4 +549,4 @@ declare function readManifestSync(): Manifest;
  */
 declare function loadManifest(courseConfig?: CourseConfig): Promise<Manifest>;
 
-export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestAssessmentItemContent, type ManifestCitation, type ManifestLesson, type ManifestLessonNotation, type ManifestNotationResolution, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };
+export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestAssessmentItemContent, type ManifestCitation, type ManifestLesson, type ManifestLessonFloat, type ManifestLessonNotation, type ManifestNotationResolution, type ManifestPart, type ManifestTitledBlock, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };