hecks 1.3.0 → 1.5.0

data/lib/hecks/ports/persistence/plugins/era/era_guard/shape_diff.rb

@@ -6,16 +6,32 @@ module Hecks
       # from the IR it is handed, which is why the Postgres mint path can
       # call it too.
       module ShapeDiff
+        # Computes an aggregate's structural signature, for comparing two eras of it.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to describe
+        # @return [Array<Array>] one `[name, signature]` pair per attribute, sorted by name;
+        #   `name` is a Symbol and `signature` is whatever `attribute_signature` returns
         def shape(aggregate)
           aggregate.attributes.map do |attribute|
             [attribute.name, attribute_signature(aggregate, attribute.type)]
           end.sort_by(&:first)
         end
 
+        # Expands a declared type into a signature that exposes its members.
+        #
         # A plain type name for a primitive; `[type_name, member_signatures]`
         # for a value object or entity, walked recursively — so two
         # attributes with the same declared type name but a different
         # internal shape are never mistaken for unchanged.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose value objects and entities
+        #   are searched for `type_name`
+        # @param type_name [String, Bluebook::Reference] the attribute's declared type
+        # @param seen [Array<String, Bluebook::Reference>] types already being expanded, which
+        #   stops a self-referencing type from recursing forever
+        # @return [String, Bluebook::Reference, Array] `type_name` itself for a primitive, a
+        #   reference, or a type already in `seen`; otherwise `[type_name, members]`, where
+        #   `members` is an Array of `[member_name, signature]` pairs sorted by member name
         def attribute_signature(aggregate, type_name, seen = [])
           container = nested_type(aggregate, type_name)
           return type_name if container.nil? || seen.include?(type_name)
@@ -26,13 +42,21 @@ module Hecks
           [type_name, members]
         end
 
+        # Looks a type name up among an aggregate's value objects, then its entities.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to search
+        # @param type_name [String, Bluebook::Reference] the declared type to find
+        # @return [Bluebook::ValueObject, Bluebook::Entity, nil] the matching declaration; nil
+        #   when the type is a primitive, a reference, or nothing this aggregate declares
         def nested_type(aggregate, type_name)
           aggregate.value_object(type_name) || aggregate.entities.find { |entity| entity.name == type_name }
         end
 
+        # Lists the new attributes that would leave an existing record with a required gap.
+        #
         # Attributes present now that the held shape never had — the
-        # addition side of drift, which `uncovered_attributes` above never
-        # looks at, since it only walks the HELD shape (vanish/retype).
+        # addition side of drift, which `uncovered_attributes` below never
+        # looks at, since it only walks the held shape (vanish/retype).
         # Most additions are free (ADR 0025, "Added attributes and
         # absence"): a default:, a list_of (frozen []), or a value object
         # whose fields all default fill an existing record automatically
@@ -40,11 +64,20 @@ module Hecks
         # non-optional attribute with no way to fill itself — can leave an
         # existing record with the field genuinely absent, and that is
         # what this reports: unfilled by a declared translation's own
-        # `backfill`, OR by a move/convert that lands an OLD field inside
+        # `backfill`, or by a move/convert that lands an old field inside
         # this brand-new attribute (`Lineage#fills?` — the destination-
         # side question, never `explains?`'s source-side one, since a
         # rename from Crate to Bin can introduce a top-level attribute
         # name that never existed to have "vanished").
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
+        # @param held_aggregate [Bluebook::Aggregate] the same aggregate as the held era's text
+        #   declares it
+        # @param lineage [Ports::Persistence::Lineage, nil] the edge's rules for this aggregate; nil
+        #   when the edge declares none, so nothing can fill an addition
+        # @return [Array<Symbol>] names of new, non-optional attributes with no default, no
+        #   list cardinality, no fully-defaulted value object and no rule filling them; `[]`
+        #   when every addition is safe
         def unsafe_additions(aggregate, held_aggregate, lineage)
           held_names = held_aggregate.attributes.map(&:name)
 
@@ -55,9 +88,17 @@ module Hecks
                    .map(&:name)
         end
 
-        # THE FOUR-ROW TABLE, as a predicate over the fourth row only — the
+        # Decides whether a new attribute could be genuinely absent from an existing record.
+        #
+        # The four-row table, as a predicate over the fourth row only — the
         # other three (default:, list_of, a fully-defaulted value object)
         # all fill an existing record for free and never reach here.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate declaring the attribute, searched
+        #   for the value object its type may name
+        # @param attribute [Bluebook::Attribute] the newly added attribute
+        # @return [Boolean] false when the attribute is optional, has a default, is a list, or
+        #   is a value object whose every field has a default; true otherwise
         def possibly_absent?(aggregate, attribute)
           return false if attribute.optional?
           return false unless attribute.default.nil?
@@ -69,14 +110,24 @@ module Hecks
           true
         end
 
+        # Lists the held paths that vanished or changed type with no rule explaining them.
+        #
         # Paths the translation needs to explain: attributes that vanished
         # by name, attributes that kept their name but changed type (a
         # `convert` is what lets that be declared at all), and — recursing
-        # into a same-named, same-typed value object — its OWN members
+        # into a same-named, same-typed value object — its own members
         # vanishing or changing type one level down, reported as a dotted
         # path ("price.currency"). A pure addition, at any depth, never
         # needs covering; only vanish-or-retype does, matching the
         # top-level rule at every depth.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
+        # @param held_aggregate [Bluebook::Aggregate] the same aggregate as the held era's text
+        #   declares it
+        # @param lineage [Ports::Persistence::Lineage, nil] the edge's rules for this aggregate; nil
+        #   when the edge declares none, so every vanished or retyped path is reported
+        # @return [Array<String>] bare attribute names and dotted member paths such as
+        #   `"price.currency"`; `[]` when the whole diff is explained
         def uncovered_attributes(aggregate, held_aggregate, lineage)
           paths = held_aggregate.attributes.flat_map do |held_attribute|
             current_attribute = aggregate.attribute(held_attribute.name)
@@ -90,20 +141,37 @@ module Hecks
           paths.reject { |path| lineage.explains?(path) }
         end
 
-        # `held_type`/`current_type` are type NAMES, resolved against each
-        # side's OWN value_object AND entity declarations — neither is ever
+        # Compares one path's held and current types, recursing into shared members.
+        #
+        # `held_type`/`current_type` are type names, resolved against each
+        # side's own value_object and entity declarations — neither is ever
         # nested in the DSL, only in the type graph, so both are always
         # looked up flat off their respective aggregate. A `list_of` entity
-        # is only reached here to DETECT a member vanish-or-retype; there is
+        # is only reached here to detect a member vanish-or-retype; there is
         # no per-element translation machinery yet (`move`/`convert`/`drop`
         # only reach into a single nested hash, not each element of an
         # array) — the only way to satisfy a refusal on an entity path
         # today is a top-level `drop` of the whole list attribute, which
         # `explains?` already recognizes as covering everything nested
         # under it. Blunt, but loud beats silent.
+        #
+        # @param path [String] the bare or dotted path being compared, reported on a mismatch
+        # @param held_type [String, Bluebook::Reference] the type the held era declares there
+        # @param current_type [String, Bluebook::Reference] the type declared there now
+        # @param held_aggregate [Bluebook::Aggregate] the held aggregate, searched for
+        #   `held_type`'s declaration
+        # @param aggregate [Bluebook::Aggregate] the current aggregate, searched for
+        #   `current_type`'s declaration
+        # @param lineage [Ports::Persistence::Lineage, nil] the edge's rules, asked whether a retype
+        #   pairs the two type names; nil means no retype is accepted
+        # @param seen [Array<String, Bluebook::Reference>] current types already being
+        #   expanded, which stops a self-referencing type from recursing forever
+        # @return [Array<String>] `[path]` when the types differ with no retype declared; the
+        #   dotted paths of members that vanished or changed type beneath it; `[]` when
+        #   nothing differs or either type is not a value object or entity
         def diff_type(path, held_type, current_type, held_aggregate, aggregate, lineage, seen = [])
           if held_type != current_type
-            # A declared retype says the two TYPE names mean the same shape
+            # A declared retype says the two type names mean the same shape
             # — accept the pair, but still recurse into the members so a
             # member drift hiding beneath the rename is caught by name.
             return [path] unless lineage&.retype?(held_type, current_type)

data/lib/hecks/ports/persistence/plugins/era/era_guard.rb

@@ -16,24 +16,34 @@ module Hecks
     # historical bluebook text under old grammar defaults. Both are real,
     # independent, currently-shipped consumers.
     #
-    # A prior version of this module ALSO drove its own top-level check —
-    # `check!`/`check_bluebook!`, walking a registry and reading/writing a
-    # held snapshot under `data/eras/*.bluebook` — duplicating, on its own,
-    # the same per-aggregate walk `CoverageCheck` already performs against
-    # `PostgresEra`'s own DB-held shapes. Nothing in production ever called
-    # it (only a direct unit spec did); deleted rather than kept unwired,
-    # per ADR 0032. Wanted again, it's rebuilt informed by `CoverageCheck`'s
-    # real orchestration, not resurrected from here.
+    # There is deliberately no top-level `check!`/`check_bluebook!` here
+    # walking a registry and reading/writing a held snapshot under
+    # `data/eras/*.bluebook`: it would duplicate, on its own, the same
+    # per-aggregate walk `CoverageCheck` already performs against
+    # `PostgresEra`'s own DB-held shapes, and nothing in production would
+    # call it — an unwired driver is not kept, per ADR 0032. If one is
+    # wanted, it is built informed by `CoverageCheck`'s real orchestration.
     module EraGuard
       extend ShapeDiff
 
       module_function
 
+      # Refuses the boot when a held aggregate is gone and no translation says where it went.
+      #
       # An aggregate that existed in the held text and answers to no
       # current name — renamed silently, with nothing declaring `was:` to
       # explain where its data went — is exactly the disease this guards
       # against, and a plain per-aggregate diff would never see it: the
       # current aggregate simply has no held counterpart to compare to.
+      #
+      # @param registry [Runtime::Registry] the registry whose declared translations are
+      #   searched for a `was:` or a `retired` entry naming the held aggregate
+      # @param bluebook [Bluebook::Chapter] the bluebook booting now
+      # @param held_bluebook [Bluebook::Chapter] the bluebook parsed from the held era's text
+      # @return [void]
+      # @raise [Runtime::WiringError] if a held aggregate matches no current aggregate by
+      #   name, no current aggregate's translation declares it as `was:`, and no translation
+      #   for this domain retires it
       def check_vanished_aggregates!(registry, bluebook, held_bluebook)
         held_bluebook.aggregates.each do |held_aggregate|
           claimed = bluebook.aggregates.any? do |aggregate|
@@ -54,9 +64,18 @@ module Hecks
         end
       end
 
+      # Raises the refusal naming every changed path no translation rule explains.
+      #
       # The Layer-1 coverage refusal — one wording, shared with whoever
       # calls it (today, `PostgresEra::LineageManager::CoverageCheck`'s
       # own mint-time coverage check).
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook booting now, named in the message
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose shape changed
+      # @param uncovered [Array<String>] the unexplained paths, as `uncovered_attributes`
+      #   returns them; must not be empty, since the first one seeds the suggested rule
+      # @return [void] never returns; always raises
+      # @raise [Runtime::WiringError] always, carrying the refusal wording
       def refuse_uncovered!(bluebook, aggregate, uncovered)
         raise WiringError,
               "cannot boot #{bluebook.name}::#{aggregate.name}: its shape changed and " \
@@ -65,9 +84,18 @@ module Hecks
               "#{suggestion(uncovered.first)}."
       end
 
+      # Raises the refusal naming every new required attribute an existing record cannot fill.
+      #
       # The addition-side sibling of refuse_uncovered! above — same
       # wording shape, different cause: nothing vanished or changed type,
       # something new arrived that an existing record has no way to hold.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook booting now, named in the message
+      # @param aggregate [Bluebook::Aggregate] the aggregate that gained the attributes
+      # @param unsafe [Array<Symbol>] the attribute names, as `unsafe_additions` returns them;
+      #   must not be empty, since the first one seeds the suggested `backfill`
+      # @return [void] never returns; always raises
+      # @raise [Runtime::WiringError] always, carrying the refusal wording
       def refuse_unsafe_addition!(bluebook, aggregate, unsafe)
         raise WiringError,
               "cannot boot #{bluebook.name}::#{aggregate.name}: #{unsafe.map { |name| ":#{name}" }.join(', ')} " \
@@ -77,8 +105,18 @@ module Hecks
               "`backfill :#{unsafe.first}, default: ...`."
       end
 
+      # Renders a path the way a translation file spells it.
+      #
+      # @param path [String] a bare attribute name or a dotted value-object member path
+      # @return [String] the path quoted (`"price.currency"`) when dotted, otherwise as a
+      #   Symbol literal (`:cost`)
       def render_path(path) = path.include?(".") ? path.inspect : ":#{path}"
 
+      # Proposes the translation rules that would explain one uncovered path.
+      #
+      # @param path [String] a bare attribute name or a dotted value-object member path
+      # @return [String] backticked example rules: `move`/`drop` for a dotted path,
+      #   `rename`/`drop` for a bare name
       def suggestion(path)
         if path.include?(".")
           "`move #{path.inspect}, to: #{path.inspect}` or `drop #{path.inspect}`"
@@ -90,60 +128,79 @@ module Hecks
       # Parses held source into its own IR, in a scratch registry so a past
       # era's text never touches the one actually booting.
       #
-      # NORMAL PARSE FIRST, shadow only as a FALLBACK — not shadow-parsing
-      # unconditionally, which is what this used to do. A handful of DSL
+      # Normal parse first, shadow only as a fallback — never shadow-parsing
+      # unconditionally. A handful of DSL
       # defaults fork on `MetaValidator.shadow_parsing?` for a reason
-      # that has NOTHING to do with syntax the live grammar can no longer
+      # that has nothing to do with syntax the live grammar can no longer
       # read at all (`identified_by { }`, `belongs_to`, `has_one`,
       # `has_many` — genuinely removed spellings, exactly what shadow-
       # parsing exists to keep readable): `reference_to`'s own default
       # mint name (`default_reference_name`, attribute_collector.rb)
-      # changed from `_id`-suffixed to bare under ADR 0025, and THAT fork
-      # applies even to text using nothing but current, live syntax.
-      # Held text minted under the CURRENT grammar — every real era in
-      # this corpus today, since nothing has ever minted a second one —
-      # parses fine normally; only the reference-naming DEFAULT differed
-      # once shadow mode engaged unconditionally, so it silently
-      # reconstructed a DIFFERENT shape (and hash) than a fresh parse of
+      # is bare under ADR 0025 and `_id`-suffixed under shadow mode, and
+      # that fork applies even to text using nothing but current, live
+      # syntax. Held text minted under the current grammar — every real
+      # era in this corpus today, since nothing has ever minted a second
+      # one — parses fine normally; under unconditional shadow mode only
+      # the reference-naming default differs, so it silently
+      # reconstructs a different shape (and hash) than a fresh parse of
       # the identical text — the same text hashing two different ways
       # depending on which code path read it, breaking `ensure_named!`'s
       # own from/to edge lookup with a spurious "no translation edge
       # covers it" refusal that has nothing to do with any real
       # translation gap.
       #
-      # A normal parse can only ever SUCCEED on text the live grammar
+      # A normal parse can only ever succeed on text the live grammar
       # fully understands — there is no way for it to silently produce a
       # wrong-but-plausible answer for genuinely legacy text, since every
       # removed spelling refuses loudly (`Malformed`) rather than
       # degrading. So: try normal first — if the ordinary grammar reads
-      # this text without complaint, that IS the canonical, unambiguous
+      # this text without complaint, that is the canonical, unambiguous
       # interpretation, the same one `label_of`/`mint_hash` on the same
       # source text always computes, whoever's asking. Only on a
       # `Malformed` refusal — the one signal that actually means "this
       # spelling doesn't exist anymore" — fall back to the legacy
-      # grammar, exactly as before this change. Any OTHER exception (a
+      # grammar. Any other exception (a
       # genuine syntax error, an unrelated validation refusal) propagates
       # unchanged; swallowing it here to retry under shadow mode would
       # risk masking a real defect in the held text behind a confusing
       # second failure instead of the original, more specific one.
       #
       # `MetaValidator.while_shadow_parsing` (ADR 0025, docs/dsl-work-
-      # slices.md's S0a) is what makes the fallback a LEGACY grammar
+      # slices.md's S0a) is what makes the fallback a legacy grammar
       # rather than just a second copy of today's: it stops
       # `BluebookBuilder.build` from judging this text against the
-      # grammar as it stands NOW, which is the one thing that would make
-      # a removed spelling refuse HISTORY the day it is removed from
+      # grammar as it stands now, which is the one thing that would make
+      # a removed spelling refuse history the day it is removed from
       # live source. The scratch registry is throwaway either way —
       # nothing here is dispatched against or exposed to the real one —
       # so skipping the judge/assemble round-trip changes nothing this
       # method reads: `shape`, `uncovered_attributes`, and friends only
       # ever ask the built IR for its own structure.
+      #
+      # @param source [String] the held bluebook text to evaluate
+      # @param path [String] the file path the text is evaluated as, which the predicate
+      #   extractor reads from disk; callers pass a tempfile holding the same text
+      # @return [Bluebook::Chapter, nil] the first bluebook the text declares; nil when it
+      #   declares none
+      # @raise [Bluebook::DSL::Malformed] if the text parses under neither the live grammar
+      #   nor the legacy one
+      # @raise [SyntaxError] if the text is not valid Ruby
       def shadow_parse(source, path)
         parse_bluebook(source, path, shadow: false)
       rescue Hecks::Bluebook::DSL::Malformed
         parse_bluebook(source, path, shadow: true)
       end
 
+      # Evaluates bluebook text once, in a throwaway registry, under one chosen grammar.
+      #
+      # @param source [String] the bluebook text to evaluate
+      # @param path [String] the file path reported to `Kernel.eval` as the text's origin
+      # @param shadow [Boolean] true evaluates inside `MetaValidator.while_shadow_parsing`
+      #   (the legacy grammar); false evaluates under the live grammar
+      # @return [Bluebook::Chapter, nil] the first bluebook the text registered in the scratch
+      #   registry; nil when it declares none
+      # @raise [Bluebook::DSL::Malformed] if the chosen grammar refuses the text
+      # @raise [SyntaxError] if the text is not valid Ruby
       def parse_bluebook(source, path, shadow:)
         scratch = Registry.new
         loading = Ports::Loading.bootstrap

data/lib/hecks/ports/persistence/plugins/era/era_tamper.rb

@@ -6,41 +6,52 @@ require_relative "storage_shape"
 module Hecks
   module Runtime
     # The refusal wording for a held era whose digest no longer matches its
-    # frozen text — the digest mismatch alone is what DETECTS tampering (a
+    # frozen text — the digest mismatch alone is what detects tampering (a
     # plain SHA256 comparison over raw bytes, unrelated to any of this);
     # this only supplies the wording once that's already fired.
     #
-    # LIVES HERE, NOT UNDER `Ports::Persistence` — `project` below directly
+    # Lives here, not under `Ports::Persistence` — `project` below directly
     # calls `Runtime::EraGuard.shadow_parse`/`Runtime::StorageShape.project`
     # (DSL-execution machinery), the "an adapter/port reaches into the
     # runtime instead of being handed already-computed data" shape that
     # has caused trouble here before. A capability this dependent on the
-    # runtime is a runtime-owned one that the Postgres adapter CALLS, not
+    # runtime is a runtime-owned one that the Postgres adapter calls, not
     # a ports-level module that happens to reach sideways into it.
     #
-    # Used to also distinguish a cosmetic edit from a real shape change
-    # here, by re-parsing the edited text — a pure quality-of-message
-    # nicety, not a safety property, since dropped: every tamper refusal
-    # reaches the same generic wording now, the one this already fell to
-    # whenever it couldn't classify an edit anyway. An operator judges
-    # "did this matter" themselves,
-    # reading the still-archived original — an anomalous recovery moment
-    # already, not a normal boot path.
+    # Every tamper refusal reaches the same generic wording, cosmetic edit
+    # or real shape change alike: telling the two apart by re-parsing the
+    # edited text is a pure quality-of-message nicety, not a safety
+    # property, and an edit that cannot be classified has to fall to the
+    # generic wording anyway. An operator judges "did this matter"
+    # themselves, reading the still-archived original — an anomalous
+    # recovery moment already, not a normal boot path.
     module EraTamper
       module_function
 
+      # Words the boot refusal for a held era text whose digest no longer matches.
+      #
+      # @param domain [String] name of the domain whose era was edited
+      # @param ordinal [Integer] the edited era's ordinal in `hecks_eras`
+      # @return [String] the refusal message, ready to raise as a `Runtime::WiringError`
       def refusal(domain:, ordinal:)
         "cannot boot #{domain}: the held text of era #{ordinal} was edited after it was frozen — " \
           "held era texts are storage facts; restore the original text, or reset the data"
       end
 
-      # The storage-shape projection of a bluebook text, JSON-normalized
-      # for structural comparison against a stored projection; nil when
-      # the text does not load. ALWAYS parsed through a fresh tempfile,
-      # never the held file's own path: the predicate extractor caches
-      # source by path, and a held path whose content has changed (the
-      # very situation this module exists for) would hand it stale
-      # lines.
+      # Parses a bluebook text and returns its storage-shape projection.
+      #
+      # The projection is JSON-normalized for structural comparison
+      # against a stored projection; nil when the text does not load.
+      # Always parsed through a fresh tempfile, never the held file's own
+      # path: the predicate extractor caches source by path, and a held
+      # path whose content has changed (the very situation this module
+      # exists for) would hand it stale lines.
+      #
+      # @param text [String] the bluebook source to parse
+      # @param _source_path [String, nil] ignored; the text is always parsed from a tempfile
+      # @return [Hash{String => Object}, nil] `StorageShape.project`'s Hash after a JSON
+      #   round-trip; nil when the text declares no bluebook, or when parsing or projecting
+      #   raises any `StandardError` or `SyntaxError`
       def project(text, _source_path = nil)
         file = Tempfile.new(["hecks-tamper-", ".bluebook"])
         begin