cooklang-parse 1.1.2 → 1.2.0

package/README.md

@@ -11,8 +11,8 @@
 
 - Full Cooklang spec support including ingredients, cookware, timers, metadata, sections, notes, and YAML frontmatter
 - Written in TypeScript with exported type definitions
-- Single function API — `parseCooklang(source)` returns a structured recipe
-- 188 tests with canonical parity against the [Rust reference implementation](https://github.com/cooklang/cooklang-rs)
+- Single function API with extension presets — `parseCooklang(source, options?)`
+- 235 tests with parity coverage against [cooklang-rs](https://github.com/cooklang/cooklang-rs) canonical and default parser behaviors
 - Source position tracking and parse error reporting
 
 ## Installation
@@ -32,16 +32,31 @@ const recipe = parseCooklang(`
 >> servings: 4
 
 Preheat #oven to 180C.
+
 Mix @flour{250%g} and @eggs{3} in a #bowl{}.
+
 Bake for ~{20%minutes}.
 `)
 
 recipe.metadata    // { servings: 4 }
-recipe.ingredients // [{ type: "ingredient", name: "flour", quantity: 250, units: "g", fixed: false }, ...]
-recipe.cookware    // [{ type: "cookware", name: "oven", quantity: 1, units: "" }, ...]
+recipe.ingredients // [{ type: "ingredient", name: "flour", quantity: 250, units: "g", fixed: false, modifiers: {...}, relation: {...} }, ...]
+recipe.cookware    // [{ type: "cookware", name: "oven", quantity: 1, units: "", modifiers: {...}, relation: {...} }, ...]
 recipe.timers      // [{ type: "timer", name: "", quantity: 20, units: "minutes" }]
-recipe.steps       // [[{ type: "text", value: "Preheat " }, { type: "cookware", ... }, ...], ...]
+recipe.inlineQuantities // [] in canonical mode
 recipe.errors      // [] (parse errors and warnings)
+
+// Steps are organized into sections:
+recipe.sections[0].name    // null (default unnamed section)
+recipe.sections[0].content // array of { type: "step", items: [...] } and { type: "text", value: "..." }
+
+// Each step contains ordered text + inline component tokens:
+const step = recipe.sections[0].content[0] // { type: "step", items: [...] }
+step.items
+// [
+//   { type: "text", value: "Preheat " },
+//   { type: "cookware", name: "oven", quantity: 1, units: "", modifiers: {...}, relation: {...} },
+//   { type: "text", value: " to 180C." }
+// ]
 ```
 
 ## Cooklang Syntax
@@ -61,31 +76,53 @@ recipe.errors      // [] (parse errors and warnings)
 | `== Title ==` | Section header | `== For the sauce ==` |
 | `>> key: value` | Metadata directive | `>> servings: 4` |
 | `---` | YAML frontmatter block | See below |
-| `=@name{qty}` | Fixed quantity (won't scale) | `=@salt{1%tsp}` |
-| `@name{=qty}` | Fixed quantity (alternate) | `@salt{=1%tsp}` |
-| `@name{}(prep)` | Ingredient with preparation | `@flour{100%g}(sifted)` |
+| `@name{=qty%unit}` | Fixed quantity (won't scale) | `@salt{=1%tsp}` |
+| `@name{qty}(note)` | Ingredient with note | `@flour{100%g}(sifted)` |
+| `#name(note)` | Cookware with note | `#pan(large)` |
 | `@name\|alias{}` | Pipe alias syntax | `@ground beef\|beef{}` |
 
 ## API
 
-### `parseCooklang(source: string): CooklangRecipe`
+### `parseCooklang(source: string, options?: ParseCooklangOptions): CooklangRecipe`
 
 Parses a Cooklang source string into a structured recipe object.
 
+```typescript
+interface ParseCooklangOptions {
+  extensions?: "canonical" | "all" // default: "canonical"
+}
+```
+
+- `"canonical"`: canonical/spec behavior (extensions off)
+- `"all"`: cooklang-rs default behavior (modes + inline temperature quantities)
+
 ```typescript
 interface CooklangRecipe {
   metadata: Record<string, unknown>
-  steps: RecipeStepItem[][]
-  ingredients: RecipeIngredient[]
-  cookware: RecipeCookware[]
-  timers: RecipeTimer[]
-  sections: string[]
-  notes: string[]
+  sections: RecipeSection[]        // Sections with interleaved steps and notes
+  ingredients: RecipeIngredient[]  // Deduplicated across all steps
+  cookware: RecipeCookware[]       // Deduplicated across all steps
+  timers: RecipeTimer[]            // Deduplicated across all steps
+  inlineQuantities: Array<{ quantity: number | string; units: string }>
   errors: ParseError[]
+  warnings: ParseError[]
+}
+
+interface RecipeSection {
+  name: string | null              // null for the default unnamed section
+  content: SectionContent[]
 }
+
+type SectionContent =
+  | { type: "step"; items: RecipeStepItem[]; number?: number }
+  | { type: "text"; value: string }          // Notes (> lines)
 ```
 
-**`steps`** is an array of steps, where each step is an array of items:
+**`sections`** contains all recipe content. Each section has a `name` (null for the default section) and `content` — an interleaved array of steps and text (notes). Steps contain ordered `RecipeStepItem[]` arrays with text and typed tokens in document order.
+
+**`ingredients`**, **`cookware`**, and **`timers`** are deduplicated across all steps.
+
+### Types
 
 ```typescript
 type RecipeStepItem =
@@ -93,27 +130,28 @@ type RecipeStepItem =
   | RecipeIngredient
   | RecipeCookware
   | RecipeTimer
-```
-
-**`ingredients`**, **`cookware`**, and **`timers`** are deduplicated across all steps.
-
-### Types
 
-```typescript
 interface RecipeIngredient {
   type: "ingredient"
   name: string
+  alias?: string            // from @name|alias{} syntax
   quantity: number | string
-  units: string
+  units: string             // only % separator: @name{qty%unit}
   fixed: boolean
-  preparation?: string
+  note?: string             // from @name{}(note) syntax
+  modifiers: RecipeModifiers
+  relation: IngredientRelation
 }
 
 interface RecipeCookware {
   type: "cookware"
   name: string
+  alias?: string
   quantity: number | string
-  units: string
+  units: string             // always ""
+  note?: string             // from #name(note) syntax
+  modifiers: RecipeModifiers
+  relation: ComponentRelation
 }
 
 interface RecipeTimer {
@@ -148,10 +186,9 @@ const recipe = parseCooklang(`
 ---
 title: Sourdough Bread
 source: My grandmother
+servings: 2
 ---
 
->> servings: 2
-
 == Starter ==
 Mix @starter{100%g} with @water{100%g}
 Let ferment for ~{8%hours}
@@ -165,18 +202,20 @@ Knead in #mixing bowl{} for ~kneading{10%minutes}
 recipe.metadata
 // { title: "Sourdough Bread", source: "My grandmother", servings: 2 }
 
-recipe.sections
-// ["Starter", "Dough"]
+recipe.sections.map(s => s.name)
+// [null, "Starter", "Dough"]
 
 recipe.ingredients.map(i => `${i.quantity} ${i.units} ${i.name}`.trim())
 // ["100 g starter", "100 g water", "500 g flour", ...]
 ```
 
+> **Note:** With YAML frontmatter (`---`), non-special `>> key: value` lines are treated as regular step text (matching [cooklang-rs](https://github.com/cooklang/cooklang-rs)). In `{ extensions: "all" }`, `[mode]/[define]/[duplicate]` directives still apply as configuration.
+
 ## Development
 
 ```bash
 bun install          # Install dependencies
-bun test             # Run all 188 tests
+bun test             # Run all 235 tests
 bun run build        # Bundle + emit declarations
 bun run typecheck    # Type-check without emitting
 bun run lint         # Lint with Biome

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { grammar, parseCooklang } from "./semantics";
+export { parseCooklang } from "./parse-cooklang";
+export { grammar } from "./parser/ohm-ast";
 export type * from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACpD,mBAAmB,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC1C,mBAAmB,SAAS,CAAA"}