feat(cph): implement nested outline manifest and batch/combined export

ADR-0029 — nested outline manifest, supersedes ADR-0008's flat [[parts]]:
- cph-model: recursive loader over manifest.toml containers / element.toml
  leaves; Lesson.parts (pure elements, DFS order) + Lesson.outline (elements
  interleaved with section headings at their DFS-open position); rejects
  ambiguous/incomplete folders and root-vs-container table misplacement
- cph-diag: new DiagCode::ManifestMalformed for carrier-document structure
  errors (discharges an existing TODO)
- cph-typst: augmented manifest now serializes the outline (element/section
  entries) instead of a flat parts array
- render/lib.typ: render-lesson renders section headings at their depth
- examples/TH-141 migrated to 5 nested section containers + 3 root segments,
  byte-identical element order; smoke-verified via cph check/build + pdftotext

ADR-0030 — batch & combined export, extends ADR-0009/0011:
- cph build with no --target batches every declared target (repeatable
  --target for an explicit subset); any target failure => non-zero exit,
  per-target ledger, independent per-target execution
- cph-model: bundle.toml loader (directory + [info]/[targets.*]/ordered
  lessons with per-lesson target overrides)
- cph-typst: augmented bundle manifest (path-prefixed member outlines),
  Engine::{compile_check_bundle,build_bundle_pdf}
- render/lib.typ: render-bundle assembles member lessons under per-lesson
  headings, depth-shifts their own section headings, resets example/lemma
  counters at each lesson boundary by default
- cph-cli: `cph bundle <path> --target <name>` subcommand, same batching
  contract as `cph build`
- new bundle fixtures/tests (cph-model unit + cph-typst through-template PDF
  compile), smoke-verified via a real 2-lesson merged PDF

Verification: cargo fmt/clippy/test clean across the workspace (68 tests);
real cph check/build/bundle runs against TH-141 and a bundle fixture, PDF
content inspected via pdftotext.
This commit is contained in:
2026-08-04 20:31:05 +08:00
committed by 洪佳荣
parent e0bd6120ec
commit 9927d38c18
165 changed files with 2638 additions and 691 deletions
+110 -18
View File
@@ -1,14 +1,14 @@
// cph-render — curriculum lesson render package.
//
// PUBLIC ENTRY: `render-lesson(info, target, parts, heading-numbering)`.
// PUBLIC ENTRY: `render-lesson(info, target, outline, heading-numbering)`.
//
// MODEL (ADR-0011). A build compiles a *template file* (e.g. `exports/student.typ`)
// as the typst main, with the manifest injected via `--input manifest=<path>`.
// The template reads the manifest, loads each part's content, and calls
// `render-lesson` here. Presentation (heading numbering) lives in the template,
// not the manifest, not hardcoded-unreachable in this package — we only provide
// the DEFAULT scheme (`default-heading-numbering`) for the template to use or
// override.
// MODEL (ADR-0011, outline shape per ADR-0029). A build compiles a *template
// file* (e.g. `exports/student.typ`) as the typst main, with the manifest
// injected via `--input manifest=<path>`. The template reads the manifest,
// loads each **element** entry's content, and calls `render-lesson` here.
// Presentation (heading numbering) lives in the template, not the manifest,
// not hardcoded-unreachable in this package — we only provide the DEFAULT
// scheme (`default-heading-numbering`) for the template to use or override.
//
// WHY THE TEMPLATE LOADS CONTENT, NOT US (the include-resolution finding):
// typst resolves an `include`/`import` path relative to THE PACKAGE/FILE THE
@@ -19,11 +19,15 @@
// Therefore the dynamic-include LOOP must live in the TEMPLATE (which lives at
// `<root>/exports/*.typ`, so `/<part.path>/<field>.typ` resolves against
// `--root`). `render-lesson` is content-in: it takes an ALREADY-ASSEMBLED
// `parts` array of dicts and never includes anything itself.
// `outline` array of entry dicts and never includes anything itself.
//
// A part dict the template hands us:
// `kind` plus that kind's content/scalar fields. Content field VALUES are
// already-evaluated typst content (the template produced them via `include`).
// An `outline` entry the template hands us is one of:
// - an ELEMENT: `entry-type: "element"`, `kind` plus that kind's
// content/scalar fields. Content field VALUES are already-evaluated typst
// content (the template produced them via `include`).
// - a SECTION (ADR-0029): `entry-type: "section"`, `title` (heading text),
// `depth` (1-based heading level). Contributes no element; it is a
// heading at its depth-first-open position in the outline.
//
// kind -> fields (MVP) — see `part-fields` below, which the template uses to
// know what to load:
@@ -41,7 +45,6 @@
// unknown : rendered conservatively == student (show only required-public
// fields). Never crashes. The "no render rule => warning"
// diagnostic is the Rust side's job, not ours.
#import "src/style.typ": base-style, default-heading-numbering, title-block, subtitle-block
#import "src/elements/segment.typ": display-segment
#import "src/elements/example.typ": display-example
@@ -106,14 +109,33 @@
}
}
/// Render one section-heading outline entry (ADR-0029): `entry.title` at
/// `entry.depth` (1-based heading level).
#let _render-section(entry) = {
heading(level: entry.at("depth", default: 1))[#entry.at("title", default: "")]
}
/// Render one outline entry: an element dispatches on `kind` via
/// [`_render-part`]; a section (ADR-0029) renders its heading and contributes
/// no element.
#let _render-entry(entry, flags) = {
if entry.at("entry-type", default: "element") == "section" {
_render-section(entry)
} else {
_render-part(entry, flags)
}
}
/// THE ENTRY POINT — called by a template (`exports/*.typ`).
///
/// - `info`: dict, e.g. (title: "…", author: "…"). `author` may be absent.
/// Templates typically pass `manifest.at("info", default: (:))`.
/// - `target`: string. MVP: "student" | "teacher". Unknown => conservative.
/// Each template hardcodes its own target (student.typ => "student").
/// - `parts`: ordered array of part dicts, ALREADY ASSEMBLED by the template
/// (content fields included, scalars read). See file header.
/// - `outline`: ordered array of outline-entry dicts (ADR-0029), ALREADY
/// ASSEMBLED by the template (element content fields included,
/// scalars read; section entries carry `title`/`depth`). See file
/// header for the entry shapes.
/// - `heading-numbering`: array of per-level numbly pattern strings, e.g.
/// `("{1:一}、", "{1:1}.{2:1}", "{1:1}.{2:1}.{3:1}")`. Presentation
/// lives in the template (ADR-0011); the template passes its chosen
@@ -122,7 +144,7 @@
#let render-lesson(
info: (:),
target: "student",
parts: (),
outline: (),
heading-numbering: default-heading-numbering,
) = {
let title = info.at("title", default: [])
@@ -146,7 +168,77 @@
subtitle-block(flags.subtitle)
// Render strictly in array order.
for part in parts {
_render-part(part, flags)
for entry in outline {
_render-entry(entry, flags)
}
}
/// Shift a section entry's `depth` by `delta`; an element entry passes through
/// unchanged (elements carry no depth). Used by [`render-bundle`] to nest each
/// lesson's own outline one level under that lesson's title heading.
#let _shift-depth(entry, delta) = {
if entry.at("entry-type", default: "element") == "section" {
entry.depth = entry.depth + delta
}
entry
}
/// THE BUNDLE ENTRY POINT (ADR-0030) — called by a bundle target's template
/// (`exports/<target>.typ` under a `bundle.toml` root) to assemble several
/// already-loaded lessons into one combined document.
///
/// - `info`: the bundle's own `[info]` (title/author of the 合集).
/// - `lessons`: ordered array of `(info: .., target: .., outline: ..)` dicts —
/// one per `bundle.toml` `lessons` entry, each ALREADY ASSEMBLED exactly as
/// a single-lesson template would assemble it for [`render-lesson`].
/// - `heading-numbering`: shared per-level numbering scheme across the whole
/// bundle (ADR-0011 presentation-in-template stance; same knob as
/// `render-lesson`).
/// - `reset-counters`: whether `example`/`lemma` auto-counters reset at each
/// lesson boundary. **Default `true`** (ADR-0030's recommended default: a
/// lesson's internal "例题3" means that lesson's 例题3, so cross-lesson
/// continuation would silently break author references). Pass `false` for
/// a genuine "全书连续编号" 合集.
///
/// Each lesson's own outline is rendered under a depth-1 heading naming that
/// lesson (`lesson.info.title`); the lesson's own section headings shift one
/// level deeper (ADR-0029's per-lesson depths are relative to that lesson, so
/// nesting under the lesson-title heading keeps the outline↔structure
/// correspondence meaningful in the combined document). `@label`/`@ref`
/// cross-references stay global across the whole compiled document (typst's
/// ordinary behavior) regardless of `reset-counters`.
#let render-bundle(
info: (:),
lessons: (),
heading-numbering: default-heading-numbering,
reset-counters: true,
) = {
let title = info.at("title", default: [])
let author = info.at("author", default: none)
set document(
title: title,
author: if author == none { () } else { author },
)
show: base-style.with(heading-numbering: heading-numbering)
title-block()
v(1.2em, weak: true)
for lesson in lessons {
if reset-counters {
example-counter.update(0)
lemma-counter.update(0)
}
let flags = _flags-for(lesson.at("target", default: "student"))
let lesson-info = lesson.at("info", default: (:))
heading(level: 1)[#lesson-info.at("title", default: [])]
for entry in lesson.at("outline", default: ()) {
_render-entry(_shift-depth(entry, 1), flags)
}
}
}