hecks 1.3.0 → 1.5.0

data/lib/hecks/grammar/evolve.rb

@@ -1,7 +1,7 @@
 module Hecks
   module Grammar
     # The file surgery under bin/evolve: reading and rewriting the
-    # aggregate-local KeywordSeed/ArgumentSeed rows as TEXT, so a
+    # aggregate-local KeywordSeed/ArgumentSeed rows as text, so a
     # proposed word enters the table exactly as a hand would write it
     # and an admitted one loses its ceremony (an absent status reads as
     # admitted — the grown-column convention).
@@ -18,11 +18,15 @@ module Hecks
       module_function
 
       # bin/evolve's own `--name value` flag reader. Only consumes the
-      # NEXT argv element as the value when that element doesn't itself
+      # next argv element as the value when that element doesn't itself
       # look like a flag — otherwise `--foo --bar` would swallow `--bar`
       # as `--foo`'s value (and `--bar` would then never be seen at
       # all), and a value-less `--foo` at the end of argv would bypass
       # whatever default `foo` promised instead of falling back to it.
+      # @param argv [Array<String>] the command-line argument list to scan
+      # @param name [String] the flag's name, without its leading `--`
+      # @param default [String, nil] value to use when the flag is absent or has no value
+      # @return [String, nil] the flag's value, or `default`
       def option(argv, name, default = nil)
         index = argv.index("--#{name}")
         return default unless index
@@ -42,6 +46,12 @@ module Hecks
       # the gate specs, not on anything this method knows about). A
       # clean return leaves the snapshots unused; the caller decides
       # from there whether the tree stands.
+      #
+      # @param paths [Array<String>] files to snapshot before running the block
+      # @yield the mutating work to run, restored from snapshot if it raises
+      # @return [Object] the block's result
+      # @raise [StandardError] re-raises whatever the block raised, after restoring
+      #   every snapshotted file
       def restore_on_raise(paths)
         snapshots = paths.to_h { |path| [path, File.read(path)] }
         yield
@@ -50,6 +60,10 @@ module Hecks
         raise
       end
 
+      # Every syntax-table file declaring a `KeywordSeed` or `ArgumentSeed`
+      # value object.
+      #
+      # @return [Array<String>] matching `.bluebook` file paths
       def syntax_paths
         Dir.glob(File.expand_path("../language/**/*.bluebook", __dir__)).select do |path|
           source = File.read(path)
@@ -60,13 +74,25 @@ module Hecks
       # Kept as a narrow compatibility door for callers deliberately doing
       # single-file surgery. Normal operation uses `syntax_paths` and discovers
       # the owning concept from the row itself.
+      #
+      # @return [String, nil] the first syntax-table path, or nil when there are none
       def syntax_path = syntax_paths.first
 
+      # Resolves the file(s) a call should search or write.
+      #
+      # @param path [String, nil] an explicit single file, or nil for every syntax path
+      # @return [Array<String>] `[path]` when given, else `syntax_paths`
       def paths_for(path) = path ? Array(path) : syntax_paths
 
       # The Keyword one_of's member rows, parsed leniently off the text —
       # enough to know each row's (word, context, status), which is all
       # the tool ever asks.
+      #
+      # @param path [String, nil] an explicit single file to read, or nil for every
+      #   syntax path
+      # @return [Array<Hash>] one Hash per member row, with `:word`, `:context`,
+      #   `:status` (`"admitted"` when unspelled), and `:was` (nil unless renamed)
+      # @raise [Refusal] if `path` is given and declares no `KeywordSeed` value object
       def keyword_rows(path = nil)
         paths_for(path).flat_map do |candidate|
           blocks = seed_blocks(File.read(candidate), "KeywordSeed")
@@ -82,6 +108,20 @@ module Hecks
         end
       end
 
+      # Declares a new, proposed keyword row in the syntax table that owns
+      # `context` (or `opens`'s own aggregate, for a `File`-context word).
+      #
+      # @param word [String] the keyword's spelling
+      # @param context [String] the grammar context the word is declared in
+      # @param body [String] the keyword's body shape; `"none"` by default
+      # @param inner [String] the keyword's inner shape, if any
+      # @param opens [String] the aggregate concept a `File`-context word opens
+      # @param fills [String] the field the keyword fills, if any
+      # @param path [String, nil] an explicit single file to search/write, or nil to
+      #   search every syntax path
+      # @return [void]
+      # @raise [Refusal] if `context`.`word` is already declared, or no syntax table
+      #   owns `context`
       def propose(word:, context:, body: "none", inner: "", opens: "", fills: "", path: nil)
         if keyword_rows(path).any? do |row|
           row[:word] == word && row[:context] == context
@@ -97,7 +137,7 @@ module Hecks
         row = %(#{indent}member word: "#{word}", context: "#{context}", body: "#{body}", ) +
               %(inner: "#{inner}", opens: "#{opens}", fills: "#{fills}", status: "proposed"\n)
 
-        # At the END of the one_of — grouping by context is a courtesy of
+        # At the end of the one_of — grouping by context is a courtesy of
         # the hand; a proposed row sits at the bottom until admission,
         # when whoever admits it may move it home.
         closing = block.rindex(/^\s*end\s*$/)
@@ -105,6 +145,17 @@ module Hecks
         File.write(path, source.sub(block, updated))
       end
 
+      # Rewrites a declared keyword row's `status:` cell in place.
+      #
+      # @param word [String] the keyword's spelling
+      # @param context [String] the grammar context the word is declared in
+      # @param to [String] the new status: `"proposed"`, `"admitted"`, `"deprecated"`,
+      #   or `"retired"`
+      # @param path [String, nil] an explicit single file to search/write, or nil to
+      #   search every syntax path
+      # @return [void]
+      # @raise [Refusal] if `to` is not one of the four stations, or `context`.`word`
+      #   is not declared
       def set_status(word:, context:, to:, path: nil)
         raise Refusal, "#{to.inspect} is not a station a word's life admits" unless %w[proposed admitted deprecated
                                                                                        retired].include?(to)
@@ -119,7 +170,7 @@ module Hecks
           next line unless member_row?(line, word, context)
 
           stripped = line.sub(/,\s*status: "[^"]*"/, "")
-          # Admitted is the default and stays UNSPELLED — only a word
+          # Admitted is the default and stays unspelled — only a word
           # entering or leaving the language carries its status.
           to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
         end.join
@@ -131,8 +182,17 @@ module Hecks
       # `was:` — one hop only. Renaming an already-renamed word refuses
       # until the language grows real eras for its own words; renaming
       # onto a spelling the context already declares refuses too. The
-      # word's Argument rows follow it — row-aware now, not the blind
-      # substitution this used to be (see `cascade_argument_rename`).
+      # word's Argument rows follow it — row-aware, not a blind
+      # substitution (see `cascade_argument_rename`).
+      #
+      # @param word [String] the keyword's current spelling
+      # @param context [String] the grammar context the word is declared in
+      # @param to [String] the keyword's new spelling
+      # @param path [String, nil] an explicit single file to search/write, or nil to
+      #   search every syntax path
+      # @return [void]
+      # @raise [Refusal] if `context`.`word` is not declared, was already renamed once,
+      #   or `to` is already declared in `context`
       def rename(word:, context:, to:, path: nil)
         row = keyword_rows(path).find { |r| r[:word] == word && r[:context] == context }
         raise Refusal, "#{context}.#{word} is not declared" unless row
@@ -160,16 +220,38 @@ module Hecks
         cascade_argument_rename(keyword: word, context: context, to: to, path: paths)
       end
 
+      # Tells whether `line` is a KeywordSeed member row for `(word, context)`.
+      #
+      # @param line [String] one raw source line
+      # @param word [String] the keyword's spelling
+      # @param context [String] the grammar context
+      # @return [Boolean]
       def member_row?(line, word, context)
         line =~ /^\s*member / && line.include?(%(word: "#{word}")) && line.include?(%(context: "#{context}"))
       end
 
+      # Finds which syntax-table path declares a keyword row.
+      #
+      # @param word [String] the keyword's spelling
+      # @param context [String] the grammar context
+      # @param paths [Array<String>] candidate syntax-table paths to search
+      # @return [String] the path whose KeywordSeed declares `(word, context)`
+      # @raise [Refusal] if no path in `paths` declares that row
       def path_holding_keyword(word, context, paths = syntax_paths)
         paths.find do |candidate|
           keyword_blocks(File.read(candidate)).any? { |block| block.lines.any? { |line| member_row?(line, word, context) } }
         end || raise(Refusal, "#{context}.#{word} is not declared")
       end
 
+      # Finds which syntax-table path declares an argument row.
+      #
+      # @param keyword [String] the argument's owning keyword
+      # @param context [String] the grammar context
+      # @param at [String] the argument's positional slot, `""` for a named-only argument
+      # @param named [String] the argument's keyword name, `""` for a positional-only argument
+      # @param paths [Array<String>] candidate syntax-table paths to search
+      # @return [String] the path whose ArgumentSeed declares this row
+      # @raise [Refusal] if no path in `paths` declares that row
       def path_holding_argument(keyword, context, at, named, paths = syntax_paths)
         paths.find do |candidate|
           argument_blocks(File.read(candidate)).any? do |block|
@@ -183,6 +265,14 @@ module Hecks
       # A new row belongs wherever that context's existing rows live. File is
       # intentionally wider than one aggregate; for a new entry point, `opens`
       # identifies the aggregate concept whose file should own it.
+      #
+      # @param context [String] the grammar context a new row is being added to
+      # @param word [String] the word being added, used only in the refusal message
+      # @param opens [String] the aggregate concept a `File`-context word opens
+      # @param paths [Array<String>] candidate syntax-table paths to search
+      # @return [String] the path that should own the new row
+      # @raise [Refusal] if no candidate path declares an existing row for `context`
+      #   (and, for a `File` context with `opens` given, no path declares that aggregate)
       def owner_path(context:, word:, opens: "", paths: syntax_paths)
         if context == "File" && !opens.to_s.empty?
           aggregate_path = paths.find { |candidate| File.read(candidate).match?(/^\s*aggregate "#{Regexp.escape(opens)}" do$/) }
@@ -197,6 +287,13 @@ module Hecks
         end || raise(Refusal, "no aggregate-local syntax table owns context #{context.inspect} for #{word}")
       end
 
+      # Every `value_object "<name>"` block's full source text, from its
+      # opener to its closing `end`.
+      #
+      # @param source [String] a `.bluebook` file's source text
+      # @param name [String] the value object's name, such as `"KeywordSeed"`
+      # @return [Array<String>] each matching block's raw source, including the
+      #   opener and closing `end` lines
       def seed_blocks(source, name)
         opener = /^([ \t]*)value_object "#{Regexp.escape(name)}" do$/
         source.to_enum(:scan, opener).map do
@@ -209,6 +306,15 @@ module Hecks
         end
       end
 
+      # The first `value_object "<name>"` block's source text.
+      #
+      # @param source [String] a `.bluebook` file's source text
+      # @param name [String] the value object's name, such as `"KeywordSeed"`
+      # @param required [Boolean] whether a missing block should raise instead of
+      #   returning nil
+      # @return [String, nil] the block's raw source, or nil when absent and not
+      #   `required`
+      # @raise [Refusal] if `required` and `source` declares no such value object
       def seed_block(source, name, required: false)
         block = seed_blocks(source, name).first
         unless block
@@ -219,21 +325,37 @@ module Hecks
         block
       end
 
-      # From `value_object "KeywordSeed"` to ITS OWN closing `end` — `member`
+      # From `value_object "KeywordSeed"` to its own closing `end` — `member`
       # rows sit bare now (S3, ADR 0025 — the `one_of do ... end` wrapper
       # is gone), so the first bare `end` line after the opener already
-      # IS the value object's own, the same fact the original one_of-
+      # is the value object's own, the same fact the original one_of-
       # nested version of this method leaned on (nothing else nested
       # inside it either, before or after).
+      # @param source [String] a `.bluebook` file's source text
+      # @return [Array<String>] each KeywordSeed block's raw source
       def keyword_blocks(source) = seed_blocks(source, "KeywordSeed")
+
+      # The first KeywordSeed block's source text.
+      #
+      # @param source [String] a `.bluebook` file's source text
+      # @return [String] the first KeywordSeed block's raw source
+      # @raise [Refusal] if `source` declares no KeywordSeed value object
       def keyword_block(source) = seed_block(source, "KeywordSeed", required: true)
 
       # ── the Argument rows — a word's own arguments, at last with tooling
       # of their own rather than the rename-only cascade above. A word may
-      # carry SEVERAL argument rows (one per position, one per named
+      # carry several argument rows (one per position, one per named
       # kwarg), so identity here is the full (keyword, context, at, named)
       # tuple, not the two-field key a Keyword row answers to.
 
+      # The ArgumentSeed's member rows, parsed leniently off the text.
+      #
+      # @param path [String, nil] an explicit single file to read, or nil for every
+      #   syntax path
+      # @return [Array<Hash>] one Hash per member row, with `:keyword`, `:context`,
+      #   `:at`, `:named`, `:kind`, `:required`, `:fills`, and `:status`
+      #   (`"admitted"` when unspelled)
+      # @raise [Refusal] if `path` is given and declares no `ArgumentSeed` value object
       def argument_rows(path = nil)
         paths_for(path).flat_map do |candidate|
           blocks = seed_blocks(File.read(candidate), "ArgumentSeed")
@@ -250,13 +372,27 @@ module Hecks
         end
       end
 
-      # `pairs_shape` — for a `pairs` argument that fills ONE field with a
+      # `pairs_shape` — for a `pairs` argument that fills one field with a
       # whole key/value list rather than naming a field per pair (the
       # shape `Handler.dispatch`'s own `with:` already carries). Without
       # it, `spec/syntax_conformance_spec.rb` reads a pairs argument
       # naming a single field as a row that "names a single field, which
       # it cannot fill" — correctly, since the two shapes are genuinely
       # different and only one of them can be checked the same way.
+      # @param keyword [String] the argument's owning keyword
+      # @param context [String] the grammar context
+      # @param kind [String] the argument's value kind
+      # @param required [String] `"true"` or `"false"`, as text like every other cell
+      # @param at [String] the argument's positional slot, `""` for a named-only argument
+      # @param named [String] the argument's keyword name, `""` for a positional-only argument
+      # @param fills [String] the field the argument fills, if any
+      # @param pairs_shape [String, nil] the shape a `pairs` argument's key/value list
+      #   fills, or nil when this argument is not a `pairs` argument
+      # @param path [String, nil] an explicit single file to search/write, or nil to
+      #   search every syntax path
+      # @return [void]
+      # @raise [Refusal] if this (keyword, context, at, named) row is already declared,
+      #   or no syntax table owns `context`
       def propose_argument(keyword:, context:, kind:, required: "false", at: "", named: "", fills: "",
                            pairs_shape: nil, path: nil)
         if argument_rows(path).any? { |r| argument_identity(r) == [keyword, context, at, named] }
@@ -280,6 +416,18 @@ module Hecks
         File.write(path, source.sub(block, updated))
       end
 
+      # Rewrites a declared argument row's `status:` cell in place.
+      #
+      # @param keyword [String] the argument's owning keyword
+      # @param context [String] the grammar context
+      # @param to [String] the new status: `"proposed"`, `"admitted"`, `"deprecated"`,
+      #   or `"retired"`
+      # @param at [String] the argument's positional slot, `""` for a named-only argument
+      # @param named [String] the argument's keyword name, `""` for a positional-only argument
+      # @param path [String, nil] an explicit single file to search/write, or nil to
+      #   search every syntax path
+      # @return [void]
+      # @raise [Refusal] if `to` is not one of the four stations, or the row is not declared
       def set_argument_status(keyword:, context:, to:, at: "", named: "", path: nil)
         raise Refusal, "#{to.inspect} is not a station an argument's life admits" unless %w[proposed admitted deprecated
                                                                                             retired].include?(to)
@@ -307,19 +455,39 @@ module Hecks
         File.write(path, source.sub(block, updated))
       end
 
+      # Tells whether `line` is an ArgumentSeed member row for this
+      # (keyword, context, at, named) tuple.
+      #
+      # @param line [String] one raw source line
+      # @param keyword [String] the argument's owning keyword
+      # @param context [String] the grammar context
+      # @param at [String] the argument's positional slot
+      # @param named [String] the argument's keyword name
+      # @return [Boolean]
       def argument_row?(line, keyword, context, at, named)
         line =~ /^\s*member / &&
           line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}")) &&
           line.include?(%(at: "#{at}")) && line.include?(%(named: "#{named}"))
       end
 
+      # The identity tuple an argument row is keyed by.
+      #
+      # @param row [Hash] an argument row, as `argument_rows` returns one
+      # @return [Array(String, String, String, String)] the row's `(keyword, context,
+      #   at, named)` identity tuple
       def argument_identity(row) = [row[:keyword], row[:context], row[:at], row[:named]]
 
-      # The rename cascade, ROW-AWARE — only the rows that actually belong
+      # The rename cascade, row-aware — only the rows that actually belong
       # to the renamed word, spelling updated in place, rather than a
       # blind `gsub` on every `keyword: "word",` substring in the file
       # (which a coincidentally-matching row elsewhere could have
       # corrupted, and which read nothing before writing).
+      # @param keyword [String] the keyword whose argument rows follow its rename
+      # @param context [String] the grammar context
+      # @param to [String] the keyword's new spelling
+      # @param path [String, nil] an explicit single file to search/write, or nil to
+      #   search every syntax path
+      # @return [void]
       def cascade_argument_rename(keyword:, context:, to:, path: nil)
         paths_for(path).each do |candidate|
           source = File.read(candidate)
@@ -337,11 +505,19 @@ module Hecks
         end
       end
 
-      # From `value_object "ArgumentSeed"` to ITS OWN closing `end` — see
+      # From `value_object "ArgumentSeed"` to its own closing `end` — see
       # `keyword_block`'s own comment for why the first bare `end` after
       # the opener is already the right one, now that `member` rows sit
       # bare (S3, ADR 0025).
+      # @param source [String] a `.bluebook` file's source text
+      # @return [Array<String>] each ArgumentSeed block's raw source
       def argument_blocks(source) = seed_blocks(source, "ArgumentSeed")
+
+      # The first ArgumentSeed block's source text.
+      #
+      # @param source [String] a `.bluebook` file's source text
+      # @return [String] the first ArgumentSeed block's raw source
+      # @raise [Refusal] if `source` declares no ArgumentSeed value object
       def argument_block(source) = seed_block(source, "ArgumentSeed", required: true)
     end
   end

data/lib/hecks/grammar.rb

@@ -7,12 +7,12 @@ require_relative "../hecks"
 
 module Hecks
   # The sublanguage grammar domains (grammar/*.bluebook) and the one boot
-  # path for reading them as DATA — the expression chapter replayed
+  # path for reading them as data — the expression chapter replayed
   # through its own admission ledger, so anything derived from it (the
   # operator projections, the conformance specs) reads the set that
   # actually survived the Admit gates, never a hand-copied list.
   #
-  # Booted on CALL, never at require: the Prism adapter normalises every
+  # Booted on call, never at require: the Prism adapter normalises every
   # predicate through CanonicalForm while a bluebook loads, so the
   # expression machinery cannot boot the chapter that configures it —
   # this module exists precisely so generators and specs boot it in a
@@ -27,6 +27,11 @@ module Hecks
     # its real commands. A refused step raises — a generator running off
     # a half-admitted ledger would project a table the gates never
     # accepted.
+    #
+    # @return [Runtime::Dispatcher] the dispatcher bound to the booted, replayed
+    #   expression chapter
+    # @raise [Runtime::WiringError] if a ledger step is refused by the chapter's
+    #   own domain rules
     def expression
       registry = Runtime::Registry.new
       root = File.expand_path("../..", __dir__)
@@ -42,7 +47,7 @@ module Hecks
       JSON.parse(File.read(LEDGER)).fetch("steps").each do |step|
         args = symbolize(step.fetch("args"))
         begin
-          dispatcher.dispatch(step.fetch("verb"), **args)
+          dispatcher.dispatch_flat(step.fetch("verb"), args)
         rescue *Runtime::DOMAIN_REFUSALS => e
           raise Runtime::WiringError,
                 "the admission ledger refused at #{step['verb']} #{step['args']} — #{e.message}"
@@ -52,6 +57,13 @@ module Hecks
       dispatcher
     end
 
+    # Reads every admitted operator from the ledger's replayed chapter.
+    #
+    # @param dispatcher [Runtime::Dispatcher] a dispatcher bound to the booted
+    #   expression chapter; defaults to booting and replaying a fresh one
+    # @return [Array<Hash>] one Hash per admitted operator, with `:symbol`,
+    #   `:category`, `:precedence`, `:arity`, and `:renderings` (an Array of
+    #   `{target:, form:}` Hashes)
     def admitted_operators(dispatcher = expression)
       records(dispatcher, "Operator").select { |op| op[:status] == "admitted" }.map do |op|
         { symbol: op[:symbol].value, category: op[:category].value,
@@ -60,6 +72,13 @@ module Hecks
       end
     end
 
+    # Reads every admitted normalisation rule from the ledger's replayed
+    # chapter, in position order.
+    #
+    # @param dispatcher [Runtime::Dispatcher] a dispatcher bound to the booted
+    #   expression chapter; defaults to booting and replaying a fresh one
+    # @return [Array<Hash>] one Hash per admitted rule, with `:strategy`,
+    #   `:source_token`, `:replacement`, `:boundary`, and `:position`
     def admitted_normalisations(dispatcher = expression)
       records(dispatcher, "Normalisation")
         .select { |rule| rule[:status] == "admitted" }
@@ -71,22 +90,34 @@ module Hecks
         end
     end
 
+    # Reads every record of one aggregate from the expression chapter's own
+    # repository.
+    #
+    # @param dispatcher [Runtime::Dispatcher] a dispatcher bound to the booted
+    #   expression chapter
+    # @param aggregate_name [String] the aggregate's declared name, such as
+    #   `"Operator"`
+    # @return [Array<Runtime::Instance>] every stored instance of the aggregate
     def records(dispatcher, aggregate_name)
       registry  = dispatcher.registry
       aggregate = registry.bluebook("Expression").aggregate(aggregate_name)
       registry.repository("Expression", aggregate).all
     end
 
-    # THE OPERATORS THE LANGUAGE STANDS ON. Every guard and invariant in
+    # The operators the language stands on. Every guard and invariant in
     # the language's own chapters — the meta-domain (Bluebook, World) and
     # the grammar chapters beside this file — evaluates through the very
     # operator table the ledger admits. An operator one of those
-    # predicates uses is SELF-BEARING: retire it and the language can no
+    # predicates uses is self-bearing: retire it and the language can no
     # longer read its own rules — found the hard way, as a projection
     # missing `!=` that could not boot the chapter to fix itself. This
     # derives the set, with a usage site per operator, so the generator
-    # and the conformance spec can refuse the retirement BY NAME instead
+    # and the conformance spec can refuse the retirement by name instead
     # of wedging.
+    #
+    # @return [Hash{String => Array<String>}] each self-bearing operator symbol
+    #   mapped to the `"Chapter Aggregate.command"`/`"Chapter Aggregate::ValueObject"`
+    #   sites that use it
     def self_bearing_operators
       sites = Hash.new { |h, k| h[k] = [] }
 
@@ -118,6 +149,9 @@ module Hecks
 
     # Every grammar/*.bluebook chapter, booted the same way the corpus
     # boots them — each alone, in a scratch registry.
+    #
+    # @return [Array<Class>] each grammar chapter, booted alone in its own scratch
+    #   registry
     def grammar_chapters
       Dir[File.join(DIR, "*.bluebook")].map do |chapter|
         registry = Runtime::Registry.new
@@ -136,6 +170,10 @@ module Hecks
     # Which admitted operators one canonical text evaluates through —
     # the evaluator's own parse, walked for its operator nodes, leaves
     # walked for the resolver's arithmetic.
+    #
+    # @param canonical [String] canonical expression text to parse
+    # @return [Array<String>] operator symbols the expression evaluates through, or
+    #   `[]` when `canonical` fails to parse
     def operators_in(canonical)
       evaluator = Bluebook::Expression::Evaluator
       begin
@@ -146,7 +184,7 @@ module Hecks
       walk_operators(node, evaluator).uniq
     end
 
-    # A recursive descent over a CLOSED, declared set of AST node types
+    # A recursive descent over a closed, declared set of AST node types
     # (Evaluator's boolean/compare/include nodes, Resolver's arithmetic
     # nodes, and the generic Struct fallback) — each branch does the
     # same one thing (name the node's own operator, recurse into its
@@ -155,6 +193,10 @@ module Hecks
     # would trade one place that shows the whole operator vocabulary for
     # several that each show a fragment, with no reduction in real
     # complexity.
+    # @param node [Object] an evaluator/resolver AST node, or a Struct fallback
+    # @param evaluator [Module] `Bluebook::Expression::Evaluator`, passed through
+    #   so nested calls don't re-resolve the constant
+    # @return [Array<String>] operator symbols found in `node` and its children
     # rubocop:disable-next Metrics/AbcSize
     def walk_operators(node, evaluator)
       resolver = Bluebook::Expression::Resolver
@@ -177,6 +219,10 @@ module Hecks
       end
     end
 
+    # Deep-symbolizes a JSON-decoded value's Hash keys.
+    #
+    # @param value [Object] a Hash, Array, or scalar decoded from JSON
+    # @return [Object] `value` with every Hash key (recursively) converted to a Symbol
     def symbolize(value)
       case value
       when Hash  then value.to_h { |k, v| [k.to_sym, symbolize(v)] }