Doctor | Cooklang: recipe markup language

The doctor command helps maintain a healthy recipe collection by checking for syntax errors, validating references, and ensuring proper organization. Think of it as a health check for your recipes.

Basic Usage

cook doctor

This runs all available checks on your recipe collection and reports any issues found.

Available Checks

Recipe Validation

Check all recipes for syntax errors and warnings:

cook doctor validate

This command:

Detects syntax errors that prevent parsing
Reports warnings about potential issues
Validates recipe references (when one recipe includes another)
Checks for invalid units or quantities
Identifies deprecated syntax

Aisle Configuration

Check for ingredients missing from your aisle configuration:

cook doctor aisle

This helps maintain complete shopping list categorization by finding ingredients that aren't assigned to any store section.

Strict Mode

Use strict mode in CI/CD pipelines:

cook doctor validate --strict
# Exits with error code 1 if any issues found

Great for:

Pre-commit hooks
GitHub Actions
Quality gates

Validate Specific Directory

cook doctor validate -b ~/recipes/italian

Custom Base Path

cook doctor aisle -b ~/my-recipes

Common Issues and Fixes

Syntax Errors

Unknown Timer Units

❌ Wrong: ~{30 mins}
✓ Correct: ~{30%minutes}

Invalid Quantities

❌ Wrong: @flour{a handful}
✓ Correct: @flour{100%g}
✓ Or: @flour{} -- about a handful

Missing Units

❌ Wrong: @salt{2}
✓ Correct: @salt{2%tsp}
✓ Or: @salt{2%pinches}

Warnings

Deprecated Syntax

⚠️  Deprecated:
&gt;&gt; servings: 4
&gt;&gt; time: 30 minutes

✓ Modern:
---
servings: 4
time: 30 minutes
---

Unsupported Metadata

⚠️  Warning: Unknown metadata key &#39;serves&#39;
✓ Use: &#39;servings&#39; instead

Reference Errors

Missing Recipe References

# Main.cook
Include @Pizza Dough.cook  ❌ File doesn&#39;t exist

# Fix: Create Pizza Dough.cook or correct the reference

Circular References

# A.cook includes B.cook
# B.cook includes A.cook
❌ Circular dependency detected

Setting Up CI/CD

GitHub Actions

Create .github/workflows/validate-recipes.yml:

name: Validate Recipes

on:
  push:
    paths:
      - &#39;**.cook&#39;
  pull_request:
    paths:
      - &#39;**.cook&#39;

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install CookCLI
        run: |
          curl -L https://github.com/cooklang/cookcli/releases/latest/download/cook-x86_64-unknown-linux-gnu.tar.gz | tar xz
          sudo mv cook /usr/local/bin/
      
      - name: Validate recipes
        run: cook doctor validate --strict

Batch Fixes

Fix common issues across all recipes:

# Fix timer units
find . -name &#34;*.cook&#34; -exec sed -i &#39;s/~{\([0-9]*\) mins}/~{\1%minutes}/g&#39; {} \;

# Update metadata format
for f in *.cook; do
  # Convert &gt;&gt; metadata to YAML frontmatter
  # (script would go here)
done

Aisle Configuration Management

Creating Aisle Configuration

Generate from existing recipes:

# Extract all ingredients
cook doctor aisle | grep &#34;^  -&#34; | cut -d&#39;-&#39; -f2- &gt; ingredients.txt

# Organize into aisle.conf
cat &gt; config/aisle.conf &lt;&lt; EOF
[produce]
tomatoes
lettuce
onions

[dairy]
milk
cheese
yogurt

[pantry]
flour
sugar
pasta
EOF

Multi-Store Configuration

Different stores have different layouts:

# walmart-aisle.conf
[aisle-1-produce]
vegetables
fruits

# whole-foods-aisle.conf
[organic-produce]
vegetables
fruits

Use appropriate configuration:

cook shopping-list *.cook --aisle walmart-aisle.conf