Crate sim_cookbook

Expand description

Cookbook engine for SIM: runnable, crate-local tutorial recipes.

A recipe is a tiny lesson – a runnable setup (in Lisp or any registered codec) plus a purpose document – that ships inside the crate it teaches. When a lib loads, it registers its recipes as Card records; the cookbook is then a projection over those cards, grouped into books and chapters and rendered by every surface (CLI, WebUI, browse, agent).

This crate owns the kernel-free cookbook engine: manifest parsing and lint, compile-time embedding, recipe stores, projection/search/next behavior, and deterministic user overlays. Runtime operations live in sim-lib-cookbook; the CLI, WebUI, browse/help, and agent surfaces all use that shared runtime projection instead of parallel cookbook logic.

Structs§

BookManifest: Parsed book.toml.
BookView: One book (all recipes from one crate) in a CookbookView.
ChapterManifest: Parsed chapter.toml (every field optional).
ChapterView: One chapter within a BookView.
CheckResult: The result of checking one Expectation after a run.
CookbookView: The full computed cookbook: every loaded recipe grouped into books.
Diagnostic: One problem found while linting recipe files on disk.
Expectation: One declared expectation, turning a recipe into a generated test.
OverlayDirectives: Parsed overlay.toml directives.
RecipeCard: The in-memory record for one recipe. Registered as a Card of kind "recipe"; the cookbook view is a projection over these.
RecipeManifest: Parsed recipe.toml.
RecipeRun: The outcome of running a recipe’s setup through its codec.
RecipeStore: A registry of loaded recipe cards, keyed by their globally unique id.

Enums§

RecipeSource: Where a recipe came from.
TomlValue: A scalar or string-array value from a manifest line.

Constants§

DEFAULT_ORDER: Default sort key when order is omitted.

Functions§

apply_directives: Apply directives to a store: hide removes, reorder sets order, retitle sets title. Directives naming an unknown recipe are ignored (the overlay may reference recipes from libs not currently loaded).
generate_embed_code: Walk recipes_root and return the Rust source for an crate::EmbeddedDir literal: a sorted &[(rel-path, include_bytes!(abs-path))]. A missing or empty directory yields an empty slice.
lint_dir: Lint one recipe directory on disk: parse recipe.toml, confirm the declared setup and purpose files exist, and that required fields are present. Returns every problem found, so an author sees all errors at once.
load_overlay: Load the overlay at root into store: upsert any overlay recipes (so they override crate recipes by id and merge into matching books), then apply the overlay.toml directives. A missing directory is a no-op.
next: The recipe immediately after id in global order, for “continue” buttons. None if id is unknown or is the last recipe.
ordered_cards: All cards in deterministic global order: by book order then id, chapter order then name, recipe order then id. Two recipes never compare equal because ids are unique, so the order is total and stable.
parse_book: Parse and validate book.toml text.
parse_chapter: Parse chapter.toml text (all fields optional).
parse_overlay: Parse overlay.toml text into directives.
parse_recipe: Parse and validate recipe.toml text.
recipes_from_embedded: Parse an embedded recipes/ tree into recipe cards (unsorted; the cookbook view applies ordering). Returns an error string on the first malformed manifest, missing file, or non-UTF-8 purpose document.
search: Rank recipes matching query (case-insensitive). A title match scores highest, then a tag match, then a purpose match; scores add. Recipes that match nothing are dropped. Ties keep deterministic global order.
view: Group the store’s cards into the nested CookbookView.
write_embed: Generate the embed slice and write it to $OUT_DIR/cookbook_recipes.rs. recipes_subdir is relative to $CARGO_MANIFEST_DIR. Intended for use from a crate’s build.rs.

Type Aliases§

EmbeddedDir: A crate’s embedded recipes/ tree: (path-relative-to-recipes, bytes). Paths use / separators. Produced at build time (see crate::generate_embed_code).