forked from EduCraft/curriculum-project-hub
1093 lines
42 KiB
Rust
1093 lines
42 KiB
Rust
//! `cph-model` — load the ADR-0008 declarative layout into an in-memory lesson.
|
|
//!
|
|
//! This crate is the **loader**, not the full checker. It reads
|
|
//! `<root>/manifest.toml` (project / info / ordered `[[parts]]` / declared
|
|
//! `[targets.*]`) and each part's `<root>/<path>/element.toml`, and produces an
|
|
//! ordered [`Lesson`] — mirroring the Lean master's `Lesson = List (Element P)`
|
|
//! (`spec/Spec/Courseware/Model/Lesson.lean`), where the order of `parts` carries
|
|
//! teaching semantics.
|
|
//!
|
|
//! Scope boundaries (deliberately staying in lane):
|
|
//! - It validates **structure** only: manifest shape, element.toml shape, and
|
|
//! the cross-check `part.kind == element.toml kind`.
|
|
//! - It does **not** validate instance data against a kind's JSON Schema (that
|
|
//! is WU-3 / `cph-schema`), does **not** check that `content` `.typ` files
|
|
//! exist (also schema-driven, WU-3), and does **not** compile typst (WU-4).
|
|
//!
|
|
//! Entry point: [`load`].
|
|
|
|
use std::path::{Component, Path, PathBuf};
|
|
|
|
use cph_diag::{DiagCode, Diagnostic};
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
/// An ordered, in-memory lesson loaded from an engineering file.
|
|
///
|
|
/// Mirrors the Lean master's `Lesson = List (Element P)`: `parts` is an ordered
|
|
/// `Vec`, and that order is the lesson's order (ADR-0008 §"the lesson manifest
|
|
/// is declarative" — the `[[parts]]` array order is the single source of truth).
|
|
#[derive(Debug, Clone, PartialEq, Serialize)]
|
|
pub struct Lesson {
|
|
/// `[project]` from the manifest (id, name).
|
|
pub project: Project,
|
|
/// `[info]` from the manifest (title, optional author).
|
|
pub info: Info,
|
|
/// The ordered parts — the lesson's element sequence.
|
|
pub parts: Vec<Part>,
|
|
/// Declared export targets, collected from the `[targets.<name>]` tables.
|
|
///
|
|
/// Per ADR-0009/0011 an export target is a *build* producing a typed
|
|
/// [`Artifact`] via an ordered list of typed [`Step`]s. This carries those
|
|
/// in declared (TOML document) order. See [`TargetConfig`].
|
|
pub targets: Vec<TargetConfig>,
|
|
/// Engineering-file root (absolute), for resolving part paths.
|
|
pub root: PathBuf,
|
|
}
|
|
|
|
impl Lesson {
|
|
/// The declared export-target names, in declared order.
|
|
///
|
|
/// Convenience for callers that only need the names (the shape this crate
|
|
/// exposed before ADR-0009 turned `targets` into structured
|
|
/// [`TargetConfig`]s).
|
|
pub fn target_names(&self) -> Vec<&str> {
|
|
self.targets.iter().map(|t| t.name.as_str()).collect()
|
|
}
|
|
}
|
|
|
|
/// One declared export target's build config (ADR-0009/0011).
|
|
///
|
|
/// An export target is a **build** producing a typed [`Artifact`] via an
|
|
/// **ordered** list of typed [`Step`]s. ADR-0011 fixed the *shape* of that
|
|
/// build: the artifact carries fields (where the product lands / which files it
|
|
/// is), and the build is a step list, each step a typed operation. Presentation
|
|
/// (heading numbering, styling) lives in the `typstCompile` template file, not
|
|
/// in the manifest — so there is no `numbering` field here anymore.
|
|
///
|
|
/// ## Defaults for a minimal manifest
|
|
///
|
|
/// - A target with **no `artifact`** key defaults to
|
|
/// [`Artifact::SingleFile`] with `filepath = "build/<name>.pdf"`, so an
|
|
/// almost-empty `[targets.student]` still produces a usable build.
|
|
/// - A target with **no `steps`** defaults to a single
|
|
/// [`Step::TypstCompile`] with `template = "exports/<name>.typ"` (the
|
|
/// framework's stock per-target template).
|
|
/// - A target with **no `covers`** key leaves [`TargetConfig::covers`] `None`,
|
|
/// meaning "coverage not declared". The consumer (`cph-check`) resolves that
|
|
/// to the full known-kind universe — see the field doc.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
pub struct TargetConfig {
|
|
/// Target name, e.g. `"student"` (the `[targets.<name>]` table key).
|
|
pub name: String,
|
|
/// The artifact this target produces. Defaults to a [`Artifact::SingleFile`]
|
|
/// at `build/<name>.pdf` when the `artifact` field is absent.
|
|
pub artifact: Artifact,
|
|
/// The ordered build steps. Defaults to a single [`Step::TypstCompile`]
|
|
/// with template `exports/<name>.typ` when no `[[steps]]` are given.
|
|
pub steps: Vec<Step>,
|
|
/// The **render-coverage declaration**: which element kinds this target
|
|
/// renders. Realizes `Spec.Courseware.TargetSpec.covers : KindId → Prop`
|
|
/// (`spec/Spec/Courseware/Export/Render.lean`) and ADR-0011's "render
|
|
/// coverage is a declaration, not a payload": the contract keeps *which
|
|
/// kinds a target renders* (used by the `renderIgnored` seed diagnostic),
|
|
/// while the rendering "how" lives in the template/steps.
|
|
///
|
|
/// `Some(kinds)` is the explicit manifest list (`covers = ["segment", …]`).
|
|
/// `None` means the `covers` key was **absent**; the loader does not own the
|
|
/// kind universe (it must not depend on `cph-schema`), so it records the
|
|
/// absence and lets `cph-check` default it to all known kinds. An empty
|
|
/// `Some(vec![])` is distinct: a target that explicitly covers nothing.
|
|
pub covers: Option<Vec<String>>,
|
|
}
|
|
|
|
/// The artifact an export target produces (ADR-0009/0011).
|
|
///
|
|
/// **Mirrors `Spec.Courseware.Artifact`** in the Lean semantic master
|
|
/// (`spec/Spec/Courseware/Export/Artifact.lean`), whose definition is exactly:
|
|
///
|
|
/// ```text
|
|
/// inductive Artifact where
|
|
/// | singleFile (filepath : String)
|
|
/// | fileTree (root : String) (outputs : String)
|
|
/// ```
|
|
///
|
|
/// ADR-0011 pinned the artifact as an ADT **with fields**: "what the product
|
|
/// is" — one file at some path vs. a tree of files under some root matching a
|
|
/// glob — is the non-obvious domain semantics that must be in the type, not
|
|
/// erased behind a bare tag. `SingleFile` is one bundled document (a 讲义 / 教案
|
|
/// PDF); `FileTree` is a tree of files (a third-party-platform archive). The
|
|
/// on-disk `artifact` inline table's `type` discriminator selects the variant:
|
|
/// `"single-file"` → [`Artifact::SingleFile`], `"file-tree"` →
|
|
/// [`Artifact::FileTree`].
|
|
///
|
|
/// As with `cph-diag`'s `Severity`, there is no CI gate enforcing this
|
|
/// alignment (see the repo constitution) — it is maintained by review, which is
|
|
/// why the correspondence is documented here.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
pub enum Artifact {
|
|
/// One bundled document landing at `filepath` (relative to the engineering
|
|
/// root). Mirrors Lean `Artifact.singleFile`. The default artifact shape.
|
|
SingleFile {
|
|
/// Where the single product is written (relative to the engineering
|
|
/// root), e.g. `build/student.pdf`.
|
|
filepath: PathBuf,
|
|
},
|
|
/// A set of files under `root` matching the `outputs` glob. Mirrors Lean
|
|
/// `Artifact.fileTree`.
|
|
FileTree {
|
|
/// The output directory (relative to the engineering root).
|
|
root: PathBuf,
|
|
/// A **glob** describing which files this build produces, e.g.
|
|
/// `**/*.{html,js,json}` — kept as a string (the contract pins the
|
|
/// field, not a path/glob algebra).
|
|
outputs: String,
|
|
},
|
|
}
|
|
|
|
impl Artifact {
|
|
/// The default artifact when `artifact` is omitted: a single file at
|
|
/// `build/<name>.pdf`.
|
|
fn default_for(name: &str) -> Artifact {
|
|
Artifact::SingleFile {
|
|
filepath: PathBuf::from(format!("build/{name}.pdf")),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// One typed build step (ADR-0011).
|
|
///
|
|
/// **Mirrors `Spec.Courseware.Step`** in the Lean semantic master
|
|
/// (`spec/Spec/Courseware/Export/Render.lean`), whose definition is exactly:
|
|
///
|
|
/// ```text
|
|
/// inductive Step where
|
|
/// | typstCompile (template : String)
|
|
/// | shell (run : String)
|
|
/// | assembleMarkdown (field : String)
|
|
/// ```
|
|
///
|
|
/// A step is a *typed* operation (extensible): `TypstCompile` compiles a
|
|
/// template file — typed, not a raw shell line, because the framework must wire
|
|
/// the manifest into it (`--input manifest=…`), which a bare `typst compile`
|
|
/// string cannot express. `Shell` is the escape hatch for steps that resist
|
|
/// declaration (ADR-0005's medium-only category (b): HTML interactive / npm
|
|
/// builds). `AssembleMarkdown` concatenates a per-element markdown content
|
|
/// field into a single-file markdown deliverable (ADR-0015: the slides outline
|
|
/// and 逐字稿 transcript surfaces, authored directly in markdown+KaTeX to
|
|
/// sidestep the typst→md conversion). The on-disk `[[steps]]` entry's `type`
|
|
/// discriminator selects the variant: `"typst-compile"` →
|
|
/// [`Step::TypstCompile`], `"shell"` → [`Step::Shell`], `"assemble-markdown"`
|
|
/// → [`Step::AssembleMarkdown`].
|
|
///
|
|
/// As with [`Artifact`], this alignment is maintained by review, not CI.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
pub enum Step {
|
|
/// Compile a template file (relative to the engineering root) into the
|
|
/// artifact; the framework injects the manifest. Mirrors Lean
|
|
/// `Step.typstCompile`.
|
|
TypstCompile {
|
|
/// The template file to compile as main, e.g. `exports/student.typ`.
|
|
template: PathBuf,
|
|
},
|
|
/// Run a shell command — the escape hatch. Mirrors Lean `Step.shell`.
|
|
Shell {
|
|
/// The command line to run.
|
|
run: String,
|
|
},
|
|
/// Assemble a single-file markdown deliverable by concatenating each
|
|
/// element's `field` markdown content file in `[[parts]]` order. Mirrors
|
|
/// Lean `Step.assembleMarkdown` (ADR-0015). Not a typst build — the
|
|
/// framework owns the read/concatenate/write itself.
|
|
AssembleMarkdown {
|
|
/// The per-element markdown content field to assemble (e.g. `slides`,
|
|
/// `transcript`).
|
|
field: String,
|
|
},
|
|
}
|
|
|
|
impl Step {
|
|
/// The default step when no `[[steps]]` are given: compile the stock
|
|
/// per-target template `exports/<name>.typ`.
|
|
fn default_for(name: &str) -> Step {
|
|
Step::TypstCompile {
|
|
template: PathBuf::from(format!("exports/{name}.typ")),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// `[project]` table.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
pub struct Project {
|
|
/// Stable project id.
|
|
pub id: String,
|
|
/// Folder / display name.
|
|
pub name: String,
|
|
}
|
|
|
|
/// `[info]` table (passed through to render targets verbatim).
|
|
///
|
|
/// **Mirrors `Spec.Courseware.Info`** in the Lean semantic master
|
|
/// (`spec/Spec/Courseware/Model/Info.lean`): the *canonical* model whose
|
|
/// `authors` is always a list. The authoring-surface form (string-or-array
|
|
/// `author`) is the separate [`RawInfo`] / [`RawAuthor`], normalized into this
|
|
/// at the load boundary — mirroring the Lean `RawInfo` / `RawAuthor` split. No
|
|
/// CI gate enforces this alignment (repo constitution); it is kept greppable.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
pub struct Info {
|
|
/// Lesson title.
|
|
pub title: String,
|
|
/// Authors, in declared order. A lesson can have several (a teaching group),
|
|
/// so this is a list, not a single name. Empty when `[info]` declares no
|
|
/// `author`. The on-disk `author` accepts either a bare string (one author)
|
|
/// or an array of strings (see [`RawAuthor`]); both load into this `Vec`.
|
|
/// Mirrors Lean `Info.authors : List String`.
|
|
pub authors: Vec<String>,
|
|
}
|
|
|
|
/// One `[[parts]]` entry plus its loaded element descriptor.
|
|
#[derive(Debug, Clone, PartialEq, Serialize)]
|
|
pub struct Part {
|
|
/// Declared kind from the manifest (one of the known kinds; ADR-0006).
|
|
pub kind: String,
|
|
/// Element folder path **as written in the manifest** (relative to root),
|
|
/// kept verbatim for diagnostics / display.
|
|
pub path: PathBuf,
|
|
/// The element's self-description loaded from its `element.toml`.
|
|
pub descriptor: ElementDescriptor,
|
|
}
|
|
|
|
/// An element's `element.toml`, parsed into kind + remaining scalar fields.
|
|
///
|
|
/// ADR-0008: `kind` is explicit in the descriptor (not inferred from the parent
|
|
/// directory), so a folder is self-describing.
|
|
#[derive(Debug, Clone, PartialEq, Serialize)]
|
|
pub struct ElementDescriptor {
|
|
/// `kind` from `element.toml`. Must equal the part's `kind`; a mismatch is
|
|
/// reported as a diagnostic (see [`load`]).
|
|
pub kind: String,
|
|
/// Element folder, absolute path.
|
|
pub dir: PathBuf,
|
|
/// The remaining `element.toml` keys (the scalar fields). Schema validation
|
|
/// of these is WU-3's job, not this loader's.
|
|
pub scalars: toml::Table,
|
|
}
|
|
|
|
// --- raw deserialization shapes (mirror the on-disk TOML) ---------------------
|
|
|
|
#[derive(Debug, Deserialize)]
|
|
struct RawManifest {
|
|
project: Option<RawProject>,
|
|
info: Option<RawInfo>,
|
|
#[serde(default)]
|
|
parts: Vec<RawPart>,
|
|
#[serde(default)]
|
|
targets: toml::Table,
|
|
}
|
|
|
|
#[derive(Debug, Deserialize)]
|
|
struct RawProject {
|
|
id: String,
|
|
name: String,
|
|
}
|
|
|
|
/// The authoring-surface `[info]` (mirrors Lean `RawInfo` in
|
|
/// `spec/Spec/Courseware/Model/Info.lean`): the raw form that exists for
|
|
/// fill-in convenience, normalized into the canonical [`Info`] at the load
|
|
/// boundary. Not the form the rest of the model traffics in.
|
|
#[derive(Debug, Deserialize)]
|
|
struct RawInfo {
|
|
title: String,
|
|
author: Option<RawAuthor>,
|
|
}
|
|
|
|
/// On-disk `author`: either a single name (`author = "…"`) or a list
|
|
/// (`author = ["…", "…"]`). Mirrors Lean `RawAuthor`: a fill-in convenience whose
|
|
/// string-or-array union lives **only** at the load boundary — [`RawAuthor::into_vec`]
|
|
/// folds it into the canonical [`Info::authors`] `Vec`, after which it never appears.
|
|
#[derive(Debug, Deserialize)]
|
|
#[serde(untagged)]
|
|
enum RawAuthor {
|
|
One(String),
|
|
Many(Vec<String>),
|
|
}
|
|
|
|
impl RawAuthor {
|
|
/// Flatten to the ordered author list (Lean `RawAuthor.normalize`): a single
|
|
/// name becomes a one-element list; a list passes through verbatim.
|
|
fn into_vec(self) -> Vec<String> {
|
|
match self {
|
|
RawAuthor::One(s) => vec![s],
|
|
RawAuthor::Many(v) => v,
|
|
}
|
|
}
|
|
}
|
|
|
|
#[derive(Debug, Deserialize)]
|
|
struct RawPart {
|
|
kind: String,
|
|
path: String,
|
|
}
|
|
|
|
/// Load the engineering file at `root` into a [`Lesson`].
|
|
///
|
|
/// Returns `(Option<Lesson>, Vec<Diagnostic>)`:
|
|
/// - `Some(lesson)` whenever the manifest parses into a `Lesson` at all. The
|
|
/// structure is produced even when individual parts have problems, so the
|
|
/// WU-5 orchestrator gets **both** the partial lesson and the collected
|
|
/// diagnostics.
|
|
/// - `None` only on a hard failure where no `Lesson` can be built: the
|
|
/// `manifest.toml` is missing/unreadable, is not valid TOML, or lacks the
|
|
/// required `[project]` / `[info]` tables. In that case the diagnostics
|
|
/// describe the hard failure.
|
|
///
|
|
/// Collected (non-fatal) diagnostics include: a part path that does not exist
|
|
/// or escapes the root via `..`, a missing/malformed `element.toml`, and a
|
|
/// `part.kind != element.toml kind` mismatch.
|
|
///
|
|
/// ## Diagnostic-code mapping (judgment call, WU-1)
|
|
///
|
|
/// `cph-diag`'s code set is closed and has **no** dedicated "manifest
|
|
/// malformed" code. We deliberately do not invent one here. Until such a code
|
|
/// is added, manifest-level structural errors (bad TOML, missing `[project]` /
|
|
/// `[info]`) are mapped to the closest existing code, [`DiagCode::SchemaViolation`],
|
|
/// with a message making the real cause clear. A genuinely missing **part
|
|
/// path** uses [`DiagCode::PartPathMissing`] (its actual meaning); a missing /
|
|
/// unreadable / malformed `element.toml` also maps to `SchemaViolation`.
|
|
// TODO(cph-diag): consider adding a dedicated `ManifestMalformed` code so
|
|
// manifest-structure errors don't overload `SchemaViolation`.
|
|
pub fn load(root: &Path) -> (Option<Lesson>, Vec<Diagnostic>) {
|
|
let mut diags = Vec::new();
|
|
|
|
let manifest_path = root.join("manifest.toml");
|
|
|
|
let manifest_src = match std::fs::read_to_string(&manifest_path) {
|
|
Ok(s) => s,
|
|
Err(e) => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("cannot read manifest.toml: {e}"),
|
|
)
|
|
.with_hint(format!(
|
|
"expected an engineering-file manifest at {}",
|
|
manifest_path.display()
|
|
)),
|
|
);
|
|
return (None, diags);
|
|
}
|
|
};
|
|
|
|
let raw: RawManifest = match toml::from_str(&manifest_src) {
|
|
Ok(r) => r,
|
|
Err(e) => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("manifest.toml is not valid TOML: {e}"),
|
|
)
|
|
.with_hint("fix the TOML syntax in manifest.toml"),
|
|
);
|
|
return (None, diags);
|
|
}
|
|
};
|
|
|
|
// `.cph-version` compatibility (ADR-0016). Decided at load time, before
|
|
// any structural/schema/compile work. An incompatible version is an
|
|
// error diagnostic (`CphVersionMismatch`); it does not halt loading, so
|
|
// any other defects surface alongside it — but an error diagnostic alone
|
|
// already makes the lesson illegal (ADR-0010), so `check`/`build` refuse.
|
|
// A missing `.cph-version` is skipped for now (ADR-0016 OPEN).
|
|
check_cph_version(root, &mut diags);
|
|
|
|
// [project] and [info] are required to build a Lesson at all.
|
|
let project = match raw.project {
|
|
Some(p) => Project {
|
|
id: p.id,
|
|
name: p.name,
|
|
},
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
"manifest.toml is missing the required [project] table",
|
|
)
|
|
.with_hint("add a [project] table with `id` and `name`"),
|
|
);
|
|
return (None, diags);
|
|
}
|
|
};
|
|
|
|
let info = match raw.info {
|
|
Some(i) => Info {
|
|
title: i.title,
|
|
authors: i.author.map(RawAuthor::into_vec).unwrap_or_default(),
|
|
},
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
"manifest.toml is missing the required [info] table",
|
|
)
|
|
.with_hint("add an [info] table with at least `title`"),
|
|
);
|
|
return (None, diags);
|
|
}
|
|
};
|
|
|
|
// Parse each [targets.<name>] table into a structured build config
|
|
// (ADR-0009/0011). Order is the TOML document order, as before. Malformed
|
|
// target config is non-fatal: it is reported and the target is kept with
|
|
// defaults so loading continues.
|
|
let targets: Vec<TargetConfig> = raw
|
|
.targets
|
|
.into_iter()
|
|
.map(|(name, value)| parse_target(name, value, &mut diags))
|
|
.collect();
|
|
|
|
// Load each part. Problems are collected, not fatal: we still build the
|
|
// Part (with a best-effort descriptor) so order/membership is observable.
|
|
let mut parts = Vec::with_capacity(raw.parts.len());
|
|
for raw_part in raw.parts {
|
|
let rel_path = PathBuf::from(&raw_part.path);
|
|
|
|
// Reject `..` traversal: a part path must stay within the root.
|
|
if has_parent_traversal(&rel_path) {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::PartPathMissing,
|
|
format!(
|
|
"part path '{}' escapes the engineering-file root via '..'",
|
|
raw_part.path
|
|
),
|
|
)
|
|
.with_hint("part paths must be relative folders inside the engineering file"),
|
|
);
|
|
// Still record the part with an empty descriptor so order is kept.
|
|
parts.push(Part {
|
|
kind: raw_part.kind.clone(),
|
|
path: rel_path.clone(),
|
|
descriptor: ElementDescriptor {
|
|
kind: raw_part.kind,
|
|
dir: root.join(&rel_path),
|
|
scalars: toml::Table::new(),
|
|
},
|
|
});
|
|
continue;
|
|
}
|
|
|
|
let dir = root.join(&rel_path);
|
|
|
|
let descriptor = if !dir.is_dir() {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::PartPathMissing,
|
|
format!("part folder '{}' does not exist", raw_part.path),
|
|
)
|
|
.with_hint(format!(
|
|
"create the folder '{}' or fix the `path` in manifest.toml",
|
|
raw_part.path
|
|
)),
|
|
);
|
|
ElementDescriptor {
|
|
kind: raw_part.kind.clone(),
|
|
dir,
|
|
scalars: toml::Table::new(),
|
|
}
|
|
} else {
|
|
load_descriptor(&dir, &rel_path, &raw_part.kind, &mut diags)
|
|
};
|
|
|
|
parts.push(Part {
|
|
kind: raw_part.kind,
|
|
path: rel_path,
|
|
descriptor,
|
|
});
|
|
}
|
|
|
|
let lesson = Lesson {
|
|
project,
|
|
info,
|
|
parts,
|
|
targets,
|
|
root: root.to_path_buf(),
|
|
};
|
|
(Some(lesson), diags)
|
|
}
|
|
|
|
/// The cph version the running CLI was built with (ADR-0016). Pulled from the
|
|
/// crate's `CARGO_PKG_VERSION` at compile time.
|
|
pub const CPH_VERSION: &str = env!("CARGO_PKG_VERSION");
|
|
|
|
/// Read the engineering file's `.cph-version` and, if present, push a
|
|
/// `CphVersionMismatch` error when it is not compatible with [`CPH_VERSION`]
|
|
/// (ADR-0016). A missing file is skipped for now (migration period; OPEN in
|
|
/// ADR-0016).
|
|
fn check_cph_version(root: &Path, diags: &mut Vec<Diagnostic>) {
|
|
let path = root.join(".cph-version");
|
|
let Ok(src) = std::fs::read_to_string(&path) else {
|
|
return; // missing `.cph-version` — skipped (ADR-0016 OPEN).
|
|
};
|
|
let file_version = src.trim();
|
|
if file_version.is_empty() {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::CphVersionMismatch,
|
|
format!(".cph-version is empty; expected cph version {CPH_VERSION}"),
|
|
)
|
|
.with_hint(format!(
|
|
"write the cph version this file targets into {} (currently {CPH_VERSION})",
|
|
path.display()
|
|
)),
|
|
);
|
|
return;
|
|
}
|
|
if !versions_compatible(file_version, CPH_VERSION) {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::CphVersionMismatch,
|
|
format!(
|
|
".cph-version declares {file_version}, but this cph is {CPH_VERSION} (incompatible)"
|
|
),
|
|
)
|
|
.with_hint(format!(
|
|
"align them: set .cph-version to {CPH_VERSION}, or install cph {file_version}"
|
|
)),
|
|
);
|
|
}
|
|
}
|
|
|
|
/// Whether an engineering file's declared cph version is compatible with the
|
|
/// running CLI's version (ADR-0016). **The rule is exact equality** — the
|
|
/// strictest choice, deliberately, while the format is young (0.0.x). This is
|
|
/// the single seam for future relaxation to a semver range: relaxing the
|
|
/// format does not change the diagnostic class, the spec, or the CLI — only
|
|
/// this predicate.
|
|
fn versions_compatible(file_version: &str, cli_version: &str) -> bool {
|
|
file_version == cli_version
|
|
}
|
|
|
|
/// Load one element's `element.toml` into an [`ElementDescriptor`], collecting
|
|
/// diagnostics. On a missing/malformed `element.toml` the descriptor falls back
|
|
/// to the part's declared kind with empty scalars so the lesson stays buildable.
|
|
fn load_descriptor(
|
|
dir: &Path,
|
|
rel_path: &Path,
|
|
part_kind: &str,
|
|
diags: &mut Vec<Diagnostic>,
|
|
) -> ElementDescriptor {
|
|
let element_toml = dir.join("element.toml");
|
|
let rel_element_toml = rel_path.join("element.toml");
|
|
|
|
let src = match std::fs::read_to_string(&element_toml) {
|
|
Ok(s) => s,
|
|
Err(e) => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"cannot read element.toml for part '{}': {e}",
|
|
rel_path.display()
|
|
),
|
|
)
|
|
.with_hint(format!(
|
|
"add an element.toml at {} with at least `kind = \"{part_kind}\"`",
|
|
rel_element_toml.display()
|
|
)),
|
|
);
|
|
return ElementDescriptor {
|
|
kind: part_kind.to_string(),
|
|
dir: dir.to_path_buf(),
|
|
scalars: toml::Table::new(),
|
|
};
|
|
}
|
|
};
|
|
|
|
let mut table: toml::Table = match toml::from_str(&src) {
|
|
Ok(t) => t,
|
|
Err(e) => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"element.toml for part '{}' is not valid TOML: {e}",
|
|
rel_path.display()
|
|
),
|
|
)
|
|
.with_hint("fix the TOML syntax in element.toml"),
|
|
);
|
|
return ElementDescriptor {
|
|
kind: part_kind.to_string(),
|
|
dir: dir.to_path_buf(),
|
|
scalars: toml::Table::new(),
|
|
};
|
|
}
|
|
};
|
|
|
|
// `kind` is required and must be a string. Pull it out of the scalar map so
|
|
// `scalars` ends up being "the remaining keys".
|
|
let kind = match table.remove("kind") {
|
|
Some(toml::Value::String(k)) => k,
|
|
Some(_) => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"element.toml for part '{}' has a non-string `kind`",
|
|
rel_path.display()
|
|
),
|
|
)
|
|
.with_hint("`kind` must be a string, e.g. `kind = \"lemma\"`"),
|
|
);
|
|
part_kind.to_string()
|
|
}
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"element.toml for part '{}' is missing the required `kind` key",
|
|
rel_path.display()
|
|
),
|
|
)
|
|
.with_hint(format!("add `kind = \"{part_kind}\"` to element.toml")),
|
|
);
|
|
part_kind.to_string()
|
|
}
|
|
};
|
|
|
|
// Cross-check: the descriptor's kind must equal the part's declared kind.
|
|
if kind != part_kind {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::UnknownKind,
|
|
format!(
|
|
"kind mismatch for part '{}': manifest says '{part_kind}', element.toml says '{kind}'",
|
|
rel_path.display()
|
|
),
|
|
)
|
|
.with_hint("make the manifest `kind` and the element.toml `kind` agree"),
|
|
);
|
|
}
|
|
|
|
ElementDescriptor {
|
|
kind,
|
|
dir: dir.to_path_buf(),
|
|
scalars: table,
|
|
}
|
|
}
|
|
|
|
/// Parse one `[targets.<name>]` table into a [`TargetConfig`] (ADR-0009/0011),
|
|
/// collecting [`DiagCode::SchemaViolation`] diagnostics for malformed fields.
|
|
///
|
|
/// Malformed config is **non-fatal**: a bad/absent `artifact` falls back to the
|
|
/// default ([`Artifact::default_for`]); a bad/absent `steps` falls back to the
|
|
/// default single `typst-compile` step ([`Step::default_for`]) — all reported,
|
|
/// never dropping the target. An empty `[targets.<name>]` body is valid (all
|
|
/// defaults, no diagnostics).
|
|
fn parse_target(name: String, value: toml::Value, diags: &mut Vec<Diagnostic>) -> TargetConfig {
|
|
// A target body must be a table; anything else (`student = 1`) is malformed.
|
|
let mut table = match value {
|
|
toml::Value::Table(t) => t,
|
|
_ => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("target '{name}' must be a table, e.g. `[targets.{name}]`"),
|
|
)
|
|
.with_hint("declare a target as a `[targets.<name>]` table"),
|
|
);
|
|
return TargetConfig {
|
|
artifact: Artifact::default_for(&name),
|
|
steps: vec![Step::default_for(&name)],
|
|
covers: None,
|
|
name,
|
|
};
|
|
}
|
|
};
|
|
|
|
let artifact = match table.remove("artifact") {
|
|
None => Artifact::default_for(&name),
|
|
Some(value) => parse_artifact(&name, value, diags),
|
|
};
|
|
|
|
let steps = match table.remove("steps") {
|
|
None => vec![Step::default_for(&name)],
|
|
Some(value) => parse_steps(&name, value, diags),
|
|
};
|
|
|
|
let covers = match table.remove("covers") {
|
|
None => None,
|
|
Some(value) => parse_covers(&name, value, diags),
|
|
};
|
|
|
|
TargetConfig {
|
|
name,
|
|
artifact,
|
|
steps,
|
|
covers,
|
|
}
|
|
}
|
|
|
|
/// Parse a target's optional `covers` array into the render-coverage declaration
|
|
/// (ADR-0011). Each entry is a kind name (a string). A non-array `covers`, or any
|
|
/// non-string entry, is reported as a [`DiagCode::SchemaViolation`]; in that case
|
|
/// the declaration falls back to `None` ("not declared"), so `cph-check` defaults
|
|
/// it to the full known-kind universe rather than silently covering nothing.
|
|
///
|
|
/// A well-formed but empty `covers = []` yields `Some(vec![])`: a target that
|
|
/// explicitly renders no kind (every used kind then draws a `renderIgnored`
|
|
/// warning) — distinct from an absent key.
|
|
fn parse_covers(
|
|
name: &str,
|
|
value: toml::Value,
|
|
diags: &mut Vec<Diagnostic>,
|
|
) -> Option<Vec<String>> {
|
|
let items = match value {
|
|
toml::Value::Array(items) => items,
|
|
_ => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' has a non-array `covers`; declare it as a list of \
|
|
kind names, e.g. `covers = [\"segment\", \"example\"]`"
|
|
),
|
|
)
|
|
.with_hint("set `covers` to an array of kind-name strings, or omit it"),
|
|
);
|
|
return None;
|
|
}
|
|
};
|
|
|
|
let mut kinds = Vec::with_capacity(items.len());
|
|
for item in items {
|
|
match item {
|
|
toml::Value::String(s) => kinds.push(s),
|
|
other => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' has a non-string entry in `covers`: {}",
|
|
json_like_type(&other)
|
|
),
|
|
)
|
|
.with_hint("each `covers` entry is a kind name (a string)"),
|
|
);
|
|
return None;
|
|
}
|
|
}
|
|
}
|
|
Some(kinds)
|
|
}
|
|
|
|
/// A short type label for a TOML value, for the `covers` non-string diagnostic.
|
|
fn json_like_type(v: &toml::Value) -> &'static str {
|
|
match v {
|
|
toml::Value::String(_) => "string",
|
|
toml::Value::Integer(_) => "integer",
|
|
toml::Value::Float(_) => "float",
|
|
toml::Value::Boolean(_) => "boolean",
|
|
toml::Value::Datetime(_) => "datetime",
|
|
toml::Value::Array(_) => "array",
|
|
toml::Value::Table(_) => "table",
|
|
}
|
|
}
|
|
|
|
/// Parse the `artifact` inline table into an [`Artifact`]. The `type`
|
|
/// discriminator selects the variant and which fields are read. An unknown or
|
|
/// malformed `type`, a non-table value, or a missing required field is reported
|
|
/// as a [`DiagCode::SchemaViolation`]; in every error case a usable default
|
|
/// ([`Artifact::default_for`]) is returned so loading continues.
|
|
fn parse_artifact(name: &str, value: toml::Value, diags: &mut Vec<Diagnostic>) -> Artifact {
|
|
let mut table = match value {
|
|
toml::Value::Table(t) => t,
|
|
_ => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' has a non-table `artifact`; it must be an \
|
|
inline table like `{{ type = \"single-file\", filepath = \"…\" }}`"
|
|
),
|
|
)
|
|
.with_hint("set `artifact` to an inline table with a `type` discriminator"),
|
|
);
|
|
return Artifact::default_for(name);
|
|
}
|
|
};
|
|
|
|
let kind = match table.remove("type") {
|
|
Some(toml::Value::String(s)) => s,
|
|
Some(_) => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("target '{name}' has a non-string `artifact.type`"),
|
|
)
|
|
.with_hint("set `artifact.type` to \"single-file\" or \"file-tree\""),
|
|
);
|
|
return Artifact::default_for(name);
|
|
}
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("target '{name}' has an `artifact` with no `type` discriminator"),
|
|
)
|
|
.with_hint("add `type = \"single-file\"` (or `\"file-tree\"`) to `artifact`"),
|
|
);
|
|
return Artifact::default_for(name);
|
|
}
|
|
};
|
|
|
|
match kind.as_str() {
|
|
"single-file" => {
|
|
let filepath = match take_string_field(&mut table, "filepath") {
|
|
Some(s) => PathBuf::from(s),
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' single-file `artifact` is missing a string \
|
|
`filepath`"
|
|
),
|
|
)
|
|
.with_hint("add `filepath = \"build/<name>.pdf\"` to the artifact"),
|
|
);
|
|
return Artifact::default_for(name);
|
|
}
|
|
};
|
|
Artifact::SingleFile { filepath }
|
|
}
|
|
"file-tree" => {
|
|
let root = take_string_field(&mut table, "root");
|
|
let outputs = take_string_field(&mut table, "outputs");
|
|
match (root, outputs) {
|
|
(Some(root), Some(outputs)) => Artifact::FileTree {
|
|
root: PathBuf::from(root),
|
|
outputs,
|
|
},
|
|
(root, outputs) => {
|
|
let mut missing = Vec::new();
|
|
if root.is_none() {
|
|
missing.push("root");
|
|
}
|
|
if outputs.is_none() {
|
|
missing.push("outputs");
|
|
}
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' file-tree `artifact` is missing required \
|
|
string field(s): {}",
|
|
missing.join(", ")
|
|
),
|
|
)
|
|
.with_hint(
|
|
"a file-tree artifact needs `root = \"<dir>\"` and \
|
|
`outputs = \"<glob>\"`",
|
|
),
|
|
);
|
|
Artifact::default_for(name)
|
|
}
|
|
}
|
|
}
|
|
other => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' has an invalid `artifact.type` '{other}'; \
|
|
valid values are \"single-file\", \"file-tree\""
|
|
),
|
|
)
|
|
.with_hint("set `artifact.type` to \"single-file\" or \"file-tree\""),
|
|
);
|
|
Artifact::default_for(name)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Parse the `steps` array-of-tables into an ordered `Vec<Step>`, preserving
|
|
/// declared order. A non-array `steps`, or any individual step with an unknown
|
|
/// or malformed `type` / missing required field, is reported as a
|
|
/// [`DiagCode::SchemaViolation`]; malformed individual steps are skipped while
|
|
/// well-formed ones are kept. If `steps` is present but yields no usable steps,
|
|
/// the default step ([`Step::default_for`]) is substituted so the build stays
|
|
/// runnable.
|
|
fn parse_steps(name: &str, value: toml::Value, diags: &mut Vec<Diagnostic>) -> Vec<Step> {
|
|
let items = match value {
|
|
toml::Value::Array(items) => items,
|
|
_ => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' has a non-array `steps`; declare steps as \
|
|
`[[targets.{name}.steps]]` entries"
|
|
),
|
|
)
|
|
.with_hint("each step is a `[[targets.<name>.steps]]` table with a `type`"),
|
|
);
|
|
return vec![Step::default_for(name)];
|
|
}
|
|
};
|
|
|
|
let mut steps = Vec::with_capacity(items.len());
|
|
for item in items {
|
|
if let Some(step) = parse_step(name, item, diags) {
|
|
steps.push(step);
|
|
}
|
|
}
|
|
|
|
if steps.is_empty() {
|
|
// `steps` was present but produced nothing usable: keep the build
|
|
// runnable with the default step (the malformed entries were reported).
|
|
vec![Step::default_for(name)]
|
|
} else {
|
|
steps
|
|
}
|
|
}
|
|
|
|
/// Parse one `[[steps]]` entry into a [`Step`]. The `type` discriminator selects
|
|
/// the variant. Returns `None` (after reporting a [`DiagCode::SchemaViolation`])
|
|
/// for a non-table entry, an unknown/malformed `type`, or a missing required
|
|
/// field.
|
|
fn parse_step(name: &str, value: toml::Value, diags: &mut Vec<Diagnostic>) -> Option<Step> {
|
|
let mut table = match value {
|
|
toml::Value::Table(t) => t,
|
|
_ => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("target '{name}' has a step that is not a table"),
|
|
)
|
|
.with_hint("each step is a `[[targets.<name>.steps]]` table with a `type`"),
|
|
);
|
|
return None;
|
|
}
|
|
};
|
|
|
|
let kind = match table.remove("type") {
|
|
Some(toml::Value::String(s)) => s,
|
|
Some(_) => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("target '{name}' has a step with a non-string `type`"),
|
|
)
|
|
.with_hint(
|
|
"set the step `type` to \"typst-compile\", \"shell\", or \"assemble-markdown\"",
|
|
),
|
|
);
|
|
return None;
|
|
}
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("target '{name}' has a step with no `type` discriminator"),
|
|
)
|
|
.with_hint(
|
|
"add `type = \"typst-compile\"` (or `\"shell\"`, `\"assemble-markdown\"`) to the step",
|
|
),
|
|
);
|
|
return None;
|
|
}
|
|
};
|
|
|
|
match kind.as_str() {
|
|
"typst-compile" => match take_string_field(&mut table, "template") {
|
|
Some(template) => Some(Step::TypstCompile {
|
|
template: PathBuf::from(template),
|
|
}),
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' typst-compile step is missing a string `template`"
|
|
),
|
|
)
|
|
.with_hint("add `template = \"exports/<name>.typ\"` to the step"),
|
|
);
|
|
None
|
|
}
|
|
},
|
|
"shell" => match take_string_field(&mut table, "run") {
|
|
Some(run) => Some(Step::Shell { run }),
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!("target '{name}' shell step is missing a string `run`"),
|
|
)
|
|
.with_hint("add `run = \"<command>\"` to the step"),
|
|
);
|
|
None
|
|
}
|
|
},
|
|
"assemble-markdown" => match take_string_field(&mut table, "field") {
|
|
Some(field) => Some(Step::AssembleMarkdown { field }),
|
|
None => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' assemble-markdown step is missing a string `field`"
|
|
),
|
|
)
|
|
.with_hint("add `field = \"slides\"` (or `\"transcript\"`) to the step"),
|
|
);
|
|
None
|
|
}
|
|
},
|
|
other => {
|
|
diags.push(
|
|
Diagnostic::error(
|
|
DiagCode::SchemaViolation,
|
|
format!(
|
|
"target '{name}' has a step with an invalid `type` '{other}'; \
|
|
valid values are \"typst-compile\", \"shell\", \"assemble-markdown\""
|
|
),
|
|
)
|
|
.with_hint(
|
|
"set the step `type` to \"typst-compile\", \"shell\", or \"assemble-markdown\"",
|
|
),
|
|
);
|
|
None
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Remove `key` from `table` and return it if it is a string; otherwise `None`
|
|
/// (a missing key and a non-string value are both treated as absent — the
|
|
/// caller reports the missing-field diagnostic with the right context).
|
|
fn take_string_field(table: &mut toml::Table, key: &str) -> Option<String> {
|
|
match table.remove(key) {
|
|
Some(toml::Value::String(s)) => Some(s),
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
/// True if `path` contains any `..` component (parent-dir traversal).
|
|
fn has_parent_traversal(path: &Path) -> bool {
|
|
path.components().any(|c| matches!(c, Component::ParentDir))
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn parent_traversal_detection() {
|
|
assert!(has_parent_traversal(Path::new("../x")));
|
|
assert!(has_parent_traversal(Path::new("a/../b")));
|
|
assert!(!has_parent_traversal(Path::new("a/b/c")));
|
|
assert!(!has_parent_traversal(Path::new("segments/intro")));
|
|
}
|
|
}
|