menuconform 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 497b0ace6a30de42bc5d0d494ae7c9e23206331407902b3a84a3636d809c40d0
-  data.tar.gz: cea2dfe8a743d55e2957381401d666eee1fb4bf339dabe3f147b37e938ae9ee2
+  metadata.gz: d7ec9be4b3e1a835ffc1fe2c723c22208ac41ab9826560c3cbc32238dc10bd8e
+  data.tar.gz: fddcc3464cd86ace1764f20f4ffdb8f50e9d0bf879f86147501691846ba9462c
 SHA512:
-  metadata.gz: 199304d9779008366dec8be4740bfb1b19e70cf89e77c84fe427b22ead45c0870f5c3a19faf60ff2c83951a97a6ce50003f1cfe4b691e817dcbd1243d2f3a8e6
-  data.tar.gz: 938be138bea321d6b64ada27c482fe46f5c56eb5b47a3cf72f16cd8923e3bfe88f99476c131eb281333d576658a799dd1440ece3b08c1a1f1502a13a3f43177e
+  metadata.gz: 2b7c7a7e881f869019dd09e4a4e11c9db19c41ffa2f293c74dd585050721391d0cc64eb8acfb6361beb8b0b8811c5bf25f442a368a1c6a36f52a42eba0f6b7e4
+  data.tar.gz: 4eeb1651ec3de2eae25f59567eb083c19509f96e55f6b3307fff6edf6132c53770c9f3352c60eee245dc0d2004aece3c42eca5b92914c7b7e5e9d4974cffc620

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.2.0 — 2026-09-13
+
+- Experimental export target for UCP proposal [#821 (Nested Options)](https://github.com/Universal-Commerce-Protocol/ucp/issues/821):
+  `menuconform export --target nested-options-821`. Every modifier group lowers
+  to a product option whose values carry `product_id` references; measured
+  corpus results in [docs/export-lossiness.md](docs/export-lossiness.md).
+- Experimental export target for UCP proposal [#824 (Selection Rules)](https://github.com/Universal-Commerce-Protocol/ucp/issues/824),
+  composing with #821: `--target selection-rules-824` emits two-axis
+  `selection_rule` on options and `quantity_rule` on option values, at depth
+  cap 6. The selection-constraints loss class disappears across the corpus.
+- Allergen vocabulary extended to the union of US big-9 and EU-14.
+- CI (GitHub Actions, Ruby 3.1 and 3.4) and issue templates.
+
+## 0.1.0 — 2026-08-31
+
+- Initial release: Menu IR v0.2 (JSON Schema 2020-12), 33-rule engine across
+  9 families including the exact cart solver (CART-001..004), published 0-100
+  scoring formula, JSON report with fix hints, NCR Voyix Menu API importer,
+  UCP catalog exporter with EXPORT- lossiness findings, 12-fixture corpus
+  with pinned expected findings, CLI (`check` / `import` / `export` / `rules`).

data/README.md

@@ -72,7 +72,12 @@ schema-invalid document at 59. Deterministic: the only time input is an injectab
 
 ## Install & use
 
-Not yet on RubyGems (soon). From source (Ruby ≥ 3.1):
+```
+gem install menuconform
+menuconform check menu.json
+```
+
+Or from source (Ruby ≥ 3.1):
 
 ```
 git clone https://github.com/amitkssolanki/menuconform && cd menuconform
@@ -125,7 +130,10 @@ shapes (`product`/`variant`/`option`/`price`) and reports what the export loses
 everything else — multi-select modifiers, nested groups, conditional prices,
 half/half, allergens, age restrictions, schedules — is dropped, degraded, or makes
 the item unrepresentable (`EXPORT-001`, exit 1). The full lossy-construct analysis
-lives in [docs/export-lossiness.md](docs/export-lossiness.md). Export findings
+lives in [docs/export-lossiness.md](docs/export-lossiness.md), including a measured
+evaluation of proposal
+[ucp#821](https://github.com/Universal-Commerce-Protocol/ucp/issues/821) via the
+experimental `--target nested-options-821`. Export findings
 deliberately do **not** affect the `check` score: `check` judges your menu data,
 `export` judges the current draft's fit for food.
 

data/lib/menuconform/cli.rb

@@ -147,11 +147,19 @@ module Menuconform
 
     # Artifact goes to --out (or stdout); EXPORT- findings go to stderr.
     # Exit 1 when any EXPORT-001 (item cannot exist under the pinned draft).
+    EXPORT_TARGETS = {
+      "catalog" => :catalog,
+      "catalog-2026-08-25" => :catalog,
+      "nested-options-821" => :nested_options,
+      "selection-rules-824" => :selection_rules
+    }.freeze
+
     def export(args)
-      options = { from: nil, config: nil, out: nil, reference_time: Time.now.utc }
+      options = { from: nil, config: nil, out: nil, reference_time: Time.now.utc, target: "catalog" }
       parser = OptionParser.new do |o|
         o.on("--from FORMAT") { |f| options[:from] = f }
         o.on("--config PATH") { |p| options[:config] = p }
+        o.on("--target TARGET") { |t| options[:target] = t }
         o.on("-o PATH", "--out PATH") { |p| options[:out] = p }
         o.on("--reference-time TIME") do |t|
           options[:reference_time] = Time.iso8601(t)
@@ -183,6 +191,9 @@ module Menuconform
         doc = result.doc
       end
 
+      target = EXPORT_TARGETS[options[:target]]
+      return usage_error("unknown export target #{options[:target].inspect} (known: #{EXPORT_TARGETS.keys.join(', ')})") unless target
+
       engine = Engine.new
       schema_gate = engine.run(doc, reference_time: options[:reference_time])
       if schema_gate.any? { |f| f.rule == "STRUCT-001" }
@@ -190,7 +201,11 @@ module Menuconform
         return 1
       end
 
-      exporter = UcpExporter.new(catalog: engine.catalog)
+      exporter = case target
+                 when :nested_options then NestedOptionsExporter.new(catalog: engine.catalog)
+                 when :selection_rules then NestedOptionsExporter.new(catalog: engine.catalog, selection_rules: true)
+                 else UcpExporter.new(catalog: engine.catalog)
+                 end
       result = exporter.call(doc, reference_time: options[:reference_time])
 
       result[:findings].each do |f|
@@ -199,7 +214,12 @@ module Menuconform
       errors = result[:findings].count { |f| f.severity == "error" }
       warns = result[:findings].count { |f| f.severity == "warn" }
       exported = result[:artifact]["catalog"]["products"].size
-      @stderr.puts "exported #{exported} product(s) against UCP #{UcpExporter::UCP_SPEC_PIN}; " \
+      label = case target
+              when :nested_options then "UCP #{UcpExporter::UCP_SPEC_PIN} + proposal #821 (experimental)"
+              when :selection_rules then "UCP #{UcpExporter::UCP_SPEC_PIN} + proposals #821+#824 (experimental)"
+              else "UCP #{UcpExporter::UCP_SPEC_PIN}"
+              end
+      @stderr.puts "exported #{exported} product(s) against #{label}; " \
                    "#{errors} unrepresentable item(s), #{warns} lossy construct(s)"
 
       json = JSON.pretty_generate(result[:artifact])

data/lib/menuconform/nested_options_exporter.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Menuconform
+  # EXPERIMENTAL export target for UCP proposal #821 ("Nested Options",
+  # Universal-Commerce-Protocol/ucp#821): option values may carry a product_id
+  # referencing another product; nesting is capped at 5 products deep; pricing
+  # is recursive addition; no selection constraints (min/max/defaults) and no
+  # non-additive pricing — both are the proposal's stated non-goals.
+  #
+  # Mapping:
+  # - Every IR modifier group becomes a product option; every option link
+  #   becomes an option value referencing a modifier-product. Nested groups
+  #   recurse. Items with any priced required group are now representable —
+  #   the class that is EXPORT-001 under the shipped catalog model.
+  # - A modifier-product is shared across links only when the link-resolved
+  #   price and child groups match; a link price_override otherwise forces a
+  #   duplicated product (#821 has no per-reference override — measured and
+  #   reported as a menu-level finding).
+  # - Conditional prices export at base/override price (estimate): exact
+  #   expression would require duplicating the whole subtree per trigger
+  #   selection, the same explosion the proposal exists to avoid.
+  # - Depth: IR group-depth d costs d+1 products (item + one per level), so
+  #   the 5-product cap holds IR depth <= 4; deeper items are EXPORT-001.
+  # - Selection constraints, included quantities, and non-full_price slot
+  #   pricing are EXPORT-002 (proposal non-goals). Allergens / min_age /
+  #   dietary / schedules are unchanged by #821 and carry the same findings
+  #   as the shipped-catalog exporter.
+  class NestedOptionsExporter
+    PROPOSAL = "Universal-Commerce-Protocol/ucp#821 (nested options, experimental)"
+    PROPOSAL_WITH_RULES = "Universal-Commerce-Protocol/ucp#821 + ucp#824 (nested options + selection rules, experimental)"
+    PRODUCT_DEPTH_CAP = 5
+    # ucp#824 composes with #821; depth 6 per the #821 thread agreement.
+    DEPTH_CAP_WITH_RULES = 6
+
+    # selection_rules: true adds ucp#824's selection_rule (on product options)
+    # and quantity_rule (on option values) — the IR's two-axis constraints,
+    # per-link quantity bounds, and defaults all become expressible, so the
+    # constraints loss class disappears from the findings.
+    def initialize(catalog:, selection_rules: false)
+      @catalog = catalog
+      @selection_rules = selection_rules
+      @depth_cap = selection_rules ? DEPTH_CAP_WITH_RULES : PRODUCT_DEPTH_CAP
+      @proposal = selection_rules ? PROPOSAL_WITH_RULES : PROPOSAL
+    end
+
+    # Returns { artifact: Hash, findings: [Finding] } (severities stamped).
+    def call(doc, reference_time: Time.now.utc)
+      menu = Menu.new(doc, reference_time: reference_time)
+      findings = []
+      products = []
+      @modifier_products = {}
+      @mod_dup_counts = Hash.new(0)
+
+      findings << finding("EXPORT-002", "menu", doc["name"] || "(unnamed)",
+                          "menu-level service windows have no UCP catalog construct (unchanged by #821)") if present?(doc["availability"])
+      findings << finding("EXPORT-002", "menu", doc["name"] || "(unnamed)",
+                          "special_hours have no UCP catalog construct (unchanged by #821)") if present?(doc["special_hours"])
+      menu.categories_by_id.each_value do |c|
+        next unless present?(c["availability"])
+        findings << finding("EXPORT-002", "category", c["id"],
+                            "category availability windows have no UCP catalog construct (unchanged by #821)")
+      end
+
+      menu.items_by_id.each_value do |item|
+        next if menu.depth_info(item)[:cyclic]
+        product, item_findings = export_item(menu, item)
+        findings.concat(item_findings)
+        products << product if product
+      end
+
+      duplicated = @mod_dup_counts.select { |_, n| n > 1 }
+      unless duplicated.empty?
+        extra = duplicated.values.sum - duplicated.size
+        findings << finding("EXPORT-002", "menu", doc["name"] || "(unnamed)",
+                            "#{duplicated.size} modifier(s) carry context-dependent prices and had to be duplicated into " \
+                            "#{extra} extra product(s) — #821 option values have no per-reference price override " \
+                            "(affected: #{duplicated.keys.sort.join(', ')})")
+      end
+
+      artifact = {
+        "ucp_spec_version" => UcpExporter::UCP_SPEC_PIN,
+        "experimental_proposal" => @proposal,
+        "generated_by" => "menuconform #{VERSION}",
+        "catalog" => { "products" => products + @modifier_products.values.sort_by { |p| p["id"] } }
+      }
+      { artifact: artifact, findings: findings.each { |f| f.severity = @catalog.severity(f.rule) } }
+    end
+
+    private
+
+    def export_item(menu, item)
+      findings = []
+      depth = menu.depth_info(item)[:max_depth]
+      if depth + 1 > @depth_cap
+        findings << finding("EXPORT-001", "item", item["id"],
+                            "nesting needs #{depth + 1} products (item + #{depth} modifier levels); " \
+                            "the cap is #{@depth_cap} — this item cannot be represented")
+        return [nil, findings]
+      end
+
+      findings.concat(lossiness_findings(menu, item))
+      [build_product(menu, item), findings]
+    end
+
+    def build_product(menu, item)
+      currency = menu.doc["currency"]
+      options = (item["modifier_group_ids"] || []).uniq.filter_map { |gid| group_option(menu, gid, [], nil) }
+      (item["slots"] || []).each do |slot|
+        (slot["modifier_group_ids"] || []).uniq.each do |gid|
+          opt = group_option(menu, gid, [], slot["name"])
+          options << opt if opt
+        end
+      end
+
+      base = {
+        "id" => item["id"],
+        "title" => item["name"],
+        "description" => { "plain" => item["description"] || item["name"] || "" },
+        "price_range" => {
+          "min" => { "amount" => item["price"], "currency" => currency },
+          "max" => { "amount" => item["price"], "currency" => currency }
+        },
+        "variants" => [base_variant(menu, item, currency)]
+      }
+      base["options"] = options unless options.empty?
+      base["tags"] = item["dietary"] if item["dietary"]&.any?
+      base
+    end
+
+    def base_variant(menu, item, currency)
+      v = {
+        "id" => "#{item['id']}~base",
+        "title" => item["name"],
+        "description" => { "plain" => item["description"] || item["name"] || "" },
+        "price" => { "amount" => item["price"], "currency" => currency }
+      }
+      v["availability"] = { "available" => false, "status" => "out_of_stock" } unless orderable?(menu, item)
+      v
+    end
+
+    def group_option(menu, gid, stack, slot_name)
+      g = menu.groups_by_id[gid]
+      return nil if g.nil? || stack.include?(gid)
+      values = (g["options"] || []).filter_map do |link|
+        next unless menu.modifiers_by_id.key?(link["modifier_id"])
+        pid = modifier_product_id(menu, link, stack + [gid])
+        value = { "id" => "#{gid}:#{link['modifier_id']}", "label" => menu.modifiers_by_id[link["modifier_id"]]["name"],
+                  "product_id" => pid }
+        if @selection_rules && (qr = quantity_rule(link))
+          value["quantity_rule"] = qr
+        end
+        value
+      end
+      return nil if values.empty?
+      option = { "name" => slot_name ? "#{slot_name}: #{g['name']}" : g["name"], "values" => values }
+      if @selection_rules && (sr = selection_rule(g))
+        option["selection_rule"] = sr
+      end
+      option
+    end
+
+    # ucp#824 selection_rule from the IR group's two constraint axes.
+    def selection_rule(g)
+      rule = {}
+      rule["min_distinct"] = g["min_select"] if (g["min_select"] || 0).positive?
+      rule["max_distinct"] = g["max_select"] unless g["max_select"].nil?
+      rule["min_units"] = g["min_total_units"] if (g["min_total_units"] || 0).positive?
+      rule["max_units"] = g["max_total_units"] unless g["max_total_units"].nil?
+      rule.empty? ? nil : rule
+    end
+
+    # ucp#824 quantity_rule from the IR option link.
+    def quantity_rule(link)
+      rule = {}
+      rule["min"] = link["min_quantity"] if (link["min_quantity"] || 0) > 1
+      rule["max"] = link["max_quantity"] if (link["max_quantity"] || 1) != 1
+      rule["default"] = link["default_quantity"] if (link["default_quantity"] || 0).positive?
+      rule.empty? ? nil : rule
+    end
+
+    # Shared when link-resolved price and child groups agree; duplicated
+    # otherwise (measured for the per-reference-override argument).
+    def modifier_product_id(menu, link, stack)
+      mod = menu.modifiers_by_id[link["modifier_id"]]
+      price = link.key?("price_override") ? link["price_override"] : mod["price"]
+      children = (link["child_modifier_group_ids"] || []).uniq
+      signature = [mod["id"], price, children]
+      return @modifier_products_by_sig[signature] if @modifier_products_by_sig&.key?(signature)
+
+      @modifier_products_by_sig ||= {}
+      @mod_dup_counts[mod["id"]] += 1
+      pid = @mod_dup_counts[mod["id"]] == 1 ? "mod:#{mod['id']}" : "mod:#{mod['id']}~#{@mod_dup_counts[mod['id']]}"
+      @modifier_products_by_sig[signature] = pid
+
+      currency = menu.doc["currency"]
+      product = {
+        "id" => pid,
+        "title" => mod["name"],
+        "description" => { "plain" => mod["description"] || mod["name"] || "" },
+        "price_range" => {
+          "min" => { "amount" => price, "currency" => currency },
+          "max" => { "amount" => price, "currency" => currency }
+        },
+        "variants" => [{
+          "id" => "#{pid}~base",
+          "title" => mod["name"],
+          "description" => { "plain" => mod["description"] || mod["name"] || "" },
+          "price" => { "amount" => price, "currency" => currency }
+        }]
+      }
+      child_options = children.filter_map { |cgid| group_option(menu, cgid, stack, nil) }
+      product["options"] = child_options unless child_options.empty?
+      product["tags"] = mod["dietary"] if mod["dietary"]&.any?
+      @modifier_products[pid] = product
+      pid
+    end
+
+    def lossiness_findings(menu, item)
+      out = []
+      id = item["id"]
+      reach = menu.reachable_group_ids(item).sort.filter_map { |gid| menu.groups_by_id[gid] }
+
+      unless @selection_rules
+        constrained = reach.select { |g| constrained?(g) }.map { |g| g["id"] }
+        unless constrained.empty?
+          out << finding("EXPORT-002", "item", id,
+                         "selection constraints on #{constrained.join(', ')} dropped (#821 non-goal) — " \
+                         "an agent can traverse this item but cannot validate a cart client-side")
+        end
+      end
+
+      conditional = reach.flat_map { |g| (g["options"] || []).select { |o| (o["conditional_prices"] || []).any? }.map { |o| o["modifier_id"] } }.uniq
+      unless conditional.empty?
+        out << finding("EXPORT-002", "item", id,
+                       "conditional prices on #{conditional.join(', ')} exported at base price (estimate) — exact " \
+                       "expression under #821 requires duplicating the subtree per trigger selection")
+      end
+
+      included = reach.select { |g| (g["included_quantity"] || 0).positive? }.map { |g| g["id"] }
+      unless included.empty?
+        out << finding("EXPORT-002", "item", id,
+                       "included/free quantities on #{included.join(', ')} dropped — #821 pricing is strictly additive")
+      end
+
+      if item["slots"]&.any? && item["slot_pricing"] != "full_price"
+        out << finding("EXPORT-002", "item", id,
+                       "half/half structure exports, but #{item['slot_pricing']} slot pricing is not additive — " \
+                       "totals are estimates until cart-create")
+      end
+
+      if item["allergens"]
+        out << finding("EXPORT-002", "item", id, "allergen declarations still have no catalog field (unchanged by #821)")
+      end
+      if item["min_age"]
+        out << finding("EXPORT-002", "item", id, "min_age #{item['min_age']} still has no catalog field (unchanged by #821)")
+      end
+      if item["dietary"]&.any?
+        out << finding("EXPORT-002", "item", id, "dietary claims still degrade to free-text tags (unchanged by #821)")
+      end
+      if present?(item["availability"])
+        out << finding("EXPORT-002", "item", id, "item availability windows still have no catalog construct (unchanged by #821)")
+      end
+      if item["suspended_until"]
+        out << finding("EXPORT-002", "item", id, "timed suspension still maps to a bare out_of_stock flag (unchanged by #821)")
+      end
+      out
+    end
+
+    def constrained?(g)
+      (g["min_select"] || 0).positive? || !g["max_select"].nil? ||
+        g.key?("min_total_units") || !g["max_total_units"].nil? ||
+        (g["options"] || []).any? { |o| (o["default_quantity"] || 0).positive? || (o["max_quantity"] || 1) != 1 || (o["min_quantity"] || 0).positive? }
+    end
+
+    def orderable?(menu, item)
+      return false if item["active"] == false
+      raw = item["suspended_until"]
+      return true unless raw
+      t = begin
+        Time.iso8601(raw)
+      rescue ArgumentError
+        nil
+      end
+      t.nil? || t <= menu.reference_time
+    end
+
+    def present?(value)
+      !value.nil? && !value.empty?
+    end
+
+    def finding(rule, type, id, message)
+      Finding.new(rule, type, id, message)
+    end
+  end
+end

data/lib/menuconform/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Menuconform
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/menuconform.rb

@@ -16,6 +16,7 @@ require_relative "menuconform/solver"
 require_relative "menuconform/rules/cart_rules"
 require_relative "menuconform/scorer"
 require_relative "menuconform/ucp_exporter"
+require_relative "menuconform/nested_options_exporter"
 require_relative "menuconform/report"
 require_relative "menuconform/engine"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: menuconform
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Amit Solanki
@@ -33,6 +33,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - config/importers/ncr_menu.json
@@ -46,6 +47,7 @@ files:
 - lib/menuconform/importers/base.rb
 - lib/menuconform/importers/ncr_menu.rb
 - lib/menuconform/menu.rb
+- lib/menuconform/nested_options_exporter.rb
 - lib/menuconform/report.rb
 - lib/menuconform/rules/age_rules.rb
 - lib/menuconform/rules/allergen_rules.rb