The Cook Standard

The Cook Standard

Version: v0.18 (head-of-main; see App. E Versions index). Status: Draft — pre-1.0, head-of-main lockstep. Source of truth (informative): the Rust parser in cli/crates/cook-lang/.

The Cook Standard is the authoritative specification of the Cookfile language. It is maintained in lockstep with the main branch: any change that affects language surface MUST be reflected in the Standard in the same commit that changes the implementation.

The Standard is a living document organised into four Parts plus front matter and annexes. Amendments to any section MUST follow the spec-first rule in CONTRIBUTING.md and add a CS-NNNN entry to E-changes.mdx.

Table of contents

Front matter

• §{intro} — Introduction
• §{conf} — Conformance
• §{notation} — Notation and conventions

Part I — The Cookfile language

• §{lexical} — Lexical structure
• §{toplevel} — Top-level structure
• §{decl} — Declarations
• §{recipes} — Recipes
• §{chores} — Chores
• §{steps} — Step kinds
• §{phl} — Placeholders
• §{xref} — Cross-recipe references
• §{comp} — Cross-Cookfile composition
• §{mods} — Modules

Part II — Execution model

• §{exec.phases} — Two-phase model
• §{exec.capture} — Capture mode
• §{exec.groups} — Step groups
• §{exec.ord} — Cross-recipe ordering and drain
• §{exec.cache} — Cache semantics
• §{exec.mat} — Output materialisation
• §{exec.diag} — Diagnostic ordering
• §{exec.ws} — Workspace root

Part III — The Cook Lua API

• §{lua} — API surface overview
• §{lua.reg} — Register-phase API
• §{lua.exe} — Execute-phase API
• §{lua.both} — Both-phase API
• §{lua.fs} — fs.* (incl. sandbox)
• §{lua.path} — path.*

Part IV — Standard module catalogue

• §{cat} — Catalogue governance
• §{cat.cc} — cc — C-family build module

Annexes

• App. A — Grammar
• App. B — Worked examples
• App. C — Rationale
• App. D — Pre-1.0 checklist
• App. E — Changes
• App. F — Conformance corpus

Conformance

• conformance/positive/ — Cookfiles that conforming implementations MUST accept. Browse the corpus at standard/conformance/positive/ in the source tree.
• conformance/negative/ — Cookfiles that conforming implementations MUST reject. Browse the corpus at standard/conformance/negative/ in the source tree.

How to change the Standard

See CONTRIBUTING.md at the repo root. In brief:

1. Any PR affecting Cookfile surface syntax, execution semantics, the Cook Lua API, or the module system MUST update standard/ in the same PR.
2. Add one entry to E-changes.mdx with a new stable CS-NNNN ID.
3. If the grammar changes, update A-grammar.mdx.
4. If the change is observable from a Cookfile, add at least one case to conformance/positive/ or conformance/negative/.

The repo ships a .githooks/pre-commit hook that checks this discipline locally. Install it with:

git config core.hooksPath .githooks

Reading order

First-time readers: read § 0, § 1, and § 2, then the chapter relevant to the construct in question; Appendix A is the formal grammar reference. Skim App. B for worked examples and App. C for design rationale.