docs(adr): cph 的 nested-manifest / batch-export 改号 0036/0037

上游 0029/0030 与本地 filelib 侧同号 ADR 相撞,cph 两份改到本地空闲号段,
代码锚点引用一并跟随。
This commit is contained in:
2026-08-06 00:51:33 +08:00
parent e878b46701
commit ecc92c9a87
27 changed files with 100 additions and 100 deletions
+12 -12
View File
@@ -41,7 +41,7 @@ enum Command {
/// Build one or more render targets. Exits 1 if any target fails.
///
/// With no `--target`, batches every target the lesson declares
/// (ADR-0030): each target builds independently — one failing does not
/// (ADR-0037): each target builds independently — one failing does not
/// stop the rest — and the exit code is non-zero if any target failed.
/// Repeat `--target` to build an explicit ordered subset instead.
Build {
@@ -57,7 +57,7 @@ enum Command {
#[arg(short = 'o', long, value_name = "OUT")]
out: Option<PathBuf>,
},
/// Build one or more bundle targets (ADR-0030): combine an ordered
/// Build one or more bundle targets (ADR-0037): combine an ordered
/// arrangement of self-contained lessons (`bundle.toml`) into one
/// artifact. Same batching/exit-code contract as `build`.
Bundle {
@@ -209,12 +209,12 @@ fn run_completions(shell: CompletionTarget) -> ExitCode {
// authoritative: whatever these write, `cph check` must accept.
/// The stock `exports/student.typ` written by `init` — the framework's default
/// render template (ADR-0011, outline-shape ADR-0029), the same file the
/// render template (ADR-0011, outline-shape ADR-0036), the same file the
/// examples ship. Kept verbatim so a freshly scaffolded engineering file
/// renders out of the box; it imports `@local/cph-render:0.1.0`, which the
/// engine resolves from the embedded package. Presentation (heading numbering,
/// styling) is editable here per engineering file, not in the manifest.
const DEFAULT_STUDENT_TEMPLATE: &str = r##"// DEFAULT STUDENT TEMPLATE (framework default; ADR-0011, outline shape ADR-0029).
const DEFAULT_STUDENT_TEMPLATE: &str = r##"// DEFAULT STUDENT TEMPLATE (framework default; ADR-0011, outline shape ADR-0036).
//
// This is a *real, editable* file that lives in an engineering file at
// `exports/student.typ`. The framework compiles it AS THE MAIN FILE with the
@@ -232,7 +232,7 @@ const DEFAULT_STUDENT_TEMPLATE: &str = r##"// DEFAULT STUDENT TEMPLATE (framewor
// PACKAGE, not the engineering root. A `/<part.path>/<field>.typ` written HERE
// (this template lives under `--root`) resolves against `--root`. So the
// template loads content and hands cph-render an already-assembled `outline`
// array (elements interleaved with section headings, ADR-0029).
// array (elements interleaved with section headings, ADR-0036).
//
// OPEN CONTRACT POINT — optional-content presence. typst has no "does this file
// exist" primitive (a missing `include` is a hard compile error). So the
@@ -259,7 +259,7 @@ const DEFAULT_STUDENT_TEMPLATE: &str = r##"// DEFAULT STUDENT TEMPLATE (framewor
// resolved against --root) and read scalar fields from <path>/element.toml.
// `part-fields` (from cph-render) is the single source of truth for
// kind->fields.
// - a "section" entry (ADR-0029): pass its title/depth straight through — no
// - a "section" entry (ADR-0036): pass its title/depth straight through — no
// content to load, it is a heading.
#let outline = raw-outline.map(raw => {
if raw.at("type", default: "element") == "section" {
@@ -432,7 +432,7 @@ template = "exports/student.typ"
/// Add a new part to the engineering file at `root`: create its folder with
/// `element.toml` + blank required content files, then append its `[[children]]`
/// entry to the root `manifest.toml` (ADR-0029 root children). Rejects unknown
/// entry to the root `manifest.toml` (ADR-0036 root children). Rejects unknown
/// kinds, unsafe names, and anything that would double-register an existing part.
fn run_add(root: &std::path::Path, kind: &str, name: &str) -> ExitCode {
let dir = match kind_dir(kind) {
@@ -524,7 +524,7 @@ fn manifest_has_child(manifest: &str, rel: &str) -> bool {
/// adjacent). The block goes immediately before the first section header that is
/// neither `[project]`/`[info]` nor an existing `[[children]]` entry (i.e. before
/// `[targets.*]`), or at end-of-file if none — either way it lands at the tail
/// of the root-children run, after `[info]` and any existing children (ADR-0029).
/// of the root-children run, after `[info]` and any existing children (ADR-0036).
/// Comment blocks are preserved.
fn insert_child(manifest: &str, kind: &str, rel: &str) -> String {
let block = format!("[[children]]\nkind = \"{kind}\"\npath = \"{rel}\"\n");
@@ -717,13 +717,13 @@ fn write_outline_output(path: &std::path::Path, bytes: &[u8], force: bool) -> Re
}
}
/// Dispatch `cph build` (ADR-0030): with an explicit `--target` (repeatable),
/// Dispatch `cph build` (ADR-0037): with an explicit `--target` (repeatable),
/// build exactly that ordered set; with none, batch every target the lesson
/// declares. Each target builds **independently** — one failing does not stop
/// the rest — and prints a per-target ledger when building more than one.
/// Exits non-zero iff **any** target failed to produce its artifact (a build
/// failure is a real defect, distinct from the non-blocking `renderIgnored`
/// warning class — ADR-0030).
/// warning class — ADR-0037).
fn run_build_command(
path: &std::path::Path,
engine: &Engine,
@@ -819,10 +819,10 @@ fn run_build_one(
}
}
/// Dispatch `cph bundle` (ADR-0030) — same batching/exit-code contract as
/// Dispatch `cph bundle` (ADR-0037) — same batching/exit-code contract as
/// [`run_build_command`], over a bundle's own declared targets. MVP bundle
/// targets are `typst-compile` only (no shell/markdown-assemble routing —
/// ADR-0030 did not extend those step kinds to bundles).
/// ADR-0037 did not extend those step kinds to bundles).
fn run_bundle_command(
path: &std::path::Path,
engine: &Engine,