hecks 2.8.0 → 3.0.0

data/lib/hecks/forms/field_shape.rb

@@ -4,106 +4,53 @@ require_relative "../naming"
 require_relative "value_object_shape"
 
 module Hecks
-  # The forms surface's own namespace — the `expose` DSL, the IR->HTML
-  # renderers, and the Rack app bridging them; see `forms.rb`'s own header,
-  # its primary opening, for the fuller design this implements.
+  # The forms surface: the `expose` DSL, the IR->HTML renderers and the Rack app (see forms.rb).
   module Forms
-    # One resolved field, ready for a renderer to turn into markup. A leaf
-    # scalar carries `kind`/`options`/etc; a `:group` or `:list` carries
-    # `children` instead and nothing else on itself.
-    #
-    # `path` is the dotted field path this attribute is reached at —
-    # `"email.address"`, `"amount.cents"` — the same convention the language
-    # already uses for a query's own cross-object `where` clauses
-    # (`where(:"customer.status" => ...)`), not a fresh one invented here. A
-    # command receives its arguments as nested hashes
-    # (`email: {address: "..."}`), so `Params.extract` (params.rb) walks
-    # this same dotted spelling back apart on submit — one convention, two
-    # directions.
+    # One resolved field, ready for a renderer. A leaf carries `kind`/`options`; a `:group`
+    # or `:list` carries `children`. `path` is the dotted path (`"amount.cents"`) that
+    # `Params.extract` walks back apart on submit.
     Field = Struct.new(
       :path, :label, :kind, :html_type, :options, :children, :default, :optional,
       :pattern, :step, :help, :target_aggregate, keyword_init: true
     ) do
-      # Tells whether this field holds a value itself rather than carrying `children`.
-      #
-      # @return [Boolean] false for a `:group` or `:list`, true for every other kind,
-      #   `:money` included
       def leaf? = kind != :group && kind != :list
 
-      # Tells whether a submission may leave this field blank.
-      #
-      # @return [Boolean, nil] the `optional` member as given; nil when the field was built
-      #   without one, which reads as required
       def optional? = optional
 
-      # Tells whether a submission must fill this field in.
-      #
-      # @return [Boolean] true unless `optional` was set truthy
       def required? = !optional
     end
 
-    # Turns a wire-spelled field or path segment into the plain-English text
-    # `FieldShape` embeds as a `Field`'s label or a group's legend.
+    # Turns a wire-spelled field or path segment into a label or legend.
     module Humanize
-      # Humanizes the last segment of a field name or dotted path into sentence-case words.
-      #
-      # "given" -> "Given", "daily_limit" -> "Daily limit", "end_to_end" ->
-      # "End to end" — the label a plain reader wants, not the wire spelling.
-      #
-      # @param text [String, Symbol, nil] a field name or dotted path, such as
-      #   `"amount.cents"`; only the part after the last `"."` is used
-      # @return [String] the humanized words, or `""` when `text` is nil or empty
+      # "daily_limit" -> "Daily limit"; only the last segment of a dotted path is used.
       def self.label(text)
-        # Split on "." first, alone, to take only the last path segment —
-        # "daily_limit" is one segment (the underscore is a word break
-        # inside it, not a path hop) and must keep both its words; only a
-        # genuinely dotted path ("amount.cents") drops everything before
-        # the last ".".
+        # Split on "." alone: an underscore is a word break within a segment, not a path hop.
         segment = text.to_s.split(".").last.to_s
         return segment if segment.empty?
 
-        # The word split itself is `Naming.words` — the one humanizer,
-        # shared with the glossary projection.
         Naming.words(segment)
       end
 
-      # Humanizes every segment of a dotted path and joins them with " → ".
-      #
-      # The full dotted path, each segment humanized and joined with
-      # " → " for a fieldset legend spanning more than one hop
-      # ("Amount → Cents") — a group's own legend, not a leaf's label.
-      #
-      # @param path [String, Symbol, nil] a dotted field path, such as `"amount.cents"`
-      # @return [String] the humanized trail, or `""` when `path` is nil or empty
+      # "amount.cents" -> "Amount → Cents", for a fieldset legend spanning several hops.
       def self.breadcrumb(path)
         path.to_s.split(".").map { |part| label(part) }.join(" → ")
       end
     end
 
-    # Attribute -> Field. The one mapping every renderer in this
-    # directory reads instead of re-deriving its own — see
-    # docs/command-form-and-query-form-bluebook.md's survey of the gap this closes (the
-    # prior generic-console attempt fell back to `type="text"` for anything
-    # that wasn't a number or an enum; a `pattern` naming an email shape, or a
-    # closed set another aggregate declares, went unread).
+    # Attribute -> Field: the one mapping every form renderer reads instead of re-deriving.
     module FieldShape
       PRIMITIVES = Bluebook::Attribute::PRIMITIVES
 
-      # Resolves one declared attribute into the field a form renders for it, choosing the
-      # input kind from the attribute's type, pattern, `admits:` set and value-object shape.
+      # Resolves one declared attribute into the field a form renders for it.
       #
-      # `aggregate:` is the Aggregate that owns this attribute (a
-      # command's, a query's, or — recursively — a value object's) —
-      # needed to resolve `reference_to`, `admits:`, and a same-chapter
-      # value object by name. `path:` defaults to the attribute's own name;
-      # a caller resolving a nested value object's attribute passes the
-      # dotted path so far.
+      # `aggregate` owns the attribute and is needed to resolve `reference_to`, `admits:`
+      # and same-chapter value objects; `path` is the dotted path reached so far.
       #
-      # @param attribute [Bluebook::Attribute] the attribute to build a field for
-      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
-      # @param path [String] dotted field path the attribute is reached at
-      # @return [Forms::Field] the resolved field; a single-attribute value object resolves
-      #   to its inner leaf, so the returned path may be longer than `path`
+      # @param attribute [Bluebook::Attribute]
+      # @param aggregate [Bluebook::Aggregate]
+      # @param path [String]
+      # @return [Forms::Field] a single-attribute value object resolves to its inner leaf,
+      #   so the returned path may be longer than `path`
       # @raise [Bluebook::DSL::Malformed] if a `reference_to` attribute cannot say which
       #   aggregate declares it
       def self.resolve(attribute, aggregate:, path: attribute.name.to_s)
@@ -119,19 +66,8 @@ module Hecks
         primitive_field(attribute, common)
       end
 
-      # Builds the `:list` field for a `list_of` attribute, carrying as its one child the field
-      # a single element would resolve to.
-      #
-      # @param attribute [Bluebook::Attribute] the list attribute
-      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
-      # @param path [String] dotted field path the list is reached at
-      # @return [Forms::Field] a `:list` field whose `children` holds exactly one element field
-      # @raise [Bluebook::DSL::Malformed] if the element is a `reference_to` that cannot say
-      #   which aggregate declares it
       def self.list_field(attribute, aggregate, path)
-        # The scalar shape one element of this list would take, so a
-        # renderer can say what belongs on each line without a second
-        # mapping table. `list:` is the only thing that differs.
+        # The scalar one element would take; `list:` is the only thing that differs.
         scalar = Bluebook::Attribute.new(
           name: attribute.name, type: attribute.type, list: false,
           default: nil, optional: true, pattern: attribute.pattern, admits: attribute.admits
@@ -140,17 +76,6 @@ module Hecks
                   children: [resolve(scalar, aggregate: aggregate, path: path)])
       end
 
-      # Builds the `:reference` field for a `reference_to` attribute, remembering the target
-      # aggregate so a renderer can offer its records.
-      #
-      # @param attribute [Bluebook::Attribute] an attribute whose type is a
-      #   `Bluebook::Reference`
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
-      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
-      # @return [Forms::Field] a `:reference` field; its `target_aggregate` is nil when the
-      #   target belongs to a domain that is not loaded
-      # @raise [Bluebook::DSL::Malformed] if the reference cannot say which aggregate
-      #   declares it
       def self.reference_field(attribute, common)
         target = attribute.type.resolve
         Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target,
@@ -161,24 +86,8 @@ module Hecks
                                   end)
       end
 
-      # Builds the radio or select field for an attribute whose `admits:` names a closed set,
-      # offering exactly that set's members.
-      #
-      # `admits:` names a closed set declared elsewhere (`"Account::
-      # LedgerDirection"`) that the value must belong to — see
-      # Runtime::Value::Admission#admitted_members, which this mirrors
-      # exactly (same split, same chapter walk, same discriminant rule) so
-      # a rendered `<select>` never offers a member the runtime would then
-      # refuse.
-      #
-      # @param attribute [Bluebook::Attribute] an attribute declaring `admits:`
-      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute; its
-      #   chapter is searched for the named set
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
-      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
-      # @return [Forms::Field] a `:radio` or `:select` field, its path extended by one hop
-      #   when the attribute's own type is a single-attribute value object; a plain
-      #   primitive field when the named set is not declared
+      # Mirrors Runtime::Value::Admission#admitted_members (same split, chapter walk and
+      # discriminant rule) so a `<select>` never offers a member the runtime would refuse.
       def self.admitted_field(attribute, aggregate, common)
         set_aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
         chapter = aggregate.hecks_owner
@@ -187,15 +96,8 @@ module Hecks
         return primitive_field(attribute, common) unless set
 
         options = select_or_radio(common, closed_set_options(set))
-        # The attribute's own type still has to be built the shape coercion
-        # expects (`Value::Coercion#fields_for` refuses anything that
-        # isn't a Hash or a Value for a value-object-typed attribute) — a
-        # plain String attribute stays a bare scalar, but a value object
-        # like `MovementDirection { value }` still needs the ".value" hop
-        # even though the set it's checked against (`admits:`) is declared
-        # somewhere else entirely. Same unwrap `value_object_field` does,
-        # kept separate because an admitted set changes the options, not
-        # which field the hop lands on.
+        # A value-object-typed attribute still needs the ".value" hop that
+        # `Value::Coercion#fields_for` expects, even though `admits:` names a set elsewhere.
         own_shape = own_value_object(attribute, aggregate)
         inner = own_shape && ValueObjectShape.sole_attribute(own_shape)
         return options unless inner
@@ -204,28 +106,10 @@ module Hecks
         options
       end
 
-      # Finds the value object an attribute's type names, looking on the owning aggregate
-      # first and then on every other aggregate of the same chapter.
-      #
-      # @param attribute [Bluebook::Attribute] the attribute whose type names a value object
-      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
-      # @return [Bluebook::ValueObject, nil] the declared shape, or nil when no aggregate in
-      #   the chapter declares a value object of that name
       def self.own_value_object(attribute, aggregate)
         aggregate.value_object(attribute.type) || cross_aggregate_value_object(aggregate, attribute.type)
       end
 
-      # Builds the field for an attribute typed as a value object: a closed-set choice, a
-      # money pair, the unwrapped inner leaf of a single-attribute shape, or a group.
-      #
-      # @param attribute [Bluebook::Attribute] an attribute whose type is not a primitive
-      # @param aggregate [Bluebook::Aggregate] the aggregate that owns the attribute
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
-      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
-      # @return [Forms::Field] the resolved field; a plain primitive field when the named
-      #   value object is not declared anywhere in the chapter
-      # @raise [Bluebook::DSL::Malformed] if a nested `reference_to` attribute cannot say
-      #   which aggregate declares it
       def self.value_object_field(attribute, aggregate, common)
         shape = own_value_object(attribute, aggregate)
         return primitive_field(attribute, common) unless shape
@@ -233,13 +117,8 @@ module Hecks
         return closed_set_field(shape, common) if shape.closed_set?
         return money_field(shape, common) if ValueObjectShape.money?(shape)
 
-        # A single-attribute value object (EmailAddress{address}, CustomerNumber{value})
-        # is a name for a scalar, not a genuine group — unwrap it so the form
-        # asks for one thing ("Email address") instead of a one-item fieldset,
-        # and so the inner attribute's own pattern (the real email regex,
-        # declared on `address`, not on the outer `email` attribute) drives
-        # the input type. [[feedback_name_the_scalar_field]] says the same
-        # thing about Ruby call sites; a form asks the identical question.
+        # A single-attribute value object names a scalar, not a group: unwrap it so the form
+        # asks for one thing and the inner attribute's own pattern drives the input type.
         if (inner = ValueObjectShape.sole_attribute(shape))
           return resolve(inner, aggregate: aggregate, path: "#{common[:path]}.#{inner.name}")
                  .tap { |field| field.optional = common[:optional] || field.optional }
@@ -248,14 +127,6 @@ module Hecks
         group_field(shape, aggregate, common)
       end
 
-      # Searches every aggregate of the owning chapter for a value object by name, so a shape
-      # declared on a sibling aggregate still resolves.
-      #
-      # @param aggregate [Bluebook::Aggregate] any aggregate of the chapter to search
-      # @param type_name [String] name of the value object, as `Bluebook::Attribute#type`
-      #   spells it
-      # @return [Bluebook::ValueObject, nil] the first match in aggregate declaration order, or
-      #   nil when none declares it or the aggregate has no owning chapter
       def self.cross_aggregate_value_object(aggregate, type_name)
         aggregate.hecks_owner&.aggregates&.each do |sibling|
           found = sibling.value_object(type_name)
@@ -264,31 +135,11 @@ module Hecks
         nil
       end
 
-      # Builds the `:group` field for a multi-attribute value object, resolving each of its
-      # attributes one path hop below the group.
-      #
-      # @param shape [Bluebook::ValueObject] the value object whose attributes become children
-      # @param aggregate [Bluebook::Aggregate] the aggregate the nested attributes resolve
-      #   against
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares; only
-      #   `:path`, `:label` and `:optional` are read
-      # @return [Forms::Field] a `:group` field with one child per attribute of `shape`
-      # @raise [Bluebook::DSL::Malformed] if a nested `reference_to` attribute cannot say
-      #   which aggregate declares it
       def self.group_field(shape, aggregate, common)
         children = shape.attributes.map { |inner| resolve(inner, aggregate: aggregate, path: "#{common[:path]}.#{inner.name}") }
         Field.new(path: common[:path], label: common[:label], kind: :group, optional: common[:optional], children: children)
       end
 
-      # Builds the `:money` field for a `cents`/`currency` value object: a required-or-not
-      # whole-cents number input beside an always-optional currency code.
-      #
-      # @param shape [Bluebook::ValueObject] the money-shaped value object, read for the
-      #   declared defaults of `cents` and `currency`
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares; only
-      #   `:path`, `:label` and `:optional` are read
-      # @return [Forms::Field] a `:money` field whose children are the `cents` and `currency`
-      #   leaves, the currency defaulting to `"USD"` when the shape declares none
       def self.money_field(shape, common)
         cents = Field.new(path: "#{common[:path]}.cents", label: "Amount (cents)", kind: :number,
                           html_type: "number", step: "1", optional: common[:optional],
@@ -300,57 +151,25 @@ module Hecks
                   children: [cents, currency])
       end
 
-      # Lists a closed set's members by their discriminant — the value object's first
-      # attribute — as the strings a form offers.
-      #
-      # @param value_object [Bluebook::ValueObject] a closed-set (`one_of`) value object
-      # @return [Array<String>] one discriminant value per declared member, in declaration
-      #   order; `[]` when the shape declares no members
+      # A member's discriminant is the value object's first attribute.
       def self.closed_set_options(value_object)
         discriminant = value_object.attributes.first.name
         value_object.members.map { |member| member[discriminant].to_s }
       end
 
-      # Builds the radio or select field for an attribute typed as a closed set, its path
-      # extended by the set's discriminant attribute.
-      #
-      # A `one_of` shape (`AccountKind{name}`, `LedgerDirection{value}`) is
-      # always single-attribute in this language — the discriminant is the
-      # whole value object — so the field's own path always gains that one
-      # hop; nothing to branch on the way `admitted_field` has to (a set
-      # named by `admits:` may sit on a multi-field value object it doesn't
-      # itself define the members of).
-      #
-      # @param shape [Bluebook::ValueObject] the closed-set value object
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
-      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
-      # @return [Forms::Field] a `:radio` or `:select` field offering the set's members
+      # A `one_of` shape is always single-attribute, so the path always gains the
+      # discriminant hop; `admitted_field` must branch because its set may be multi-field.
       def self.closed_set_field(shape, common)
         discriminant = shape.attributes.first.name
         select_or_radio(common.merge(path: "#{common[:path]}.#{discriminant}"), closed_set_options(shape))
       end
 
-      # Builds a choice field over fixed options, as radio buttons for four or fewer and a
-      # `<select>` beyond that.
-      #
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
-      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
-      # @param options [Array<String>] the values offered; each is its own label
-      # @return [Forms::Field] a `:radio` or `:select` field whose `options` are
-      #   `[value, label]` pairs
+      # Radio buttons for four or fewer options, a `<select>` beyond that.
       def self.select_or_radio(common, options)
         kind = options.size <= 4 ? :radio : :select
         Field.new(**common, kind: kind, html_type: "text", options: options.map { |value| [value, value] })
       end
 
-      # Builds the leaf field for a primitive-typed attribute: a number input for `Integer`
-      # and `Float`, a checkbox for a boolean, and a text-family input for anything else.
-      #
-      # @param attribute [Bluebook::Attribute] the attribute whose type picks the input
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
-      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
-      # @return [Forms::Field] a `:number`, `:boolean`, `:text` or `:textarea` leaf; an
-      #   `Integer` carries `step` `"1"`, a `Float` `"any"`
       def self.primitive_field(attribute, common)
         case attribute.type.to_s
         when "Integer" then Field.new(**common, kind: :number, html_type: "number", step: "1")
@@ -362,10 +181,9 @@ module Hecks
         end
       end
 
-      # Vocabulary::FieldHint (language/bluebook/vocabulary.bluebook), read
-      # off the generated table: `pattern` is the regex source, matched
-      # case-insensitively. bin/project_field_hints writes the Rust host's
-      # copy from the same rows.
+      # Vocabulary::FieldHint rows (language/bluebook/vocabulary.bluebook), matched
+      # case-insensitively. hecks project_field_hints writes the Rust host's copy from the same
+      # rows.
       HINTS = Hecks::Vocabulary.rows("FieldHint")
                                .to_h { |row| [row["name"], Regexp.new(row["pattern"], Regexp::IGNORECASE)] }
                                .freeze
@@ -374,15 +192,6 @@ module Hecks
       TEL_HINT      = HINTS.fetch("tel")
       TEXTAREA_HINT = HINTS.fetch("textarea")
 
-      # Builds a text-family leaf, picking `email`, `url`, `tel` or plain `text` from the
-      # attribute's pattern and the `FieldHint` name patterns, and a textarea for a
-      # long-text name.
-      #
-      # @param attribute [Bluebook::Attribute] the attribute whose name and pattern are read
-      # @param common [Hash{Symbol => Object}] the `Field` members every kind shares, keyed
-      #   `:path`, `:label`, `:default`, `:optional`, `:pattern`
-      # @return [Forms::Field] a `:text` leaf, or `:textarea` when the input type is plain
-      #   `"text"` and the name matches `TEXTAREA_HINT`
       def self.text_field(attribute, common)
         name = attribute.name.to_s
         pattern = attribute.pattern.to_s

data/lib/hecks/forms/html.rb

@@ -2,20 +2,13 @@ require "uri"
 
 module Hecks
   module Forms
-    # Hand-rolled, on purpose — the repo has no ERB anywhere and no template
-    # engine dependency (see docs/command-form-and-query-form-bluebook.md's survey). Every
-    # other generator in this codebase (bin/reference's markdown, the IR's own
-    # `to_h`) builds output as plain Ruby strings; this does the same for HTML,
-    # with exactly one job: nothing that reaches `Escape.html` ever becomes a
-    # tag. A feature developer's own domain data — a customer's name, an
-    # account number a support rep typed into a form and got wrong — flows
-    # through here on every render, so escaping is not optional decoration.
+    # HTML, URL-query and URL-path escaping for values that come from domain data.
+    # Nothing that reaches `Escape.html` becomes a tag.
     module Escape
       # Escapes a value for HTML text content, replacing `&`, `<`, `>`, `"` and `'` with
       # entities so nothing in it becomes a tag.
       #
-      # Order matters — `&` first, or every escape this method itself just
-      # wrote (`&amp;`, `&lt;`, ...) gets re-escaped a second time.
+      # `&` is replaced first so the entities written here are not escaped again.
       #
       # @param value [Object, nil] the value to show, rendered with `to_s`; nil renders as `""`
       # @return [String] the escaped text
@@ -30,10 +23,8 @@ module Hecks
 
       # Escapes a value for use inside a quoted HTML attribute.
       #
-      # Safe inside a double-quoted HTML attribute specifically — `html`
-      # already covers this (it escapes `"`), kept as a named alias so a
-      # call site reads "this value fills an attribute" rather than repeating
-      # the same escaping and leaving the reader to check they match.
+      # Safe inside a double-quoted attribute; an alias of `html` so call sites say what
+      # the value fills.
       #
       # @param value [Object, nil] the attribute value, rendered with `to_s`; nil renders
       #   as `""`
@@ -42,24 +33,9 @@ module Hecks
 
       # Percent-encodes a value for use as a query-string value.
       #
-      # L12 (docs/audits/2026-08-10-main-bug-audit.md) — safe as a
-      # query-string value. `html`/`attr` guard against the value becoming
-      # markup, but say nothing about it staying inside the URL syntax
-      # position it was placed in: an aggregate's identity is free-form
-      # unless its value object declares a `pattern:` (see S3 in the same
-      # audit), so `&`, `+`, `?`, `#`, and `/` are all otherwise legal id
-      # characters, and each would corrupt an href/Location built by naive
-      # interpolation (a stray `&` smuggles a second query parameter, `#`
-      # truncates the path at a fragment, `/` splits the path into an
-      # extra segment, ...). Percent-encodes via
-      # `application/x-www-form-urlencoded` (`+` for space) — correct only
-      # for a query-string value (query_form_renderer.rb's `quick_links`,
-      # record_renderer.rb's `?to=`). For a URL path segment use `path`
-      # below instead — `+` is a literal plus there, not an escaped space,
-      # so this method would corrupt any id containing a space. Callers
-      # still wrap the assembled href/Location in `attr` (or `html`) as
-      # usual — this only covers the id's own component, not the
-      # surrounding markup.
+      # Aggregate ids are free-form, so `&`, `#` and `/` must not reach a URL raw. Correct
+      # for a query-string value only; use `path` for a path segment. Callers still wrap
+      # the assembled href in `attr`.
       #
       # @param value [Object, nil] the value to encode, rendered with `to_s`
       # @return [String] the `application/x-www-form-urlencoded` form, a space rendered as `+`
@@ -67,13 +43,7 @@ module Hecks
 
       # Percent-encodes a value for use as one URL path segment.
       #
-      # Same guard as `url`, for a URL path segment instead of a
-      # query-string value. `encode_www_form_component` renders space as
-      # `+`, which is only meaningful inside a query string — in a path
-      # segment `+` is a literal plus, so an id like "John Smith" would
-      # round-trip to "John+Smith" and 404 against the real id "John
-      # Smith". Reuse the same percent-encoding and just correct that one
-      # character back to `%20`.
+      # Like `url`, but a space becomes `%20`: `+` is a literal plus in a path segment.
       #
       # @param value [Object, nil] the segment to encode, rendered with `to_s`
       # @return [String] the percent-encoded segment, a space rendered as `%20` and `/` as
@@ -81,11 +51,8 @@ module Hecks
       def self.path(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
     end
 
-    # A tiny attribute-hash -> string helper, shared by every renderer in
-    # this directory so `<input ...>` doesn't get hand-assembled five
-    # different ways with five different escaping bugs waiting in each.
-    # `true` renders as a bare boolean attribute (`required`, not
-    # `required="true"`); `nil`/`false` are dropped entirely.
+    # Attribute-hash to string helper shared by the form renderers.
+    # `true` renders a bare boolean attribute; `nil` and `false` are dropped.
     module Tag
       # Renders a Hash of attributes as the text that sits inside an opening tag, escaping
       # every value and spelling an underscored name with hyphens.
@@ -118,9 +85,7 @@ module Hecks
       # Renders a void element such as `<input>`. A self-closing tag reads the same as an
       # opening one; HTML5 needs no slash.
       #
-      # `self.open(...)`, not bare `open(...)` — this `Tag.open` (an HTML tag
-      # renderer, right above) shadows Kernel#open safely either way, but the
-      # explicit receiver also settles Security/Open's static ambiguity.
+      # The explicit `self.open` receiver keeps Security/Open from flagging Kernel#open.
       #
       # @param name [String] the element name, such as `"input"`
       # @param pairs [Hash{Symbol => Object}] attributes, rendered as `attrs` renders them

data/lib/hecks/forms/index_renderer.rb

@@ -2,10 +2,7 @@ require_relative "html"
 
 module Hecks
   module Forms
-    # The home page: every exposed chapter, every aggregate on it — the
-    # entry point into what would otherwise be a URL you'd have to already
-    # know. `chapters` is `{domain_name => Bluebook::Chapter}`, in `expose`
-    # order (see `Forms::Config` in forms.rb).
+    # The home page: every exposed chapter and the aggregates on it.
     module IndexRenderer
       # Renders the home page body: one section per exposed chapter, each linking to its
       # aggregates.

data/lib/hecks/forms/page.rb

@@ -2,12 +2,8 @@ require_relative "html"
 
 module Hecks
   module Forms
-    # The one HTML shell every page in this app renders inside — nav,
-    # typography, form/table/badge styles, all inline (no CDN, no build
-    # step: this ships inside the `hecks` gem, and a project that
-    # embeds it gets one dependency-free response per request). Themed via
-    # `prefers-color-scheme` alone; nothing here reads a cookie or a query
-    # param for it, so it is never wrong for the browser rendering it.
+    # The HTML shell every page renders inside, with styles and script inline.
+    # Themed by `prefers-color-scheme` alone.
     module Page
       # Wraps one page's own body HTML in the shared shell: doctype, head, nav, footer,
       # inline styles and script.
@@ -146,9 +142,7 @@ module Hecks
         .actions { display: flex; flex-wrap: wrap; gap: .5rem; margin: .6rem 0 1.4rem; }
       CSS
 
-      # Decorative only — every form here already works with JS disabled
-      # (plain `<form method=post>`/`method=get`), matching this repo's own
-      # "no ERB, nothing scripted" bar for the domain layer itself.
+      # Decorative only; every form works with JS disabled.
       SCRIPT = <<~JS.freeze
         document.addEventListener("click", (event) => {
           const button = event.target.closest("[data-copy]");