parsanol 1.3.107 → 1.3.109

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8abeb4082542a6c2378e0f4ba5a338ced5149738a4845542aeab170d2defaa9e
-  data.tar.gz: 73a47fa86137e2c27bde722d78214de3b5cb6a4e7795c7030eee3f90159ee7f2
+  metadata.gz: 7abef89c341c194089d17849bb5e877e4f45a5b2f20a73e347b29905e49a377a
+  data.tar.gz: 4e3619755881576b2ea58c74b8d95ec70ee736cc0dfb258a511e44f83f73a2cf
 SHA512:
-  metadata.gz: cdb7d4f19ceff94dee5163f2b8732e2131c7afa08989df44cbb4933df11af31a36300720155588899c4b4d6f11c241db98071dead025f745faf152f9e0138f54
-  data.tar.gz: 3c26a7b7887be5025f8031e5705c09a7a75f9fde38ef3765620d92b561c20231d92865460e290bca34ed84d33ce545680bd35866d7bd9b8bdc1a9303c00e793e
+  metadata.gz: 3f128038206f01fe80038c2f5c02f44fd2202155e322386bd810b6e4f04cd1f08dc7c545cedc69270ec6f2d5eb539ef8a2561d6ff5837092bfa5cecffb2a81dc
+  data.tar.gz: bca7e6ef0d98b589d08973a0f20c198d0d864f394cf511b69fc5195f35c90bfd924455acd1a27a0558788723df864cc9b96c51a8d226e33854748d84f396d72a

data/Cargo.lock

@@ -307,16 +307,34 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "parsanol"
-version = "0.18.18"
+version = "0.18.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ff4312053fc791388b79b6699ce5763489a00ecea29a5688f9ea5dd7512dff28"
+checksum = "6b6762cda50ce912cb3b247e97559a4da27cec3843103a132568251952fbe9d0"
+dependencies = [
+ "ahash",
+ "getrandom 0.3.4",
+ "getrandom 0.4.3",
+ "hashbrown",
+ "parsanol-derive 0.18.21",
+ "regex",
+ "regex-syntax",
+ "serde",
+ "serde_json",
+ "sha2",
+]
+
+[[package]]
+name = "parsanol"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "366ad171b2117387a355e5a09fb0dfaa0a2177ca7536d9b3a0b18ae63cca3594"
 dependencies = [
  "ahash",
  "getrandom 0.3.4",
  "getrandom 0.4.3",
  "hashbrown",
  "magnus",
- "parsanol-derive",
+ "parsanol-derive 0.19.0",
  "regex",
  "regex-syntax",
  "serde",
@@ -326,9 +344,20 @@ dependencies = [
 
 [[package]]
 name = "parsanol-derive"
-version = "0.18.18"
+version = "0.18.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77eed76fe86c54c683fbb8e2b462495506e9bc2f3007beec82bf6d90b8a82209"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.6",
+]
+
+[[package]]
+name = "parsanol-derive"
+version = "0.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "092b5c4037948433d9fe2ffec742637365f5edf41a98dea3cd554f2c3fed5cfd"
+checksum = "271be27b8391e4c5731af22bd9294536592a2731e258566caa4b7045d09edf3d"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -339,7 +368,7 @@ dependencies = [
 name = "parsanol_cdylib"
 version = "1.3.52"
 dependencies = [
- "parsanol",
+ "parsanol 0.18.21",
 ]
 
 [[package]]
@@ -348,7 +377,7 @@ version = "1.0.2"
 dependencies = [
  "log",
  "magnus",
- "parsanol",
+ "parsanol 0.19.0",
  "rb-sys",
 ]
 

data/ext/parsanol_native/Cargo.toml

@@ -32,7 +32,7 @@ magnus = { version = "0.9" }
 # parsanol parser library (crates.io; 0.17.0 carries the LookSpec regex
 # lookbehind (rs#163 gap 1) and the widened opaque writeback: the
 # lazy-continuation fix, parsanol-ruby#160)
-parsanol = { version = "0.18.0", features = ["ruby"] }
+parsanol = { version = "0.19.0", features = ["ruby"] }
 
 # Logging
 log = "0.4"

data/lib/parsanol/parg/cli.rb

@@ -29,6 +29,13 @@ module Parsanol
           repl    <file> [--entry E]        interactive parse loop (blank
                                             line quits, :quit exits)
           doc     <file> [rule]             print rule documentation
+          export  <file|artifact.json> --target xgrammar
+                                            lower the compiled artifact to a
+                                            decoder-facing grammar (ruby#321)
+          lint    <file> [--suggest-upgrades]
+                                            print lint errors (exit 1) and
+                                            warnings; the flag adds
+                                            machine-applicable upgrades
 
         options:
           --tables DIR   directory for alt-from-table data (default:
@@ -51,6 +58,7 @@ module Parsanol
           @argv.delete_at(index)
         end
         @json = !!@argv.delete("--json")
+        @suggest_upgrades = !!@argv.delete("--suggest-upgrades")
         command = @argv.shift
         case command
         when "compile" then compile
@@ -60,6 +68,9 @@ module Parsanol
         when "check" then check
         when "repl" then repl
         when "doc" then doc
+        when "lint" then lint
+        when "export" then export_grammar
+        when "diff" then diff_artifacts
         when "lsp" then Lsp.new.run && 0
         else
           warn USAGE
@@ -84,6 +95,48 @@ module Parsanol
         end
       end
 
+      # `parg export FILE --target xgrammar`: the decoder-facing
+      # lowering (ruby#321). Reads a .parg (compiling it) or an
+      # artifact json, prints the target grammar on stdout.
+      def export_grammar
+        source = @argv.shift
+        target = (flag_value("--target") || "xgrammar").to_sym
+        json = if source.end_with?(".json")
+                 File.read(source)
+               else
+                 JSON.generate(compile_source(source).envelope)
+               end
+        print Export.call(json, target: target)
+        0
+      end
+
+      # `parg lint FILE`: the lint suite on one grammar — errors
+      # first (exit 1), then every warning including the advisory
+      # strategies. --suggest-upgrades adds the machine-applicable
+      # upgrade suggestions on top.
+      def lint
+        source = @argv.shift
+        tables = @tables_dir || default_tables_dir(source)
+        document = Parsanol::PARG::Parser.new(PARG.read_utf8(source)).parse
+        Parsanol::PARG::Imports.merge!(document, [File.dirname(source)])
+        compiler = Parsanol::PARG::Compiler.new(document, tables)
+        document.rules.each_key { |rule| compiler.atom_for(rule) }
+
+        errors = Lints.errors(document, compiler)
+        errors.each { |error| puts "error: #{error}" }
+        return 1 unless errors.empty?
+
+        Lints.warnings(document, compiler).each { |warning| puts "warning: #{warning}" }
+        if @suggest_upgrades
+          Lints::CoreRuleDuplicates.new.warnings(document, compiler)
+            .each { |upgrade| puts "upgrade: #{upgrade}" }
+        end
+        0
+      rescue Parsanol::PARG::ParseError, Parsanol::PARG::Error => e
+        warn "#{e.class}: #{e.message}"
+        1
+      end
+
       def compile
         source = @argv.shift
         out = flag_value("-o") || default_artifact_name(source)
@@ -162,6 +215,50 @@ module Parsanol
         0
       end
 
+      # parg diff OLD.artifact.json NEW.artifact.json [--json] [--suggest-bump] [--check LEVEL]
+      # Semantic classification of a grammar change (ruby#306): majors
+      # break consumers, minors extend them, patches preserve behavior.
+      def diff_artifacts
+        old_path = @argv.shift
+        new_path = @argv.shift
+        unless old_path && new_path
+          warn "usage: parsanol parg diff OLD.artifact.json NEW.artifact.json [--json] [--suggest-bump] [--check minor]"
+          return 2
+        end
+        suggest = !!@argv.delete("--suggest-bump")
+        check = @argv.delete("--check")
+        check_level = check && check.split("=", 2).last&.to_sym
+
+        old_env = JSON.parse(File.read(old_path))
+        new_env = JSON.parse(File.read(new_path))
+        findings = Diff.diff(old_env, new_env)
+        level = Diff.level(findings)
+
+        if @json
+          payload = {
+            level: level.to_s,
+            findings: findings.map { |f| { level: f.level.to_s, kind: f.kind.to_s, detail: f.detail } },
+          }
+          payload[:suggested] = Diff.suggest_bump(findings) if suggest
+          puts JSON.generate(payload)
+        else
+          if findings.empty?
+            puts "no semantic changes (#{level})"
+          else
+            findings.each { |f| puts "#{f.level.upcase} #{f.kind}: #{f.detail}" }
+            puts "level: #{level}"
+          end
+          puts Diff.suggest_bump(findings) if suggest
+        end
+
+        if check_level
+          ok = Diff::SEVERITY[level] >= Diff::SEVERITY[check_level]
+          warn "check: #{level} is #{ok ? 'at least' : 'BELOW'} #{check_level}" unless @json
+          return ok ? 0 : 3
+        end
+        0
+      end
+
       def parse
         file = @argv.shift
         entry = flag_value("--entry")

data/lib/parsanol/parg/compiler.rb

@@ -66,6 +66,19 @@ module Parsanol
 
       # QoL shorthands (ABNF core rules): materialized on reference when
       # the grammar does not define its own rule of that name.
+      # Character-class core rules (TODO.sota/9 T1, ruby#303): the RFC
+      # 5234 prelude that is expressible as a class. A grammar's own
+      # rule of the same name shadows these — fetch_rule checks the
+      # document first. ALNUM/WORD/ANY predate the RFC set.
+      # Unicode general categories (U3): one-letter groups plus the
+      # two-letter codes grammars actually reach for. Both regex
+      # engines carry the tables; this gate rejects misspellings at
+      # compile time instead of silently matching nothing.
+      GENERAL_CATEGORIES = %w[
+        L Lu Ll Lt Lm Lo M Mn Mc Me N Nd Nl No P Pc Pd Ps Pe Pi Pf Po
+        S Sm Sc Sk So Z Zs Zl Zp C Cc Cf Co Cn
+      ].freeze
+
       BUILTIN_CLASSES = {
         "DIGIT" => [[0x30, 0x39]],
         "ALPHA" => [[0x41, 0x5A], [0x61, 0x7A]],
@@ -73,15 +86,30 @@ module Parsanol
         "WORD" => [[0x30, 0x39], [0x41, 0x5A], [0x5F, 0x5F], [0x61, 0x7A]],
         "HEXDIG" => [[0x30, 0x39], [0x41, 0x46], [0x61, 0x66]],
         "ANY" => [[0x00, 0x10FFFF]],
+        "BIT" => [[0x30, 0x31]],
+        "CHAR" => [[0x01, 0x7F]],
+        "CR" => [[0x0D, 0x0D]],
+        "CTL" => [[0x00, 0x1F], [0x7F, 0x7F]],
+        "DQUOTE" => [[0x22, 0x22]],
+        "HTAB" => [[0x09, 0x09]],
+        "LF" => [[0x0A, 0x0A]],
+        "OCTET" => [[0x00, 0xFF]],
+        "SP" => [[0x20, 0x20]],
+        "VCHAR" => [[0x21, 0x7E]],
+        "WSP" => [[0x20, 0x20], [0x09, 0x09]],
       }.freeze
 
       def compile
+        inject_core_rules!
         expand_left_recursion!
         @document.rules.each_key { |name| atom_for(name) }
         errors = Lints.errors(@document, self)
         raise CompileError, errors.join("\n") unless errors.empty?
 
-        @warnings = Lints.warnings(@document, self)
+        # The author sees every finding; the envelope carries only the
+        # semantic subset (see Lints::Advisory).
+        @warnings = Lints.warnings(@document, self).map(&:to_s)
+        @envelope_warnings = Lints.envelope_warnings(@document, self)
         failures = run_tests
         raise CompileError, failures.join("\n") unless failures.empty?
 
@@ -120,6 +148,65 @@ module Parsanol
         end.flatten
       end
 
+      # The structured core rules (TODO.sota/9 T1, ruby#303): CRLF and
+      # LWSP are not character classes, so BUILTIN_CLASSES cannot serve
+      # them — they inject as real rules when referenced and missing,
+      # transitively (LWSP needs CRLF). Class-expressible members of
+      # the RFC 5234 set ride BUILTIN_CLASSES above; a grammar's own
+      # rule of the same name shadows either mechanism. Injected at the
+      # front so definitions precede references for the order lint.
+      STRUCTURED_CORE_RULES_SOURCE = <<~PARG
+        grammar CoreRules version "1.0.0" {
+          CRLF = %x0D.0A
+          LWSP = *( WSP / CRLF WSP )
+        }
+      PARG
+
+      STRUCTURED_CORE_RULE_NAMES = %w[CRLF LWSP].freeze
+
+      def inject_core_rules!
+        return if @core_rules_injected
+
+        @core_rules_injected = true
+        missing = STRUCTURED_CORE_RULE_NAMES.select do |name|
+          !@document.rules.key?(name) &&
+            @document.rules.each_value.any? { |node| references_atom?(node, name) }
+        end
+        return if missing.empty?
+
+        # Snapshot before the prelude merges: lints distinguish an
+        # authored shadow from an injected prelude rule.
+        @document.authored_rules ||= @document.rules.keys
+        prelude = Parser.new(STRUCTURED_CORE_RULES_SOURCE).parse
+        injected = {}
+        until missing.empty?
+          name = missing.pop
+          next if injected.key?(name) || @document.rules.key?(name)
+
+          node = prelude.rules.fetch(name)
+          injected[name] = node
+          STRUCTURED_CORE_RULE_NAMES.each do |dep|
+            missing << dep if !injected.key?(dep) && !@document.rules.key?(dep) &&
+              references_atom?(node, dep)
+          end
+        end
+        # rules is deliberately read-only on the document: prepend in place.
+        @document.rules.replace(injected.merge(@document.rules))
+      end
+
+      def references_atom?(node, name)
+        walk = lambda do |n|
+          case n.kind
+          when :ref then return true if n.a == name
+          when :alt, :seq then n.a.each { |b| return true if references_atom?(b, name) }
+          when :cap, :pred then return true if references_atom?(n.b, name)
+          when :rep, :opt then return true if references_atom?(n.a, name)
+          end
+          false
+        end
+        walk.call(node) == true
+      end
+
       def resolve_custom(name)
         class_name = @document.customs.fetch(name)
         klass = Object.const_get(class_name)
@@ -142,6 +229,7 @@ module Parsanol
       end
 
       def atom_for(name)
+        inject_core_rules!
         expand_left_recursion! unless @expanded
         @atom_cache[name] ||= begin
           atom = build_atom(fetch_rule(name))
@@ -600,6 +688,14 @@ module Parsanol
             Atoms::Str.new(node.a)
           end
         when :class then Atoms::Re.new(class_pattern(node.a))
+        when :category
+          code = node.a
+          unless GENERAL_CATEGORIES.include?(code)
+            raise CompileError,
+                  "unknown general category %p{#{code}} -- use one of " \
+                  "#{GENERAL_CATEGORIES.join(' ')}"
+          end
+          Atoms::Re.new("[\\p{#{code}}]")
         when :until
           # QoL: (*( !terminal any_char )) — consume everything up to
           # (and excluding) the delimiter.
@@ -858,9 +954,10 @@ module Parsanol
       def compute_first(node)
         case node.kind
         when :lit
-          # The zero-width marker ("" as name) consumes nothing: its
-          # first set is empty, which also marks the node nullable.
-          return Set.new if node.a.empty?
+          # The zero-width marker ("" as name) consumes nothing: EPS in
+          # its first set marks the node nullable (the convention every
+          # nullable? check uses).
+          return Set.new([EPS]) if node.a.empty?
 
           set = Set.new(node.a[0].bytes)
           set += node.a[0].upcase.bytes + node.a[0].downcase.bytes if node.b
@@ -954,7 +1051,7 @@ module Parsanol
           "entries" => entries,
           "preprocess" => @document.preprocess,
           "tables" => table_manifest,
-          "lint" => { "order_warnings" => @warnings.uniq },
+          "lint" => { "order_warnings" => @envelope_warnings.uniq },
           "default_entry" => begin
             resolve_default_entry
           rescue StandardError

data/lib/parsanol/parg/diff.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Parsanol
+  module PARG
+    # ruby#306: `parg diff OLD NEW` — semantic classification of grammar
+    # changes against the artifact contract. Atoms are compared by
+    # canonical rendering, never by JSON bytes, so compiler-version churn
+    # and key order never read as a grammar change.
+    #
+    # Levels: :major breaks consumers (capture/entry/branch removals,
+    # binding changes, mode change), :minor extends them (new entries,
+    # captures, branches), :patch is behavior-preserving detail (literal
+    # fixes, doc changes, added tests). Ambiguous cases land at the
+    # higher level with the evidence attached — never guessed down.
+    module Diff
+      Finding = Struct.new(:level, :kind, :detail)
+
+      SEVERITY = { none: 0, patch: 1, minor: 2, major: 3 }.freeze
+
+      module_function
+
+      def diff(old_envelope, new_envelope)
+        findings = []
+        findings.concat(diff_mode(old_envelope, new_envelope))
+        findings.concat(diff_entries(old_envelope, new_envelope))
+        findings.concat(diff_bindings(old_envelope, new_envelope))
+        findings.concat(diff_tests(old_envelope, new_envelope))
+        findings
+      end
+
+      def level(findings)
+        findings.reduce(:none) { |acc, finding| higher(acc, finding.level) }
+      end
+
+      def higher(left, right)
+        SEVERITY[left] >= SEVERITY[right] ? left : right
+      end
+
+      def suggest_bump(findings)
+        level = level(findings)
+        level == :none ? "no bump needed" : "bump #{level}"
+      end
+
+      # -- entries ------------------------------------------------------
+
+      def diff_entries(old_env, new_env)
+        old_entries = old_env["entries"] || {}
+        new_entries = new_env["entries"] || {}
+        findings = (old_entries.keys - new_entries.keys).map do |name|
+          Finding.new(:major, :entry_removed, "entry #{name.inspect} removed")
+        end
+        (new_entries.keys - old_entries.keys).each do |name|
+          findings << Finding.new(:minor, :entry_added, "entry #{name.inspect} added")
+        end
+        old_entries.each do |name, old_entry|
+          new_entry = new_entries[name]
+          next unless new_entry
+
+          findings.concat(diff_entry(name, old_entry, new_entry))
+        end
+        findings
+      end
+
+      def diff_entry(name, old_entry, new_entry)
+        old_atoms = old_entry.dig("grammar", "atoms") || []
+        new_atoms = new_entry.dig("grammar", "atoms") || []
+        old_root = old_entry.dig("grammar", "root")
+        new_root = new_entry.dig("grammar", "root")
+        return [Finding.new(:major, :entry_changed, "entry #{name.inspect} lost its root")] if old_root.nil? || new_root.nil?
+
+        old_render = render_atom(old_atoms, old_root)
+        new_render = render_atom(new_atoms, new_root)
+        return [] if old_render == new_render
+
+        findings = []
+        findings.concat(diff_captures(name, old_render, new_render))
+        findings.concat(diff_branches(name, mask(old_render), mask(new_render)))
+        if findings.empty?
+          findings << if mask(old_render) == mask(new_render)
+                        # Same captures, same branches, same structure: the
+                        # difference is inside literals, bounds, or trivia markers —
+                        # behavior-preserving.
+                        Finding.new(:patch, :literal_or_bound_change,
+                                    "entry #{name.inspect}: literal/bound/doc-level change")
+                      else
+                        # Structure reshuffled without a detectable capture or
+                        # branch delta — evidence over a guess.
+                        Finding.new(:minor, :structure_changed,
+                                    "entry #{name.inspect}: structure changed " \
+                                    "(no capture or branch removed): " \
+                                    "#{mask(old_render)[0, 60]} -> #{mask(new_render)[0, 60]}")
+                      end
+        end
+        findings
+      end
+
+      # -- captures -----------------------------------------------------
+
+      def diff_captures(entry_name, old_render, new_render)
+        old_names = capture_names(old_render)
+        new_names = capture_names(new_render)
+        removed = old_names - new_names
+        added = new_names - old_names
+        removed.map { |n| Finding.new(:major, :capture_removed, "entry #{entry_name.inspect}: capture #{n.inspect} removed") } +
+          added.map { |n| Finding.new(:minor, :capture_added, "entry #{entry_name.inspect}: capture #{n.inspect} added") }
+      end
+
+      def capture_names(render)
+        render.scan(/\(name "([^"]+)"/).flatten.uniq
+      end
+
+      # -- alternative branches ----------------------------------------
+
+      # A branch that stops matching is the ambiguous-breaking case:
+      # inputs it used to accept now reject. Removed branches are major;
+      # added-only is the documented minor.
+      def diff_branches(entry_name, old_render, new_render)
+        old_branches = alt_branches(old_render)
+        new_branches = alt_branches(new_render)
+        removed = old_branches - new_branches
+        added = new_branches - old_branches
+        removed.map { |b| Finding.new(:major, :branch_removed, "entry #{entry_name.inspect}: alternative branch #{b} no longer matches") } +
+          added.map { |b| Finding.new(:minor, :branch_added, "entry #{entry_name.inspect}: alternative branch #{b} added") }
+      end
+
+      # Literals masked: branch identity is structural, not spelling —
+      # a literal fix inside a branch is not that branch's removal.
+      def mask(render)
+        render.gsub(/str:"[^"]*"/, "str:#").gsub(/const:[^\s)]+/, "const:#")
+      end
+
+      # Every alternative branch's canonical rendering, anywhere in the
+      # tree (alternatives inside repetitions, groups, captures…).
+      # Balanced-paren walk: branches nest.
+      def alt_branches(render)
+        branches = []
+        index = render.index("(alt ")
+        while index
+          start = index + 5
+          depth = 1
+          cursor = start
+          while depth.positive? && cursor < render.length
+            case render[cursor]
+            when "(" then depth += 1
+            when ")" then depth -= 1
+            end
+            cursor += 1
+          end
+          body = render[start...(cursor - 1)]
+          child_depth = 0
+          current = +""
+          body.each_char do |ch|
+            case ch
+            when "(" then child_depth += 1
+            when ")" then child_depth -= 1
+            when " "
+              if child_depth.zero?
+                branches << current unless current.empty?
+                current = +""
+                next
+              end
+            end
+            current << ch
+          end
+          branches << current unless current.empty?
+          index = render.index("(alt ", cursor)
+        end
+        branches.uniq.sort
+      end
+
+      # -- mode ---------------------------------------------------------
+
+      def diff_mode(old_env, new_env)
+        old_mode = old_env["mode"]
+        new_mode = new_env["mode"]
+        return [] if old_mode == new_mode
+
+        [Finding.new(:major, :mode_changed,
+                     "mode changed #{old_mode.inspect} -> #{new_mode.inspect} " \
+                     "(every uncaptured node's tree shape changes)")]
+      end
+
+      # -- bindings -----------------------------------------------------
+
+      def diff_bindings(old_env, new_env)
+        old_bindings = old_env["bindings"]
+        new_bindings = new_env["bindings"]
+        return [] if old_bindings == new_bindings
+        return [Finding.new(:minor, :bindings_added, "bindings section added")] if old_bindings.nil?
+        return [Finding.new(:major, :bindings_removed, "bindings section removed")] if new_bindings.nil?
+
+        [Finding.new(:major, :bindings_changed,
+                     "bindings changed — binding paths/types re-validate " \
+                     "against the tree")]
+      end
+
+      # -- tests --------------------------------------------------------
+
+      def diff_tests(old_env, new_env)
+        old_tests = old_env["tests"].to_a
+        new_tests = new_env["tests"].to_a
+        return [] if old_tests == new_tests
+
+        # Pins per kind: a pin whose INPUT changed alongside a literal
+        # fix is the pin following the grammar (patch), not a removal.
+        old_counts = old_tests.each_with_object(Hash.new(0)) { |t, counts| counts[t["kind"]] += 1 }
+        new_counts = new_tests.each_with_object(Hash.new(0)) { |t, counts| counts[t["kind"]] += 1 }
+        dropped = old_counts.keys.select { |kind| new_counts[kind] < old_counts[kind] }
+        unless dropped.empty?
+          return [Finding.new(:major, :tests_removed,
+                              "#{dropped.join(', ')} pin(s) removed — the contract weakened")]
+        end
+
+        [Finding.new(:patch, :tests_added,
+                     "test pins changed/added (#{old_tests.size} -> #{new_tests.size})")]
+      end
+
+      # -- canonical rendering ------------------------------------------
+
+      # Canonical s-expression of one atom index. Entities resolve; keyed
+      # hashes render in fixed field order; nothing escapes — this is a
+      # diff key, not output text.
+      def render_atom(atoms, idx, depth = 0)
+        return "…" if depth > 64
+
+        a = atoms[idx]
+        return "missing:#{idx}" if a.nil?
+
+        if (str = a["Str"])
+          "str:#{str['pattern'].inspect}"
+        elsif (re = a["Re"])
+          "re:#{re['pattern']}"
+        elsif (sequence = a["Sequence"])
+          "(seq #{sequence['atoms'].map { |i| render_atom(atoms, i, depth + 1) }.join(' ')})"
+        elsif (alt = a["Alternative"])
+          "(alt #{alt['atoms'].map { |i| render_atom(atoms, i, depth + 1) }.join(' ')})"
+        elsif (rep = a["Repetition"])
+          "(rep #{rep['min']} #{rep['max'].nil? ? '*' : rep['max']} #{rep['tag']} #{render_atom(atoms, rep['atom'], depth + 1)})"
+        elsif (named = a["Named"])
+          "(name \"#{named['name']}\" #{render_atom(atoms, named['atom'], depth + 1)})"
+        elsif (entity = a["Entity"])
+          render_atom(atoms, entity["atom"], depth + 1)
+        elsif (look = a["Lookahead"])
+          "(look #{look['positive'] ? '&' : '!'} #{render_atom(atoms, look['atom'], depth + 1)})"
+        elsif (behind = a["Lookbehind"])
+          "(behind #{behind['positive'] ? '&' : '!'} #{behind['look'].inspect})"
+        elsif a["Cut"]
+          "cut"
+        elsif (ignore = a["Ignore"])
+          "(ignore #{render_atom(atoms, ignore['atom'], depth + 1)})"
+        elsif (trivia = a["Trivia"])
+          "(trivia #{render_atom(atoms, trivia['atom'], depth + 1)})"
+        elsif (capture_trivia = a["TriviaCapture"])
+          "(trivia-cap #{capture_trivia['rules'].map { |m, k| "#{m}=#{k}" }.join(',')} " \
+            "#{render_atom(atoms, capture_trivia['atom'], depth + 1)})"
+        elsif (constant = a["Constant"])
+          "const:#{constant['value'].inspect}"
+        else
+          "unknown:#{a.keys.first}"
+        end
+      end
+    end
+  end
+end