menuconform 0.1.0

data/schema/menu_ir.schema.json

@@ -0,0 +1,413 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/amitkssolanki/menuconform/main/schema/menu_ir.schema.json",
+  "title": "menuconform Menu IR",
+  "description": "Intermediate representation of a restaurant menu for UCP food-ordering conformance checking. Design principle: this schema validates SHAPE AND TYPES only. It deliberately admits semantically broken menus (negative prices, min_select > max_select, dangling references) so the rule engine can load them and report findings. Referential integrity, ID uniqueness, and the modifier-group nesting depth limit (error above 6, warn above 4) are graph properties checked by STRUCT- rules, not by this schema. v0.2 informed by field study of Uber Eats, DoorDash, Grubhub, and Checkmate menu models (2026-08-30).",
+  "type": "object",
+  "required": ["ir_version", "name", "currency", "timezone", "categories", "items", "modifier_groups", "modifiers"],
+  "properties": {
+    "ir_version": {
+      "const": "0.2",
+      "description": "IR schema version this document conforms to."
+    },
+    "name": {
+      "type": "string",
+      "description": "Display name of the menu (e.g. 'Main Menu', 'Breakfast'). Importers may synthesize one if the source has none. A source location with multiple daypart menus becomes multiple IR documents."
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$",
+      "description": "ISO 4217 currency code. All prices in this document are integers in this currency's minor units (USD: cents). Deliberately required in-document even though delivery platforms carry it out-of-band."
+    },
+    "timezone": {
+      "type": "string",
+      "minLength": 1,
+      "description": "IANA timezone name (e.g. 'America/Chicago') that all availability windows are interpreted in. AVAIL- rules validate that it resolves. Deliberately required in-document even though delivery platforms carry it out-of-band."
+    },
+    "locale": {
+      "type": "string",
+      "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$",
+      "description": "BCP 47 language tag for names and descriptions. Single-locale in IR 0.2. Defaults to en-US.",
+      "default": "en-US"
+    },
+    "availability": {
+      "$ref": "#/$defs/availabilityWindows",
+      "description": "Menu-level service windows. Categories and items may narrow (but conceptually not widen) these; AVAIL- rules check for contradictions."
+    },
+    "special_hours": {
+      "type": "array",
+      "description": "Date-specific exceptions layered over the weekly windows (holidays, one-off closures, extended hours). On a listed date these replace the weekly windows entirely for the whole menu.",
+      "items": { "$ref": "#/$defs/specialHours" }
+    },
+    "source": {
+      "type": "object",
+      "description": "Provenance of this IR document. Informational; surfaced in reports.",
+      "properties": {
+        "system": { "type": "string", "description": "Generic source system label (e.g. 'generic-json', 'generic-csv'). No vendor-proprietary identifiers in public fixtures." },
+        "importer": { "type": "string", "description": "Name/version of the importer that produced this document." },
+        "exported_at": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+    "categories": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/category" }
+    },
+    "items": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/item" }
+    },
+    "modifier_groups": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/modifierGroup" }
+    },
+    "modifiers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/modifier" }
+    }
+  },
+  "patternProperties": { "^x_": {} },
+  "additionalProperties": false,
+
+  "$defs": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Opaque identifier, unique within its collection (uniqueness checked by STRUCT- rules, not schema). Deliberately unconstrained beyond non-empty: POS exports produce numeric strings, GUIDs, and worse."
+    },
+    "minorUnits": {
+      "type": "integer",
+      "description": "Money as an integer in the menu currency's minor units. Negative values pass schema; PRICE- rules decide whether they are legitimate (e.g. a discounting modifier) or a finding."
+    },
+    "idArray": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/id" }
+    },
+    "isoDate": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "Calendar date YYYY-MM-DD in the menu timezone."
+    },
+
+    "availabilityWindows": {
+      "type": "array",
+      "description": "A set of recurring weekly service windows. Empty array means 'never available' (a finding, but valid shape). Absent means 'inherit from parent scope' (item -> category -> menu -> always).",
+      "items": { "$ref": "#/$defs/availabilityWindow" }
+    },
+    "availabilityWindow": {
+      "type": "object",
+      "required": ["start", "end"],
+      "properties": {
+        "days": {
+          "type": "array",
+          "items": { "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] },
+          "uniqueItems": true,
+          "description": "Days this window applies to. Absent means all seven days."
+        },
+        "start": { "$ref": "#/$defs/timeOfDay" },
+        "end": {
+          "$ref": "#/$defs/timeOfDay",
+          "description": "End time. '24:00' is accepted as end-of-day. end < start means the window crosses midnight into the following day."
+        },
+        "start_date": {
+          "$ref": "#/$defs/isoDate",
+          "description": "First calendar date this window is in effect (inclusive). Absent = no lower bound. Supports seasonal/LTO windows (all four studied platforms have date-bounded availability)."
+        },
+        "end_date": {
+          "$ref": "#/$defs/isoDate",
+          "description": "Last calendar date this window is in effect (inclusive). Absent = no upper bound."
+        }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+    "specialHours": {
+      "type": "object",
+      "required": ["date"],
+      "properties": {
+        "date": { "$ref": "#/$defs/isoDate" },
+        "closed": {
+          "type": "boolean",
+          "default": false,
+          "description": "true = closed on this date (all day, or between start/end if given). false = open per the start/end given, replacing the weekly windows."
+        },
+        "start": { "$ref": "#/$defs/timeOfDay" },
+        "end": { "$ref": "#/$defs/timeOfDay" }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+    "timeOfDay": {
+      "type": "string",
+      "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$",
+      "description": "Local wall-clock time HH:MM in the menu timezone."
+    },
+
+    "category": {
+      "type": "object",
+      "required": ["id", "name", "item_ids"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "item_ids": {
+          "$ref": "#/$defs/idArray",
+          "description": "Ordered item references. An item may appear in multiple categories. Empty is valid shape (STRUCT- finding)."
+        },
+        "availability": { "$ref": "#/$defs/availabilityWindows" }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+
+    "item": {
+      "type": "object",
+      "required": ["id", "name", "price"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "price": {
+          "$ref": "#/$defs/minorUnits",
+          "description": "Base price, required and explicit. 0 is legitimate for items priced entirely through modifiers (e.g. pizza priced by size selection); PRICE-/CART- rules verify a positive total is reachable."
+        },
+        "active": {
+          "type": "boolean",
+          "default": true,
+          "description": "Menu-authored state: false = intentionally not orderable. Distinct from suspended_until (operational 86ing) — all four studied platforms separate these."
+        },
+        "suspended_until": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Operationally 86'd until this instant (ISO 8601). A timestamp in the past means not suspended (idempotent auto-recovery, per Checkmate/Uber convention). Absent = not suspended."
+        },
+        "modifier_group_ids": {
+          "$ref": "#/$defs/idArray",
+          "description": "Modifier groups attached directly to the item (nesting depth 1)."
+        },
+        "slots": {
+          "type": "array",
+          "description": "Half/half (or n-way split) construct. Each slot is a named portion of the item carrying its own modifier groups. When present, slot_pricing is required. No studied platform has a first-class equivalent — exporters lower slots to nested-group conventions.",
+          "items": { "$ref": "#/$defs/slot" }
+        },
+        "slot_pricing": {
+          "enum": ["proportional", "full_price", "max_slot"],
+          "description": "How a priced modifier applied to a slot contributes to the item total. proportional: modifier price x slot fraction, rounded half-up per selection. full_price: full modifier price regardless of slot. max_slot: for each modifier group shared across slots, charge as if the most expensive slot's selections applied to the whole item. All three exist in the wild. Applied AFTER conditional-price resolution."
+        },
+        "availability": { "$ref": "#/$defs/availabilityWindows" },
+        "fulfillment_modes": {
+          "type": "array",
+          "items": { "enum": ["pickup", "delivery", "dine_in"] },
+          "uniqueItems": true,
+          "description": "Modes this item may be ordered through. Absent means all. Availability gating only — per-mode pricing is out of scope: importers materialize one IR document per priced channel (Checkmate precedent)."
+        },
+        "allergens": { "$ref": "#/$defs/allergenInfo" },
+        "dietary": { "$ref": "#/$defs/dietaryList" },
+        "min_age": {
+          "type": "integer",
+          "description": "Minimum purchaser age in years (21 = US alcohol, 18 = tobacco). Absent means unrestricted. AGE- rules key off this."
+        },
+        "calories": { "$ref": "#/$defs/calorieRange" },
+        "external_ids": { "$ref": "#/$defs/externalIds" }
+      },
+      "dependentRequired": {
+        "slots": ["slot_pricing"]
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+
+    "slot": {
+      "type": "object",
+      "required": ["id", "name", "fraction", "modifier_group_ids"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string", "description": "e.g. 'Left Half', 'Right Half'." },
+        "fraction": {
+          "type": "number",
+          "description": "Portion of the whole item this slot represents (0.5 for a half). Used by proportional slot pricing. Rules check fractions sum to 1."
+        },
+        "modifier_group_ids": { "$ref": "#/$defs/idArray" }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+
+    "modifierGroup": {
+      "type": "object",
+      "required": ["id", "name", "min_select", "max_select", "options"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string" },
+        "min_select": {
+          "type": "integer",
+          "description": "Minimum number of DISTINCT options that must be selected (v0.2 redefinition — radio/checkbox semantics; all three major platforms constrain distinct-option counts and total units as separate axes). 0 = optional group. Negative passes schema; CONFLICT- rules flag it."
+        },
+        "max_select": {
+          "type": ["integer", "null"],
+          "description": "Maximum number of DISTINCT options selectable. null = unlimited. Required so importers must state it explicitly rather than us guessing a default."
+        },
+        "min_total_units": {
+          "type": "integer",
+          "description": "Minimum total selection units across all options (a quantity of 2 of one option counts as 2). Absent = unconstrained. Second constraint axis, alongside distinct-option min_select/max_select."
+        },
+        "max_total_units": {
+          "type": ["integer", "null"],
+          "description": "Maximum total selection units across all options. null = unlimited. Absent = unconstrained."
+        },
+        "included_quantity": {
+          "type": "integer",
+          "default": 0,
+          "description": "First N free within this group; selections beyond N are charged at their resolved option price. What N counts is set by included_counting; which selections go free is set by included_allocation. 0 = nothing included. Values exceeding the group's maxima or negative pass schema; CONFLICT- rules flag them."
+        },
+        "included_counting": {
+          "enum": ["units", "options"],
+          "default": "units",
+          "description": "What included_quantity counts: 'units' = total selection units (Uber charge_above style); 'options' = distinct options, all units of a free option are free (DoorDash num_free_options style)."
+        },
+        "included_allocation": {
+          "enum": ["cheapest_first", "most_expensive_first"],
+          "default": "cheapest_first",
+          "description": "Which selections the free allocation covers. Default cheapest_first — the only allocation order any studied platform documents (DoorDash). The cart solver depends on this being pinned."
+        },
+        "options": {
+          "type": "array",
+          "description": "The selectable options. Empty is valid shape; CONFLICT- rules flag a required group with no options.",
+          "items": { "$ref": "#/$defs/option" }
+        }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+
+    "option": {
+      "type": "object",
+      "required": ["modifier_id"],
+      "properties": {
+        "modifier_id": { "$ref": "#/$defs/id" },
+        "price_override": {
+          "$ref": "#/$defs/minorUnits",
+          "description": "Overrides the modifier's base price within this group only. POS systems price the same modifier differently per group ('Cheese' free on a burger, 150 on fries). Precedence: matched conditional_prices > price_override > modifier.price."
+        },
+        "conditional_prices": {
+          "type": "array",
+          "description": "Price matrix keyed by a sibling selection: this option costs `price` when the option `when_modifier_id` is selected on the same item (topping-by-size, combo upsell priced by base combo size — Aloha-style price levels lower to this). Constraint enforced by CONFLICT- rules, not schema: every when_modifier_id in one option's list must reference options of a single max_select:1 group attached to the same item, so at most one entry can match. Unmatched -> fall back to price_override/base price. Slot pricing applies after resolution.",
+          "items": { "$ref": "#/$defs/conditionalPrice" }
+        },
+        "default_quantity": {
+          "type": "integer",
+          "default": 0,
+          "description": "Units of this option pre-selected when the item is added (replaces v0.1 boolean is_default; DoorDash recipes and Grubhub default_units have quantity defaults > 1). 0 = not a default. The cart solver's default cart starts from these."
+        },
+        "min_quantity": {
+          "type": "integer",
+          "default": 0,
+          "description": "Minimum units of this option IF it is selected at all (0 = no minimum)."
+        },
+        "max_quantity": {
+          "type": "integer",
+          "default": 1,
+          "description": "Maximum units of this option in one selection (extra-extra cheese). Each unit counts toward the group's total-unit constraints."
+        },
+        "child_modifier_group_ids": {
+          "$ref": "#/$defs/idArray",
+          "description": "Nested modifier groups presented when this option is selected. Attached at the option (link) level, not the modifier, because POS systems attach follow-up questions per context ('Fries' asks for size as a combo side but not a la carte). Depth counted from the item: item->group is 1. STRUCT- rules flag depth > 6 as error and depth > 4 as warn (DoorDash's canonical pizza pattern is 4 deep; Uber demonstrates 6; Grubhub documents 6)."
+        }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+
+    "conditionalPrice": {
+      "type": "object",
+      "required": ["when_modifier_id", "price"],
+      "properties": {
+        "when_modifier_id": {
+          "$ref": "#/$defs/id",
+          "description": "The triggering option's modifier id in the single-select trigger group."
+        },
+        "price": { "$ref": "#/$defs/minorUnits" }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+
+    "modifier": {
+      "type": "object",
+      "required": ["id", "name", "price"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "price": {
+          "$ref": "#/$defs/minorUnits",
+          "description": "Base price adjustment, required and explicit (0 = free). Negative is a discounting modifier ('No cheese -50'); PRICE- rules decide if the resulting totals stay sane."
+        },
+        "active": {
+          "type": "boolean",
+          "default": true,
+          "description": "Menu-authored state; see item.active."
+        },
+        "suspended_until": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Operationally 86'd until this instant; see item.suspended_until."
+        },
+        "allergens": { "$ref": "#/$defs/allergenInfo" },
+        "dietary": { "$ref": "#/$defs/dietaryList" },
+        "min_age": { "type": "integer" },
+        "calories": { "$ref": "#/$defs/calorieRange" },
+        "external_ids": { "$ref": "#/$defs/externalIds" }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+
+    "allergenInfo": {
+      "type": "object",
+      "properties": {
+        "contains": { "$ref": "#/$defs/allergenList" },
+        "may_contain": { "$ref": "#/$defs/allergenList" },
+        "notes": { "type": "string", "description": "Free-text allergen statement from the source when it doesn't map to the enum." }
+      },
+      "patternProperties": { "^x_": {} },
+      "additionalProperties": false
+    },
+    "allergenList": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "milk", "eggs", "fish", "shellfish", "tree_nuts", "peanuts", "wheat", "soy", "sesame",
+          "gluten", "crustaceans", "molluscs", "celery", "mustard", "lupin", "sulphites"
+        ],
+        "description": "Union of the US FASTER Act big-9 and the EU-14 allergen vocabularies (Square's catalog standardized on EU-14; interop requires both). US declarations typically use the first nine; wheat vs gluten and shellfish vs crustaceans/molluscs are distinct entries because the regimes split them differently."
+      }
+    },
+    "dietaryList": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": ["vegan", "vegetarian", "gluten_free"],
+        "description": "Dietary absence-claims (distinct from allergens, which are contains-claims). The intersection supported by all three major US delivery platforms."
+      }
+    },
+
+    "calorieRange": {
+      "type": "object",
+      "required": ["lower"],
+      "properties": {
+        "lower": { "type": "integer" },
+        "upper": { "type": "integer", "description": "Absent means exact value = lower." }
+      },
+      "additionalProperties": false,
+      "description": "kcal, as a range to match US menu-labeling practice for variable items."
+    },
+
+    "externalIds": {
+      "type": "object",
+      "description": "Source-system identifiers keyed by a neutral label (e.g. 'plu', 'sku', 'pos_id'). Vendor field mappings live in importer config, never here.",
+      "additionalProperties": { "type": "string" }
+    }
+  }
+}

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: menuconform
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Amit Solanki
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Checks whether an AI agent could build a valid, correctly priced, makeable
+  cart from a restaurant menu under the UCP Food Ordering catalog/cart model. Scored
+  report with per-rule findings and fix hints.
+email:
+- amitkssolanki@gmail.com
+executables:
+- menuconform
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- config/importers/ncr_menu.json
+- exe/menuconform
+- lib/menuconform.rb
+- lib/menuconform/catalog.rb
+- lib/menuconform/cli.rb
+- lib/menuconform/engine.rb
+- lib/menuconform/finding.rb
+- lib/menuconform/importers.rb
+- lib/menuconform/importers/base.rb
+- lib/menuconform/importers/ncr_menu.rb
+- lib/menuconform/menu.rb
+- lib/menuconform/report.rb
+- lib/menuconform/rules/age_rules.rb
+- lib/menuconform/rules/allergen_rules.rb
+- lib/menuconform/rules/avail_rules.rb
+- lib/menuconform/rules/cart_rules.rb
+- lib/menuconform/rules/conflict_rules.rb
+- lib/menuconform/rules/name_rules.rb
+- lib/menuconform/rules/price_rules.rb
+- lib/menuconform/rules/struct_rules.rb
+- lib/menuconform/scorer.rb
+- lib/menuconform/solver.rb
+- lib/menuconform/ucp_exporter.rb
+- lib/menuconform/version.rb
+- rules/catalog.json
+- schema/menu_ir.schema.json
+homepage: https://github.com/amitkssolanki/menuconform
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: UCP food-ordering menu conformance kit
+test_files: []