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

feat(checker): compile template as main, augmented manifest closes optional-content (WU-D', ADR-0011)

Browse Source 
Replace generated-driver compilation with the template model.

cph-typst:
- driver.rs DELETED (generate_driver, static-include driver, numbering-threading).
- New manifest.rs: build_augmented_manifest(&Lesson) emits a TOML doc with [info]
  + ordered [[parts]] each carrying a `fields` array = the kind's content fields
  whose <root>/<path>/<field>.typ exists on disk. Reuses cph-schema's
  content_field_names (new dep; no cycle). This closes the OPEN point WU-C'
  surfaced: typst has no file-exists primitive, so the engine (which has disk
  access) tells the template which optional content (lemma proof) is present.
- World main = the real engineering-file template (<root>/<template>); the
  augmented manifest is served as an in-memory virtual file at /.cph/manifest.toml
  (never written to the tree), injected via sys.inputs.manifest. render_dir kept
  only for @local/cph-render + vendored @preview/numbly resolution.
- Artifact handling: SingleFile+TypstCompile compiles; FileTree, shell-only, and
  undeclared-target are blocking "deferred/not-declared" diagnostics (ADR-0011).
- Engine public signatures unchanged; LessonWorld::new takes template+manifest_src.

cph-check: no source change needed (only uses lesson.targets/target.name +
unchanged Engine methods); pipeline + Legal alignment intact.

Fixtures: mini gets exports/{student,teacher}.typ (from render/templates/) + v2
manifest + a second proof-less lemma to exercise optional content. render-stub
retired (tests use the real render/). Through-template PDFs offline: student 44KB,
teacher 56KB; proof-less lemma compiles clean (optional-content confirmed).
Workspace: fmt + clippy -D warnings + all tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
李知远
2026-06-22 10:05:03 +08:00
parent 7e15cf34f6
commit d76f9f9a54
15 changed files with 705 additions and 573 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/cph-typst/src/diag.rs
+18 -8
View File
@@ -12,11 +12,13 @@
//! 3. compute 1-based line/col from the file's [`typst::syntax::Source`] via
//! `lines().byte_to_line_column` (0-based ⇒ `+1`).
//!
//! A span whose `FileId` is the generated **driver** is re-pointed: its `file`
//! is set to the driver vpath and a hint flags it as driver-internal (a
//! driver-gen bug indicator) rather than dropped or mis-attributed to a user
//! file. Spans in the `cph-render` package are reported with an
//! `@local/cph-render:…` pseudo-path.
//! The `main` file is now the real **template** (`exports/<target>.typ`), so a
//! span there resolves naturally to an authored file — no re-pointing needed. A
//! span landing in the **virtual augmented manifest** ([`crate::MANIFEST_VPATH`],
//! served in-memory, not on disk) is reported with its vpath plus a hint marking
//! it as the framework-synthesized manifest (a manifest-generation bug
//! indicator) rather than mis-attributed to a user file. Spans in the
//! `cph-render` package are reported with an `@local/cph-render:…` pseudo-path.
use std::path::PathBuf;
@@ -55,10 +57,11 @@ pub fn map_diagnostic(world: &LessonWorld, d: &SourceDiagnostic) -> Diagnostic {
if let Some(id) = d.span.id() {
if let Some(file) = file_for(world, id) {
if id == world.main() {
if is_virtual_manifest(id) {
hints.push(
"this span is inside the generated driver (.cph/driver-*.typ), \
not a lesson source file — likely a driver-generation issue"
"this span is inside the framework-synthesized manifest \
(/.cph/manifest.toml), not a lesson source file — likely a \
manifest-generation issue"
.to_string(),
);
}
@@ -80,6 +83,13 @@ pub fn map_diagnostic(world: &LessonWorld, d: &SourceDiagnostic) -> Diagnostic {
diag
}
/// Whether `id` is the in-memory augmented-manifest virtual file
/// ([`crate::MANIFEST_VPATH`]) the engine injects (not a real lesson file).
fn is_virtual_manifest(id: FileId) -> bool {
matches!(id.root(), VirtualRoot::Project)
&& id.vpath().get_with_slash() == crate::MANIFEST_VPATH
}
/// 1-based (line, col) for a byte offset in file `id`, defaulting to `(1, 1)`
/// when the source can't be read or the offset is out of range.
fn line_col(world: &LessonWorld, id: FileId, byte: usize) -> (u32, u32) {
crates/cph-typst/src/driver.rs
-235
View File
@@ -1,235 +0,0 @@
//! Driver generation: turn a [`Lesson`] + target into a typst entrypoint that
//! `include`s each part's content files and calls `cph-render`'s `display`.
//!
//! ## Decisions
//!
//! - **Include-path style: root-relative (`/segments/…`).** The lesson root is
//! mounted as the typst project root ([`crate::world::LessonWorld`] uses
//! `VirtualRoot::Project`), so a leading-`/` path resolves against the root
//! regardless of where the driver itself sits. This keeps include paths
//! identical to the part `path`s recorded in the manifest, independent of the
//! driver's `.cph/` location.
//! - **Content via `include`, not `import`** (ADR-0006): a `content` field's
//! value is the module *body*, which `include` yields (`import` would expose
//! only `#let` exports).
//! - **`@local/cph-render`** is referenced by the standard package import; the
//! World resolves it from the render directory (see `crate::world`).
//! - **Optional `proof`** (lemma) is emitted only when `<part.dir>/proof.typ`
//! exists on disk.
//! - **Scalars** (example `source`) come from `part.descriptor.scalars` and are
//! emitted as escaped typst string literals.
use cph_model::{Lesson, Part};
/// Locate the [`cph_model::TargetConfig`] for `target` by name, if declared.
fn target_config<'a>(lesson: &'a Lesson, target: &str) -> Option<&'a cph_model::TargetConfig> {
lesson.targets.iter().find(|t| t.name == target)
}
/// In-memory directory the generated driver is mounted under (relative to the
/// lesson root). Not written to disk.
pub const DRIVER_DIR: &str = ".cph";
/// The package import line the driver opens with.
const RENDER_IMPORT: &str = "#import \"@local/cph-render:0.1.0\": display";
/// The content fields of each kind, in render-contract order. The `bool` is
/// whether the field is optional (only emitted if its `<field>.typ` exists).
fn content_fields(kind: &str) -> &'static [(&'static str, bool)] {
match kind {
"segment" => &[("textbook", false)],
"example" => &[("problem", false), ("solution", false)],
"lemma" => &[("stmt", false), ("proof", true)],
"sop" => &[("sop", false)],
// Unknown kind: emit nothing for it; the render package surfaces the
// unknown kind visibly, and cph-model/cph-schema report it upstream.
_ => &[],
}
}
/// The optional **scalar** string fields per kind (read from `element.toml`).
fn scalar_fields(kind: &str) -> &'static [&'static str] {
match kind {
"example" => &["source"],
_ => &[],
}
}
/// Generate the driver source for `lesson` under `target`.
///
/// The result is deterministic and order-preserving (parts emitted in
/// `lesson.parts` order, matching the render contract). It is pure text
/// generation — it touches the filesystem only to test for optional content
/// files (e.g. lemma `proof.typ`).
pub fn generate_driver(lesson: &Lesson, target: &str) -> String {
let mut s = String::new();
s.push_str(RENDER_IMPORT);
s.push('\n');
// One `#let _pN_field = include "…"` per content file, then the parts array
// referencing those bindings.
let mut part_dicts: Vec<String> = Vec::with_capacity(lesson.parts.len());
for (i, part) in lesson.parts.iter().enumerate() {
let mut entries: Vec<String> = Vec::new();
entries.push(format!("kind: {}", typst_str(&part.kind)));
for &(field, optional) in content_fields(&part.kind) {
if optional && !content_file_exists(part, field) {
continue;
}
let binding = format!("_p{i}_{field}");
let inc_path = include_path(part, field);
s.push_str(&format!(
"#let {binding} = include {}\n",
typst_str(&inc_path)
));
entries.push(format!("{field}: {binding}"));
}
for &field in scalar_fields(&part.kind) {
if let Some(value) = scalar_string(part, field) {
entries.push(format!("{field}: {}", typst_str(&value)));
}
}
part_dicts.push(format!("({})", entries.join(", ")));
}
s.push_str("#display(\n");
s.push_str(&format!(" info: {},\n", info_dict(lesson)));
s.push_str(&format!(" target: {},\n", typst_str(target)));
s.push_str(" parts: (\n");
for dict in &part_dicts {
s.push_str(&format!(" {dict},\n"));
}
// Trailing comma already present per element; ensure a 1-element array is
// still an array (typst needs the trailing comma, which we always emit).
s.push_str(" ),\n");
s.push_str(&format!(" config: {},\n", config_dict(lesson, target)));
s.push_str(")\n");
s
}
/// The `config:` dict for `target` (ADR-0009 presentation overrides).
///
/// Looks up the matching [`cph_model::TargetConfig`] by name and emits the
/// file-resident presentation slice the render package understands. For MVP
/// that is `numbering.heading` (an array of numbly pattern strings):
/// `config: (numbering: (heading: ("…", "…")))`. When the target declares no
/// `numbering.heading` override (or the target isn't declared at all), an empty
/// dict `(:)` is emitted so the render package applies its own correct default.
fn config_dict(lesson: &Lesson, target: &str) -> String {
let heading = target_config(lesson, target)
.and_then(|tc| tc.numbering.as_ref())
.and_then(|n| n.heading.as_ref());
match heading {
Some(patterns) => {
let arr = patterns
.iter()
.map(|p| typst_str(p))
.collect::<Vec<_>>()
.join(", ");
// A 1-element typst array needs a trailing comma; always emitting
// one keeps any arity a valid array.
format!("(numbering: (heading: ({arr},)))")
}
None => "(:)".to_string(),
}
}
/// `(title: "…", author: "…")` — author key omitted when absent.
fn info_dict(lesson: &Lesson) -> String {
let mut parts = vec![format!("title: {}", typst_str(&lesson.info.title))];
if let Some(author) = &lesson.info.author {
parts.push(format!("author: {}", typst_str(author)));
}
format!("({})", parts.join(", "))
}
/// Root-relative include path for `part`'s `field` content file, e.g.
/// `/segments/开场对照导言/textbook.typ`. Always forward-slashed and
/// leading-`/` so it resolves against the typst project root.
fn include_path(part: &Part, field: &str) -> String {
let mut p = String::from("/");
// `part.path` is the manifest-relative folder; join the `<field>.typ`.
p.push_str(&path_to_forward_slash(&part.path));
if !p.ends_with('/') {
p.push('/');
}
p.push_str(field);
p.push_str(".typ");
p
}
/// Does `<part.dir>/<field>.typ` exist on disk? Used to gate optional content.
fn content_file_exists(part: &Part, field: &str) -> bool {
part.descriptor.dir.join(format!("{field}.typ")).is_file()
}
/// Pull a scalar string field out of the element descriptor, if present and a
/// string (and non-empty).
fn scalar_string(part: &Part, field: &str) -> Option<String> {
match part.descriptor.scalars.get(field) {
Some(toml::Value::String(s)) if !s.is_empty() => Some(s.clone()),
_ => None,
}
}
/// Render a `PathBuf` (folder) as a forward-slash string, dropping any leading
/// `./` or `/`. Element folder names are UTF-8 (Chinese) and kept verbatim.
fn path_to_forward_slash(path: &std::path::Path) -> String {
use std::path::Component;
let mut out = String::new();
for comp in path.components() {
// Only `Normal` segments contribute; RootDir / CurDir / Prefix /
// ParentDir are ignored. `..` is already rejected by cph-model's loader,
// and the part path is relative.
if let Component::Normal(s) = comp {
if !out.is_empty() {
out.push('/');
}
out.push_str(&s.to_string_lossy());
}
}
out
}
/// Quote `value` as a typst string literal, escaping `\` and `"`. Unicode is
/// passed through as UTF-8 (typst sources are UTF-8). Control chars that would
/// break a single-line literal (newline, CR, tab) are escaped too.
fn typst_str(value: &str) -> String {
let mut out = String::with_capacity(value.len() + 2);
out.push('"');
for c in value.chars() {
match c {
'\\' => out.push_str("\\\\"),
'"' => out.push_str("\\\""),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
_ => out.push(c),
}
}
out.push('"');
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn escapes_quotes_and_backslashes() {
assert_eq!(typst_str(r#"a"b\c"#), r#""a\"b\\c""#);
// Unicode passes through.
assert_eq!(typst_str("自拟"), "\"自拟\"");
}
#[test]
fn forward_slash_path_keeps_unicode() {
let p = std::path::Path::new("segments/开场对照导言");
assert_eq!(path_to_forward_slash(p), "segments/开场对照导言");
}
}
crates/cph-typst/src/lib.rs
+125 -68
View File
@@ -1,16 +1,32 @@
//! `cph-typst` — typst `World`, driver generation, compile, PDF, span mapping.
//! `cph-typst` — typst `World`, augmented-manifest injection, compile, PDF,
//! span mapping.
//!
//! Owned by **WU-4**. Embeds the typst 0.15 compiler as a library to:
//! - **compile-check** a [`cph_model::Lesson`] (collect typst errors+warnings as
//! [`cph_diag::Diagnostic`]s), and
//! - **compile-check** a [`cph_model::Lesson`] for a target (collect typst
//! errors+warnings as [`cph_diag::Diagnostic`]s), and
//! - **export a PDF** for a render target.
//!
//! The lesson's engineering-file directory tree (ADR-0007) is mounted as the
//! typst project root; a generated *driver* entrypoint (one per target) lives
//! in-memory under `.cph/driver-<target>.typ` and `include`s each part's
//! content files (ADR-0006: a `content` value denotes the module **body**, so
//! the driver uses `include`, never `import`). The driver hands an ordered
//! `parts` array to the `@local/cph-render` package's `display` entry.
//! ## Model (ADR-0011): compile a template, inject a manifest
//!
//! There is **no framework-generated driver** any more. An export target is a
//! build with a typed [`cph_model::Step::TypstCompile`] naming a **template
//! file** (e.g. `exports/student.typ`) that lives in the engineering file. The
//! engine:
//!
//! 1. mounts the lesson's engineering-file tree (ADR-0007) as the typst project
//! root (`--root`);
//! 2. sets the World's `main` to that **real template file** under the root, so
//! diagnostic spans resolve to an authored file;
//! 3. builds an **augmented manifest** (the lesson's `info` + ordered `parts`,
//! each with a `fields` array of the content fields present on disk — see
//! [`manifest`]) and serves it as a virtual in-memory file at
//! [`world::MANIFEST_VPATH`], injecting `sys.inputs.manifest` to point there;
//! 4. lets the template `toml()`-read that manifest and `include` each part's
//! content via computed root-relative paths (legal per ADR-0011).
//!
//! The augmented manifest closes the OPEN optional-content point: typst has no
//! file-exists primitive, so the engine (which has filesystem access) tells the
//! template which optional content fields exist via the per-part `fields` array.
//!
//! ## typst version
//!
@@ -19,25 +35,31 @@
//! VirtualPath)`, and a diagnostic span is a `DiagSpan` (not a bare `Span`).
mod diag;
mod driver;
mod manifest;
mod world;
use std::path::PathBuf;
use cph_diag::{DiagCode, Diagnostic};
use cph_model::{ArtifactKind, Lesson};
use cph_model::{Artifact, Lesson, Step, TargetConfig};
use typst_kit::fonts::{self, FontStore};
use typst_layout::PagedDocument;
use typst_pdf::PdfOptions;
pub use driver::{generate_driver, DRIVER_DIR};
pub use world::{render_package_spec, LessonWorld};
pub use manifest::build_augmented_manifest;
pub use world::{render_package_spec, LessonWorld, MANIFEST_VPATH};
/// The compile/PDF engine: holds the shared font store and the on-disk location
/// of the `cph-render` package.
///
/// Fonts are discovered once (system + embedded) and shared across every
/// compilation via an [`std::sync::Arc`] inside the per-compile [`LessonWorld`].
///
/// `render_dir` is the directory the World resolves `@local/cph-render` (and the
/// vendored `@preview/*`) from. It is **not** where the compiled template comes
/// from: the template is a real file under the lesson root (`<root>/<template>`),
/// found via the normal project-file mapping. `render_dir` only matters for
/// package resolution.
pub struct Engine {
fonts: std::sync::Arc<FontStore>,
render_dir: PathBuf,
@@ -45,15 +67,16 @@ pub struct Engine {
impl Engine {
/// Construct an engine, discovering system + embedded fonts. The render
/// package directory is taken from the `CPH_RENDER_DIR` environment
/// variable when set, otherwise defaults to `<repo>/render` resolved
/// relative to this crate (`CARGO_MANIFEST_DIR/../../render`).
/// package directory is taken from the `CPH_RENDER_DIR` environment variable
/// when set, otherwise defaults to `<repo>/render` resolved relative to this
/// crate (`CARGO_MANIFEST_DIR/../../render`).
pub fn new() -> Self {
Self::with_render_dir(default_render_dir())
}
/// Construct an engine pointing at an explicit `cph-render` package
/// directory (the folder containing `lib.typ` / `typst.toml`).
/// directory (the folder containing `lib.typ` / `typst.toml`, and the
/// vendored `@preview/*` tree under `vendor/`).
pub fn with_render_dir(render_dir: PathBuf) -> Self {
let mut store = FontStore::new();
// System fonts first (so the host's CJK fonts are preferred), then the
@@ -74,14 +97,17 @@ impl Engine {
/// Compile-check `lesson` for `target`, returning every typst diagnostic
/// (errors **and** warnings) mapped to [`Diagnostic`]s. An empty `Vec` means
/// a clean compile. Spans are resolved to files relative to `lesson.root`;
/// spans landing in the generated driver are re-pointed with a hint marking
/// them as driver-internal (a driver-gen bug indicator) rather than dropped.
/// a clean compile. Spans are resolved to files relative to `lesson.root`.
///
/// A request the engine cannot honor (unknown target, or an MVP-unsupported
/// artifact/step shape) short-circuits to a single blocking diagnostic; see
/// [`target_precheck`].
pub fn compile_check(&self, lesson: &Lesson, target: &str) -> Vec<Diagnostic> {
if let Some(blocking) = target_precheck(lesson, target) {
return blocking;
}
let world = self.world_for(lesson, target);
let template = match self.world_for(lesson, target) {
Ok(world) => world,
Err(blocking) => return blocking,
};
let world = template;
let warned = typst::compile::<PagedDocument>(&world);
let mut out = Vec::new();
@@ -93,13 +119,16 @@ impl Engine {
}
/// Build a PDF for `lesson` / `target`. On a clean compile returns the PDF
/// bytes; on fatal errors returns the mapped diagnostics. Compile warnings
/// are not surfaced here (use [`Engine::compile_check`] for those).
/// bytes; on a blocking precheck failure or fatal compile errors returns the
/// mapped diagnostics. Compile warnings are not surfaced here (use
/// [`Engine::compile_check`] for those).
///
/// The bytes are returned, not written: for a [`Artifact::SingleFile`] the
/// artifact's `filepath` is the *default* output location, but the caller
/// (cph-check / the CLI) owns where the PDF lands (and may override with
/// `-o`).
pub fn build_pdf(&self, lesson: &Lesson, target: &str) -> Result<Vec<u8>, Vec<Diagnostic>> {
if let Some(blocking) = target_precheck(lesson, target) {
return Err(blocking);
}
let world = self.world_for(lesson, target);
let world = self.world_for(lesson, target)?;
let warned = typst::compile::<PagedDocument>(&world);
let doc = match warned.output {
Ok(doc) => doc,
@@ -108,15 +137,18 @@ impl Engine {
typst_pdf::pdf(&doc, &PdfOptions::default()).map_err(|errors| map_all(&world, &errors))
}
fn world_for(&self, lesson: &Lesson, target: &str) -> LessonWorld {
let driver_src = generate_driver(lesson, target);
LessonWorld::new(
/// Build the [`LessonWorld`] for `(lesson, target)`, or `Err(blocking)` when
/// the request cannot be honored (see [`target_precheck`]).
fn world_for(&self, lesson: &Lesson, target: &str) -> Result<LessonWorld, Vec<Diagnostic>> {
let template = target_precheck(lesson, target)?;
let manifest_src = build_augmented_manifest(lesson);
Ok(LessonWorld::new(
lesson.root.clone(),
self.render_dir.clone(),
target,
driver_src,
&template,
manifest_src,
self.fonts.clone(),
)
))
}
}
@@ -126,47 +158,72 @@ impl Default for Engine {
}
}
/// Validate a `(lesson, target)` request before compiling. Returns
/// `Some(blocking_diagnostics)` when the request cannot be honored, or `None`
/// when it is fine to proceed:
/// Validate a `(lesson, target)` request and resolve the template path to
/// compile. Returns `Ok(template_path)` (relative to the lesson root) when the
/// request is buildable, or `Err(blocking_diagnostics)` when it is not:
///
/// - **Unknown target** (the `--target` name isn't in `lesson.targets`): a
/// `SchemaViolation` error — a target must be declared in the manifest to be
/// built (ADR-0009: an export target is a declared build).
/// - **`FileTree` artifact**: deferred for MVP. ADR-0009 makes the artifact kind
/// decide assembly; only `SingleFile` (one bundled PDF) is implemented, so a
/// `FileTree` target returns a clear `SchemaViolation` rather than wrong
/// output. `SingleFile` proceeds to the normal one-PDF path.
///
/// A target with **no** declared `[targets.*]` config at all is *not* an error
/// here: callers (e.g. `cph-check`) may compile-check a defaulted `"student"`
/// target that the lesson never declared. Only a name that *is* declared but is
/// `FileTree` is blocked; an undeclared name is the "unknown target" error.
fn target_precheck(lesson: &Lesson, target: &str) -> Option<Vec<Diagnostic>> {
match lesson.targets.iter().find(|t| t.name == target) {
None if lesson.targets.is_empty() => {
/// - **Unknown target** (the `--target` name isn't in `lesson.targets`, and the
/// lesson declares at least one target): a `SchemaViolation` error — a target
/// must be declared in the manifest to be built (ADR-0009).
/// - **No declared targets at all**: not an error — callers (e.g. `cph-check`)
/// may compile-check a defaulted `"student"` target the lesson never declared.
/// The stock template path `exports/<target>.typ` is used (the framework
/// default; ADR-0011 [`cph_model::Step::default_for`]).
/// - **MVP-unsupported shape**: per ADR-0011 only a [`Artifact::SingleFile`] with
/// a [`Step::TypstCompile`] step is implemented this round. A
/// [`Artifact::FileTree`] artifact, or a target whose (only) step is a
/// [`Step::Shell`], returns a clear "not yet implemented" `SchemaViolation`
/// rather than wrong output. The template is taken from the **first**
/// `TypstCompile` step (MVP: one step per target).
fn target_precheck(lesson: &Lesson, target: &str) -> Result<PathBuf, Vec<Diagnostic>> {
let Some(tc) = lesson.targets.iter().find(|t| t.name == target) else {
if lesson.targets.is_empty() {
// Lesson declares no targets; the orchestrator compiles a defaulted
// target. Proceed with render-package defaults (SingleFile).
None
// target. Use the stock template path (matches cph-model's default).
return Ok(PathBuf::from(format!("exports/{target}.typ")));
}
None => Some(vec![Diagnostic::error(
return Err(vec![Diagnostic::error(
DiagCode::SchemaViolation,
format!("target '{target}' not declared in manifest"),
)
.with_hint(format!(
"add a `[targets.{target}]` table to manifest.toml, or build a declared target"
))]),
Some(tc) => match tc.artifact {
ArtifactKind::SingleFile => None,
ArtifactKind::FileTree => Some(vec![Diagnostic::error(
DiagCode::SchemaViolation,
"file-tree artifact not yet implemented (MVP supports single-file)",
)
.with_hint(format!(
"set `[targets.{target}].artifact` to \"single-file\" for now"
))]),
},
))]);
};
// MVP supports a single-file artifact only.
if let Artifact::FileTree { .. } = tc.artifact {
return Err(vec![Diagnostic::error(
DiagCode::SchemaViolation,
"file-tree artifact not yet implemented (MVP supports single-file typst-compile)",
)
.with_hint(format!(
"set `[targets.{target}].artifact` to a single-file artifact for now"
))]);
}
template_step(tc).ok_or_else(|| {
vec![Diagnostic::error(
DiagCode::SchemaViolation,
format!(
"target '{target}' has no typst-compile step; only single-file \
typst-compile builds are implemented (MVP)"
),
)
.with_hint(format!(
"add a `typst-compile` step with `template = \"exports/{target}.typ\"`, \
or defer this target (shell/file-tree builds are not yet implemented)"
))]
})
}
/// The template of the first [`Step::TypstCompile`] in `tc`, if any (MVP: a
/// target has one step; a `Shell`-only target yields `None`).
fn template_step(tc: &TargetConfig) -> Option<PathBuf> {
tc.steps.iter().find_map(|s| match s {
Step::TypstCompile { template } => Some(template.clone()),
Step::Shell { .. } => None,
})
}
/// Map a batch of typst diagnostics to `cph-diag` ones against `world`.
crates/cph-typst/src/manifest.rs
+124
View File
@@ -0,0 +1,124 @@
//! Augmented-manifest construction (ADR-0011).
//!
//! 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`).
//!
//! 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`.
//!
//! ## `fields` is computed from `cph-schema`
//!
//! `cph-schema` already encodes each kind's content fields
//! ([`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
//! `fields` iff `<root>/<part.path>/<field>.typ` is a real file.
use cph_model::Lesson;
/// 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`.
pub fn build_augmented_manifest(lesson: &Lesson) -> String {
let mut doc = toml::Table::new();
// [info]
let mut info = toml::Table::new();
info.insert(
"title".to_string(),
toml::Value::String(lesson.info.title.clone()),
);
if let Some(author) = &lesson.info.author {
info.insert("author".to_string(), toml::Value::String(author.clone()));
}
doc.insert("info".to_string(), toml::Value::Table(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(
"path".to_string(),
toml::Value::String(path_to_forward_slash(&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));
toml::to_string(&doc).expect("augmented manifest serializes")
}
/// The content fields of `part`'s kind whose `<root>/<part.path>/<field>.typ`
/// file exists on disk, in schema order.
///
/// The kind→content-fields knowledge is reused from `cph-schema`
/// ([`cph_schema::schema_for`]); an unknown kind has no schema and yields an
/// empty list (the render package surfaces an unknown kind on its own). Both
/// required and optional content fields are probed — listing a *required* field
/// here is harmless (the template includes required fields unconditionally), and
/// it keeps `fields` a faithful "what exists on disk" record.
fn present_fields(lesson: &Lesson, part: &cph_model::Part) -> Vec<String> {
let Some(schema) = cph_schema::schema_for(&part.kind) else {
return Vec::new();
};
let part_dir = lesson.root.join(&part.path);
schema
.content_field_names()
.into_iter()
.filter(|field| part_dir.join(format!("{field}.typ")).is_file())
.map(str::to_string)
.collect()
}
/// Render a relative `PathBuf` as a forward-slash string, dropping any leading
/// `./` or `/` and ignoring `..` (already rejected by the cph-model loader).
/// Element folder names are UTF-8 (e.g. Chinese) and kept verbatim. The template
/// rebuilds an absolute root-relative include path as `"/" + path + "/" + field`,
/// so `path` must be a clean relative slash path.
fn path_to_forward_slash(path: &std::path::Path) -> String {
use std::path::Component;
let mut out = String::new();
for comp in path.components() {
if let Component::Normal(s) = comp {
if !out.is_empty() {
out.push('/');
}
out.push_str(&s.to_string_lossy());
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn forward_slash_path_keeps_unicode() {
let p = std::path::Path::new("segments/开场对照导言");
assert_eq!(path_to_forward_slash(p), "segments/开场对照导言");
}
}
crates/cph-typst/src/world.rs
+90 -42
View File
@@ -1,36 +1,45 @@
//! [`LessonWorld`] — a typst [`World`] over an engineering-file directory tree
//! plus an in-memory generated driver and a disk-mounted `cph-render` package.
//! plus an in-memory augmented manifest and a disk-mounted `cph-render` package.
//!
//! ## Model (ADR-0011)
//!
//! The `main` file is the target's **template** (e.g. `<root>/exports/student.typ`),
//! a *real* file under the lesson root — no framework-generated driver. The
//! template `toml()`-reads an injected manifest and `include`s each part's
//! content via computed root-relative paths. The engine injects the manifest as
//! a virtual file (see below) and sets `sys.inputs.manifest` to its vpath.
//!
//! ## File resolution
//!
//! - **The driver** (`main()`): mounted in-memory at `VirtualRoot::Project` +
//! vpath `/.cph/driver-<target>.typ`. `source()` returns it from the field;
//! it is never written to disk. Its root-relative `include "/segments/…"`
//! paths therefore anchor at the lesson root.
//! - **Project files**: any `FileId` with `VirtualRoot::Project` is read from
//! `root.join(vpath.realize)`. Used for content `.typ`, images, `toml()`, etc.
//! - **`@local/cph-render`**: a `FileId` whose root is the render package spec
//! is read from `render_dir.join(vpath.realize)`. This avoids installing the
//! package into the typst local-package directory (MVP: no environment
//! coupling).
//! - **The template** (`main()`): a `FileId` with `VirtualRoot::Project` whose
//! vpath is the template's path under the lesson root (e.g. `/exports/student.typ`).
//! It is read from disk like any other project file; its `include "/<part>/…"`
//! paths anchor at the lesson root (`--root`).
//! - **The augmented manifest**: served in-memory at `VirtualRoot::Project` +
//! vpath [`MANIFEST_VPATH`] (`/.cph/manifest.toml`). It is **never** written to
//! disk — the engine builds it (original manifest + a per-part `fields` array)
//! and the template reads it via `toml(sys.inputs.manifest)`.
//! - **Project files**: any other `FileId` with `VirtualRoot::Project` is read
//! from `root.join(vpath.realize)`. Used for content `.typ`, images,
//! `element.toml` `toml()`, etc.
//! - **`@local/cph-render`**: a `FileId` whose root is the render package spec is
//! read from `render_dir.join(vpath.realize)`, avoiding installing the package
//! into the typst local-package directory.
//! - **`@preview/<name>:<version>`**: resolved offline from the in-repo vendored
//! preview tree at `<render_dir>/vendor/typst-packages/preview/<name>/<version>/`
//! (mirroring typst's preview-cache layout). The render package imports
//! `@preview/numbly:0.1.0` (per-level heading numbering); reading it from the
//! vendored dir keeps compilation network-free with no `typst-kit` package
//! download. This is general — any `@preview/*` resolves from the vendored
//! preview dir; numbly 0.1.0 is the only one currently present.
//! preview tree at `<render_dir>/vendor/typst-packages/preview/<name>/<version>/`.
//! The render package imports `@preview/numbly:0.1.0`; reading it from the
//! vendored dir keeps compilation network-free.
//! - Any *other* `@package` namespace yields a `NotFound` error.
//!
//! Sources are cached in a `Mutex<HashMap<FileId, Source>>` so repeated
//! accesses during one compilation are cheap, as the `World` contract expects.
//! Sources are cached in a `Mutex<HashMap<FileId, Source>>` so repeated accesses
//! during one compilation are cheap, as the `World` contract expects.
use std::collections::HashMap;
use std::path::PathBuf;
use std::path::{Component, Path, PathBuf};
use std::sync::{Arc, Mutex};
use typst::diag::{FileError, FileResult};
use typst::foundations::{Bytes, Datetime, Duration};
use typst::foundations::{Bytes, Datetime, Dict, Duration, Value};
use typst::syntax::package::{PackageSpec, PackageVersion};
use typst::syntax::{FileId, RootedPath, Source, VirtualPath, VirtualRoot};
use typst::text::{Font, FontBook};
@@ -38,9 +47,15 @@ use typst::utils::LazyHash;
use typst::{Library, LibraryExt, World};
use typst_kit::fonts::FontStore;
use crate::driver::DRIVER_DIR;
/// Root-relative vpath the augmented manifest is served at (in-memory only).
///
/// A **leading slash** is essential: the template lives under `exports/`, and
/// `toml(sys.inputs.manifest)` resolves a relative path against the template's
/// own directory — a bare name would miss. A root-relative absolute path anchors
/// at `--root` (the lesson root) regardless of where the template sits.
pub const MANIFEST_VPATH: &str = "/.cph/manifest.toml";
/// The package spec the driver imports and the World mounts from `render_dir`.
/// The package spec the template imports and the World mounts from `render_dir`.
pub fn render_package_spec() -> PackageSpec {
PackageSpec {
namespace: "local".into(),
@@ -61,11 +76,13 @@ pub struct LessonWorld {
render_dir: PathBuf,
/// The render package spec (`@local/cph-render:0.1.0`).
render_spec: PackageSpec,
/// FileId of the in-memory driver entrypoint.
/// FileId of the template entrypoint (a real file under `root`).
main: FileId,
/// The driver source, parsed once.
driver_source: Source,
/// Standard library (default configuration).
/// FileId of the in-memory augmented manifest.
manifest_id: FileId,
/// The augmented-manifest source (in-memory; never on disk).
manifest_source: Source,
/// Standard library, with `sys.inputs.manifest` set.
library: LazyHash<Library>,
/// Shared font store (book + lazily-loaded fonts).
fonts: Arc<FontStore>,
@@ -74,27 +91,42 @@ pub struct LessonWorld {
}
impl LessonWorld {
/// Build a world. `driver_src` is the generated entrypoint text; it is
/// mounted in-memory at `/.cph/driver-<target>.typ` under the project root.
/// Build a world whose `main` is the template at `<root>/<template>` and
/// whose injected manifest is `manifest_src` (served virtually at
/// [`MANIFEST_VPATH`], with `sys.inputs.manifest` pointing there).
///
/// `template` is the lesson-root-relative template path (e.g.
/// `exports/student.typ`), taken from the target's `Step::TypstCompile`.
pub fn new(
root: PathBuf,
render_dir: PathBuf,
target: &str,
driver_src: String,
template: &Path,
manifest_src: String,
fonts: Arc<FontStore>,
) -> Self {
let driver_vpath = VirtualPath::new(format!("/{DRIVER_DIR}/driver-{target}.typ"))
.expect("driver vpath is a valid virtual path");
let main = FileId::new(RootedPath::new(VirtualRoot::Project, driver_vpath));
let driver_source = Source::new(main, driver_src);
let main_vpath = VirtualPath::new(format!("/{}", path_to_forward_slash(template)))
.expect("template vpath is a valid virtual path");
let main = FileId::new(RootedPath::new(VirtualRoot::Project, main_vpath));
let manifest_vpath =
VirtualPath::new(MANIFEST_VPATH).expect("manifest vpath is a valid virtual path");
let manifest_id = FileId::new(RootedPath::new(VirtualRoot::Project, manifest_vpath));
let manifest_source = Source::new(manifest_id, manifest_src);
// Inject `sys.inputs.manifest = "/.cph/manifest.toml"` so the template's
// `toml(sys.inputs.manifest)` reads the augmented manifest.
let mut inputs = Dict::new();
inputs.insert("manifest".into(), Value::Str(MANIFEST_VPATH.into()));
let library = Library::builder().with_inputs(inputs).build();
Self {
root,
render_dir,
render_spec: render_package_spec(),
main,
driver_source,
library: LazyHash::new(Library::default()),
manifest_id,
manifest_source,
library: LazyHash::new(library),
fonts,
sources: Mutex::new(HashMap::new()),
}
@@ -131,7 +163,8 @@ impl LessonWorld {
}
}
/// Read raw bytes for `id` from disk (driver excluded — handled by callers).
/// Read raw bytes for `id` from disk (virtual files excluded — handled by
/// callers).
fn read_bytes(&self, id: FileId) -> FileResult<Vec<u8>> {
let path = self.resolve(id)?;
std::fs::read(&path).map_err(|e| FileError::from_io(e, &path))
@@ -152,8 +185,8 @@ impl World for LessonWorld {
}
fn source(&self, id: FileId) -> FileResult<Source> {
if id == self.main {
return Ok(self.driver_source.clone());
if id == self.manifest_id {
return Ok(self.manifest_source.clone());
}
// Cache hit?
if let Some(src) = self.sources.lock().expect("sources mutex").get(&id) {
@@ -170,8 +203,8 @@ impl World for LessonWorld {
}
fn file(&self, id: FileId) -> FileResult<Bytes> {
if id == self.main {
return Ok(Bytes::from_string(self.driver_source.text().to_string()));
if id == self.manifest_id {
return Ok(Bytes::from_string(self.manifest_source.text().to_string()));
}
let bytes = self.read_bytes(id)?;
Ok(Bytes::new(bytes))
@@ -186,3 +219,18 @@ impl World for LessonWorld {
None
}
}
/// Render a relative `Path` as a forward-slash string, dropping any leading
/// `./` or `/` and ignoring `..`. UTF-8 segments kept verbatim.
fn path_to_forward_slash(path: &Path) -> String {
let mut out = String::new();
for comp in path.components() {
if let Component::Normal(s) = comp {
if !out.is_empty() {
out.push('/');
}
out.push_str(&s.to_string_lossy());
}
}
out
}