hecks 1.3.0 → 1.5.0

data/lib/hecks/codemod.rb

@@ -1,49 +1,58 @@
 require_relative "bluebook/meta_validator"
+require_relative "corpus"
 
 module Hecks
-  # SHARED MACHINERY for a codemod that migrates real `.bluebook` source
-  # once a DSL builder change makes some previously-required declaration
-  # optional/redundant — pulled out of `bin/codemod_implicit_append_fields`
-  # (the first one built), which needed three real, hard-won fixes before
-  # it could be trusted: a process-lifetime AST cache with no
-  # invalidation, a batch-revert granularity that let one unsafe
-  # candidate sink every other safe one sharing its boot, and (in the
-  # SPINE the codemod migrates FOR, not here) an append-at-end insertion
-  # that only round-tripped correctly for whichever field happened to be
-  # last. None of those are guessable in advance; they only surface by
-  # actually running a real edit against real self-hosted code. This
-  # module is that lesson, kept — the NEXT codemod plugs in two rule-
-  # specific procs (`find_candidates`, `apply_candidate`) and inherits
-  # the boot/safety-net machinery rather than rediscovering it.
+  # Shared machinery for a codemod that migrates real `.bluebook` source.
   #
-  # A CODEMOD IS NOT PATTERN-MATCHING ALONE. Deciding "is this line safe
-  # to delete" means knowing what the RUNTIME would resolve it to — so
+  # ## Why this module exists
+  #
+  # For migrating source once a DSL builder change turns a required
+  # declaration into an optional, redundant one — pulled out of
+  # `bin/codemod_implicit_append_fields` (the first one built), which
+  # needed three real, hard-won fixes before it could be trusted: a
+  # process-lifetime AST cache with no invalidation, a batch-revert
+  # granularity that let one unsafe candidate sink every other safe one
+  # sharing its boot, and (in the spine the codemod migrates for, not
+  # here) an append-at-end insertion that only round-tripped correctly
+  # for whichever field happened to be last. None of those are guessable
+  # in advance; they only surface by actually running a real edit
+  # against real self-hosted code. This module is that lesson, kept —
+  # the next codemod plugs in two rule-specific procs (`find_candidates`,
+  # `apply_candidate`) and inherits the boot/safety-net machinery rather
+  # than rediscovering it.
+  #
+  # ## The three-step contract
+  #
+  # **A codemod is not pattern-matching alone**. Deciding "is this line safe
+  # to delete" means knowing what the runtime would resolve it to — so
   # every codemod built on this module follows the same three steps:
   #   1. Boot the real domain (or the self-hosted meta-domain) and read
-  #      its IR to find CANDIDATES — provided by the caller's own
+  #      its IR to find candidates — provided by the caller's own
   #      `find_candidates`, since the actual redundancy rule is specific
   #      to whichever spine change this migration serves.
   #   2. Locate and remove each candidate's own source text — the
   #      caller's own `apply_candidate`.
   #   3. Re-boot from the edited text and diff the full IR export
   #      against the pre-edit export. Byte-identical -> keep. Anything
-  #      else (including a RAISED exception — the self-hosted
-  #      meta-domain DISPATCHES itself into being, S14, so a bad edit
+  #      else (including a raised exception — the self-hosted
+  #      meta-domain dispatches itself into being, S14, so a bad edit
   #      can surface as a runtime refusal, not just a differing export)
-  #      -> revert and report SKIPPED, never silently guessed past.
+  #      -> revert and report skipped, never silently guessed past.
+  #
+  # ## Design-time checklist for a future codemod
   #
-  # DESIGN-TIME CHECKLIST for the SPINE change a future codemod migrates
-  # corpus text for — both items below are real bugs THIS module's own
-  # first use found, not hypothetical:
-  #   - Does the resolved value get inserted into an ORDER-SENSITIVE
+  # For the spine change a future codemod migrates corpus text for —
+  # both items below are real bugs this module's own first use found,
+  # not hypothetical:
+  #   - Does the resolved value get inserted into an order-sensitive
   #     list (the exported IR is array-order-sensitive throughout)? If
-  #     so, the spine's own insertion must preserve the ORIGINAL
+  #     so, the spine's own insertion must preserve the original
   #     position, not just append — an append-at-end insertion only
   #     round-trips correctly for a value that already happened to be
   #     last.
-  #   - Does resolution depend on ANOTHER construct already being
+  #   - Does resolution depend on another construct already being
   #     declared (the aggregate/entity a `sets`/`append:` field resolves
-  #     against)? If a creator command can be declared BEFORE the
+  #     against)? If a creator command can be declared before the
   #     construct it creates (real, live: `command "Handler"` before
   #     `entity "Handler"`, one file down), one-pass resolution
   #     genuinely cannot see it yet — not a codemod bug, a structural
@@ -51,16 +60,16 @@ module Hecks
   module Codemod
     ROOT = File.expand_path("../..", __dir__)
 
-    EXAMPLE_ROOTS = Dir.glob(File.join(ROOT, "examples", "*")).select { |p| File.directory?(p) }.sort
+    EXAMPLE_ROOTS = Corpus.members(:example, root: ROOT).map(&:path)
     META_FILES    = (Dir.glob(File.join(ROOT, "lib/hecks/grammar/*.bluebook")) +
                       Dir.glob(File.join(ROOT, "lib/hecks/framework/bluebook/*.bluebook")) +
                       Dir.glob(File.join(ROOT, "lib/hecks/language/bluebook/**/*.bluebook"))).sort
 
-    # THE SAME LIGHTWEIGHT PATH `spec/spec_helper.rb`'s own
+    # The same lightweight path `spec/spec_helper.rb`'s own
     # `boot_in_memory` uses — `Hecks.with_registry` satisfies
     # `Hecks.bluebook`'s own `collect`'s "loaded outside a boot" check
     # without `Hecks.boot`'s full era-check/adapter-wiring path, which
-    # needs a LIVE Postgres connection for `compliance` and would make
+    # needs a live Postgres connection for `compliance` and would make
     # every codemod depend on a database it has no reason to touch — a
     # codemod only ever reads a chapter's own declared IR, never a
     # stored record.
@@ -69,19 +78,27 @@ module Hecks
     MEMORY_ADAPTER   = File.join(ROOT, "lib/hecks/adapters/driven/memory.adapter")
     PRISM_ADAPTER    = File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter")
 
+    # Exports a booted registry's canonical IR as JSON, for a before/after diff.
+    #
+    # @param registry [Runtime::Registry] the booted registry to export
+    # @return [String] the pretty-printed JSON IR export
     def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
 
     # `Hecks::Adapters::Prism` caches a file's parsed AST for the
-    # life of the PROCESS, keyed by path — fine for every existing
+    # life of the process, keyed by path — fine for every existing
     # caller (a file loads once per process: one `bin/ir` run, one
-    # rspec worker), but a codemod legitimately reloads the SAME path
+    # rspec worker), but a codemod legitimately reloads the same path
     # after editing it, and a stale cached tree reports a
-    # `given`/`ensures` block at its OLD line number, which no longer
+    # `given`/`ensures` block at its old line number, which no longer
     # matches the freshly re-executed file's own `block.source_location`
     # — surfacing as "did not survive extraction" on a perfectly valid
     # file. `Prism.forget` is the real invalidation API this module's
     # own first use motivated (found here, fixed at the source rather
     # than left as a private `TREES.clear` poke from outside).
+    #
+    # @param path [String, Array<String>] a single `.bluebook` file, a directory
+    #   to glob every `.bluebook` file from, or an explicit list of file paths
+    # @return [Runtime::Registry] a fresh registry with every file loaded and judged
     def self.load_bluebook(path)
       paths = if path.is_a?(Array)
                 path
@@ -104,16 +121,21 @@ module Hecks
       registry
     end
 
-    # `forget_all`, not a single `forget` — the meta-domain is NINE
+    # `forget_all`, not a single `forget` — the meta-domain is nine
     # files (`MetaValidator::GRAMMAR_FILES`) merged into one registry,
     # and a caller here (the codemod runner) doesn't generally know in
-    # advance which ONE it just edited.
+    # advance which one it just edited.
+    # @return [String] the freshly re-derived meta-domain's canonical IR, as JSON
     def self.boot_meta
       Hecks::Adapters::Prism.forget_all
       Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
       export_json(Hecks::Bluebook::MetaValidator.grammar_registry)
     end
 
+    # Forces the self-hosted meta-domain to re-derive from its current source,
+    # discarding any cached parse trees or memoized registry.
+    #
+    # @return [Runtime::Registry] the freshly re-derived meta-domain's registry
     def self.meta_registry
       Hecks::Adapters::Prism.forget_all
       Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
@@ -123,10 +145,18 @@ module Hecks
     # Walks every aggregate (and every nested entity, recursively)
     # across every chapter in a booted registry, yielding [owning
     # construct, command] pairs — `construct` is whichever
-    # Aggregate/Entity actually OWNS the command, the same distinction
+    # Aggregate/Entity actually owns the command, the same distinction
     # `AggregateBuilder#command` vs `EntityBuilder#command` already
     # draws. Generic enough for any rule that needs to walk real
     # commands, not specific to the attribute-redundancy rule.
+    #
+    # @param registry [Runtime::Registry] a booted registry
+    # @yield [construct, command] every command in the registry, once per aggregate
+    #   and once per nested entity
+    # @yieldparam construct [Bluebook::Aggregate, Bluebook::Entity] whichever
+    #   aggregate or entity actually owns `command`
+    # @yieldparam command [Bluebook::Command] the command
+    # @return [Hash{String => Bluebook::Chapter}] `registry.bluebooks`, unchanged
     def self.each_command(registry)
       registry.bluebooks.each_value do |chapter|
         chapter.aggregates.each do |aggregate|
@@ -139,38 +169,74 @@ module Hecks
       end
     end
 
+    # Finds one construct's own attribute by name.
+    #
+    # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct to search
+    # @param name [String, Symbol, #to_s] the attribute's declared name
+    # @return [Bluebook::Attribute, nil] the matching attribute, or nil if `construct`
+    #   declares no attribute named `name`
     def self.owner_attribute(construct, name)
       construct.attributes.find { |attr| attr.name.to_s == name.to_s }
     end
 
-    # A LIST attribute's own element construct — the value object or
+    # A list attribute's own element construct — the value object or
     # entity `list_of(...)` names, resolved by `hecks_name` the same way
     # `AttributeCollector#resolve_identity_field!` already does. Shared
     # because "what does this list actually hold" is a question any
     # append-shaped rule needs answered, not just this one.
+    #
+    # Nothing in the DSL stops a value object and an entity nested under
+    # the same aggregate from sharing a `hecks_name` — they are declared
+    # through two separate collections with no cross-kind uniqueness
+    # check between them. A silent value-objects-before-entities pick
+    # would resolve such a pair the same way every time regardless of
+    # which one `list_field` actually names, so a genuine collision is
+    # refused instead, the same "never first-wins silently" call
+    # `EntityBuilder#install_closed_sets!` already makes for a same-named
+    # closed set.
+    #
+    # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+    #   declaring `list_field`
+    # @param list_field [String, Symbol, #to_s] the name of the `list_of(...)` attribute
+    # @return [Bluebook::Entity, Bluebook::ValueObject, nil] the construct
+    #   `list_field` holds a list of, or nil if `list_field` names no attribute,
+    #   isn't a list, or names no known value object or entity
+    # @raise [RuntimeError] if a value object and an entity both match `list_field`'s type
     def self.element_construct_for(construct, list_field)
       list_attr = owner_attribute(construct, list_field)
       return nil unless list_attr&.list?
 
-      pool = construct.respond_to?(:value_objects) ? construct.value_objects.dup : []
-      pool.concat(construct.entities) if construct.respond_to?(:entities)
-      pool.find { |c| c.hecks_name.to_s == list_attr.type.to_s }
+      value_objects = construct.respond_to?(:value_objects) ? construct.value_objects : []
+      entities      = construct.respond_to?(:entities) ? construct.entities : []
+      matches = (value_objects + entities).select { |c| c.hecks_name.to_s == list_attr.type.to_s }
+
+      if matches.size > 1
+        raise "#{construct.hecks_name}##{list_field} names #{list_attr.type}, held by both a value " \
+              "object and an entity — ambiguous, cannot resolve which one the list holds"
+      end
+
+      matches.first
     end
 
-    # Either a raised exception OR a differing export counts as unsafe
+    # Either a raised exception or a differing export counts as unsafe
     # — see the module header on why the meta-domain specifically can
     # raise. Returns [value_or_nil, error_message_or_nil].
+    #
+    # @yield the risky boot/export step to run
+    # @return [Array(Object, nil), Array(nil, String)] `[the block's result, nil]`
+    #   on success, or `[nil, "ExceptionClass: message"]` if the block raises
+    #   any StandardError
     def self.safely
       [yield, nil]
     rescue StandardError => e
       [nil, "#{e.class}: #{e.message}"]
     end
 
-    # THE REUSABLE RUNNER — every real bug fix this module carries lives
+    # **The reusable runner** — every real bug fix this module carries lives
     # here, not in a caller's own script. A caller supplies:
     #
     #   find_candidates: ->(registry) { [...] }
-    #     Given a booted registry, return every CANDIDATE this rule
+    #     Given a booted registry, return every candidate this rule
     #     could migrate. A candidate is whatever shape the caller wants
     #     — `apply_candidate` is the only other thing that reads it.
     #
@@ -178,19 +244,36 @@ module Hecks
     #     Given one file's current text and one candidate, return the
     #     edited text and whether a match was actually found/removed —
     #     `false` (text unchanged) when the candidate doesn't apply to
-    #     THIS file, which is how the meta-domain's multi-file search
+    #     this file, which is how the meta-domain's multi-file search
     #     below finds the right one without the caller needing to know
     #     which file a candidate lives in ahead of time.
     #
     #   label: ->(candidate) { "..." }
     #     One-line description for the results report.
     class Runner
+      # @param find_candidates [Proc] `->(registry) { [...] }` — given a booted
+      #   registry, returns every candidate this rule could migrate; a candidate's
+      #   shape is the caller's own, read back only by `apply_candidate`
+      # @param apply_candidate [Proc] `->(text, candidate) { [new_text, changed_bool] }`
+      #   — given one file's current text and one candidate, returns the edited text
+      #   and whether a match was found; `false` means the candidate doesn't apply to
+      #   this file
+      # @param label [Proc] `->(candidate) { "..." }` — a one-line description of a
+      #   candidate, for the results report
       def initialize(find_candidates:, apply_candidate:, label:)
         @find_candidates = find_candidates
         @apply_candidate = apply_candidate
         @label = label
       end
 
+      # Runs this rule's codemod across every example domain and the meta-domain.
+      #
+      # @param dry_run [Boolean] when true, every safe edit is still written and
+      #   reverified, then reverted rather than kept
+      # @return [Hash{Symbol => Array}] `:applied` (`Array<Hash{file: String,
+      #   candidates: Array<String>}>`), `:skipped` (`Array<Hash{file: String,
+      #   reason: String, candidates: Array<String>}>`), and `:clean`
+      #   (`Array<String>` of domain directories or `"meta-domain"` with no candidates)
       def run(dry_run: false)
         results = { applied: [], skipped: [], clean: [] }
         run_example_domains(results, dry_run)
@@ -198,6 +281,11 @@ module Hecks
         results
       end
 
+      # Prints `run`'s results to stdout.
+      #
+      # @param results [Hash{Symbol => Array}] a `run` result
+      # @param dry_run [Boolean] whether this was a dry run, for the report's own heading
+      # @return [void]
       def report(results, dry_run:)
         puts "== results (#{dry_run ? 'DRY RUN — nothing written' : 'applied'}) =="
         puts "clean (no candidates): #{results[:clean].join(', ')}" unless results[:clean].empty?
@@ -279,10 +367,10 @@ module Hecks
         end
       end
 
-      # PER-CANDIDATE, not one batched write-then-verify — the
-      # meta-domain is ONE shared registry (SyntaxBoot DISPATCHES it
+      # Per-candidate, not one batched write-then-verify — the
+      # meta-domain is one shared registry (SyntaxBoot dispatches it
       # into itself, S14), so a single unsafe candidate among many would
-      # otherwise sink every OTHER, genuinely safe candidate in the same
+      # otherwise sink every other, genuinely safe candidate in the same
       # run: this module's first real run found exactly that (25
       # candidates, one dispatch-time break, all 25 reverted as a batch
       # before this per-candidate loop existed). `before_meta` stays the
@@ -291,8 +379,8 @@ module Hecks
       # still equal the pristine original after each kept edit, by
       # definition, no moving target needed.
       # Same shape and same reason as run_example_domains just above (see
-      # its own comment) — the write/verify/revert sequence, PER
-      # CANDIDATE (this method's own comment explains why it cannot
+      # its own comment) — the write/verify/revert sequence, per
+      # candidate (this method's own comment explains why it cannot
       # batch), is one coherent unit; splitting it would scatter
       # before_meta/live_meta/applied_by_file state across methods for
       # no gain.
@@ -323,7 +411,7 @@ module Hecks
           live_meta[target_file] = text
           Codemod::META_FILES.each { |f| File.write(f, live_meta[f]) }
 
-          # DRY RUN STILL VERIFIES — see run_example_domains' own
+          # **Dry run still verifies** — see run_example_domains' own
           # comment; the edit is always written and rebooted for real,
           # then always reverted afterward when dry-run (whether or not
           # it was safe) so the next candidate is judged against the

data/lib/hecks/construct.rb

@@ -1,14 +1,16 @@
 module Hecks
   # The invisible field a built construct carries.
   #
-  # A construct is a RECORD WITH AN OWNER CHAIN — the chapter (Bluebook)
+  # ## Identity
+  #
+  # A construct is a record with an owner chain — the chapter (Bluebook)
   # owns its aggregates, an aggregate owns everything declared on it — and the
   # bluebook identity is carried in its own field, under a `hecks_` prefix that
   # no domain attribute can collide with. Invisible means exactly that: not an
   # attribute, not a key in `to_h`, not a reader on instances. Framework
   # metadata about the construct, not part of the domain it describes.
   #
-  # The identity is COMPUTED by walking owners rather than stamped, so nothing
+  # The identity is computed by walking owners rather than stamped, so nothing
   # has to be re-stamped when a chapter is assembled after its aggregates:
   #
   #     Pizzas                     the chapter — no owner
@@ -17,10 +19,10 @@ module Hecks
   #
   # That spelling is not invented here. It is the id `MetaValidator::Judge`
   # already mints in `#identify`, so a construct and the meta-domain's
-  # record OF that construct carry the same identity, and there is no
+  # record of that construct carry the same identity, and there is no
   # translation table between them to be quietly wrong in.
   #
-  # Usage:
+  # ## Usage
   #
   #     price = Class.new(ValueObject)   # a declaration holder
   #     price.hecks_name  = "Price"
@@ -37,25 +39,37 @@ module Hecks
     attr_writer :hecks_name
 
     # A chapter is the only construct that legitimately has no owner. Everything
-    # else is DECLARED IN something, so a missing owner is an unstamped construct
+    # else is declared in something, so a missing owner is an unstamped construct
     # rather than a top — see hecks_fqn.
     attr_writer :hecks_root
 
+    # Whether this construct is the top of its own owner chain.
+    #
+    # @return [Boolean] true for a chapter, which sets `hecks_root`; false otherwise
     def hecks_root? = @hecks_root ? true : false
 
     # The name as the bluebook declares it, never the constant path.
+    #
+    # @return [String] the construct's own name, without any owner prefix
     def hecks_name = @hecks_name
 
     # How this construct joins its owner. An aggregate is a member of its
-    # chapter's namespace (`::`) ; everything else is declared ON its owner
+    # chapter's namespace (`::`) ; everything else is declared on its owner
     # (`.`). Overridden by Aggregate, defaulted here for every other construct.
+    #
+    # @return [String] `"."`, the separator this construct uses in `hecks_fqn`
     def hecks_separator = "."
 
-    # REFUSES rather than guesses. A construct with no owner and no claim to be a
+    # Refuses rather than guesses. A construct with no owner and no claim to be a
     # chapter has simply not been stamped yet — entity commands are in that state
     # while entities are still IR objects — and answering the bare name would be a
     # plausible half-truth that no test would notice. That shape of falsehood is
     # what this repo keeps finding, so it goes red instead.
+    #
+    # @return [String] the fully-qualified name, joining every owner from the
+    #   chapter down to this construct
+    # @raise [Construct::Unowned] if this construct has no owner and is not itself
+    #   a chapter (root)
     def hecks_fqn
       return hecks_name.to_s if hecks_root?