bai/curriculum-project-hub
1
0
Fork 1
forked from EduCraft/curriculum-project-hub
Code Pull Requests Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
crates/cph-typst/src/manifest.rs
+155 -34
View File
@@ -1,18 +1,28 @@
//! Augmented-manifest construction (ADR-0011).
//! Augmented-manifest construction (ADR-0011, outline shape per ADR-0029).
//!
//! The template (`exports/<target>.typ`) reads the manifest via
//! `toml(sys.inputs.manifest)`, then for each part `include`s its content fields
//! by a **computed** path and reads scalar fields from `<path>/element.toml`.
//! For *optional* content fields the template must know whether the file exists
//! on disk — typst has no file-exists primitive and a missing `include` is a
//! hard error (see the OPEN contract point in `render/templates/student.typ`).
//! `toml(sys.inputs.manifest)`, then for each **element** outline entry
//! `include`s its content fields by a **computed** path and reads scalar
//! fields from `<path>/element.toml`. For *optional* content fields the
//! template must know whether the file exists on disk — typst has no
//! file-exists primitive and a missing `include` is a hard error (see the OPEN
//! contract point in `render/templates/student.typ`).
//!
//! The ENGINE has filesystem access, so it closes that gap: it builds an
//! **augmented manifest** = the lesson's `[info]` + ordered `[[parts]]`, with a
//! per-part **`fields` array** listing the content fields whose `<field>.typ`
//! actually exists under the lesson root. The augmented manifest is served as an
//! in-memory virtual file in the [`crate::world::LessonWorld`] (it is **never**
//! written to the user's tree), and injected via `sys.inputs.manifest`.
//! **augmented manifest** = the lesson's `[info]` + the ordered `[[outline]]`
//! (ADR-0029's depth-first rendering order — elements interleaved with section
//! headings at their DFS-open position). Each `[[outline]]` entry carries a
//! `type` discriminator (`"element"` | `"section"`):
//!
//! - `type = "element"`: `kind`, `path`, and a per-part **`fields` array**
//! listing the content fields whose `<field>.typ` actually exists under the
//! lesson root (same contract as before ADR-0029).
//! - `type = "section"`: `kind`, `title`, `depth`, `path` — a section heading;
//! the template renders it without touching any content file.
//!
//! The augmented manifest is served as an in-memory virtual file in the
//! [`crate::world::LessonWorld`] (it is **never** written to the user's tree),
//! and injected via `sys.inputs.manifest`.
//!
//! ## `fields` is computed from `cph-schema`
//!
@@ -20,23 +30,104 @@
//! ([`cph_schema::KindSchema::content_field_names`]) — the same knowledge the
//! render package exposes as `part-fields`. We reuse it here rather than
//! re-deriving a kind→fields map, so the engine and the template agree on what a
//! kind's content fields are. For each part, a content field is listed in
//! kind's content fields are. For each element, a content field is listed in
//! `fields` iff `<root>/<part.path>/<field>.typ` is a real file.
use cph_model::Lesson;
use std::path::Path;
use cph_model::{Bundle, BundleLesson, Lesson, OutlineEntry};
/// Build the augmented-manifest TOML source for `lesson`.
///
/// The result is a self-contained TOML document the template's
/// `toml(sys.inputs.manifest)` reads. It carries `[info]` (title + optional
/// author) and the ordered `[[parts]]`, each with `kind`, `path`, and a
/// `fields = [...]` array of the content fields present on disk (per
/// [`present_fields`]). It does **not** reproduce `[project]` or `[targets.*]`
/// — the template only consumes `info` and `parts`.
/// author) and the ordered `[[outline]]` (ADR-0029's depth-first rendering
/// order), each entry typed `"element"` or `"section"` per the module docs. It
/// does **not** reproduce `[project]` or `[targets.*]` — the template only
/// consumes `info` and `outline`.
pub fn build_augmented_manifest(lesson: &Lesson) -> String {
let mut doc = toml::Table::new();
// [info]
doc.insert("info".to_string(), toml::Value::Table(info_table(lesson)));
// [[outline]] — ADR-0029's depth-first rendering order: elements
// interleaved with section headings at their DFS-open position.
let outline: Vec<toml::Value> = lesson
.outline
.iter()
.map(|entry| toml::Value::Table(outline_entry_table(lesson, entry, None)))
.collect();
doc.insert("outline".to_string(), toml::Value::Array(outline));
toml::to_string(&doc).expect("augmented manifest serializes")
}
/// Build the augmented **bundle** manifest TOML source for `bundle` (ADR-0030).
///
/// The bundle template (`exports/<target>.typ` under the `bundle.toml` root)
/// reads it via `toml(sys.inputs.manifest)`. It carries `[info]` (the bundle's
/// own title/author) and the ordered `[[lessons]]`, each a
/// `(info, target, outline)` table — the same shape a single-lesson template
/// would assemble, except every outline entry's `path` is **prefixed with that
/// lesson's own bundle-root-relative directory** (`BundleLesson::path`), since
/// the bundle template's computed include paths resolve against the *bundle*
/// root, not each lesson's own root (ADR-0030: combination reads
/// already-authored lessons at export time; each lesson's `path` bookkeeping
/// stays correct because the prefix is applied only here, in the manifest the
/// template consumes — never inside a lesson's own authored content).
pub fn build_augmented_bundle_manifest(bundle: &Bundle) -> String {
let mut doc = toml::Table::new();
let mut info = toml::Table::new();
info.insert(
"title".to_string(),
toml::Value::String(bundle.info.title.clone()),
);
if !bundle.info.authors.is_empty() {
let authors = bundle
.info
.authors
.iter()
.cloned()
.map(toml::Value::String)
.collect();
info.insert("author".to_string(), toml::Value::Array(authors));
}
doc.insert("info".to_string(), toml::Value::Table(info));
let lessons: Vec<toml::Value> = bundle
.lessons
.iter()
.map(|bl| toml::Value::Table(bundle_lesson_table(bl)))
.collect();
doc.insert("lessons".to_string(), toml::Value::Array(lessons));
toml::to_string(&doc).expect("augmented bundle manifest serializes")
}
/// Build one `[[lessons]]` entry's table: that member lesson's own `info`,
/// its selected `target`, and its outline with every entry's `path` prefixed
/// by the lesson's bundle-relative directory.
fn bundle_lesson_table(bl: &BundleLesson) -> toml::Table {
let mut t = toml::Table::new();
t.insert(
"info".to_string(),
toml::Value::Table(info_table(&bl.lesson)),
);
t.insert("target".to_string(), toml::Value::String(bl.target.clone()));
let outline: Vec<toml::Value> = bl
.lesson
.outline
.iter()
.map(|entry| toml::Value::Table(outline_entry_table(&bl.lesson, entry, Some(&bl.path))))
.collect();
t.insert("outline".to_string(), toml::Value::Array(outline));
t
}
/// Build the `[info]` table shared by a single-lesson manifest and a bundle
/// member's `info` entry.
fn info_table(lesson: &Lesson) -> toml::Table {
let mut info = toml::Table::new();
info.insert(
"title".to_string(),
@@ -52,30 +143,60 @@ pub fn build_augmented_manifest(lesson: &Lesson) -> String {
.collect();
info.insert("author".to_string(), toml::Value::Array(authors));
}
doc.insert("info".to_string(), toml::Value::Table(info));
info
}
// [[parts]] — preserve declared order; attach the on-disk `fields` array.
let parts: Vec<toml::Value> = lesson
.parts
.iter()
.map(|part| {
let mut entry = toml::Table::new();
entry.insert("kind".to_string(), toml::Value::String(part.kind.clone()));
entry.insert(
/// Build one `[[outline]]` entry's table for either variant of
/// [`OutlineEntry`]. `bundle_prefix`, when set (ADR-0030's bundle case), is
/// joined onto the emitted `path` so the bundle template's computed include
/// resolves against the bundle root rather than the lesson's own root.
fn outline_entry_table(
lesson: &Lesson,
entry: &OutlineEntry,
bundle_prefix: Option<&Path>,
) -> toml::Table {
let mut e = toml::Table::new();
match entry {
OutlineEntry::Element { part_index } => {
let part = &lesson.parts[*part_index];
e.insert("type".to_string(), toml::Value::String("element".into()));
e.insert("kind".to_string(), toml::Value::String(part.kind.clone()));
e.insert(
"path".to_string(),
toml::Value::String(path_to_forward_slash(&part.path)),
toml::Value::String(prefixed_forward_slash(bundle_prefix, &part.path)),
);
let fields = present_fields(lesson, part)
.into_iter()
.map(toml::Value::String)
.collect();
entry.insert("fields".to_string(), toml::Value::Array(fields));
toml::Value::Table(entry)
})
.collect();
doc.insert("parts".to_string(), toml::Value::Array(parts));
e.insert("fields".to_string(), toml::Value::Array(fields));
}
OutlineEntry::Section {
kind,
title,
depth,
path,
} => {
e.insert("type".to_string(), toml::Value::String("section".into()));
e.insert("kind".to_string(), toml::Value::String(kind.clone()));
e.insert("title".to_string(), toml::Value::String(title.clone()));
e.insert("depth".to_string(), toml::Value::Integer(i64::from(*depth)));
e.insert(
"path".to_string(),
toml::Value::String(prefixed_forward_slash(bundle_prefix, path)),
);
}
}
e
}
toml::to_string(&doc).expect("augmented manifest serializes")
/// [`path_to_forward_slash`], with `prefix` (a bundle member's own
/// bundle-relative directory) joined in front when present.
fn prefixed_forward_slash(prefix: Option<&Path>, path: &Path) -> String {
match prefix {
Some(p) => path_to_forward_slash(&p.join(path)),
None => path_to_forward_slash(path),
}
}
/// The content fields of `part`'s kind whose `<root>/<part.path>/<field>.typ`