parsanol 1.3.107-aarch64-linux → 1.3.109-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a248ea2b74e5e7a7be04c806fd97f180b76514e96281f5daaf04a99e9ca317e
-  data.tar.gz: bf7fe292aadabb0107f3353f6b0e96c0f6d2b0c1cc4006398590d0a34b7796c6
+  metadata.gz: c17015cb92f4e965c312eb69e7bb14e212700d6660650061ccfb0bb59da35cde
+  data.tar.gz: d246068f5c2b4b6bfe56aac5da14e450b29a8b39f36836ea5da65ab2d15a56af
 SHA512:
-  metadata.gz: ef2edf2620ccaf4369731c83f9bdc5ae063898b0dcc5813dbbfa5a690e2e85b7f99e47dea01cca770198a9c406b1f5c147c540782b84e111d34d6e75be2757d3
-  data.tar.gz: 586b3121956c700428f7bedbc3218ece7a15c6aaaf79f49216ad3a724e4ee2a04e50934f36a57a055386f9342e141a1d8942fc464fbb0bf2d3f325ad6a6abc9d
+  metadata.gz: fe6458c0af76600f87a58c24c00405e0148dfd50aa75b694761f1c2a88a480ed9a8113419f65eaf8407dcdcfe5ae2e4b920df995018ad8d6440d45962619d4fb
+  data.tar.gz: e14f4c3c3bc2ed0decdae5d6339b6d06c7978f7e75e767a4f8a2cc48ffb93ae461792660eae5d81e6b26d60ddb6c248cda296834cc63acb4de98a13462150a04

data/lib/parsanol/3.2/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/3.2/parsanol_native.so
-size: 40743256 bytes
-sha256: f27084008a8a2764ecb363b009685fd79d6b549460089afd8cffdeee1d286d83
+size: 42420800 bytes
+sha256: 81dd5dcbde9d4188c86c316102dabdb522048fe218134d89180db1334f5d2e77

data/lib/parsanol/3.3/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/3.3/parsanol_native.so
-size: 40978344 bytes
-sha256: 9c09c91329de7f138e37a561a3f700520f37c39968d201c941bc58636cbf7b9b
+size: 42655808 bytes
+sha256: 3c87af92ff773b9d78c286d55c8c82c7fd11d1331e0a09ca9942c28fc184ac47

data/lib/parsanol/3.4/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/3.4/parsanol_native.so
-size: 40973960 bytes
-sha256: 967c4b42655705c1aa762e03499986fc185657ff4008297e093c73ecaa8cb60a
+size: 42651368 bytes
+sha256: 4bc273e8b1473a31c24ef9b882ee53b001a337c620467000fe4021954bb640eb

data/lib/parsanol/4.0/parsanol_native.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/4.0/parsanol_native.so
-size: 40983992 bytes
-sha256: 5de5e2e7a682e336ae7f34c7d3967341320c85b4fc969e41354ed46498b892bb
+size: 42661424 bytes
+sha256: 6c9c533b9b53407c3ef7c2c789c610fe35e860a470d7406dad4629be3f94cbf5

data/lib/parsanol/native/libparsanol.so

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: data/lib/parsanol/native/libparsanol.so
-size: 36501808 bytes
-sha256: aba1f5e1e7283015e5650abd249c27d9f0e095747a3bd1921aa981a1d9c64a10
+size: 36759888 bytes
+sha256: 885d841e5628d9fae0b43e78bd28ef5f27195ca0f3b543d35aaba7e8167ef2f4

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

data/lib/parsanol/parg/document.rb

@@ -18,15 +18,20 @@ module Parsanol
       Test = Struct.new(:entry, :kind, :input, :expect)
 
       attr_accessor :grammar_name, :version, :source, :uses, :skip_declaration, :skip_source,
-                    :atomic_rules, :skip_capture_key
+                    :atomic_rules, :skip_capture_key, :brace_rules
       # R2 declared resync: rule name -> skip pattern (the span matched
       # at a recovery point is consumed as annotated error text).
       attr_reader :resyncs
       attr_reader :rules, :bindings, :preprocess, :entries, :docs, :tests, :render, :derive,
+                  :declaration_order,
                   :customs, :states
       # Entries authored in this file (pre-import); nil-entry tests resolve
       # against these first.
       attr_accessor :own_entries
+      # Rule names the grammar itself wrote, snapshotted before the
+      # compiler injects core rules — lints must not mistake an injected
+      # prelude rule for an authored shadow.
+      attr_accessor :authored_rules
 
       def initialize
         @grammar_name = nil
@@ -38,6 +43,7 @@ module Parsanol
         @bindings = {}
         @preprocess = {}
         @entries = {}
+        @declaration_order = []
         @docs = {}
         @tests = []
         @uses = []
@@ -48,6 +54,8 @@ module Parsanol
         # suppressed inside their bodies (token-shaped rules match
         # contiguously).
         @atomic_rules = []
+        @brace_rules = []
+        @authored_rules = nil
         # R2 declared resync: rule -> skip pattern. Recovery consumes
         # each pattern match at a failure point as annotated error text
         # and resumes the iteration after it.