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
+23 -11
View File
@@ -1,4 +1,4 @@
# Default export templates (ADR-0011)
# Default export templates (ADR-0011, outline shape ADR-0029)
`student.typ` / `teacher.typ` are the **framework default templates**. In a real
engineering file they live at `exports/student.typ` / `exports/teacher.typ`; the
@@ -9,11 +9,16 @@ offline smoke test below.
Each template:
1. reads the injected manifest: `toml(sys.inputs.manifest)`;
2. loops `manifest.parts`, `include`-ing each content field via a computed
**root-relative absolute** path `/<part.path>/<field>.typ`, and reading scalar
fields (example `source`) from `/<part.path>/element.toml`;
3. assembles a `parts` array and calls `cph-render`'s `render-lesson(...)`,
passing the per-level heading numbering (presentation lives in the template).
2. loops `manifest.outline` (ADR-0029's depth-first rendering order — elements
interleaved with section headings at their DFS-open position). For an
`type = "element"` entry: `include`-ing each content field via a computed
**root-relative absolute** path `/<part.path>/<field>.typ`, and reading
scalar fields (example `source`) from `/<part.path>/element.toml`. For a
`type = "section"` entry: passing its `title`/`depth` straight through — no
content to load, it is a heading;
3. assembles an `outline` array of entry dicts and calls `cph-render`'s
`render-lesson(...)`, passing the per-level heading numbering (presentation
lives in the template).
## Why the include loop is in the template, not in cph-render
@@ -23,7 +28,7 @@ root**. A dynamic `include` written inside the package resolves against the
*package* dir — even an absolute `/segments/x.typ` — never the engineering
`--root`. Verified empirically. The template lives under `--root`, so its
`/<part.path>/<field>.typ` resolves against `--root`. Hence the template loads
content and hands `render-lesson` an already-assembled `parts` array;
content and hands `render-lesson` an already-assembled `outline` array;
`render-lesson` never includes anything.
## Key path facts for the engine
@@ -36,9 +41,13 @@ content and hands `render-lesson` an already-assembled `parts` array;
relative to the *template's* location (`exports/`), so a bare
`manifest=manifest.toml` would look in `exports/`. Pass the leading `/`.
- **Optional content presence** (lemma `proof`): typst has no file-exists
primitive, so the template cannot probe disk. It reads a per-part `fields`
array from the manifest listing the content fields present on disk. *(OPEN: the
exact manifest shape for this is for the Rust/manifest contract to pin.)*
primitive, so the template cannot probe disk. It reads a per-element
`fields` array from the manifest listing the content fields present on
disk. *(OPEN: the exact manifest shape for this is for the Rust/manifest
contract to pin.)*
- **Sections carry no content fields.** A `type = "section"` outline entry
(ADR-0029) has only `kind`/`title`/`depth`/`path`; the template passes it
through untouched — no `include`, no `element.toml` read.
## Offline smoke test
@@ -60,4 +69,7 @@ typst compile --root examples/smoke-eng \
```
(`examples/smoke-eng/exports/{student,teacher}.typ` are copies of the defaults
here, mirroring how a real engineering file carries its own templates.)
here, mirroring how a real engineering file carries its own templates. The
`examples/smoke-eng/manifest.toml` is hand-authored directly in the augmented
`[[outline]]` shape that `cph_typst::build_augmented_manifest` would otherwise
produce, since this smoke test bypasses the Rust engine entirely.)