kitchen-md/.claude/spec/core-parser.md

Problem Statement

@kitchen-md/core has an empty entry point. There is no Parser implementation, no public API, and no AST types. Tooling that needs to extract structured data from Recipe Files — the CLI, and eventually an Obsidian plugin — has nothing to build on.

Solution

Implement the Parser in @kitchen-md/core: a pure function that accepts a Recipe File string and returns a Document AST. The Parser uses remark internally to handle CommonMark and OFM syntax, runs a custom annotation transform to surface Ingredient, Cookware, and Timer nodes, and exposes a clean public API using core's own types — no remark internals leak through.

User Stories

1. As a tooling user, I want to call parse with a Recipe File string and receive a Document AST so that I can build structured tooling without writing a parser myself.
2. As a tooling user, I want frontmatter passed through as a plain object so that I can read whatever fields I need without the parser imposing a schema.
3. As a tooling user, I want heading blocks in the Document AST so that I can render or reason about document structure.
4. As a tooling user, I want paragraph blocks with typed inline nodes so that I can render prose and distinguish plain text from structured content.
5. As a tooling user, I want list blocks with ordered and unordered variants so that recipe steps written as lists are represented faithfully.
6. As a tooling user, I want code blocks passed through without annotation parsing so that example syntax in documentation is not mistakenly extracted as recipe data.
7. As a tooling user, I want wikilinks represented as typed Inline Nodes so that I can render or process [[links]] distinctly from plain text.
8. As a tooling user, I want transclusions — including KitchenMD Step References — represented as typed Inline Nodes so that tooling can resolve them.
9. As a tooling user, I want Ingredient Annotations represented as Inline Nodes carrying name, quantity, and unit so that I can extract ingredient data from any recipe prose.
10. As a tooling user, I want Cookware Annotations represented as Inline Nodes carrying name and optional quantity so that I can extract equipment requirements.
11. As a tooling user, I want Timer Annotations represented as Inline Nodes carrying a value or range and a canonical unit so that I can extract timing information.
12. As a tooling user, I want annotations inside code spans and code blocks to be ignored so that the parser follows CommonMark inline processing rules.
13. As a future Obsidian plugin author, I want to import @kitchen-md/core without taking a transitive dependency on remark so that my plugin bundle does not include remark's internals.

Implementation Decisions

• The public API exports a single parse function. Given a Recipe File string, it returns a DocumentAST. It is a pure function — no filesystem access, no side effects.

• DocumentAST top-level shape: { frontmatter, blocks }.

  • frontmatter — the raw parsed YAML metadata as a plain object, passed through without schema enforcement. Empty object when no frontmatter is present.
  • blocks — a flat, ordered array of Block nodes representing the document body. The flat structure means headings are siblings of their following content, not parents of it. See ADR 0003 and the Document AST entry in the domain glossary.

• Block types (initial set):

  • HeadingBlock — level (1–6) and an inline content array.
  • ParagraphBlock — an inline content array.
  • ListBlock — ordered flag and an array of list items, each carrying an inline content array.
  • CodeBlock — optional language identifier and a literal text string. Annotation parsing does not run on code block content.
  • ThematicBreakBlock — no content fields.
  • RawBlock — carries the raw text of any remark node type not explicitly modelled above. Ensures forward compatibility when the fixture or future files use block types not yet in the catalogue.

• Inline Node types:

  • TextNode — a literal string of plain text.
  • EmphasisNode — an inline content array (italic).
  • StrongNode — an inline content array (bold).
  • CodeSpanNode — a literal string. Annotation parsing does not run on code span content.
  • LinkNode — href string and an inline content array.
  • WikilinkNode — target (filename without extension) and optional display text. Covers both [[link]] and [[link|display]].
  • TransclusionNode — target and optional anchor string. Covers ![[link]], ![[link#heading]], and KitchenMD Step References (![[file#section:N]] and ![[file#N]]). The anchor is passed through as-is; Step Reference resolution is out of scope for the parser.
  • IngredientNode — name, optional quantity string, optional unit string.
  • CookwareNode — name, optional quantity string, optional unit string.
  • TimerNode — value string (single) or value + high strings (range), and a canonical unit abbreviation.

• remark is used internally as the CommonMark parser (see ADR 0002). OFM wikilinks and transclusions are handled by remark-wiki-link and its underlying micromark and mdast-util packages. KitchenMD annotations are processed by a custom remark transform plugin that walks mdast text nodes outside code contexts and splits them into annotation Inline Nodes. remark types do not appear in @kitchen-md/core's public API (see ADR 0003). An internal translation layer maps remark's mdast output to core's own types before returning.

• Annotation parsing naturally respects CommonMark inline scoping: the annotation transform plugin operates only on mdast text nodes, which do not appear inside code spans or code blocks. No additional scoping logic is required.

• Timer unit aliases are normalised to canonical abbreviations at parse time (mins → min, hours → hr, etc.). The full alias table is defined in the Timer Annotation entry of the domain glossary.

• Quantity strings are preserved as-is (e.g. "1 1/2", "0.5", "1/2"). No numeric coercion or arithmetic is performed at the parser level.

• Core's own types are defined in a dedicated types module within @kitchen-md/core and re-exported from the package entry point alongside parse.

Testing Decisions

• All tests assert the public parse function's output. No remark internals, no transform plugin internals, no mdast types appear in tests.

• Unit tests use inline raw strings only — no filesystem access. Each test passes a Recipe File string to parse and asserts the returned Document AST. Coverage must include:

  • Frontmatter passthrough (arbitrary fields, empty frontmatter, no frontmatter)
  • Each Block type: heading (all levels), paragraph, ordered list, unordered list, code block, thematic break
  • Each Inline Node type: plain text, emphasis, strong, code span, link, WikilinkNode, TransclusionNode
  • Ingredient Annotation: name, quantity, unit; multi-word name; unit-less quantity; no quantity
  • Cookware Annotation: name with quantity and unit; name with no quantity; multi-word name
  • Timer Annotation: single value form; range form; all supported unit aliases normalised to canonical form
  • Annotations embedded mid-sentence (not at the start of a line)
  • Annotations inside code spans — not extracted
  • Annotations inside code blocks — not extracted
  • A Step Reference transclusion — anchor passed through as-is

• Integration tests pass the content of fixtures/basic.md through parse and assert the complete Document AST, covering all annotation types, OFM features, and frontmatter together in a single realistic input.

• Tests are co-located with the source module and follow the {module}_test.ts naming convention established in the project scaffold.

Out of Scope

• Quantity arithmetic or numeric normalisation (e.g. 1/2 → 0.5). Quantities are preserved as strings.
• Unit normalisation for Ingredient and Cookware units. Those units are free-form and passed through as-is.
• Step counting and Step Reference resolution. The parser surfaces TransclusionNode with the raw anchor; resolution is a consumer concern.
• Combined Recipe validation.
• Aisle mapping.
• Shopping list generation.
• CLI implementation (covered by the cli-view spec).

Further Notes

• The "built from scratch" statement in the project spec refers to not forking Cooklang's parser. Using remark as an internal dependency is consistent with that intent — see ADR 0002.
• The annotation transform plugin running only on text nodes is what enforces CommonMark scoping for free, without any explicit code-span or code-block detection logic in the plugin itself.
• RawBlock is a safety valve, not a target. Implementation should aim to model all block types that appear in recipe fixtures explicitly.