soustack 0.2.3 → 0.3.0

package/README.md

@@ -45,6 +45,7 @@ npm install soustack
 - **Web Extraction**:
   - Browser-safe HTML parsing: `extractSchemaOrgRecipeFromHTML()` (convert to Soustack with `fromSchemaOrg()`)
   - Node-only scraping entrypoint: `scrapeRecipe()` and helpers via `import { ... } from 'soustack/scrape'`
+- **Unit Conversion**: `convertLineItemToMetric()` converts ingredient line items from imperial volumes/masses into metric with deterministic rounding and ingredient-aware equivalencies.
 
 ## 🚀 Quickstart
 
@@ -68,21 +69,61 @@ const scaled = scaleRecipe(recipe, { multiplier: 2 });
 
 ### Profile-aware validation
 
-Use profiles to enforce integration contracts (e.g., **Block** vs **Integrator** payloads).
+Use profiles to enforce integration contracts. Available profiles:
+- **minimal**: Basic recipe structure with minimal requirements
+- **core**: Enhanced profile with structured ingredients and instructions
 
 ```ts
 import { detectProfiles, validateRecipe } from 'soustack';
 
 // Discover which profiles a recipe already satisfies
-const profiles = detectProfiles(recipe); // e.g. ['block']
+const profiles = detectProfiles(recipe); // e.g. ['minimal', 'core']
 
-// Validate while requiring specific profiles
-const result = validateRecipe(recipe, { profiles: ['block', 'integrator'] });
+// Validate with a specific profile (defaults to 'core' if not specified)
+const result = validateRecipe(recipe, { profile: 'minimal' });
 if (!result.valid) {
   console.error('Profile validation failed', result.errors);
 }
+
+// Validate with modules
+const recipeWithModules = {
+  profile: 'minimal',
+  modules: ['nutrition@1', 'times@1'],
+  name: 'Test Recipe',
+  ingredients: ['1 cup flour'],
+  instructions: ['Mix'],
+  nutrition: { calories: 100, protein_g: 5 }, // Module payload required if declared
+  times: { prepMinutes: 10, cookMinutes: 20, totalMinutes: 30 }, // v0.3: uses *Minutes fields
+};
+const result2 = validateRecipe(recipeWithModules);
+// Validates using: base + minimal profile + nutrition@1 module + times@1 module
+// Module contract: if module is declared, payload must exist (and vice versa)
+```
+
+### Imperial → metric ingredient conversion
+
+```ts
+import { convertLineItemToMetric } from 'soustack';
+
+const flour = convertLineItemToMetric(
+  { ingredient: 'flour', quantity: 2, unit: 'cup' },
+  'mass'
+);
+// -> { ingredient: 'flour', quantity: 240, unit: 'g', notes: 'Converted using 120g per cup...' }
+
+const liquid = convertLineItemToMetric(
+  { ingredient: 'milk', quantity: 2, unit: 'cup' },
+  'volume'
+);
+// -> { ingredient: 'milk', quantity: 473, unit: 'ml' }
 ```
 
+The converter rounds using “sane” defaults (1 g/ml under 1 kg/1 L, then 5 g/10 ml and 2 decimal places for kg/L) and surfaces typed errors:
+
+- `UnknownUnitError` for unsupported unit tokens
+- `UnsupportedConversionError` if you request a mismatched dimension
+- `MissingEquivalencyError` when no volume→mass density is registered for the ingredient/unit combo
+
 ### Browser-safe vs. Node-only entrypoints
 
 - **Browser-safe:** `import { extractSchemaOrgRecipeFromHTML, fromSchemaOrg, validateRecipe, scaleRecipe } from 'soustack';`
@@ -92,10 +133,60 @@ if (!result.valid) {
 
 ## Spec compatibility & bundled schemas
 
-- Targets Soustack spec **v0.2.1** (`spec/SOUSTACK_SPEC_VERSION`, exported as `SOUSTACK_SPEC_VERSION`).
-- Ships the base schema plus profile schemas in `spec/` and mirrors them into `src/` for consumers.
+- Targets Soustack spec **v0.3.0** (`spec/SOUSTACK_SPEC_VERSION`, exported as `SOUSTACK_SPEC_VERSION`).
+- Ships the base schema, profile schemas, and module schemas in `spec/schemas/recipe/` and mirrors them into `src/schemas/recipe/` for consumers.
 - Vendored fixtures live in `spec/fixtures` so tests can run offline, and version drift can be checked via `npm run validate:version`.
 
+### Composed Validation Model
+
+Soustack v0.3.0 uses a **composed validation model** where recipes are validated using JSON Schema's `allOf` composition:
+
+```json
+{
+  "allOf": [
+    { "$ref": "base.schema.json" },
+    { "$ref": "profiles/{profile}.schema.json" },
+    { "$ref": "modules/{module1}/{version}.schema.json" },
+    { "$ref": "modules/{module2}/{version}.schema.json" }
+  ]
+}
+```
+
+The validator:
+- **Base schema**: Defines the core recipe structure (`@type`, `name`, `ingredients`, `instructions`, `profile`, `modules`)
+- **Profile overlay**: Adds profile-specific requirements (e.g., `minimal` or `core`)
+- **Module overlays**: Each declared module adds its own validation rules
+
+**Defaults:**
+- If `profile` is missing, it defaults to `"core"`
+- If `modules` is missing, it defaults to `[]`
+
+**Module Contract:** Modules enforce a symmetric contract:
+- If a module is declared in `modules`, the corresponding payload must exist
+- If a payload exists (e.g., `nutrition`, `times`), the module must be declared
+- The validator automatically infers modules from payloads and enforces this contract
+
+**Caching:** Validators are cached by `${profile}::${sortedModules.join(",")}` for performance.
+
+### Module Resolution
+
+Modules are resolved to schema references using the pattern:
+- Module identifier format: `<name>@<version>` (e.g., `nutrition@1`, `schedule@1`)
+- Schema reference: `https://soustack.org/schemas/recipe/modules/<name>/<version>.schema.json`
+
+The module registry (`schemas/registry/modules.json`) defines which modules are available and their properties, including:
+- `schemaOrgMappable`: Whether the module can be converted to Schema.org format
+- `minProfile`: Minimum profile required to use the module
+- `allowedOnMinimal`: Whether the module can be used with the minimal profile
+
+**Available Modules (v0.3.0):**
+- `attribution@1`: Source attribution (url, author, datePublished)
+- `taxonomy@1`: Classification (keywords, category, cuisine)
+- `media@1`: Images and videos (images, videos arrays)
+- `times@1`: Timing information (prepMinutes, cookMinutes, totalMinutes)
+- `nutrition@1`: Nutritional data (calories, protein_g as numbers)
+- `schedule@1`: Task scheduling (requires core profile, includes instruction dependencies)
+
 ## Programmatic Usage
 
 ```ts
@@ -113,7 +204,7 @@ import {
 } from 'soustack/scrape';
 
 // Validate a Soustack recipe JSON object with profile enforcement
-const validation = validateRecipe(recipe, { profiles: ['block'] });
+const validation = validateRecipe(recipe, { profile: 'core' });
 if (!validation.valid) {
   console.error(validation.errors);
 }
@@ -167,6 +258,8 @@ async function convert(url: string) {
 
 Use the helpers to move between Schema.org JSON-LD and Soustack's structured recipe format. The conversion automatically handles image normalization, supporting multiple image formats from Schema.org.
 
+**BREAKING CHANGE in v0.3.0:** `toSchemaOrg()` now targets the **minimal profile** and only includes modules that are marked as `schemaOrgMappable` in the modules registry. Non-mappable modules (e.g., `nutrition@1`, `schedule@1`) are excluded from the conversion.
+
 ```ts
 import { fromSchemaOrg, toSchemaOrg, normalizeImage } from 'soustack';