hecks 2.9.0 → 3.0.1

data/lib/hecks/tools/drop_implicit_append_fields.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Removes a command's `attribute :field, Type` line when it only repeats what an `append:`
+    # target element already declares (see `CommandBuilder#resolve_append_fields!`). The
+    # edit/reboot/diff-or-revert machinery lives in `Hecks::Codemod`.
+    #
+    #   hecks drop_implicit_append_fields [--dry-run]
+    module DropImplicitAppendFields
+      # One attribute a command repeats.
+      Candidate = Struct.new(:command_name, :field, :type, keyword_init: true)
+
+      module_function
+
+      # Runs the codemod over every example domain and prints what it found.
+      #
+      # @param argv [Array<String>] `--dry-run` to restore every file after the rewrite is checked
+      # @param root [String] the checkout (unused: the examples come from `Codemod`)
+      # @return [Integer] 0
+      def main(argv, root: Tools::ROOT)
+        _ = root
+        require "hecks"
+        require "hecks/codemod"
+        dry_run = argv.include?("--dry-run")
+
+        runner = Hecks::Codemod::Runner.new(find_candidates: method(:find_candidates),
+                                            apply_candidate: method(:apply_candidate),
+                                            label:           ->(c) { "#{c.command_name}##{c.field} (#{c.type})" })
+        results = runner.run(dry_run: dry_run)
+        runner.report(results, dry_run: dry_run)
+        0
+      end
+
+      # @param candidate [Candidate] the attribute a command declares
+      # @param owner_attr [Object, nil] the same attribute on the element the command appends to
+      # @return [Boolean] whether the two declare the same thing
+      def identical_attribute?(candidate, owner_attr)
+        return false unless owner_attr
+
+        %i[type pattern optional? admits].all? { |m| candidate.public_send(m) == owner_attr.public_send(m) }
+      end
+
+      # Replays `CommandBuilder#resolve_append_fields!`'s lookup against the booted IR.
+      #
+      # @param registry [Object] the booted bluebooks
+      # @return [Array<Candidate>] the attributes that can be dropped
+      def find_candidates(registry)
+        found = []
+        Hecks::Codemod.each_command(registry) do |construct, command|
+          command.mutations.select { |m| m.op == :append }.each do |mutation|
+            element = Hecks::Codemod.element_construct_for(construct, mutation.target)
+            next unless element
+
+            mutation.source.each do |field, value|
+              next unless value.is_a?(Symbol) && value.to_s == field.to_s
+
+              local = command.attributes.find { |attr| attr.name.to_s == field.to_s }
+              next unless local
+
+              owner_attr = Hecks::Codemod.owner_attribute(element, field)
+              next unless identical_attribute?(local, owner_attr)
+
+              found << Candidate.new(command_name: command.hecks_name, field: field.to_s, type: local.type)
+            end
+          end
+        end
+        found
+      end
+
+      # @param text [String] a bluebook's source
+      # @param candidate [Candidate] the attribute to drop
+      # @return [Array(String, Boolean)] `[new_text, true]` on a single clean match, `[text, false]`
+      #   when ambiguous or absent
+      def apply_candidate(text, candidate)
+        window_start = text.index(/^\s*command\s+"#{Regexp.escape(candidate.command_name)}"/)
+        return [text, false] unless window_start
+
+        window_end = text.index(/^\s*emits\s/, window_start)
+        return [text, false] unless window_end
+
+        before = text[0...window_start]
+        window = text[window_start...window_end]
+        after = text[window_end..]
+
+        pattern = /^[ \t]*attribute\s+:#{Regexp.escape(candidate.field)}\s*,[^\n]*\n/
+        return [text, false] unless window.scan(pattern).size == 1
+
+        [before + window.sub(pattern, "") + after, true]
+      end
+    end
+  end
+end

data/lib/hecks/tools/era_projection_backfill.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Backfills `hecks_eras.held_projection` for rows that predate it, by calling the same path
+    # `EraStore#eras` already takes on boot, explicitly. Idempotent.
+    #
+    #   hecks backfill_projections <domain path>
+    module EraProjectionBackfill
+      module_function
+
+      # Backfills the rows that carry no projection and prints how many it fixed.
+      #
+      # @param argv [Array<String>] the domain directory
+      # @param root [String] unused: the domain is read from the path given
+      # @return [Integer] 0, or 1 when a row fails its own integrity check
+      # @raise [SystemExit] when the domain cannot be loaded or its adapter holds no eras
+      def main(argv, **)
+        domain_path = argv.first
+        abort "usage: hecks backfill_projections <domain path>" unless domain_path
+
+        loading = Hecks::Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(domain_path)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(loading.shared_root(nil, directory))
+          loading.load_each(directory, %w[*.port *.adapter *.bluebook *.hecksagon *.world])
+        end
+
+        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        backfill(bluebook, lineage_settings(registry, bluebook))
+      end
+
+      # @return [Hash] the persistence binding's settings
+      # @raise [SystemExit] when the bound adapter holds no eras
+      def lineage_settings(registry, bluebook)
+        first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        capable =
+          begin
+            adapter_class = registry.adapter_class(adapter_name)
+            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+          rescue StandardError
+            false
+          end
+        # Only a lineage-capable adapter holds eras — every other adapter has no held_projection
+        # column to migrate.
+        abort "#{bluebook.name} is bound to #{adapter_name}, which holds no eras — nothing to migrate." unless capable
+
+        registry.binding_settings(bluebook.name, Hecks::Ports::Persistence::VERB, adapter_name)
+      end
+
+      # @return [Integer] the exit status
+      def backfill(bluebook, settings)
+        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
+        lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+        lineage.ensure_base!
+
+        missing = lambda {
+          db.exec_params(
+            "SELECT count(*)::int AS n FROM hecks_eras WHERE domain = $1 AND held_projection IS NULL",
+            [bluebook.name]
+          )[0]["n"].to_i
+        }
+
+        before = missing.call
+        if before.zero?
+          puts "#{bluebook.name}: every held era already carries a projection — nothing to do."
+          return 0
+        end
+
+        begin
+          # Raises on the first row whose own digest check fails — a tampered row, not a merely
+          # legacy one, which backfilling must not paper over.
+          lineage.eras
+        rescue Hecks::Runtime::WiringError => e
+          puts "#{bluebook.name}: stopped at a row that isn't merely legacy — it fails its own integrity check:"
+          puts "  #{e.message}"
+          puts "  resolve that first (see hecks reattest), then run this again for the remaining rows."
+          return 1
+        end
+
+        backfilled = before - missing.call
+        puts "#{bluebook.name}: backfilled #{backfilled} era#{'s' unless backfilled == 1} — " \
+             "every row now carries a projection."
+        0
+      end
+    end
+  end
+end

data/lib/hecks/tools/era_reattest.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "json"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Re-attests an era's held text after a digest-integrity refusal, once a human has read it.
+    # Refuses without `--accept`; each attestation (old digest, new digest, when) is logged. The
+    # digest is tamper-evidence against drift, not against an adversary.
+    #
+    #   hecks reattest <domain> <era ordinal> [--accept]
+    module EraReattest
+      USAGE = "usage: hecks reattest <domain> <era ordinal> [--accept]"
+
+      module_function
+
+      # Shows the held text against its recorded digest and, with `--accept`, re-freezes it.
+      #
+      # @param argv [Array<String>] the domain directory, the era's ordinal and `--accept`
+      # @param root [String] unused: the domain is read from the path given
+      # @return [Integer] 0 when nothing needed attesting or it was attested, 1 when refused
+      # @raise [SystemExit] when the domain cannot be loaded or holds no such era
+      def main(argv, **)
+        argv = argv.dup
+        accept = argv.delete("--accept")
+        domain_path = argv.shift
+        ordinal = argv.shift&.to_i
+        abort USAGE unless domain_path && ordinal&.positive?
+
+        registry, bluebook = load_domain(domain_path)
+        lineage = open_lineage(registry, bluebook)
+        era = lineage.raw_era(ordinal) or abort "#{bluebook.name} holds no era #{ordinal}"
+        verify(bluebook, lineage, era, ordinal, accept)
+      end
+
+      # No translations are loaded: an unresolved edge must not block attesting a text.
+      #
+      # @param domain_path [String] the domain directory
+      # @return [Array] the registry and its bluebook
+      def load_domain(domain_path)
+        loading = Hecks::Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(domain_path)
+        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(loading.shared_root(nil, directory))
+          loading.load_each(directory, %w[*.port *.adapter *.bluebook *.hecksagon *.world])
+        end
+        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        [registry, bluebook]
+      end
+
+      # @return [Object] the domain's ensured lineage
+      # @raise [SystemExit] when the bound adapter holds no eras
+      def open_lineage(registry, bluebook)
+        first = bluebook.aggregates.first or abort "#{bluebook.name} declares no aggregates"
+        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
+        capable =
+          begin
+            adapter_class = registry.adapter_class(adapter_name)
+            adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?
+          rescue StandardError
+            false
+          end
+        # Only a lineage-capable adapter holds era texts.
+        unless capable
+          abort "#{bluebook.name} is bound to #{adapter_name}, which holds no eras — " \
+                "there is no frozen text to re-attest."
+        end
+
+        settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+        db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
+        lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
+        lineage.ensure_base!
+        lineage
+      end
+
+      # @return [Integer] the exit status
+      def verify(bluebook, lineage, era, ordinal, accept)
+        text = era[:held_text]
+        stored = era[:held_digest]
+        computed = Digest::SHA256.hexdigest(text)
+        if stored == computed
+          puts "#{bluebook.name} era #{ordinal}: the held text matches its digest — nothing to re-attest."
+          return 0
+        end
+
+        puts "#{bluebook.name} era #{ordinal}: the held text does NOT match its recorded digest."
+        puts "  recorded: #{stored || '(none)'}"
+        puts "  computed: #{computed}"
+        return 1 unless shape_unchanged?(bluebook, era, ordinal, text)
+
+        show(text)
+        return refuse_without_accept unless accept
+
+        fresh = lineage.reattest!(ordinal)
+        puts
+        puts "ATTESTED: era #{ordinal} re-frozen as #{fresh[0, 12]}… — the old and new digests are recorded."
+        0
+      end
+
+      # A shape change refuses hard; no `--accept` passes it.
+      #
+      # @return [Boolean] false after printing the refusal
+      def shape_unchanged?(bluebook, era, ordinal, text)
+        stored_projection = era[:held_projection] && JSON.parse(era[:held_projection])
+        verdict = Hecks::Translation::Reattest.shape_guard!(
+          domain: bluebook.name, ordinal: ordinal, text: text,
+          stored_hash: era[:hash], stored_projection: stored_projection
+        )
+        case verdict
+        when :cosmetic
+          puts "  shape:    unchanged — the edit is cosmetic (the text still projects to era #{ordinal}'s " \
+               "minted name)"
+        when :unnamed
+          puts "  shape:    era #{ordinal} was never named, so no shape comparison is possible — read carefully"
+        end
+        true
+      rescue Hecks::Runtime::WiringError => e
+        puts
+        puts "REFUSED: #{e.message}"
+        false
+      end
+
+      # @return [void]
+      def show(text)
+        puts
+        puts "The held text AS IT NOW STANDS — the original is gone; this is what you would be attesting to:"
+        puts "─" * 72
+        puts text
+        puts "─" * 72
+      end
+
+      # @return [Integer] 1
+      def refuse_without_accept
+        puts
+        puts "REFUSED: nothing changed. If you have read the text above and accept it as this era's"
+        puts "frozen source, run again with --accept. The attestation (old digest, new digest, when)"
+        puts "goes on the record either way you decide."
+        1
+      end
+    end
+  end
+end

data/lib/hecks/tools/evolve_run.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Walks a bluebook language change (syntax row, builder, golden) through its lifecycle:
+    # `status`, `propose`, `admit`, `deprecate`, `retire` and `rename` a word, and the
+    # `argument-*` forms of the same for a keyword's arguments (see `USAGE`).
+    #
+    #   hecks evolve propose <word> --context Aggregate  a row enters, proposed
+    #   hecks evolve admit   <word> --context Aggregate  proposed -> admitted
+    #   hecks evolve rename  <word> --context X --to new
+    #
+    # Mutating commands regenerate the golden and run the gates; a failing gate restores every file.
+    module EvolveRun
+      # The specs a change must keep green.
+      GATES = %w[
+        spec/syntax_conformance_spec.rb
+        spec/syntax_lifecycle_spec.rb
+        spec/ir_golden_spec.rb
+      ].freeze
+
+      # Words that move a word to a status.
+      WORD_STATUS = { "admit" => "admitted", "deprecate" => "deprecated", "retire" => "retired" }.freeze
+
+      # Words that move a keyword's argument to a status.
+      ARGUMENT_STATUS = { "argument-admit" => "admitted", "argument-deprecate" => "deprecated",
+                          "argument-retire" => "retired" }.freeze
+
+      USAGE = "usage: hecks evolve status|propose|admit|deprecate|retire <word> --context <Context> " \
+              "[--body none|keywords|source|rows] [--inner X] [--opens X] [--fills x]\n   " \
+              "or: hecks evolve argument-propose|argument-admit|argument-deprecate|argument-retire " \
+              "<keyword> --context <Context> [--kind K] [--at N] [--named NAME] [--required true|false] " \
+              "[--fills F]"
+
+      module_function
+
+      # Runs one lifecycle command.
+      #
+      # @param argv [Array<String>] the command, its word or keyword, then its flags
+      # @param root [String] the checkout whose syntax tables and golden are edited
+      # @return [Integer] 0, or 1 when a gate refuses and the files are restored
+      # @raise [SystemExit] with the reason when an argument is missing
+      def main(argv, root: Tools::ROOT)
+        require "hecks/grammar/evolve"
+        args = argv.dup
+        command = args.shift
+        evolve = Hecks::Grammar::Evolve
+        ok =
+          case command
+          when "status" then status(evolve)
+          when "propose" then propose(args, evolve, root)
+          when *WORD_STATUS.keys then set_status(command, args, evolve, root)
+          when "rename" then rename(args, evolve, root)
+          when "argument-propose" then propose_argument(args, evolve, root)
+          when *ARGUMENT_STATUS.keys then set_argument_status(command, args, evolve, root)
+          else abort USAGE
+          end
+        ok == false ? 1 : 0
+      end
+
+      # Rewrites spec/golden/ir/Bluebook.json by running its spec with `GOLDEN=rewrite`.
+      #
+      # @param root [String] the checkout
+      # @return [Boolean, nil] whether the spec ran green
+      def regenerate!(root)
+        system({ "GOLDEN" => "rewrite" },
+               "bundle", "exec", "rspec", "spec/ir_golden_spec.rb",
+               chdir: root, out: File::NULL, err: File::NULL)
+      end
+
+      # Runs the syntax conformance, syntax lifecycle and golden IR specs.
+      #
+      # @param root [String] the checkout
+      # @return [Boolean, nil] whether they passed
+      def gates_pass?(root)
+        system("bundle", "exec", "rspec", *GATES, chdir: root)
+      end
+
+      # Runs one grammar edit inside the snapshot/regenerate/gate sequence, restoring every
+      # snapshot if the block raises or a gate fails.
+      #
+      # @param word [String] what the edit is about, for the report
+      # @param context [String] the aggregate the word belongs to
+      # @param evolve [Module] `Hecks::Grammar::Evolve`
+      # @param root [String] the checkout
+      # @return [Boolean] true if the block ran and the gates held
+      def guarded(word, context, evolve, root, &)
+        paths = evolve.syntax_paths + [File.join(root, "spec/golden/ir/Bluebook.json")]
+        snapshots = paths.to_h { |path| [path, File.read(path)] }
+        evolve.restore_on_raise(paths, &)
+        regenerate!(root)
+        if gates_pass?(root)
+          puts "\n#{context}.#{word} — the gates hold. Regenerated projections and the golden are in the tree."
+          true
+        else
+          snapshots.each { |path, content| File.write(path, content) }
+          puts "\nRESTORED — the gates refused, and the failures above are the checklist. " \
+               "Nothing was changed."
+          false
+        end
+      rescue StandardError => e
+        # `restore_on_raise` has already restored the files; this only reports.
+        puts "\nRESTORED — #{e.message} Nothing was changed."
+        false
+      end
+
+      # @return [true]
+      def status(evolve) # rubocop:disable Naming/PredicateMethod
+        rows = evolve.keyword_rows
+        moving = rows.reject { |row| row[:status] == "admitted" }
+        renamed = rows.reject { |row| row[:was].to_s.empty? }
+        puts "#{rows.size} keyword rows; #{moving.size} not simply admitted; #{renamed.size} renamed"
+        moving.each { |row| puts "  #{row[:status].ljust(10)} #{row[:context]}.#{row[:word]}" }
+        renamed.each { |row| puts "  renamed    #{row[:context]}.#{row[:word]} (was #{row[:was]})" }
+        true
+      end
+
+      # @return [Boolean] whether the gates held
+      def propose(args, evolve, root)
+        word = args.shift or abort "propose what word?"
+        context = evolve.option(args, "context") or abort "--context is required — a word is a word somewhere"
+        ok = guarded(word, context, evolve, root) do
+          evolve.propose(word: word, context: context,
+                         body: evolve.option(args, "body", "none"), inner: evolve.option(args, "inner", ""),
+                         opens: evolve.option(args, "opens", ""), fills: evolve.option(args, "fills", ""))
+        end
+        if ok
+          puts "Proposed. It reaches no projection until admitted. Before `hecks evolve admit`:"
+          puts "  1. teach the #{context} builder the word (and its spec/dsl_spec example)"
+        end
+        ok
+      end
+
+      # @return [Boolean] whether the gates held
+      def set_status(command, args, evolve, root)
+        word = args.shift or abort "#{command} what word?"
+        context = evolve.option(args, "context") or abort "--context is required"
+        guarded(word, context, evolve, root) do
+          evolve.set_status(word: word, context: context, to: WORD_STATUS.fetch(command))
+        end
+      end
+
+      # @return [Boolean] whether the gates held
+      def rename(args, evolve, root)
+        word = args.shift or abort "rename what word?"
+        context = evolve.option(args, "context") or abort "--context is required"
+        to = evolve.option(args, "to") or abort "--to is required — a rename goes somewhere"
+        ok = guarded(word, context, evolve, root) { evolve.rename(word: word, context: context, to: to) }
+        if ok
+          puts "Renamed. The old spelling keeps parsing — that is the point. Before this holds:"
+          puts "  1. alias the new word to the old in the #{context} builder (alias_method :#{to}, :#{word})"
+          puts "  2. add the identical-IR example to spec/dsl_spec.rb"
+        end
+        ok
+      end
+
+      # @return [Boolean] whether the gates held
+      def propose_argument(args, evolve, root)
+        keyword = args.shift or abort "argument-propose which keyword's argument?"
+        context = evolve.option(args, "context") or abort "--context is required"
+        kind = evolve.option(args, "kind") or abort "--kind is required — text|symbol|number|flag|literal|constant|pairs|list"
+        ok = guarded("#{keyword} argument", context, evolve, root) do
+          evolve.propose_argument(keyword: keyword, context: context, kind: kind,
+                                  required: evolve.option(args, "required", "false"),
+                                  at: evolve.option(args, "at", ""), named: evolve.option(args, "named", ""),
+                                  fills: evolve.option(args, "fills", ""),
+                                  pairs_shape: evolve.option(args, "pairs-shape"))
+        end
+        if ok
+          puts "Proposed. It reaches no projection until admitted. Before `hecks evolve argument-admit`:"
+          puts "  1. teach the #{context} builder's #{keyword} method the argument"
+        end
+        ok
+      end
+
+      # @return [Boolean] whether the gates held
+      def set_argument_status(command, args, evolve, root)
+        keyword = args.shift or abort "#{command} which keyword's argument?"
+        context = evolve.option(args, "context") or abort "--context is required"
+        guarded("#{keyword} argument", context, evolve, root) do
+          evolve.set_argument_status(keyword: keyword, context: context, to: ARGUMENT_STATUS.fetch(command),
+                                     at: evolve.option(args, "at", ""), named: evolve.option(args, "named", ""))
+        end
+      end
+    end
+  end
+end