soustack 0.3.0 → 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)
@@ -54,15 +54,21 @@ 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 });
 ```
@@ -70,24 +76,29 @@ const scaled = scaleRecipe(recipe, { multiplier: 2 });
 ### Profile-aware validation
 
 Use profiles to enforce integration contracts. Available profiles:
-- **minimal**: Basic recipe structure with minimal requirements
-- **core**: Enhanced profile with structured ingredients and instructions
+- **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. ['minimal', 'core']
+const profiles = detectProfiles(recipe);
 
-// 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 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: 'minimal',
+  profile: 'base',
   modules: ['nutrition@1', 'times@1'],
   name: 'Test Recipe',
   ingredients: ['1 cup flour'],
@@ -96,7 +107,7 @@ const recipeWithModules = {
   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
+// Validates using: base + profile + nutrition@1 module + times@1 module
 // Module contract: if module is declared, payload must exist (and vice versa)
 ```
 
@@ -154,11 +165,11 @@ Soustack v0.3.0 uses a **composed validation model** where recipes are validated
 
 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`)
+- **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 `"core"`
+- 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:
@@ -177,7 +188,7 @@ Modules are resolved to schema references using the pattern:
 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
+- `allowedOnLite`: Whether the module can be used with the lite profile
 
 **Available Modules (v0.3.0):**
 - `attribution@1`: Source attribution (url, author, datePublished)
@@ -185,7 +196,7 @@ The module registry (`schemas/registry/modules.json`) defines which modules are
 - `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)
+- `schedule@1`: Task scheduling (requires timed profile, includes instruction dependencies)
 
 ## Programmatic Usage
 
@@ -204,9 +215,9 @@ import {
 } from 'soustack/scrape';
 
 // Validate a Soustack recipe JSON object with profile enforcement
-const validation = validateRecipe(recipe, { profile: 'core' });
-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")
@@ -258,7 +269,7 @@ 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.
+**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';
@@ -361,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