hecks 2.9.0 → 3.0.1

data/lib/hecks/hecks/adapters/codebase/regeneration.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "ruby_child"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `RegenerationRun` asks of the working tree: regenerating every corpus
+      # domain's committed Rust output.
+      #
+      # It runs `Hecks::Tools::RegenerationRun` in this process: the run forks once for each
+      # domain, in a fixed order, because the domains share the files they stamp. With `check` it
+      # projects into a scratch copy of the crate and compares, and never writes the tree. Without
+      # `confirm` the run is that same check, so a regeneration that would rewrite tracked generated
+      # files reports drift and writes only when it is confirmed.
+      module Regeneration
+        # Every operation this family carries out.
+        OPERATIONS = %w[regenerate_corpus].freeze
+
+        # How many lines of a script's output a refusal keeps.
+        KEPT_LINES = 60
+
+        module_function
+
+        # Carries out the regeneration.
+        #
+        # @param _operation [String] `regenerate_corpus`
+        # @param held [Hash] the `RegenerationRun` record's fields: `check`, `confirm`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused: the tool runs in this process
+        # @return [String] how many domains were checked or regenerated
+        # @raise [ConsoleCapture::Failure] with the difference, when a check finds drift, or with
+        #   what the script printed when it ends badly
+        def call(_operation, held, tree, shell: nil)
+          flag = ->(name) { (held[name].is_a?(Hash) ? held[name][:value] : held[name]) == true }
+          check = flag.call(:check) || !flag.call(:confirm)
+          child = RubyChild.new(tree)
+          result = child.capture("regen_codegen_domains", *("--check" if check))
+          raise ConsoleCapture::Failure, refusal(result) unless result.ok?
+
+          summary(result.out, check)
+        end
+
+        # @param output [String] what the script printed
+        # @param check [Boolean] whether it only compared
+        # @return [String] the verdict, with how many domains it covered
+        def summary(output, check)
+          count = output[/regenerating ([0-9]+) domain/, 1]
+          return "regenerated #{count} corpus domains into the checkout" unless check
+
+          "checked #{count} corpus domains against a scratch crate: no drift " \
+            "(add --confirm to regenerate into the checkout)"
+        end
+
+        # @param result [Shell::Result] how the script ended
+        # @return [String] the last lines it printed: the difference, or why it stopped
+        def refusal(result)
+          lines = [result.out, result.err].join.lines.map(&:chomp).reject(&:empty?)
+          shown = lines.last(KEPT_LINES)
+          note = lines.size > shown.size ? ["(the last #{shown.size} of #{lines.size} lines)"] : []
+          [*note, *shown].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/release_facts.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks/release/runner"
+require_relative "tree"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The facts a release is judged by, read from git and the checkout's files and judged by
+      # nothing here: the rules are the givens of the `Clear` command of `PublishingRun`.
+      #
+      # It reads the branch, whether `HEAD` is `origin/main` (after a fetch), whether the tree is
+      # clean, the gem's version and the client package's, whether the changelog has a heading for
+      # the version, and where a tag for the version already points. Nothing is changed but the
+      # remote-tracking refs a fetch updates.
+      class ReleaseFacts
+        # The line of `lib/hecks/version.rb` that declares the version.
+        VERSION_LINE = /^\s*VERSION\s*=\s*"(?<version>[^"]+)"/
+
+        # Where the client package declares its version, relative to the checkout.
+        CLIENT_PACKAGE = "packages/hecks-client/package.json"
+
+        # @param tree [Tree] the checkout
+        # @param commands [#capture, #run!] starts each process, as `Release::Runner::Commands` does
+        def initialize(tree, commands:)
+          @tree = tree
+          @git = Release::Runner::Git.new(root: tree.root, commands: commands)
+        end
+
+        # Reads the facts a run of the operation needs.
+        #
+        # @param operation [String] `publish` (every fact) or `publish_gem` (the versions only)
+        # @return [Hash] each fact as the run holds it: every one a value object
+        #   as a hash, and `ships_from` the checkout's path
+        # @raise [ConsoleCapture::Failure] when git or a file cannot be read
+        def gather(operation)
+          version = declared_version
+          facts = { operation: word(operation), version: word(version), client_version: word(client_version),
+                    ir_version: word("#{Bluebook::Chapter::IR_VERSION}.0.0"), ships_from: { path: @tree.root } }
+          return facts if operation == "publish_gem"
+
+          facts.merge(git_facts(version)).merge(changelog: flag(changelog?(version)))
+        rescue Release::Runner::Refusal, Errno::ENOENT, JSON::ParserError, KeyError => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        private
+
+        def git_facts(version)
+          fetch = @git.capture("fetch", "origin")
+          raise ConsoleCapture::Failure, "git fetch origin failed (#{fetch.stderr.strip})" unless fetch.success?
+
+          head = read("rev-parse", "HEAD")
+          { branch: word(read("rev-parse", "--abbrev-ref", "HEAD")), head: word(head),
+            on_origin: flag(head == read("rev-parse", "origin/main")),
+            clean: flag(read("status", "--porcelain").empty?), tag_state: word(tag_state("v#{version}", head)) }
+        end
+
+        def tag_state(tag, head)
+          tagger = Release::Runner::Tagger.new(git: @git, console: nil, dry_run: true)
+          commits = [tagger.local_commit(tag), tagger.remote_commit(tag)].compact
+          return "none" if commits.empty?
+
+          commits.all?(head) ? "at_release_commit" : "elsewhere"
+        end
+
+        def read(*) = @git.read(*).strip
+
+        def declared_version
+          match = File.read(@tree.path("lib/hecks/version.rb")).match(VERSION_LINE)
+          raise Release::Runner::Refusal, "lib/hecks/version.rb declares no VERSION; restore it" unless match
+
+          match[:version]
+        end
+
+        def client_version = JSON.parse(File.read(@tree.path(CLIENT_PACKAGE))).fetch("version")
+
+        def changelog?(version)
+          File.read(@tree.path("CHANGELOG.md")).match?(/^## \[#{Regexp.escape(version)}\]/)
+        end
+
+        def word(text) = { value: text }
+
+        def flag(truth) = { value: truth }
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/ruby_child.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../shell"
+require_relative "../console_capture"
+require "hecks/tools"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # Runs one of this repository's own tools, by its name in `Hecks::Tools::REGISTRY`.
+      #
+      # The tool runs in this process from the checkout's root, its output and exit status
+      # captured: the gem carries every tool, so nothing is started as a child.
+      class RubyChild
+        # @param tree [Tree] the checkout the tool belongs to
+        def initialize(tree)
+          @tree = tree
+        end
+
+        # Runs the tool with the arguments and answers what it printed.
+        #
+        # @param script [String] the tool's name in `Hecks::Tools::REGISTRY`
+        # @param args [Array<String>] its arguments
+        # @param env [Hash{String => String}] unused; a tool reads this process's environment
+        # @return [String] what it wrote to stdout, and to stderr when there was any
+        # @raise [ConsoleCapture::Failure] when it ends with a non-zero status; the message is
+        #   everything it printed
+        def answer(script, *, env: {})
+          result = capture(script, *, env: env)
+          return printed(result) if result.ok?
+
+          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+        end
+
+        # Runs the tool with the arguments and answers only what it printed to stdout, for a tool
+        # whose stdout is its data and whose stderr is progress.
+        #
+        # @param script [String] the tool's name in `Hecks::Tools::REGISTRY`
+        # @param args [Array<String>] its arguments
+        # @param env [Hash{String => String}] unused; a tool reads this process's environment
+        # @return [String] its stdout, without the trailing newline
+        # @raise [ConsoleCapture::Failure] when it ends with a non-zero status; the message is
+        #   everything it printed
+        def read(script, *, env: {})
+          result = capture(script, *, env: env)
+          return result.out.chomp if result.ok?
+
+          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+        end
+
+        # Runs the tool with the arguments and hands back how it ended.
+        #
+        # @param script [String] the tool's name in `Hecks::Tools::REGISTRY`
+        # @param args [Array<String>] its arguments
+        # @param env [Hash{String => String}] unused; a tool reads this process's environment
+        # @return [Shell::Result] its output (stderr included) and status
+        # @raise [KeyError] when no tool has that name
+        def capture(script, *args, env: {})
+          in_process(script, args)
+        end
+
+        private
+
+        def in_process(script, args)
+          code = nil
+          outcome = ConsoleCapture.capture { code = Tools.run(script, args, root: @tree.root) }
+          Shell::Result.new(outcome.output, "", Status.new(code))
+        end
+
+        # How a tool run in this process ended, answering as a `Process::Status` does.
+        Status = Struct.new(:exitstatus) do
+          # @return [Boolean] whether it ended with status 0
+          def success? = exitstatus.zero?
+        end
+
+        def printed(result, otherwise = "")
+          text = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
+          text.empty? ? otherwise : text
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/secret_vault.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `SecretVault` adapter: runs a program with the secrets a 1Password `op run` env file
+      # names, so a key or token never sits in a file, a variable of ours or a command line.
+      #
+      # It starts `op` through the object it is given, which answers `capture` and `run!` as
+      # `Hecks::Release::Runner::Commands` does; a spec hands it a recorder.
+      class SecretVault
+        # @param commands [#capture, #run!] starts each process
+        def initialize(commands:)
+          @commands = commands
+        end
+
+        # @return [Boolean] whether the 1Password CLI is installed
+        def installed?
+          @commands.capture("op", "--version").success?
+        end
+
+        # Runs a program with the env file's secrets in its environment, its output going to the
+        # terminal so a prompt (Touch ID, an approval link) reaches the person.
+        #
+        # @param env_file [String] the env file `op run` reads, absolute or relative to `chdir`
+        # @param argv [Array<String>] the program and its arguments
+        # @param chdir [String, nil] the directory to run in
+        # @return [true] when the program exits zero
+        # @raise [Hecks::Release::Runner::CommandFailed] when it does not
+        def run!(env_file, *argv, chdir: nil)
+          @commands.run!("op", "run", "--env-file=#{env_file}", "--", *argv, chdir: chdir)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/source_tree.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/codebase/source_tree"
+
+Hecks.adapter "SourceTree" do
+  port "SourceTree"
+end

data/lib/hecks/hecks/adapters/codebase/source_tree.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "language"
+require_relative "kernel_tables"
+require_relative "conformance"
+require_relative "regeneration"
+require_relative "style"
+require_relative "codemods"
+require_relative "test_suite"
+require_relative "corpus_tasks"
+require_relative "publishing"
+require_relative "../git"
+
+module Hecks
+  module Adapters
+    # The `SourceTree` port's adapter: everything Codebase does to the working tree of this
+    # repository.
+    #
+    # It answers the one fact every Codebase request needs (`examine`: is the tree a hecks
+    # checkout?), carries out an accepted request (`perform`), and answers Codebase's queries. Each
+    # of them refuses "needs a hecks checkout" outside a checkout, so an installed gem never touches
+    # an absent `rust/` or rewrites its own `lib/`, even when the journaled guard is bypassed.
+    # `perform` finds the task family that carries an operation out; a family lives beside this
+    # file and does the work with the existing generators, linters and tools.
+    class SourceTree
+      class << self
+        # @return [#capture, nil] starts each child process; a `Shell` when nil. A spec replaces it
+        #   so no gate has to run to test what is asked of it.
+        attr_accessor :shell
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Reports whether the working tree is a hecks checkout. For a release it also reports the
+      # facts the Git adapter surveys, since a release's rules are judged with the checkout rule.
+      #
+      # @param held [Hash] the record: `operation`
+      # @return [Hash{Symbol => Hash}] `checkout:` whether hecks.gemspec stands beside lib/, and for
+      #   a release the facts to judge
+      def examine(**held)
+        answer = { checkout: { value: tree.checkout? } }
+        operation = plain(held[:operation])
+        return answer unless Codebase::Publishing::OPERATIONS.include?(operation)
+
+        facts = tree.checkout? ? Git.new.survey(**held) : Codebase::Publishing.no_facts(operation)
+        answer.merge(facts)
+      end
+
+      # Carries out the operation an accepted request names.
+      #
+      # @param held [Hash] the record: `operation` and every argument the request set
+      # @return [Hash{Symbol => Hash}] `report:` what was found, or done; a task that does more
+      #   than report (a release) answers its own fields, `report:` among them
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when no family carries the operation out, or it refuses
+      def perform(**held)
+        tree.require_checkout!
+        operation = plain(held[:operation])
+        family = FAMILIES.find { |candidate| candidate::OPERATIONS.include?(operation) }
+        raise ConsoleCapture::Failure, "no task carries out #{operation.inspect}" unless family
+
+        args = held.except(:operation)
+        done = family.call(operation, args, tree, shell: self.class.shell || Shell.new)
+        done.is_a?(Hash) ? done : { report: { value: done } }
+      end
+
+      # @return [Hash] `text:` where every word of the language stands
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def word_status(**)
+        tree.require_checkout!
+        { text: Codebase::Language.word_status }
+      end
+
+      # @param args [Hash] the query's arguments: `paths`, `only`, `json`, `top`
+      # @return [Hash] `text:` the Ruby comment violations, as the linter reports them
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the linter refuses its arguments
+      def report_comments(**args)
+        { text: report("report_comments", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `paths`, `only`, `json`, `top`
+      # @return [Hash] `text:` the Rust comment violations, as the linter reports them
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the linter refuses its arguments
+      def report_rust_comments(**args)
+        { text: report("report_rust_comments", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `group`, `groups`, `runtime_log`
+      # @return [Hash] `text:` the spec files one group of a runtime-balanced split runs
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the script refuses its arguments
+      def shard_specs(**args)
+        { text: test_suite("shard_specs", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `exclude`, `tags`, `check`
+      # @return [Hash] `text:` the spec files with an example the tag filter selects, one per line
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the list is stale, or the script refuses its arguments
+      def list_io_parallel_specs(**args)
+        { text: test_suite("list_io_parallel_specs", args) }
+      end
+
+      # @return [Hash] `text:` the expected match results of the pattern cases, as JSON
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def record_pattern_cases(**)
+        { text: test_suite("record_pattern_cases", {}) }
+      end
+
+      # @return [Hash] `text:` the feature and directory of every domain with a Rust feature
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def rust_domains(**)
+        { text: corpus("rust_domains", {}) }
+      end
+
+      # @return [Hash] `text:` the directories regeneration walks, in the order it walks them
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def regen_order(**)
+        { text: corpus("regen_order", {}) }
+      end
+
+      # @return [Hash] `text:` whether each generated Rust module is covered
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when a module is not covered
+      def corpus_rust_coverage(**)
+        { text: corpus("corpus_rust_coverage", {}) }
+      end
+
+      # @param args [Hash] the query's arguments: `names`
+      # @return [Hash] `text:` each IR construct's diff from its meta-domain
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def ir_constructs(**args)
+        { text: corpus("ir_constructs", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `domains`, `meta`
+      # @return [Hash] `text:` the rules declared more than once
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def ir_duplicates(**args)
+        { text: corpus("ir_duplicates", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `name`, `field`
+      # @return [Hash] `text:` which propagation touchpoints already show the field
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the construct is not one
+      def ir_impact(**args)
+        { text: corpus("ir_impact", args) }
+      end
+
+      private
+
+      def test_suite(operation, args)
+        tree.require_checkout!
+        plain_args = args.transform_values { |value| plain(value) }
+        Codebase::TestSuite.report(operation, plain_args, tree, shell: self.class.shell)
+      end
+
+      def corpus(operation, args)
+        tree.require_checkout!
+        plain_args = args.transform_values { |value| plain(value) }
+        Codebase::CorpusTasks.report(operation, plain_args, tree, shell: self.class.shell)
+      end
+
+      def report(operation, args)
+        tree.require_checkout!
+        plain_args = args.transform_values { |value| plain(value) }
+        Codebase::Style.report(operation, plain_args, tree, shell: self.class.shell)
+      end
+
+      # The task families, each carrying out the operations it lists.
+      FAMILIES = [Codebase::Language, Codebase::KernelTables, Codebase::Conformance, Codebase::Regeneration,
+                  Codebase::Style, Codebase::Codemods, Codebase::TestSuite, Codebase::CorpusTasks, Codebase::Publishing].freeze
+      private_constant :FAMILIES
+
+      def tree = Codebase::Tree.new
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/sqlite_fixture.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "../shell"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `SqliteFixture` adapter: regenerates the persistence legacy fixtures
+      # (`spec/fixtures/persistence_legacy/`) by writing through the real adapters.
+      #
+      # The fixtures are a baseline that later adapters are compared with, so the run is never
+      # started by accident: unconfirmed it reports what it would rewrite and whether the `sqlite3`
+      # program it dumps a database with is installed, and writes nothing. Confirmed, it runs
+      # `PersistenceLegacyFixture::Regenerate` in this process, which needs a reachable Postgres as
+      # well.
+      class SqliteFixture
+        # Where the fixtures stand, relative to the checkout.
+        DIRECTORY = "spec/fixtures/persistence_legacy"
+
+        # The stores each fixture set is written for.
+        STORES = %w[heki sqlite d1 postgres postgres_era].freeze
+
+        # @param tree [Tree] the checkout whose fixtures are rewritten
+        # @param shell [#capture, nil] starts the `sqlite3` probe; a `Shell` when nil
+        # @param regenerator [#call, nil] rewrites the fixtures, as `call(dir:)` answering what was
+        #   written; `PersistenceLegacyFixture::Regenerate` when nil
+        def initialize(tree, shell: nil, regenerator: nil)
+          @tree = tree
+          @shell = shell || Shell.new
+          @regenerator = regenerator
+        end
+
+        # Regenerates the fixtures, or reports what a regeneration would rewrite.
+        #
+        # @param confirm [Boolean] whether to rewrite
+        # @return [String] what was written, or (unconfirmed) what would be
+        # @raise [ConsoleCapture::Failure] when a fixture cannot be written
+        def regenerate(confirm:)
+          return rewrite if confirm
+
+          "dry run, would rewrite #{DIRECTORY}/ for #{STORES.join(', ')} through the real adapters " \
+            "(#{installed}; add --confirm)"
+        end
+
+        # @return [Boolean] whether the `sqlite3` program answers
+        def sqlite_installed?
+          @shell.capture("sqlite3", "--version").ok?
+        end
+
+        private
+
+        def rewrite
+          regenerator.call(dir: @tree.path(DIRECTORY))
+        rescue LoadError, StandardError => e
+          raise ConsoleCapture::Failure, "#{e.class}: #{e.message}"
+        end
+
+        def regenerator
+          @regenerator ||= begin
+            require "hecks/persistence_legacy_fixture"
+            PersistenceLegacyFixture::Regenerate
+          end
+        end
+
+        def installed = sqlite_installed? ? "sqlite3 is installed" : "sqlite3 is not installed"
+      end
+    end
+  end
+end