soustack 0.2.3 → 0.4.0

package/README.md

@@ -37,7 +37,7 @@ npm install soustack
 
 ## What's Included
 
-- **Validation**: `validateRecipe()` validates Soustack JSON against the bundled schema.
+- **Validation**: `validateRecipe()` validates Soustack JSON against the bundled schema and optional conformance checks.
 - **Scaling & Computation**: `scaleRecipe()` scales a recipe while honoring per-ingredient scaling rules and instruction timing.
 - **Schema.org Conversion**:
   - `fromSchemaOrg()` (Schema.org JSON-LD → Soustack)
@@ -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
 
@@ -53,36 +54,87 @@ Validate and scale a recipe in just a few lines:
 ```ts
 import { validateRecipe, scaleRecipe } from 'soustack';
 
-// Validate against the bundled Soustack schema
-const { valid, errors, warnings } = validateRecipe(recipe);
-if (!valid) {
-  throw new Error(JSON.stringify(errors, null, 2));
+// Validate against the bundled Soustack schema + conformance rules
+const { ok, schemaErrors, conformanceIssues, warnings } = validateRecipe(recipe);
+if (!ok) {
+  throw new Error(JSON.stringify({ schemaErrors, conformanceIssues }, null, 2));
 }
 if (warnings?.length) {
   console.warn('Non-blocking warnings', warnings);
 }
 
+// Schema-only validation (skip conformance checks)
+const schemaOnly = validateRecipe(recipe, { mode: 'schema' });
+if (!schemaOnly.ok) {
+  console.error(schemaOnly.schemaErrors);
+}
+
 // Scale to a new yield (multiplier, target yield, or servings)
 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:
+- **base**
+- **equipped**
+- **illustrated**
+- **lite**
+- **prepped**
+- **scalable**
+- **timed**
 
 ```ts
 import { detectProfiles, validateRecipe } from 'soustack';
 
 // Discover which profiles a recipe already satisfies
-const profiles = detectProfiles(recipe); // e.g. ['block']
+const profiles = detectProfiles(recipe);
 
-// Validate while requiring specific profiles
-const result = validateRecipe(recipe, { profiles: ['block', 'integrator'] });
-if (!result.valid) {
-  console.error('Profile validation failed', result.errors);
+// Validate with a specific profile
+const result = validateRecipe(recipe, { profile: 'base' });
+if (!result.ok) {
+  console.error('Profile validation failed', result.schemaErrors);
 }
+
+// Validate with modules
+const recipeWithModules = {
+  profile: 'base',
+  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 + 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 +144,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., `base` or `lite`)
+- **Module overlays**: Each declared module adds its own validation rules
+
+**Defaults:**
+- If `profile` is missing, it defaults to the schema bundle's configured default
+- 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
+- `allowedOnLite`: Whether the module can be used with the lite 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 timed profile, includes instruction dependencies)
+
 ## Programmatic Usage
 
 ```ts
@@ -113,9 +215,9 @@ import {
 } from 'soustack/scrape';
 
 // Validate a Soustack recipe JSON object with profile enforcement
-const validation = validateRecipe(recipe, { profiles: ['block'] });
-if (!validation.valid) {
-  console.error(validation.errors);
+const validation = validateRecipe(recipe, { profile: 'base' });
+if (!validation.ok) {
+  console.error({ schemaErrors: validation.schemaErrors, conformanceIssues: validation.conformanceIssues });
 }
 
 // Scale a recipe to a target yield amount (returns a "computed recipe")
@@ -167,6 +269,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 **lite 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';
 
@@ -268,10 +372,16 @@ const parsed = extractRecipeFromHTML(html);
 
 ```bash
 # Validate with profiles (JSON output for pipelines)
-npx soustack validate recipe.soustack.json --profile block --strict --json
+npx soustack validate recipe.soustack.json --profile base --strict --json
+
+# Schema-only validation (skip semantic conformance checks)
+npx soustack validate recipe.soustack.json --schema-only
+
+# Stable JSON conformance report for CI
+npx soustack check recipe.soustack.json --json
 
 # Repo-wide test run (validates every *.soustack.json)
-npx soustack test --profile block
+npx soustack test --profile base
 
 # Convert Schema.org ↔ Soustack
 npx soustack convert --from schemaorg --to soustack recipe.jsonld -o recipe.soustack.json