dotfiles/.config/dot/.claude/spec/tree-sitter-cooklang.md

Problem Statement

Editors with tree-sitter support (Neovim, Helix, Zed, Emacs) have no reliable way to get syntax highlighting for Cooklang recipe files today. Cooklang's own documentation recommends wiring up the community grammar addcninblue/tree-sitter-cooklang via nvim-treesitter, but that grammar ships no highlight queries at all: it has no queries/ directory, and its own README lists "Syntax highlighting" as an unchecked TODO item. The documented setup snippet also has a bug (branch = "main", but the repo's actual default branch is master). Following the documented path exactly produces a parser that compiles and attaches to .cook buffers, but renders no highlighting whatsoever, because nothing tells tree-sitter which grammar nodes map to which highlight groups.

Solution

Write a new, standalone tree-sitter grammar for Cooklang from scratch, grounded in the official EBNF spec (cooklang/spec) and validated against that same repo's official canonical.yaml conformance test suite — the same correctness bar every official and community Cooklang parser implementation (Rust, Swift, Go, and others) is held to. Pair the grammar with a hand-authored highlights.scm query file, so the result actually produces working syntax highlighting once wired into any tree-sitter-consuming editor, rather than a parser with no highlighting story.

User Stories

1. As a Cooklang recipe author, I want ingredients, cookware, timers, quantities/units, comments, and metadata each highlighted distinctly, so recipes are visually parseable at a glance.
2. As a grammar maintainer, I want the grammar to correctly parse the full Cooklang canonical test suite, so the highlighting reflects real document structure rather than an approximation.
3. As a grammar maintainer, I want corpus tests derived directly from canonical.yaml, so the grammar's correctness tracks the same bar every other Cooklang implementation must pass, rather than a bespoke set of hand-picked examples.
4. As a grammar maintainer, I want the grammar published as a normal, git-clonable repository, so any tree-sitter consumer's parser-install mechanism (e.g. nvim-treesitter's install_info.url) can point at it exactly like any other community grammar.
5. As an editor user on any tree-sitter-consuming editor (not just Neovim), I want the grammar to be generic and editor-agnostic, so it's reusable beyond one person's personal config.
6. As a grammar maintainer, I want highlights.scm to map onto standard tree-sitter highlight captures (@string, @number, @comment, etc.), so it renders correctly under any standard colorscheme without bespoke handling.

Implementation Decisions

• New standalone repository, with its own git history — not bundled into any other project. Hosting, naming, and publishing logistics are the maintainer's own call and deliberately not specified here.
• Grammar authored from scratch using tree-sitter's grammar.js DSL. A hand-written external scanner (in C) is expected to be necessary, for the same reason the community grammar needed one: Cooklang's comment syntax (-- ..., [- ... -]), metadata lines, and ingredient/cookware/timer modifier braces ({...}) require context-sensitive lexing that a pure CFG can't express.
• Ground truth for grammar structure: cooklang/spec's EBNF (EBNF.md). Ground truth for correctness: cooklang/spec/tests/canonical.yaml (837 lines as of writing) — every case in that file gets converted into a tree-sitter corpus test (.cook source in, expected parse tree out). Passing the full derived corpus is the grammar's release bar, in the same sense "conforming" is used across the other official/community implementations.
• highlights.scm is authored by hand against this grammar's own node types — full control over naming, since the grammar is written fresh alongside it, rather than reverse-engineering someone else's node names.
• Scope is highlighting only: no folds.scm or indents.scm. Nothing in this project calls for code folding or custom indentation behavior for Cooklang files; adding those query files would be building capability nobody asked for.
• Explicitly rejected: reusing addcninblue/tree-sitter-cooklang as the grammar. It has real strengths worth recording — a working custom C scanner, and contributions from two recognized tree-sitter-ecosystem contributors (amaanq, who did a scanner rewrite; clason, who regenerated the parser/bindings) — but it ships no query files at all, and its own README acknowledges highlighting was never finished. The existence of canonical.yaml as a rigorous, official test oracle de-risks writing a fresh grammar enough that starting clean (full control over node naming, no inherited "hacky" workarounds — the existing grammar's own README flags one, around punctuation in ingredient names) was judged better than building on an incomplete, unofficial base.

Testing Decisions

• Correctness: tree-sitter test against a corpus derived from cooklang/spec/tests/canonical.yaml — each canonical case becomes a corpus fixture. Passing 100% of the derived corpus is the bar for calling the grammar done.
• highlights.scm itself is not covered by automated tests as part of this spec. Verification of the query file's output is manual/visual, done from the consuming editor side (see the companion integration spec for how this plays out in this machine's Neovim config). Automated highlight-assertion tests could be added later by a consumer that needs stronger guarantees, but nothing in this spec calls for that.
• No CI/build pipeline decisions are made here — ownership of hosting and any CI is the maintainer's call, out of scope for this spec.

Out of Scope

• Reusing addcninblue/tree-sitter-cooklang as the underlying grammar (evaluated and rejected — see Implementation Decisions).
• folds.scm / indents.scm (a possible future addition, not built now).
• Any specific editor's integration wiring (the companion tree-sitter-cooklang-integration spec covers this machine's Neovim config; no other editor or consumer is addressed here).
• Repository hosting, naming, and CI/publishing logistics.
• Automated highlight-assertion testing.
• Installing or provisioning tree-sitter-cli/Node build tooling — a normal prerequisite of grammar authoring, not a design decision this spec needs to make.

Further Notes

• addcninblue/tree-sitter-cooklang (evaluated and passed over): no queries/ directory, README lists syntax highlighting as an unchecked TODO. The official cooklang.org blog's own documented Neovim setup snippet for it also has a bug — branch = "main" in the install_info, when the repo's actual default branch is master — which would make :TSInstall cooklang fail as written.
• cooklang/spec/tests/canonical.yaml is the same conformance suite used to validate roughly ten official/community Cooklang parser implementations across languages (Rust's cooklang-rs, Swift's CookInSwift, Go's cooklang-go, and others). Using it here gives this from-scratch grammar the same correctness bar as those.
• Mirrors the existing gitea-axi / gitea-axi-integration spec pair in this same .claude/spec/ directory: one spec for the generic, reusable tool, one for how a specific project adopts it.