hecks 2.7.0 → 2.9.0

data/lib/hecks/forms/params.rb

@@ -4,38 +4,19 @@ require_relative "field_renderer"
 
 module Hecks
   module Forms
-    # The two directions between a flat, dotted, all-strings web payload
-    # (`{"amount.cents"=>"1050", "amount.currency"=>"USD"}`, whether it came
-    # off a POST form body or a GET query string — Rack hands back the same
-    # flat shape for both as long as nothing uses `[]` bracket names) and the
-    # nested, typed hash `Dispatcher#dispatch`/`#query` actually take
-    # (`{amount: {cents: 1050, currency: "USD"}}`).
+    # Converts between flat dotted web params (`{"amount.cents"=>"1050"}`) and the nested
+    # hash of typed values a dispatch takes (`{amount: {cents: 1050}}`).
     #
-    # `extract` needs the Field tree, not just the raw params — a numeric
-    # leaf's own runtime check (`Value::Coercion#check_numeric_fields`)
-    # requires an actual `Integer`/`Float`, not a String that merely looks
-    # like one (`given.is_a?(expected)`, no coercion attempted there); a web
-    # form can only ever hand back strings, so the cast has to happen here,
-    # once, using the same shape `FieldShape` already resolved for
-    # rendering the input in the first place — one reading of the IR, not
-    # two that could disagree.
+    # `extract` needs the Field tree because the runtime's numeric check rejects
+    # numeric-looking Strings, so the cast happens here.
     module Params
       # Casts a flat, all-strings web payload into the nested, typed arguments a command or
       # query takes, guided by the field tree the form was rendered from.
       #
-      # Every leaf field carries its own full dotted path regardless of how
-      # deep `FieldShape` nested it to get there — a single-attribute value
-      # object unwraps to a leaf sitting at the top of the fields array with
-      # a two-segment path (`"reference.value"`), the exact same shape a
-      # `:group`'s own child carries. So this collects every leaf as
-      # (full path -> value) first, and nests by the path's own segments
-      # last — one nesting rule, blind to how a field arrived at its path.
-      #
-      # @param fields [Array<Forms::Field>] the resolved field tree the payload was posted
-      #   against
+      # @param fields [Array<Forms::Field>] the resolved field tree the payload was posted against
       # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
-      # @return [Hash{Symbol => Object}] nested, typed arguments keyed by path segment, ready
-      #   to splat into a dispatch; a blank optional field is left out
+      # @return [Hash{Symbol => Object}] nested, typed arguments ready to splat into a dispatch;
+      #   a blank optional field is left out
       # @raise [ArgumentError] if a number field's text is not numeric, or two fields collide
       #   at one path (see `nest`)
       # @raise [TypeError] if a required number field is missing from `raw`
@@ -68,23 +49,8 @@ module Hecks
       # Nests values keyed by dotted path into a Hash keyed by path segment, refusing two
       # paths that cannot share one result.
       #
-      # A path-prefix collision: one field named (say) "price" alongside
-      # another named "price.cents" implies "price" is both a scalar leaf
-      # and the parent of a nested group — the two can never coexist in
-      # the same result hash. Depending on which pair `each_with_object`
-      # reaches first, an unguarded walk fails in one of two ways: a scalar
-      # planted first leaves `acc[segment] ||= {}` seeing a truthy non-Hash
-      # and reusing it as `node`, so the next `node[leaf] = value` blows up
-      # with a raw `TypeError` from calling `String#[]=` with a Symbol key;
-      # a scalar planted after the nested group instead sails through
-      # `node[leaf] = value` and silently clobbers the entire nested hash
-      # with the scalar, losing every sibling under it with no error at
-      # all. Both directions are checked explicitly here so either order
-      # raises the same clear `ArgumentError` instead of a confusing crash
-      # or silent data loss — this is the family of error every
-      # command/query submission path in app.rb already rescues into a 422
-      # (`ArgumentError` sits right alongside the domain refusals in every
-      # one of those rescue clauses).
+      # "price" and "price.cents" cannot coexist. Both orders are checked so a collision
+      # raises ArgumentError (rescued into a 422) rather than a TypeError or silent data loss.
       #
       # @param pairs [Hash{String => Object}] values keyed by dotted path, such as
       #   `{"amount.cents" => 1050}`
@@ -121,11 +87,8 @@ module Hecks
 
       # Reads a `:list` field's textarea into an Array, one element per non-blank line.
       #
-      # One line of the textarea per element. A line that itself needs
-      # several fields (a multi-attribute value object as a list element)
-      # is read as JSON on that one line — the honest fallback documented in
-      # docs/command-form-and-query-form-bluebook.md rather than a second
-      # widget this prototype doesn't build yet.
+      # One textarea line per element; a multi-attribute value object element is read as
+      # JSON on its line.
       #
       # @param field [Forms::Field] a `:list` field whose first child describes one element
       # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
@@ -191,13 +154,8 @@ module Hecks
       # Flattens held values back into the dotted-path, all-strings pairs a query string
       # carries — the reverse of `extract`.
       #
-      # The other direction — a nested value hash back to the flat dotted
-      # pairs a GET link's query string carries, so a query view's
-      # "shareable link" and its filter form stay two renderings of the
-      # same data rather than two formats that can drift. Reads with
-      # `FieldRenderer.dig` — the identical full-path lookup a re-rendered
-      # input's own value comes from — for the same reason `extract` above
-      # nests by full path rather than by tree shape.
+      # Reads with `FieldRenderer.dig`, the same full-path lookup a re-rendered input uses,
+      # so a shareable link and its filter form cannot drift.
       #
       # @param fields [Array<Forms::Field>] the field tree naming which paths to read
       # @param values [Hash{String, Symbol => Object}] held values, flat or nested; see
@@ -221,11 +179,7 @@ module Hecks
       # Lists every dotted path a field tree submits under, whether or not anything was
       # entered for it.
       #
-      # Every leaf/list path a field tree carries, independent of any
-      # values — what `command_form_renderer.rb`'s inspect panel wants
-      # ("which fields does this command take"), where `flatten` above wants
-      # "what does this one submission look like" and returns nothing for a
-      # field nothing was entered for.
+      # Unlike `flatten`, this does not depend on values, so unset fields are listed too.
       #
       # @param fields [Array<Forms::Field>] the field tree to walk
       # @param into [Array<String>] accumulator the paths are appended to in place

data/lib/hecks/forms/port_argument.rb

@@ -1,24 +1,7 @@
 module Hecks
   module Forms
-    # bin/present's own `-p`/`--port` reader, pulled out of the script so
-    # it can be driven directly instead of only through a real server
-    # boot. Two spellings the previous inline version got wrong:
-    #
-    #   --port=8080   the equals form — the old `ARGV.each_cons(2)` scan
-    #                 only ever recognized "--port", "8080" as two
-    #                 separate argv entries, so this spelling matched
-    #                 nothing and silently fell through to the default.
-    #   -p abc        a non-numeric value — the old code did `.to_i` on
-    #                 whatever followed unconditionally, so a typo
-    #                 quietly became port 0 (Rackup/WEBrick's actual
-    #                 behavior for `Port: 0` is to bind an ephemeral
-    #                 port — arguably useful on purpose elsewhere, but
-    #                 never what a mistyped `-p abc` meant to ask for).
-    #
-    # Returns `[port, nil]` on a clean parse (falling back to `default`
-    # when neither spelling appears at all) or `[nil, message]` when an
-    # explicit port was given but isn't a real port number — the caller
-    # decides what to do with a refusal (bin/present aborts on it).
+    # Reads bin/present's `-p PORT` / `--port PORT` / `--port=PORT` argument.
+    # Returns `[port, nil]` or `[nil, message]`; a non-numeric port is refused, not read as 0.
     module PortArgument
       module_function
 

data/lib/hecks/forms/query_form_renderer.rb

@@ -9,32 +9,10 @@ require_relative "record_table"
 
 module Hecks
   module Forms
-    # Query -> the page body for its GET view — the working half of what
-    # `query_form.bluebook` names (see docs/command-form-and-query-form-
-    # bluebook.md): a canonical, shareable link (queries are GETs — every
-    # one of them is already a URL, so this says so up front rather than
-    # hiding that behind a form); a row of ready-made links for any
-    # closed-set parameter, since a caller filtering by an enum should not
-    # have to fill in a form to get a link they could just click; a filter
-    # form for everything else, which — being a GET form — produces
-    # exactly the same kind of link on submit; and the results table once
-    # a request actually supplies parameters.
+    # The GET view of a query: canonical link, quick links, filter form and results.
+    # See docs/command-form-and-query-form-bluebook.md.
     module QueryFormRenderer
-      # Renders one query's whole GET view: header, canonical link, quick links, filter
-      # form, any error, results, and the inspect panel.
-      #
-      # @param registry [Runtime::Registry] the booted registry, for resolving reference
-      #   fields' target aggregates
-      # @param domain [String] the owning chapter's name
-      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
-      # @param query [Bluebook::Query] the query being rendered
-      # @param action [String] the form's `action` URL and the canonical link's base
-      # @param params [Hash] the request's own query params, pre-filling the filter form
-      # @param results [Array<Hash>, nil] the query's own answer rows; `nil` renders no
-      #   results section
-      # @param error [StandardError, nil] a raised error to show in the error banner;
-      #   `nil` renders none
-      # @return [String] the page body markup
+      # Renders one query's whole GET view as the page body.
       def self.render(registry:, domain:, aggregate:, query:, action:, params: {}, results: nil, error: nil)
         fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
         reference_options = ReferenceOptions.collect(registry, domain, fields)
@@ -50,12 +28,6 @@ module Hecks
         HTML
       end
 
-      # Renders the query's title, description and badges.
-      #
-      # @param domain [String] the owning chapter's name
-      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
-      # @param query [Bluebook::Query] the query being rendered
-      # @return [String] the header markup
       def self.header(domain, aggregate, query)
         <<~HTML
           <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}")}</h1>
@@ -64,22 +36,12 @@ module Hecks
         HTML
       end
 
-      # Renders the query's declared badges — today, just its `limit` when it declares one.
-      #
-      # @param query [Bluebook::Query] the query being rendered
-      # @return [String] the badge markup; `""` when the query declares no `limit`
       def self.badges(query)
         parts = []
         parts << %(<span class="badge">limit #{Escape.html(query.limit.to_h[:value])}</span>) if query.limit
         parts.join
       end
 
-      # Renders the query's plain-GET canonical link template, one `path={path}` per
-      # parameter.
-      #
-      # @param action [String] the query's base URL
-      # @param fields [Array<Forms::Field>] the resolved field tree naming the parameters
-      # @return [String] the help text and the templated link markup
       def self.canonical_link(action, fields)
         paths = Params.paths(fields)
         template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join('&')}"
@@ -89,18 +51,7 @@ module Hecks
         HTML
       end
 
-      # The one enum-shaped parameter (if there is one) rendered as literal,
-      # clickable links — no form to fill in for "show me the suspended
-      # ones". Capped at the first closed-set field on purpose: a second one
-      # would mean a cross product of links, which reads as noise rather
-      # than help. A query with more than one is still fully reachable
-      # through the filter form below.
-      #
-      # @param action [String] the query's base URL
-      # @param fields [Array<Forms::Field>] the resolved field tree to search for a
-      #   `:select` or `:radio` field
-      # @return [String] one clickable link per option of the first closed-set field
-      #   found; `""` when no field is `:select` or `:radio`
+      # Capped at the first closed-set field: a second would mean a cross product of links.
       def self.quick_links(action, fields)
         field = fields.find { |f| %i[select radio].include?(f.kind) }
         return "" unless field
@@ -112,14 +63,6 @@ module Hecks
         %(<div class="example-links">#{links.join}</div>)
       end
 
-      # Renders the GET filter form covering every declared parameter.
-      #
-      # @param action [String] the form's `action` URL
-      # @param fields [Array<Forms::Field>] the resolved field tree to render
-      # @param params [Hash] the request's own query params, pre-filling each field
-      # @param reference_options [Hash{String => Array<Array(String, String)>, nil}] each
-      #   `:reference` field's own dropdown options, as `ReferenceOptions.collect` returns
-      # @return [String] the form markup; `""` when the query declares no parameters
       def self.filter_form(action, fields, params, reference_options)
         return "" if fields.empty?
 
@@ -131,10 +74,6 @@ module Hecks
         HTML
       end
 
-      # Renders a raised error as a dismissable-looking alert banner.
-      #
-      # @param error [StandardError, nil] the error to show
-      # @return [String] the banner markup; `""` when `error` is `nil`
       def self.error_banner(error)
         return "" unless error
 
@@ -142,26 +81,12 @@ module Hecks
           "#{Escape.html(error.message)}</p></div>"
       end
 
-      # Renders the results heading and table, once a request actually supplied
-      # parameters.
-      #
-      # @param aggregate [Bluebook::Aggregate] the aggregate whose fields shape the table
-      # @param results [Array<Hash>, nil] the query's own answer rows
-      # @param domain [String] the owning chapter's name, for building record links
-      # @return [String] the results section markup; `""` when `results` is `nil`
       def self.results_section(aggregate, results, domain)
         return "" unless results
 
         "<h2>Results (#{results.size})</h2>#{RecordTable.render(aggregate, results, domain: domain)}"
       end
 
-      # Renders a collapsed panel with the query's own parameter list and raw IR JSON.
-      #
-      # @param domain [String] the owning chapter's name
-      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
-      # @param query [Bluebook::Query] the query being rendered
-      # @param fields [Array<Forms::Field>] the resolved field tree, for the parameter list
-      # @return [String] the `<details>` panel markup
       def self.inspect_panel(domain, aggregate, query, fields)
         verb = "#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}"
         paths = Params.paths(fields)

data/lib/hecks/forms/record_renderer.rb

@@ -4,19 +4,10 @@ require_relative "record_table"
 
 module Hecks
   module Forms
-    # The two pages a `.bluebook` doesn't declare but a browsing developer
-    # always wants: every record of an aggregate, and one record's own
-    # state plus what it can legally do next. Neither is a `query` — they
-    # read the repository directly, the same way `AggregateDoor#all`/`#find`
-    # do (facade/surface/aggregate_door.rb) — so they exist for every
-    # aggregate whether or not its bluebook declared a query at all.
+    # The index and show pages every aggregate gets, whether or not it declares a query.
+    # They read the repository directly, like `AggregateDoor#all`/`#find`.
     module RecordRenderer
-      # Renders the index page listing every record of one aggregate.
-      #
-      # @param registry [Runtime::Registry] the booted registry holding the domain
-      # @param domain [String, Symbol] the domain name
-      # @param aggregate [Bluebook::Aggregate] the aggregate whose records are listed
-      # @return [String] the index page's rendered HTML
+      # Renders the page listing every record of one aggregate.
       def self.index(registry:, domain:, aggregate:)
         instances = registry.repository(domain, aggregate).all
         <<~HTML
@@ -29,12 +20,6 @@ module Hecks
         HTML
       end
 
-      # Renders the "+ Command" buttons for every creating command.
-      #
-      # @param domain [String, Symbol] the domain name
-      # @param aggregate [Bluebook::Aggregate] the aggregate whose creating commands
-      #   are linked
-      # @return [String] HTML action buttons, or `""` if the aggregate declares none
       def self.creating_links(domain, aggregate)
         creators = aggregate.commands.select(&:creates?)
         return "" if creators.empty?
@@ -46,15 +31,8 @@ module Hecks
         %(<div class="actions">#{links.join}</div>)
       end
 
-      # Renders one record's state page: its current fields, plus the commands and
-      # queries it can dispatch next.
-      #
-      # @param registry [Runtime::Registry] the booted registry holding the domain
-      # @param domain [String, Symbol] the domain name
-      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
-      # @param id [String, Object] the record's identity
-      # @return [String, nil] the record page's rendered HTML, or nil if no record
-      #   has that id
+      # Renders one record's state plus the commands and queries it can dispatch next.
+      # Returns nil when no record has that id.
       def self.show(registry:, domain:, aggregate:, id:)
         instance = registry.repository(domain, aggregate).find(id)
         return nil unless instance
@@ -71,10 +49,6 @@ module Hecks
         HTML
       end
 
-      # Renders a record's state as an HTML field table.
-      #
-      # @param state [Hash{Symbol => Object}] the record's stored attribute values
-      # @return [String] an HTML table of the state's fields, values escaped
       def self.state_table(state)
         rows = state.map do |key, value|
           "<tr><th>#{Escape.html(Humanize.label(key.to_s))}</th><td>#{Escape.html(render_value(value))}</td></tr>"
@@ -82,13 +56,7 @@ module Hecks
         %(<div class="table-scroll"><table><tbody>#{rows.join}</tbody></table></div>)
       end
 
-      # `Value.materialize` first — a stored field is a `Runtime::Value`
-      # wherever its attribute is a value object, not a plain Hash (see
-      # record_table.rb's own note on the same read).
-      #
-      # @param value [Object] a stored field's value, possibly a `Runtime::Value`
-      # @return [String] the value rendered as text: a Hash as `"key: value, ..."`
-      #   pairs, an Array `;`-joined, anything else its own `to_s`
+      # A stored field is a `Runtime::Value` wherever its attribute is a value object.
       def self.render_value(value)
         case (value = Runtime::Value.materialize(value))
         when Hash then value.map { |k, v| "#{k}: #{render_value(v)}" }.join(", ")
@@ -97,27 +65,13 @@ module Hecks
         end
       end
 
-      # Every non-creating command, except a lifecycle transition that does
-      # not apply from the record's current state — the same rule
-      # `Rules#admissible_transition` enforces at dispatch, read here so a
-      # link that would only refuse is never offered in the first place.
-      #
-      # @param domain [String, Symbol] the domain name
-      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
-      # @param id [String, Object] the record's identity
-      # @param current_state [String, nil] the record's current lifecycle state, or
-      #   nil if the aggregate has no lifecycle field or it is unset
-      # @return [String] an HTML list of admissible command links, or a message
-      #   when no command currently applies
+      # Omits lifecycle transitions that dispatch would refuse from the current state.
       def self.command_links(domain, aggregate, id, current_state)
         commands = aggregate.commands.reject(&:creates?).select { |cmd| applies?(aggregate, cmd, current_state) }
         return "<p><em>No commands act on an existing #{Escape.html(aggregate.hecks_name)}.</em></p>" if commands.empty?
 
         items = commands.map do |cmd|
-          # L12 — the id is free-form (S3): percent-encoded as the query
-          # value (a raw `&` here would smuggle a second bogus query
-          # parameter), then the assembled href is attribute-escaped as
-          # usual.
+          # The id is free-form, so it is percent-encoded as a query value.
           href = "/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html?to=#{Escape.url(id)}"
           %(<li><a href="#{Escape.attr(href)}"><span>#{Escape.html(cmd.hecks_name)}</span>) \
             "<span class=\"kind\">#{Escape.html(cmd.goal.to_s)}</span></a></li>"
@@ -125,14 +79,6 @@ module Hecks
         %(<ul class="verb-list">#{items.join}</ul>)
       end
 
-      # Whether the aggregate's lifecycle admits dispatching `command` from
-      # `current_state`.
-      #
-      # @param aggregate [Bluebook::Aggregate] the aggregate the command belongs to
-      # @param command [Bluebook::Command] the command to check
-      # @param current_state [String, nil] the record's current lifecycle state
-      # @return [Boolean] true if the aggregate declares no lifecycle transitions for
-      #   this command, or one of them admits `current_state`
       def self.applies?(aggregate, command, current_state)
         transitions = aggregate.lifecycle&.transitions_for(command.hecks_name) || []
         return true if transitions.empty?
@@ -140,12 +86,6 @@ module Hecks
         transitions.any? { |t| t.from.nil? || Array(t.from).map(&:to_s).include?(current_state.to_s) }
       end
 
-      # Renders the "Queries" link list for an aggregate's own queries.
-      #
-      # @param domain [String, Symbol] the domain name
-      # @param aggregate [Bluebook::Aggregate] the aggregate whose queries are linked
-      # @return [String] an HTML section listing every query, or `""` if the
-      #   aggregate declares none
       def self.query_links(domain, aggregate)
         return "" if aggregate.queries.empty?
 
@@ -156,13 +96,6 @@ module Hecks
         %(<h2>Queries</h2><ul class="verb-list">#{items.join}</ul>)
       end
 
-      # Renders the full command-and-query index for an aggregate, independent of
-      # any one record's state.
-      #
-      # @param domain [String, Symbol] the domain name
-      # @param aggregate [Bluebook::Aggregate] the aggregate whose verbs are listed
-      # @return [String] an HTML section listing every non-creating command and every
-      #   query, or `""` if the aggregate declares neither
       def self.verb_list(domain, aggregate)
         commands = aggregate.commands.reject(&:creates?)
         return "" if commands.empty? && aggregate.queries.empty?

data/lib/hecks/forms/record_table.rb

@@ -3,42 +3,20 @@ require_relative "field_shape"
 
 module Hecks
   module Forms
-    # The one shape every renderer in this directory reads a record as —
-    # `id` plus its state hash. `Runtime::Instance` already answers both,
-    # so `repository.all`'s own records pass straight through; a query's
-    # answer does not (`QueryInterpreter#call` flattens `{id:}.merge(state)`
-    # into one hash with no method to call — see
-    # docs/command-form-and-query-form-bluebook.md's note on why), so
-    # app.rb wraps those results in one of these before they ever reach a
-    # renderer, and every renderer here only has to know one shape.
+    # A record as every renderer here reads it: `id` plus its state hash.
+    # Query results are flat hashes, so they are wrapped in one before rendering.
     Record = Struct.new(:id, :state)
 
-    # An array of Record (or anything answering `#id`/`#state` — a
-    # Runtime::Instance qualifies without wrapping) -> an HTML table.
-    # Shared by the aggregate index page (record_renderer.rb) and a
-    # query's own results (query_form_renderer.rb) — the same records
-    # read the same columns either way.
+    # Records (a Record or anything answering `#id`/`#state`) as an HTML table.
     module RecordTable
-      # Picks which fields to show as columns: identity, lifecycle state, then scalar
-      # attributes, capped at seven.
-      #
-      # @param aggregate [Bluebook::Aggregate] the aggregate whose records will be shown
-      # @return [Array<Symbol>] up to 7 unique field names, in that order; excludes
-      #   reference and list attributes
+      # Identity, lifecycle state, then scalar attributes, capped at seven columns.
       def self.columns(aggregate)
         lifecycle = aggregate.lifecycle&.field
         scalars = aggregate.attributes.reject { |a| a.reference? || a.list? }.map(&:name)
         [*aggregate.identity_heads, lifecycle, *scalars].compact.uniq.first(7)
       end
 
-      # Renders a list of records as an HTML table, one row per record.
-      #
-      # @param aggregate [Bluebook::Aggregate] the aggregate the records belong to
-      # @param instances [Array<Runtime::Instance, Forms::Record>] the records to render;
-      #   anything answering `#id`/`#state` works
-      # @param domain [String] the owning chapter's name, for building each row's link
-      # @return [String] the table markup; `"<p><em>No records.</em></p>"` when
-      #   `instances` is empty
+      # Renders records as an HTML table, one row per record.
       def self.render(aggregate, instances, domain:)
         cols = columns(aggregate)
         head = (["id"] + cols).map { |name| "<th>#{Escape.html(Humanize.label(name.to_s))}</th>" }.join
@@ -53,36 +31,15 @@ module Hecks
         HTML
       end
 
-      # Renders one record's own table row, linked to its show page.
-      #
-      # @param instance [Runtime::Instance, Forms::Record] the record to render
-      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
-      # @param cols [Array<Symbol>] the column field names, as `columns` returns them
-      # @param domain [String] the owning chapter's name, for building the row's link
-      # @return [String] the `<tr>` markup
       def self.row(instance, aggregate, cols, domain)
         cells = cols.map { |name| "<td>#{Escape.html(cell(instance, name))}</td>" }.join
-        # L12 — the id is free-form (S3): percent-encoded as the path
-        # segment, HTML-escaped as the link text, and the assembled href
-        # is itself attribute-escaped (belt-and-suspenders — nothing else
-        # in `href` is untrusted, but this matches the convention used
-        # everywhere else an href is built from parts).
+        # The id is free-form, so it is percent-encoded in the path.
         href = "/#{domain}/#{aggregate.hecks_name}/#{Escape.path(instance.id)}.html"
         "<tr><td><a href=\"#{Escape.attr(href)}\">#{Escape.html(instance.id)}</a></td>#{cells}</tr>"
       end
 
-      # Reads one field's value for display, unwrapped to a single cell value.
-      #
-      # @param instance [Runtime::Instance, Forms::Record] the record to read
-      # @param name [Symbol] the field name to read
-      # @return [Object] the field's own value; for a Hash-shaped value object, its
-      #   first member's value; `""` for `nil`
       def self.cell(instance, name)
-        # `state` holds `Runtime::Value` wherever an attribute is a value
-        # object, not a plain Hash — `.materialize` is the runtime's own
-        # unwrap (value.rb), the same one a `to_h` read anywhere else in
-        # this codebase goes through, so a table cell agrees with every
-        # other reader about what a stored field actually contains.
+        # `state` holds a `Runtime::Value` wherever an attribute is a value object.
         value = Runtime::Value.materialize(instance.state[name])
         case value
         when Hash then value.values.first

data/lib/hecks/forms/reference_options.rb

@@ -1,33 +1,15 @@
 module Hecks
   module Forms
-    # A Field tree (field_shape.rb) -> `{path => [[id, label], ...]}` for
-    # every `:reference` field in it — the options a `<select>` needs.
-    # Shared by CommandFormRenderer and QueryFormRenderer alike: a
-    # command's own reference field and a query's own reference parameter
-    # resolve against the same repository the same way, and neither word
-    # owns this more than the other.
+    # The `<select>` options for every `:reference` field in a Field tree, keyed by path.
+    # Shared by the command and query form renderers.
     module ReferenceOptions
-      # Collects every `:reference` field's own dropdown options out of a resolved field
-      # tree.
-      #
-      # @param registry [Runtime::Registry] the booted registry to read repositories from
-      # @param domain [String] the owning chapter's name
-      # @param fields [Array<Forms::Field>] the resolved field tree to search
-      # @return [Hash{String => Array<Array(String, String)>, nil}] one entry per
-      #   `:reference` field found, keyed by its `path`; `nil` when the field's target
-      #   could not be resolved or its options could not be read
+      # Returns `{path => [[id, id], ...]}`; nil for a field whose options cannot be read.
       def self.collect(registry, domain, fields)
         targets = {}
         walk(fields) { |field| targets[field.path] = field.target_aggregate if field.kind == :reference }
         targets.transform_values { |aggregate| aggregate && options_for(registry, domain, aggregate) }
       end
 
-      # Visits every field in a tree, depth-first, including each `:list`/`:group`
-      # field's own children.
-      #
-      # @param fields [Array<Forms::Field>] the field tree to walk
-      # @yieldparam field [Forms::Field] each field visited, parent before children
-      # @return [void]
       def self.walk(fields, &block)
         fields.each do |field|
           block.call(field)
@@ -35,15 +17,6 @@ module Hecks
         end
       end
 
-      # Reads up to 200 records' ids as `<select>` options, for one reference field's
-      # target aggregate.
-      #
-      # @param registry [Runtime::Registry] the booted registry to read the repository from
-      # @param domain [String] the owning chapter's name
-      # @param aggregate [Bluebook::Aggregate] the referenced aggregate to list
-      # @return [Array<Array(String, String)>, nil] up to 200 `[id, id]` pairs; `nil` when
-      #   the repository cannot be resolved (a wiring gap degrades to a plain text id
-      #   input, not a 500)
       def self.options_for(registry, domain, aggregate)
         registry.repository(domain, aggregate).all.first(200).map { |instance| [instance.id, instance.id] }
       rescue StandardError

data/lib/hecks/forms/value_object_shape.rb

@@ -1,53 +1,26 @@
 module Hecks
   module Forms
-    # The value-object classification every consumer of a resolved VO
-    # shape needs, spelled once — `field_shape.rb` (a command's own
-    # form), `ui_schema.rb` (the console app's table/detail-panel
-    # renderer, a separate app, not this repo), and
-    # `adapters/driven/sql_query_builder.rb` (a query's own ORDER BY/
-    # where compiler) each grew their own copy of "is this VO money-
-    # shaped," "does it have exactly one attribute, worth unwrapping,"
-    # and "which member of it is numeric" — the same three questions,
-    # answered identically by definition (a VO's shape doesn't change
-    # depending on who's asking), so a fix to one copy was never
-    # guaranteed to reach the others.
+    # Shared value-object shape classification, so callers such as
+    # field_shape.rb, ui_schema.rb and sql_query_builder.rb agree on it.
     module ValueObjectShape
       module_function
 
-      # `Price{cents:, currency:}`/`ContractValue{cents:, currency:}` —
-      # every money-shaped VO in the corpus spells it exactly this way,
-      # the two-attribute convention the language itself never enforces
-      # but every real chapter follows.
-      # @param value_object [Bluebook::ValueObject] the value object to classify
-      # @return [Boolean] true if its attributes are exactly `cents` and `currency`
+      # True if the VO's attributes are exactly `cents` and `currency`, the
+      # convention every money-shaped VO in the corpus follows.
       def money?(value_object)
         value_object.attributes.map { |a| a.name.to_s }.sort == %w[cents currency]
       end
 
-      # A VO with exactly one attribute is a name for a scalar, not a
-      # genuine group (EmailAddress{address}, CustomerNumber{value}) —
-      # [[feedback_name_the_scalar_field]]'s own reasoning, shared here
-      # rather than re-decided per caller. Returns the sole attribute,
-      # or nil for anything else.
-      #
-      # @param value_object [Bluebook::ValueObject] the value object to inspect
-      # @return [Bluebook::Attribute, nil] its one declared attribute, or nil if
-      #   it declares zero or more than one
+      # A VO with exactly one attribute names a scalar, not a genuine group.
+      # Returns that attribute, or nil for anything else.
       def sole_attribute(value_object)
         return nil unless value_object.attributes.size == 1
 
         value_object.attributes.first
       end
 
-      # The first Integer/Float member, or nil — what a numeric
-      # comparison or an ORDER BY compiles against when the VO isn't
-      # money-shaped (money's own two members are handled by `money?`
-      # instead, since which one governs ordering is a money-specific
-      # decision, not a general "pick the first number" one).
-      #
-      # @param value_object [Bluebook::ValueObject] the value object to inspect
-      # @return [Bluebook::Attribute, nil] its first Integer- or Float-typed
-      #   attribute, or nil if it declares none
+      # The first Integer/Float member, or nil — what a numeric comparison or
+      # ORDER BY compiles against when the VO isn't money-shaped.
       def numeric_member(value_object)
         value_object.attributes.find { |a| %w[Integer Float].include?(a.type.to_s) }
       end