hecks 1.4.0 → 1.5.1

data/lib/hecks/projections/parser_table.rb

@@ -16,25 +16,47 @@ module Hecks
 
       module_function
 
+      # Projects the Rust parser's keyword and closed-set tables for one chapter.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project; the language's own
+      #   for the ordinary `bin/project_parser_table` run
+      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @return [String] the rendered Rust source
       def call(bluebook:, options: {}) = render(bluebook)
 
       module_function
 
-      # The chapter is handed over, not reached for. This used to open the
-      # grammar registry itself, which meant the projection could only ever
-      # project one chapter — the language's own. Taking it as an argument is
-      # what the projector protocol asks for, and it costs nothing.
+      # The chapter is handed over, not reached for — reaching for the grammar
+      # registry directly would pin the projection to one chapter, the language's
+      # own, and the projector protocol already hands over the chapter as an
+      # argument, at no cost.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to read the Syntax aggregate
+      #   from
+      # @return [Bluebook::Aggregate, nil] the chapter's `"Syntax"` aggregate, `nil` if
+      #   it declares none
       def syntax(bluebook) = bluebook.aggregate("Syntax")
 
       # Every cell as text — exactly spec/syntax_conformance_spec.rb's own
       # `rows` helper, reused rather than re-derived: a member's fields decode
       # back through typed literal decoding on the way out of reconstruction,
       # and this reads it back as what was written.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to read from
+      # @param name [String] the closed-set value object's name, such as `"Context"`
+      # @return [Array<Hash{Symbol => String}>] one row per declared member, every
+      #   field stringified
       def rows(bluebook, name)
         syntax(bluebook).value_objects.find { |vo| vo.hecks_name == name }
               .members.map { |row| row.to_h.transform_values(&:to_s) }
       end
 
+      # Reads one closed set's member names, for a Rust `&[&str]` constant.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to read from
+      # @param name [String] the closed-set value object's name
+      # @return [Array<String>] every declared member's `:name` field
       def closed_set_members(bluebook, name) = rows(bluebook, name).map { |row| row[:name] }
 
       KEYWORD_FIELDS  = %i[word context body inner opens fills status was resolves_via disambiguator].freeze
@@ -45,18 +67,34 @@ module Hecks
       # plain ASCII (a word, a context name, a digit, "true"/"false"), so this
       # only has to be safe against the two characters Rust string literals
       # themselves reserve.
+      #
+      # @param value [Object] the field value to render; stringified before escaping
+      # @return [String] a quoted Rust string literal
       def rust_string(value) = "\"#{value.to_s.gsub('\\', '\\\\\\\\').gsub('"', '\\"')}\""
 
+      # Renders one `KEYWORDS` table entry.
+      #
+      # @param row [Hash{Symbol => String}] one keyword row, keyed by `KEYWORD_FIELDS`
+      # @return [String] one `KeywordRow { ... },` line
       def keyword_row(row)
         fields = KEYWORD_FIELDS.map { |field| rust_string(row[field]) }
         "    KeywordRow { #{KEYWORD_FIELDS.zip(fields).map { |name, value| "#{name}: #{value}" }.join(', ')} },"
       end
 
+      # Renders one `ARGUMENTS` table entry.
+      #
+      # @param row [Hash{Symbol => String}] one argument row, keyed by `ARGUMENT_FIELDS`
+      # @return [String] one `ArgumentRow { ... },` line
       def argument_row(row)
         fields = ARGUMENT_FIELDS.map { |field| rust_string(row[field]) }
         "    ArgumentRow { #{ARGUMENT_FIELDS.zip(fields).map { |name, value| "#{name}: #{value}" }.join(', ')} },"
       end
 
+      # Renders one `pub static NAME: &[&str]` constant.
+      #
+      # @param name [String] the Rust constant's name
+      # @param values [Array<String>] the constant's member strings
+      # @return [String] the rendered `pub static` declaration
       def const_str_array(name, values)
         lines = values.map { |value| "    #{rust_string(value)}," }
         "pub static #{name}: &[&str] = &[\n#{lines.join("\n")}\n];\n"
@@ -66,10 +104,13 @@ module Hecks
       # now, dispatched (not merely declared) so their own `status`
       # really is a lifecycle. `SyntaxBoot.call` reads the still-static
       # seed rows (`KeywordSeed`/`ArgumentSeed`), dispatches each one
-      # through the real admission/lifecycle door, and hands back the
-      # exact same shape `rows` used to read straight off the closed set
-      # — symbol keys, string values, `status` included — so nothing
-      # else in this file needed to change.
+      # through the real admission/lifecycle door, and hands back rows in
+      # the same shape `rows` reads for every other closed set here —
+      # symbol keys, string values, `status` included — so nothing else
+      # in this file needs to change.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @return [String] the rendered `KEYWORDS`/`ARGUMENTS`/closed-set Rust source
       def render(bluebook)
         table     = Hecks::Bluebook::MetaValidator::SyntaxBoot.call
         keywords  = table[:keywords]

data/lib/hecks/projections/reference.rb

@@ -25,6 +25,18 @@ module Hecks
 
       module_function
 
+      # Renders one reference page per DSL keyword context, carrying prose
+      # over from whatever is already committed under `options[:from]`.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Syntax aggregate to render pages from; unused beyond admission, since the
+      #   keyword table this reads comes from the global `Syntax` grammar
+      # @param options [Hash] must include `:from`
+      # @option options [String] :from directory holding the already-committed
+      #   reference pages, read to harvest their prose
+      # @return [Hash{String => String}] each page's filename => its rendered
+      #   Markdown, including `"index.md"`
+      # @raise [ArgumentError] if `options[:from]` is missing or falsy
       def call(bluebook:, options: {})
         from = options[:from] or
           raise ArgumentError,

data/lib/hecks/projections/rust_vocabulary.rb

@@ -4,7 +4,7 @@ require_relative "vocabulary"
 
 module Hecks
   module Projections
-    # **The language's closed sets, projected into the Rust kernel** — one
+    # The language's closed sets, projected into the Rust kernel — one
     # `rust/src/kernel/vocab/<table>.rs` per Vocabulary table, each a
     # `pub enum` plus `match`-based accessors with no wildcard arm, so a
     # row the chapter gains is a compile error at every exhaustive match
@@ -18,21 +18,24 @@ module Hecks
     # which read Runtime::RefusalWording::TEMPLATES — a hand-typed copy of
     # the RefusalTemplate rows. This reads the chapter itself.
     #
-    # **Only TABLES the kernel needs**. Each entry in TABLES names its enum
-    # and its generated extras; a table not listed is not projected. The
-    # enum names that differ from the table name keep existing Rust call
-    # sites (`RefusalSite`) and the dispatch-step names D1 consumes
-    # (`AggregateStep`, `EntityStep`).
+    # ## Only `TABLES` the kernel needs
     #
-    # TYPED REFUSAL ARGUMENTS. The templates table also reads
-    # RefusalSiteArgument: every site gets a `<Variant>Args` struct whose
-    # fields are exactly the site's declared arguments (a `&str` per
-    # scalar, a `&[&str]` per list) and a `render_args` that formats each
-    # one by its row. `render` itself stays private to the generated
-    # module, so no call site can pass an argument list by hand — leaving
-    # one out does not compile. The generated test pins every site's
-    # `render_args` output (empty, single and multiple unsorted lists)
-    # against Runtime::RefusalWording.render_with, computed here in Ruby.
+    # Each entry in `TABLES` names its enum and its generated extras; a
+    # table not listed is not projected. The enum names that differ from
+    # the table name keep existing Rust call sites (`RefusalSite`) and the
+    # dispatch-step names D1 consumes (`AggregateStep`, `EntityStep`).
+    #
+    # ## Typed refusal arguments
+    #
+    # The templates table also reads RefusalSiteArgument: every site gets a
+    # `<Variant>Args` struct whose fields are exactly the site's declared
+    # arguments (a `&str` per scalar, a `&[&str]` per list) and a
+    # `render_args` that formats each one by its row. `render` itself stays
+    # private to the generated module, so no call site can pass an argument
+    # list by hand — leaving one out does not compile. The generated test
+    # pins every site's `render_args` output (empty, single and multiple
+    # unsorted lists) against Runtime::RefusalWording.render_with, computed
+    # here in Ruby.
     module RustVocabulary
       extend Projector::Target
 
@@ -62,8 +65,24 @@ module Hecks
 
       module_function
 
+      # The projector protocol.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to project
+      # @param options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [Hash{String => String}] each generated file's path, relative to
+      #   `rust/src/kernel/`, mapped to its full Rust source
       def call(bluebook:, options: {}) = render(bluebook)
 
+      # Renders every file `TABLES` projects: `vocab/mod.rs` plus one `.rs` file
+      # per table, each an exhaustive enum with accessors and a pinned test module.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to render
+      # @return [Hash{String => String}] each generated file's path, relative to
+      #   `rust/src/kernel/`, mapped to its full Rust source
+      # @raise [ArgumentError] if `bluebook` does not declare a `TABLES`-named table,
+      #   or the `:arguments` table a `:templates` entry names
       def render(bluebook)
         tables = Vocabulary.tables(bluebook)
         files = TABLES.to_h do |table, spec|
@@ -76,6 +95,11 @@ module Hecks
         { "vocab/mod.rs" => mod_file }.merge(files)
       end
 
+      # The generated-file banner every projected file opens with.
+      #
+      # @param table [String] the Vocabulary table name being projected, such as
+      #   `"RefusalTemplate"`
+      # @return [String] the banner, as Rust line comments
       def header(table)
         <<~RUST
           // GENERATED by #{GENERATOR} (Hecks::Projections::RustVocabulary,
@@ -85,6 +109,10 @@ module Hecks
         RUST
       end
 
+      # Renders `vocab/mod.rs`, the entry point that re-exports every projected enum.
+      #
+      # @return [String] `vocab/mod.rs`'s full source: one `pub mod` and `pub use`
+      #   per entry in `TABLES`
       def mod_file
         mods    = TABLES.values.map { |spec| "pub mod #{spec[:file]};" }.join("\n")
         exports = TABLES.values.map { |spec| "pub use #{spec[:file]}::#{spec[:enum]};" }.join("\n")
@@ -104,6 +132,18 @@ module Hecks
         RUST
       end
 
+      # One table's full `.rs` source: its exhaustive enum, per-field accessors,
+      # `from_name`, its `:order`/`:templates` extras, and its `#[cfg(test)]` module.
+      #
+      # @param table [String] the Vocabulary table name, such as `"RefusalTemplate"`
+      # @param spec [Hash] the table's `TABLES` entry (`:enum`, `:variant_from`,
+      #   `:file`, `:kind`, and, for `:templates`, `:arguments`)
+      # @param rows [Array<Hash{String => String}>] the table's rows, as read off
+      #   the chapter by `Vocabulary.tables`
+      # @param argument_rows [Array<Hash{String => String}>, nil] the
+      #   `RefusalSiteArgument` rows, only when `spec[:kind] == :templates`
+      # @return [String] the table's full `.rs` file source
+      # @raise [ArgumentError] if two rows would generate the same enum variant name
       def table_file(table, spec, rows, argument_rows = nil)
         variants = rows.map { |row| variant_name(row, spec[:variant_from]) }
         duplicates = variants.tally.select { |_, count| count > 1 }.keys
@@ -132,6 +172,14 @@ module Hecks
         "#{body.flatten.join("\n").rstrip}\n"
       end
 
+      # Renders the enum's declared-order constant: `ORDER` for `:order`, `ALL` otherwise.
+      #
+      # @param enum [String] the Rust enum name, such as `"RefusalSite"`
+      # @param variants [Array<String>] each row's generated variant name, in
+      #   declared order
+      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
+      # @return [Array<String>] the lines declaring the enum's `ORDER` constant
+      #   (`:order`) or `ALL` constant (otherwise)
       def constants(enum, variants, kind)
         list = variants.map { |variant| "        #{enum}::#{variant}," }
         if kind == :order
@@ -143,6 +191,16 @@ module Hecks
         end
       end
 
+      # Renders one field's `pub fn` accessor, an exhaustive match over every variant.
+      #
+      # @param enum [String] the Rust enum name
+      # @param field [String] the row field this accessor reads, such as `"name"`
+      # @param variants [Array<String>] each row's generated variant name, in
+      #   declared order, matching `rows`
+      # @param rows [Array<Hash{String => String}>] the table's rows, in the same
+      #   order as `variants`
+      # @return [Array<String>] the lines for the field's `pub fn` accessor, one
+      #   match arm per variant
       def accessor(enum, field, variants, rows)
         arms = variants.zip(rows).map { |variant, row| "            #{enum}::#{variant} => #{rust_string(row.fetch(field))}," }
         ["    /// The row's declared `#{field}`.",
@@ -156,6 +214,10 @@ module Hecks
 
       # Built on the enum's own list and name accessor, not a string
       # match, so it needs no wildcard arm either.
+      #
+      # @param enum [String] the Rust enum name
+      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
+      # @return [Array<String>] the lines for the enum's `from_name` associated function
       def from_name(enum, kind)
         list  = kind == :order ? "ORDER" : "ALL"
         field = kind == :templates ? "site" : name_field(kind)
@@ -166,6 +228,14 @@ module Hecks
          ""]
       end
 
+      # Renders the extra methods a table's `:kind` adds beyond the shared accessors.
+      #
+      # @param enum [String] the Rust enum name
+      # @param variants [Array<String>] each row's generated variant name, in
+      #   declared order
+      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
+      # @return [Array<String>] `:order`'s `position` method, `:templates`'s private
+      #   `render` method, or `[]` for `:set`
       def extras(enum, variants, kind)
         case kind
         when :order
@@ -196,6 +266,17 @@ module Hecks
       # [refusal, site] => that site's argument rows, in declared order —
       # refused unless they name exactly the template's own placeholders,
       # in the order each first appears, with only known formatting rules.
+      #
+      # @param rows [Array<Hash{String => String}>] the `RefusalTemplate` rows,
+      #   in declared order
+      # @param argument_rows [Array<Hash{String => String}>] the `RefusalSiteArgument`
+      #   rows for every site
+      # @return [Hash{Array<String> => Array<Hash{String => String}>}] each
+      #   `[refusal, site]` pair mapped to its declared argument rows, in declared order
+      # @raise [ArgumentError] if an argument row names a `refusal`/`site` no
+      #   `RefusalTemplate` row declares, if a site's declared arguments do not match
+      #   its template's `{placeholder}`s in order, or if `check_rule!` rejects a
+      #   row's `"shape"`, `"quoting"`, or `"sorted"` value
       def site_arguments(rows, argument_rows)
         grouped = argument_rows.group_by { |row| [row.fetch("refusal"), row.fetch("site")] }
         orphans = grouped.keys - rows.map { |row| [row.fetch("refusal"), row.fetch("site")] }
@@ -215,6 +296,18 @@ module Hecks
         end
       end
 
+      # Refuses a `RefusalSiteArgument` row whose formatting fields are not
+      # recognized rules.
+      #
+      # @param key [Array<String>] the `[refusal, site]` pair `spec` belongs to,
+      #   used in the raised message
+      # @param spec [Hash{String => String}] one `RefusalSiteArgument` row
+      #   (`"shape"`, `"quoting"`, `"sorted"`)
+      # @return [void]
+      # @raise [ArgumentError] if `spec`'s `"shape"` is not in
+      #   `Runtime::RefusalWording::SHAPES`, its `"quoting"` is not in
+      #   `Runtime::RefusalWording::QUOTINGS`, or its `"sorted"` is not
+      #   `"true"`/`"false"`
       def check_rule!(key, spec)
         where = "#{key.join('/')}.#{spec.fetch('argument')}"
         unless Runtime::RefusalWording::SHAPES.include?(spec.fetch("shape"))
@@ -228,6 +321,17 @@ module Hecks
         raise ArgumentError, "#{where}: sorted must be \"true\" or \"false\""
       end
 
+      # Renders every `:templates` variant's typed argument struct, plus the two
+      # helper functions (`quoted`, `list`) they share.
+      #
+      # @param enum [String] the Rust enum name
+      # @param variants [Array<String>] each row's generated variant name, matching `rows`
+      # @param rows [Array<Hash{String => String}>] the `RefusalTemplate` rows, in
+      #   the same order as `variants`
+      # @param by_site [Hash{Array<String> => Array<Hash{String => String}>}] each
+      #   `[refusal, site]` pair's declared argument rows, as built by `site_arguments`
+      # @return [Array<String>] the shared `quoted`/`list` helper functions, followed
+      #   by every variant's `<Variant>Args` struct and `render_args` implementation
       def argument_types(enum, variants, rows, by_site)
         support = [
           "/// Ruby's `#inspect` of a name, as a refusal quotes it: `{:?}` on a",
@@ -258,6 +362,15 @@ module Hecks
         end
       end
 
+      # Renders one variant's `<Variant>Args` struct and its `render_args` method.
+      #
+      # @param enum [String] the Rust enum name
+      # @param variant [String] the row's generated variant name
+      # @param row [Hash{String => String}] the `RefusalTemplate` row this variant projects
+      # @param specs [Array<Hash{String => String}>] the variant's declared
+      #   `RefusalSiteArgument` rows, in declared order
+      # @return [Array<String>] the lines for the variant's `<Variant>Args` struct
+      #   and its `render_args` method
       def args_struct(enum, variant, row, specs)
         fields = specs.flat_map do |spec|
           type = spec.fetch("shape") == "list" ? "&'a [&'a str]" : "&'a str"
@@ -288,6 +401,15 @@ module Hecks
          ""]
       end
 
+      # The `let` binding, if any, `args_struct` inserts before a variant's
+      # `render_args` computes its argument pairs.
+      #
+      # @param spec [Hash{String => String}] one `RefusalSiteArgument` row
+      #   (`"argument"`, `"shape"`, `"quoting"`, and, for a list, `"sorted"`,
+      #   `"separator"`, `"when_empty"`)
+      # @return [String, nil] the `let` line formatting the argument through
+      #   `list`/`quoted`, or `nil` if the argument needs no formatting local
+      #   (a scalar written as-is)
       def formatted_local(spec)
         name  = spec.fetch("argument")
         field = "self.#{rust_field(name)}"
@@ -299,6 +421,13 @@ module Hecks
         end
       end
 
+      # Describes one argument's formatting rule in English, for its struct field's doc comment.
+      #
+      # @param spec [Hash{String => String}] one `RefusalSiteArgument` row
+      #   (`"shape"`, `"quoting"`, and, for a list, `"sorted"`, `"separator"`,
+      #   `"when_empty"`)
+      # @return [String] a short English reading of the row's formatting rule,
+      #   used as the struct field's own doc comment
       def rule_reading(spec)
         quoting = spec.fetch("quoting") == "inspect" ? ", quoted" : ""
         return "scalar#{quoting}" unless spec.fetch("shape") == "list"
@@ -307,10 +436,33 @@ module Hecks
         "list#{sorted}#{quoting}, joined #{spec.fetch('separator').inspect}, empty reads #{spec.fetch('when_empty').inspect}"
       end
 
+      # The local variable name `formatted_local` binds an argument's formatted value to.
+      #
+      # @param argument [String] the `RefusalSiteArgument` row's `"argument"` name
+      # @return [String] the Rust local variable name `formatted_local` binds the
+      #   formatted value to
       def local_name(argument) = "#{argument}_text"
 
+      # An argument name, escaped for use as a Rust field/parameter identifier.
+      #
+      # @param argument [String] the `RefusalSiteArgument` row's `"argument"` name
+      # @return [String] `argument`, prefixed with `r#` if it collides with a Rust
+      #   keyword in `RUST_KEYWORDS`
       def rust_field(argument) = RUST_KEYWORDS.include?(argument) ? "r##{argument}" : argument
 
+      # Renders the table's `#[cfg(test)]` module: every kind's `from_name` round-trip
+      # test, plus `:order`'s and `:templates`' own tests.
+      #
+      # @param enum [String] the Rust enum name
+      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
+      # @param variants [Array<String>] each row's generated variant name, only
+      #   read when `kind == :templates`
+      # @param rows [Array<Hash{String => String}>] the table's rows, only read
+      #   when `kind == :templates`
+      # @param by_site [Hash{Array<String> => Array<Hash{String => String}>}, nil]
+      #   each `[refusal, site]` pair's declared argument rows, only read when
+      #   `kind == :templates`
+      # @return [Array<String>] the `#[cfg(test)]` module's full source lines
       def tests(enum, kind, variants = [], rows = [], by_site = nil)
         list = kind == :order ? "ORDER" : "ALL"
         name = accessor_name(kind == :templates ? "site" : name_field(kind))
@@ -336,6 +488,11 @@ module Hecks
         lines + ["}"]
       end
 
+      # The `:order` kind's own test, checked into every order table's test module.
+      #
+      # @param enum [String] the Rust enum name
+      # @return [Array<String>] the test asserting `ORDER`'s index matches each
+      #   variant's `position`
       def order_test(enum)
         ["    #[test]",
          "    fn position_is_the_index_in_order() {",
@@ -348,6 +505,10 @@ module Hecks
 
       # Placeholders are read off each template's own text, never a second
       # hand-kept list.
+      #
+      # @param enum [String] the Rust enum name
+      # @return [Array<String>] the test asserting every site's `render` leaves
+      #   no `{...}` placeholder unfilled
       def placeholder_test(enum)
         ["    #[test]",
          "    fn every_site_renders_with_no_leftover_placeholder() {",
@@ -377,12 +538,21 @@ module Hecks
          "    }"]
       end
 
-      # THE RUBY ORACLE, PINNED. Every site renders through its typed
+      # The Ruby oracle, pinned. Every site renders through its typed
       # `render_args` for each edge case a list argument has — empty, one
       # item, several out of order — and must equal what
       # Runtime::RefusalWording.render_with answers for the same values,
       # computed here at generation time. Scalars carry a `"` so quoting
       # is compared too.
+      #
+      # @param variants [Array<String>] each row's generated variant name, matching `rows`
+      # @param rows [Array<Hash{String => String}>] the `RefusalTemplate` rows, in
+      #   the same order as `variants`
+      # @param by_site [Hash{Array<String> => Array<Hash{String => String}>}] each
+      #   `[refusal, site]` pair's declared argument rows, as built by `site_arguments`
+      # @return [Array<String>] the test asserting every variant's `render_args`
+      #   output for each `argument_cases` case matches
+      #   `Runtime::RefusalWording.render_with`, computed here in Ruby
       def render_args_test(variants, rows, by_site)
         asserts = variants.zip(rows).flat_map do |variant, row|
           specs = by_site.fetch([row.fetch("refusal"), row.fetch("site")])
@@ -407,6 +577,14 @@ module Hecks
 
       LIST_CASES = [[], ["only \"one\""], %w[zeta alpha mid]].freeze
 
+      # Builds the argument-value cases `render_args_test` checks a site's
+      # `render_args` against.
+      #
+      # @param specs [Array<Hash{String => String}>] one site's declared
+      #   `RefusalSiteArgument` rows
+      # @return [Array<Hash{Symbol => Object}>] one argument Hash per test case —
+      #   `LIST_CASES` (empty, one item, several unsorted) if any spec is
+      #   list-shaped, else a single scalar case, each scalar value carrying a `"`
       def argument_cases(specs)
         cases = specs.any? { |spec| spec.fetch("shape") == "list" } ? LIST_CASES : [nil]
         cases.map do |items|
@@ -417,12 +595,29 @@ module Hecks
         end
       end
 
+      # The row field a table's `from_name`/round-trip test treats as its "name".
+      #
+      # @param kind [Symbol] the table's `:kind` (`:order`, `:templates`, or `:set`)
+      # @return [String] the row field used as this kind's "name" — `"step"` for
+      #   `:order`, `"name"` otherwise
       def name_field(kind) = kind == :order ? "step" : "name"
 
       # `refusal` is a Rust-safe word but reads ambiguously beside the
       # kernel's own `Refusal` enum; the accessor says what it answers.
+      #
+      # @param field [String] a row field name, such as `"name"` or `"refusal"`
+      # @return [String] the Rust accessor method name for `field` —
+      #   `"refusal_class"` for `"refusal"`, `field` otherwise
       def accessor_name(field) = field == "refusal" ? "refusal_class" : field
 
+      # Builds one row's Rust enum variant name from its declared `variant_from` fields.
+      #
+      # @param row [Hash{String => String}] the table row to name
+      # @param fields [Array<String>] the row fields, PascalCased and concatenated
+      #   in order to build the variant name
+      # @return [String] the row's generated Rust enum variant name
+      # @raise [ArgumentError] if the built name is not a valid Rust variant
+      #   identifier (uppercase first letter, alphanumeric only)
       def variant_name(row, fields)
         name = fields.map { |field| pascal(row.fetch(field)) }.join
         raise ArgumentError, "#{name.inspect} is not a Rust variant name" unless name.match?(/\A[A-Z][A-Za-z0-9]*\z/)
@@ -430,10 +625,18 @@ module Hecks
         name
       end
 
+      # PascalCases one field value for use inside a generated variant name.
+      #
+      # @param text [String, Symbol, nil] the value to PascalCase; each
+      #   `_`-separated part's first letter is upcased
+      # @return [String] `text` converted to PascalCase, or `""` if `text` is `nil`
       def pascal(text) = text.to_s.split("_").map { |part| part[0].to_s.upcase + part[1..].to_s }.join
 
       # A Rust string literal: only `\`, `"` and newlines need escaping in
       # the text any vocabulary row holds.
+      #
+      # @param text [String] the value to render as a Rust string literal
+      # @return [String] `text`, backslash/quote/newline-escaped and wrapped in `"..."`
       def rust_string(text)
         escaped = text.to_s.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("\n") { "\\n" }
         "\"#{escaped}\""

data/lib/hecks/projections/shape.rb

@@ -31,6 +31,14 @@ module Hecks
       # is "every file here registers," not "every projection always
       # succeeds") but refuses clearly if asked to run with the plugin
       # unloaded, rather than raising on an undefined constant.
+      # Projects the storage shape of `bluebook` — the structural form an era
+      # bump/no-bump question is answered by diffing.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook to reduce to its storage shape
+      # @param options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [Hash{String => Object}] `Runtime::StorageShape.project`'s Hash: `"name"`
+      #   and a sorted `"aggregates"` array
+      # @raise [RuntimeError] if the era persistence plugin is not loaded
       def call(bluebook:, options: {})
         unless Ports::Persistence.plugin?(:era)
           raise "the :shape projection needs the era persistence plugin loaded " \