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 single pure, total function that accepts a Recipe File string and returns a Document AST.
It never throws — every input produces a usable Document AST, and the one class of genuinely invalid input (malformed frontmatter YAML) is reported through a diagnostics channel rather than as an exception (see ADR 0004).
Internally the Parser uses remark with a deliberately minimal plugin set to handle CommonMark and OFM, runs a custom annotation transform to surface Ingredient, Cookware, and Timer nodes, and exposes a clean public API built entirely from core's own types — no remark internals leak through (see ADR 0003).

## 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 `parse` to never throw and to report malformed frontmatter as a diagnostic so that I never have to wrap it in `try`/`catch`, yet can still distinguish a broken frontmatter block from an absent one.
4. As a tooling user, I want heading blocks in the Document AST so that I can render or reason about document structure.
5. 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.
6. As a tooling user, I want list blocks with ordered and unordered variants, whose items are containers holding blocks, so that recipe steps written as lists are represented faithfully and annotations inside them are still extracted.
7. As a tooling user, I want blockquote blocks modelled as containers so that prose and annotations inside blockquotes and callouts are preserved and extracted rather than lost.
8. 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.
9. As a tooling user, I want any OFM construct the parser does not model preserved verbatim as a raw block or raw inline so that no source is ever discarded and a document round-trips unchanged.
10. As a tooling user, I want wikilinks represented as typed Inline Nodes so that I can render or process `[[links]]` distinctly from plain text.
11. As a tooling user, I want transclusions — including KitchenMD Step References — represented as typed Inline Nodes so that tooling can resolve them.
12. 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.
13. As a tooling user, I want Cookware Annotations represented as Inline Nodes carrying name, quantity, and unit so that I can extract equipment requirements.
14. 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.
15. As a tooling user, I want ingredient and cookware units matching a known alias normalised to a canonical abbreviation, with unknown units passed through unchanged, so that I get consistent units for aggregation without losing unusual free-form ones.
16. 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.
17. 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 — and a total function that never throws (see ADR 0004).

- `DocumentAST` top-level shape: `{ frontmatter, blocks, diagnostics }`.
  - `frontmatter` — the raw parsed YAML metadata as a plain object, passed through without schema enforcement.
    Empty object when no frontmatter is present, and also empty when the frontmatter block is present but invalid.
  - `blocks` — a flat, ordered array of Block nodes representing the document body.
    The array is flat at the top level: headings are siblings of their following content, not parents of it.
    Container blocks (list items, blockquotes) nest their own child blocks; the flatness applies to the top level, not inside containers.
    See ADR 0003 and the Document AST entry in the domain glossary.
  - `diagnostics` — an ordered array of non-fatal Diagnostic warnings surfaced during parsing.
    Empty in the normal case.

- **Total function and diagnostics** (see ADR 0004):
  - `parse` never throws.
    Genuinely invalid input is reported through `diagnostics`, not exceptions, so a consumer always receives a usable Document AST.
  - The only diagnostic emitted today is `invalid-frontmatter`: when the `---` block is present but not valid YAML, the body still parses, `frontmatter` is `{}`, and the raw YAML plus the parse error are preserved in the diagnostic.
  - A `Diagnostic` has the shape `{ severity, code, message, source?, position? }`.
    `severity` is a level such as `"warning"`; `code` is a stable machine-readable identifier (e.g. `"invalid-frontmatter"`); `message` is human-readable; `source` preserves the offending raw text verbatim; `position` locates it in the input.
    `Diagnostic` is a public API type; adding new codes later is additive and non-breaking.

- **Block types** (initial set):
  - `HeadingBlock` — level (1–6) and an inline content array.
  - `ParagraphBlock` — an inline content array.
  - `ListBlock` — an ordered flag and an array of `ListItemBlock`.
  - `ListItemBlock` — a container block holding a `Block[]`.
    A list item wraps its own child blocks (typically a paragraph), not a bare inline array, so `- a $ladle{}` becomes a list item containing a paragraph.
    This mirrors how CommonMark models list items and is what lets annotation extraction reach inside them.
  - `BlockquoteBlock` — a container block holding a `Block[]`.
    OFM callouts (`> [!note]`) carry no dedicated node; they parse as ordinary blockquotes whose text is preserved, and annotations inside them are extracted like any other container content.
  - `CodeBlock` — optional language identifier and a literal text string.
    Annotation parsing does not run on code block content.
  - `ThematicBreakBlock` — no content fields.
  - `RawBlock` — the block-level raw fallback for any remark node type not explicitly modelled above (see ADR 0005).
    It exposes a single `value` string and nothing else — no `kind` or type hint.
    `value` is captured by position-slicing the original input, so it is byte-for-byte what the author wrote and round-trips unchanged.

- **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, anchor?, display? }`.
    `target` is the filename without extension; `anchor` is the part after `#`, passed through verbatim; `display` is the alias after `|`.
    Covers `[[link]]`, `[[link#heading]]`, and `[[link|display]]`.
  - `TransclusionNode` — the same `{ target, anchor?, display? }` shape as `WikilinkNode`, but a distinct node type marking an embed (`![[…]]`).
    The node type — not a boolean flag — is the discriminator between a reference and an embed.
    Covers `![[link]]`, `![[link#heading]]`, `![[link|alt]]`, and KitchenMD Step References (`![[file#section:N]]` and `![[file#N]]`), whose 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.
  - `RawInline` — the inline-level raw fallback for any remark inline node type not explicitly modelled above (see ADR 0005).
    Like `RawBlock`, it exposes only a position-sliced verbatim `value` string and no `kind` hint.

- The internal remark plugin set is deliberately minimal (see ADR 0002 and ADR 0005): `remark-parse` + `remark-frontmatter` + `remark-gfm` (tables, task lists, strikethrough, autolinks) + `remark-wiki-link` (links and embeds), plus core's own annotation transform.
  Most other OFM syntax needs no dedicated plugin: `==highlight==`, `%%comment%%`, `$math$`, and `$$block math$$` are left as literal text with their markers intact, and callouts parse as ordinary blockquotes.
  Anything remark tokenises into a node core does not model (e.g. a GFM table, strikethrough) falls through to `RawBlock` or `RawInline`.
  remark types do not appear in `@kitchen-md/core`'s public API; an internal translation layer maps remark's mdast output to core's own types before returning, recursing into container children rather than collapsing them.

- 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.
  Annotation parsing naturally respects CommonMark inline scoping: the transform operates only on mdast text nodes, which do not appear inside code spans, code blocks, HTML comments, or raw HTML blocks, so no additional scoping logic is required.
  Because it only rewrites text nodes (which are always modelled, never raw), it does not invalidate the parse positions the raw fallbacks depend on.

- The Ingredient/Cookware quantity/unit split is grammar-driven, not last-space-driven.
  The quantity is matched greedily against the numeric grammar (mixed number → fraction → decimal → integer) anchored at the start of the braces, and any non-empty remainder after the delimiting space is the unit.
  If the brace content does not begin with a grammar-valid quantity (e.g. `@stock{a splash}`), the entire content is preserved as the quantity string and the unit is left empty, so no annotation is dropped.
  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.

- **Ingredient and Cookware unit normalisation** (see ADR 0006):
  - A unit whose text matches a known alias is normalised to its canonical abbreviation; any unit not in the table is passed through verbatim (original casing and spacing preserved).
  - Lookup is case-insensitive; the node stores only the canonical unit — the author's original spelling is not retained.
  - Multi-word aliases match on the whole unit remainder (e.g. `200 fluid ounces` → unit `fl oz`).
  - Alias table (case-insensitive; anything unlisted passes through unchanged):

    | Canonical | Aliases |
    |-----------|---------|
    | `g`     | g, gram, grams |
    | `kg`    | kg, kilogram, kilograms, kilo, kilos |
    | `mg`    | mg, milligram, milligrams |
    | `oz`    | oz, ounce, ounces |
    | `lb`    | lb, lbs, pound, pounds |
    | `ml`    | ml, milliliter, millilitre, milliliters, millilitres |
    | `l`     | l, liter, litre, liters, litres |
    | `tsp`   | tsp, teaspoon, teaspoons |
    | `tbsp`  | tbsp, tablespoon, tablespoons |
    | `cup`   | cup, cups |
    | `fl oz` | fl oz, fluid ounce, fluid ounces |
    | `pt`    | pt, pint, pints |
    | `qt`    | qt, quart, quarts |
    | `gal`   | gal, gallon, gallons |

  - Single-letter cooking abbreviations (`t`, `T`, `c`) are intentionally excluded — they are ambiguous and would collide under case-insensitive lookup.
    Count and descriptive units (`clove`, `pinch`, `dash`, `can`, `large`, `to taste`) have no canonical form and pass through unchanged.

- **Timer unit normalisation**: aliases are normalised to canonical abbreviations at parse time, using the same case-insensitive matching as ingredient/cookware units (see ADR 0006).
  Alias table (case-insensitive):

  | Canonical | Aliases |
  |-----------|---------|
  | `s`   | sec, secs, second, seconds |
  | `min` | min, mins, minute, minutes |
  | `hr`  | hr, hrs, hour, hours |

  The unit matches only as a complete word and the longest known alias wins; `~5 minsx` is not a timer because `minsx` is not a known unit.

- 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)
  - Malformed frontmatter — `parse` does not throw, `frontmatter` is `{}`, body still parses, and an `invalid-frontmatter` diagnostic is emitted with the raw YAML preserved
  - Each Block type: heading (all levels), paragraph, ordered list, unordered list, code block, thematic break, blockquote
  - `ListItemBlock` wraps a paragraph (a list item holds child blocks, not a bare inline array)
  - Annotation extraction inside a container (an annotation inside a blockquote or list item is surfaced)
  - Each Inline Node type: plain text, emphasis, strong, code span, link, `WikilinkNode`, `TransclusionNode`
  - `WikilinkNode` with an anchor and with a display alias; `TransclusionNode` with a display alias
  - A remark node core does not model falls through to `RawBlock` (block level, e.g. a GFM table) and `RawInline` (inline level), with the verbatim source preserved
  - 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
  - Ingredient/Cookware unit normalisation: a known alias normalised to canonical (`grams` → `g`, `Tbsp` → `tbsp`), case-insensitive matching, a multi-word unit (`fluid ounces` → `fl oz`), and an unknown unit passed through verbatim
  - Timer unit matching is case-insensitive (`~5 Mins` → `min`)
  - 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 (including a blockquote with an annotation and a non-canonical unit that normalises), 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.
- 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` and `RawInline` are safety valves, not targets.
  The implementation models every construct that appears in recipe fixtures explicitly and lets only genuinely unmodelled syntax fall through to a raw node.
  Their verbatim `value` is captured by position-slicing the original input — never re-stringified — so unmodelled constructs round-trip byte-for-byte.