hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,62 @@
+require_relative "corpus_tasks"
+require_relative "static_directory"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `CorpusRun` asks of the working tree to preview a static site: serve one
+      # directory of files on the loopback address only, until the server is stopped.
+      #
+      # The server hook is the one `CorpusTasks` has, so a spec replaces every server the same way.
+      module Previewing
+        # Every operation this family carries out.
+        OPERATIONS = %w[preview].freeze
+
+        # The port the preview listens on when none is named.
+        DEFAULT_PORT = 4580
+
+        # The only address the preview binds: it carries no authentication.
+        HOST = "127.0.0.1".freeze
+
+        module_function
+
+        # Serves the directory.
+        #
+        # @param operation [String] `preview`
+        # @param held [Hash] the `CorpusRun` record's fields: `port` and `directory`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused
+        # @return [String] a note that the server stopped
+        # @raise [ConsoleCapture::Failure] when the directory is not named or is not a directory
+        def call(operation, held, tree, shell: nil)
+          _ = [operation, shell, tree]
+          fields = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          root = directory(fields[:directory])
+          port = fields[:port] || DEFAULT_PORT
+          warn "previewing #{root} on http://#{HOST}:#{port}/ - no authentication; do not expose beyond localhost"
+          (CorpusTasks.web_server || method(:serve)).call(app: StaticDirectory.new(root), port: port, host: HOST)
+          "previewed on port #{port}, now stopped"
+        end
+
+        # @param app [#call] the Rack app
+        # @param port [Integer] the port
+        # @param host [String] the address to bind
+        # @return [void]
+        def serve(app:, port:, host:)
+          require "rackup"
+          Rackup::Server.start(app: app, Host: host, Port: port, server: "webrick")
+        end
+
+        # @param named [String, nil] the directory the run names
+        # @return [String] its absolute path
+        # @raise [ConsoleCapture::Failure] when it is not named or is not a directory
+        def directory(named)
+          path = File.expand_path(named.to_s)
+          return path if !named.to_s.empty? && File.directory?(path)
+
+          raise ConsoleCapture::Failure, "preview needs directory=<path> naming a directory, not #{named.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/promotion/gate.rb

@@ -7,7 +7,7 @@ module Hecks
   module Adapters
     module Codebase
       module Promotion
-        # Where every `RequiredCheck` of the Vocabulary chapter stands against one commit.
+        # Where every `RequiredCheck` of the Vocabulary bluebook stands against one commit.
         #
         # It reports and does not decide: `Accept` holds the rule that a promotion needs every check
         # green. A check that has not finished (or has not started) is told apart from one that

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "search"
+require_relative "declarations"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `ReadSource`, `Outline` and `Declaration` queries ask of the working tree:
+      # reading a file, saying what it declares, and finding where a named construct lives, so a
+      # reader never has to leave the launcher for `cat` or `sed`.
+      #
+      # A construct is found by name, not by pattern, from the scan {Declarations} keeps. The
+      # answer is a `path:from-to` range, so one `Declaration` and one `ReadSource` read exactly
+      # the block and nothing around it; `show` does both in one call.
+      module Reading
+        # The most lines `ReadSource` returns when `top` is not named.
+        DEFAULT_TOP = 200
+
+        module_function
+
+        # @param args [Hash] the query's arguments: `path`, `from`, `to`, `top`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `line: text` row per line read, then a note when `top` cut it short
+        # @raise [ConsoleCapture::Failure] when the path is not a readable text file of the checkout
+        def read(args, tree)
+          lines = File.readlines(readable(tree, args.fetch(:path)), chomp: true)
+          from, upto, shown = window(args, lines.length)
+          rows = (from..shown).map { |number| "#{number}: #{lines[number - 1]}" }
+          rows << "(#{upto - shown} more lines to #{upto}; ask from=#{shown + 1})" if shown < upto
+          rows.join("\n")
+        end
+
+        # @return [Array<Integer>] the first line, the last line asked for, and the last line shown
+        def window(args, total)
+          from = args[:from] || 1
+          upto = [args[:to] || total, total].min
+          [from, upto, [upto, from + (args[:top] || DEFAULT_TOP) - 1].min]
+        end
+
+        # @param args [Hash] the query's argument: `path`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `from-to: kind name` row per declaration, indented by nesting
+        # @raise [ConsoleCapture::Failure] when the path is not a readable text file of the checkout
+        def outline(args, tree)
+          file = args.fetch(:path)
+          found = Declarations.outline(file, File.readlines(readable(tree, file), chomp: true))
+          found.map { |entry| "#{nesting(found, entry)}#{entry.from}-#{entry.to}: #{entry.label}" }.join("\n")
+        end
+
+        # @param args [Hash] the query's arguments: `name`, `kind`, `paths`, `show`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `path:from-to: kind "Name"` row per declaration, the block's text
+        #   after each when `show` is set
+        # @raise [ConsoleCapture::Failure] when nothing by that name is declared
+        def declaration(args, tree)
+          found = matching(Declarations.entries(tree, args[:paths]), args)
+          raise ConsoleCapture::Failure, "nothing is declared as #{args[:name].inspect}" if found.empty?
+
+          found.map { |entry| args[:show] ? shown(entry, tree) : "#{entry.range}: #{entry.label}" }.join("\n\n")
+        end
+
+        # @return [String] the file's absolute path, once it is known to be one to read
+        # @raise [ConsoleCapture::Failure] when it leaves the tree, is absent, or holds binary
+        def readable(tree, file)
+          absolute = File.expand_path(file, tree.root)
+          raise ConsoleCapture::Failure, "outside the checkout: #{file}" unless absolute.start_with?("#{tree.root}/")
+          raise ConsoleCapture::Failure, "no such file: #{file}" unless File.file?(absolute)
+          raise ConsoleCapture::Failure, "not a text file: #{file}" unless Search.text?(tree, tree.relative(absolute))
+
+          absolute
+        end
+
+        # @return [Array<Declarations::Entry>] the entries of the name (and kind, when asked)
+        def matching(entries, args)
+          entries.select { |entry| entry.name == args.fetch(:name) && [nil, entry.kind].include?(args[:kind]) }
+        end
+
+        # @return [String] two spaces for each declaration that encloses `entry`
+        def nesting(all, entry)
+          "  " * all.count { |other| other.from < entry.from && other.to >= entry.to }
+        end
+
+        def shown(entry, tree)
+          text = File.readlines(tree.path(entry.file), chomp: true)[(entry.from - 1)...entry.to]
+          body = text.each_with_index.map { |line, at| "#{entry.from + at}: #{line}" }
+          ["#{entry.range}: #{entry.label}", *body].join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 
 require_relative "tree"
 require_relative "ruby_child"
+require "hecks/tools/gate_memo/standalone"
 
 module Hecks
   module Adapters
@@ -10,17 +11,23 @@ module Hecks
       # domain's committed Rust output, and projecting the CI path gates into the workflows.
       #
       # 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.
+      # domain, a few at a time (`workers`, one per core unless told), and prints their output in
+      # a fixed domain order. The domains share the bluebooks they attach, and each writes the same
+      # bytes to them whichever runs first. 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 project_ci_gates project_lanes project_tools_doc decide_ci_gate].freeze
+        OPERATIONS = %w[regenerate_corpus project_ci_gates project_ci_pipeline project_lanes project_tools_doc
+                        decide_ci_gate].freeze
 
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
 
+        # The line the script prints before regenerating, capturing how many domains it covers.
+        REGENERATED_COUNT = /regenerating ([0-9]+) domain/
+
         module_function
 
         # Carries out the regeneration.
@@ -37,13 +44,42 @@ module Hecks
           child = RubyChild.new(tree)
           case operation
           when "project_ci_gates" then project_ci_gates(child, check)
+          when "project_ci_pipeline" then project_ci_pipeline(child, check)
           when "project_lanes" then project_lanes(child, check, set?(held, :live), set?(held, :confirm))
           when "project_tools_doc" then project_tools_doc(child, check)
           when "decide_ci_gate" then decide_ci_gate(child, held)
-          else regenerate(child, check)
+          else regenerate_remembered(child, tree, held, check)
           end
         end
 
+        # A check of the whole corpus that is not confirmed is skipped when the gate or an earlier
+        # check passed on the same files. A run that writes, or checks only some domains, always
+        # runs.
+        #
+        # @return [String] the verdict, or that the check was skipped as unchanged
+        def regenerate_remembered(child, tree, held, check)
+          args = [*domains(held), *workers(held)]
+          whole = check && args.empty? && !set?(held, :confirm)
+          return regenerate(child, check, args) unless whole
+
+          Tools::GateMemo::Standalone.guard(tree.root, "codegen_drift") { regenerate(child, check, args) }
+        end
+
+        # @param held [Hash] the `RegenerationRun` record's fields: `domains`
+        # @return [Array<String>] the tool's argument naming the domains to run, empty for every one
+        def domains(held)
+          named = held[:domains].is_a?(Hash) ? held[:domains][:value] : held[:domains]
+          named.to_s.empty? ? [] : ["domains=#{named}"]
+        end
+
+        # @param held [Hash] the `RegenerationRun` record's fields: `workers`
+        # @return [Array<String>] the tool's argument saying how many domains run at once, empty to
+        #   leave it to the tool's default
+        def workers(held)
+          count = held[:workers].is_a?(Hash) ? held[:workers][:value] : held[:workers]
+          count.to_s.empty? ? [] : ["workers=#{count}"]
+        end
+
         # @param held [Hash] the record's fields: `check`, `confirm`
         # @return [Boolean] whether the run only compares: asked for, or not confirmed
         def check_only?(held)
@@ -59,10 +95,12 @@ module Hecks
 
         # @param child [RubyChild] the checkout's tool runner
         # @param check [Boolean] whether to only compare
+        # @param domains [Array<String>] `domains=a,b` when only those are to run and `workers=n`
+        #   when told how many at once, else empty
         # @return [String] how many domains were checked or regenerated
         # @raise [ConsoleCapture::Failure] with the difference, or with what the script printed
-        def regenerate(child, check)
-          result = child.capture("regen_codegen_domains", *("--check" if check))
+        def regenerate(child, check, domains = [])
+          result = child.capture("regen_codegen_domains", *("--check" if check), *domains)
           raise ConsoleCapture::Failure, refusal(result) unless result.ok?
 
           summary(result.out, check)
@@ -76,6 +114,14 @@ module Hecks
           child.answer("project_ci_gates", *("--check" if check))
         end
 
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare
+        # @return [String] what the tool printed
+        # @raise [ConsoleCapture::Failure] with the stale workflows, when a check finds drift
+        def project_ci_pipeline(child, check)
+          child.answer("project_ci_pipeline", *("--check" if check))
+        end
+
         # Projects the `Lane` rows, or with `live` compares GitHub's rulesets with them. Only a live
         # run that is confirmed changes GitHub, so without `confirm` a live run is a comparison.
         #
@@ -112,7 +158,7 @@ module Hecks
         # @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]
+          count = output[REGENERATED_COUNT, 1]
           return "regenerated #{count} corpus domains into the checkout" unless check
 
           "checked #{count} corpus domains against a scratch crate: no drift " \
@@ -122,7 +168,8 @@ module Hecks
         # @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?)
+          printed = [result.out, result.err].join
+          lines = printed.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")

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

@@ -42,7 +42,7 @@ module Hecks
         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 } }
+                    ir_version: word("#{Bluebook::Declaration::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)))

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

@@ -29,7 +29,7 @@ module Hecks
           result = capture(script, *, env: env)
           return printed(result) if result.ok?
 
-          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+          raise ConsoleCapture::Failure, printed(result, ended(result))
         end
 
         # Runs the tool with the arguments and answers only what it printed to stdout, for a tool
@@ -45,7 +45,7 @@ module Hecks
           result = capture(script, *, env: env)
           return result.out.chomp if result.ok?
 
-          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+          raise ConsoleCapture::Failure, printed(result, ended(result))
         end
 
         # Runs the tool with the arguments and hands back how it ended.
@@ -73,6 +73,9 @@ module Hecks
           def success? = exitstatus.zero?
         end
 
+        # How a run that failed ended, for a failure that printed nothing.
+        def ended(result) = "ended with status #{result.exit_code}"
+
         def printed(result, otherwise = "")
           text = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
           text.empty? ? otherwise : text

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What a spec run's arguments become: the variables the specs read, and the flags a stress run takes.
+      # A person names them in a request, so they never set them in a shell.
+      module RunOptions
+        module_function
+
+        # The variables the specs read, set for one example only.
+        #
+        # @param args [Hash] `strict`, `seeds`, `environment` and `declaration_cache`, each
+        #   perhaps absent
+        # @return [Hash{String => String}] only those the run named
+        def spec_env(args)
+          { "CI" => ("true" if args[:strict] == true), "PROPERTY_SEEDS" => args[:seeds]&.to_s,
+            "HECKS_ENVIRONMENT" => args[:environment],
+            "HECKS_NO_DECLARATION_CACHE" => ("1" if args[:declaration_cache] == false) }.compact
+        end
+
+        # @param args [Hash] `runs`, `parallel` and `seed_start`
+        # @return [Array<String>] the script's flags for those that are named
+        def stress_flags(args)
+          { "--runs" => :runs, "--parallel" => :parallel, "--seed-start" => :seed_start }
+            .filter_map { |flag, name| [flag, args[name].to_s] if args[name] }.flatten
+        end
+
+        # @param args [Hash] `fixture`, perhaps absent
+        # @return [Hash{String => String}] the variable that names the one fixture to re-seed
+        def seed_env(args) = args[:fixture] ? { "SEED" => args[:fixture] } : {}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../../../tools/move_disables"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `ScriptRun` asks of the working tree: one named one-off script, planned, or
+      # applied once confirmed. A script's body is a tool under `lib/hecks/tools`; `SCRIPTS` names
+      # the ones this family may run, so a record cannot reach a tool it does not list.
+      module Scripting
+        # Every operation this family carries out.
+        OPERATIONS = %w[plan_script apply_script].freeze
+
+        # Each script a record may name, with the tool that carries it out.
+        SCRIPTS = { "move_disables" => Hecks::Tools::MoveDisables }.freeze
+
+        module_function
+
+        # Carries out one operation on the named script.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `ScriptRun` record's fields
+        # @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] the tool's plan, or the plan and what it wrote
+        # @raise [ConsoleCapture::Failure] when the record names no script this family runs
+        def call(operation, held, tree, shell: nil)
+          args = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          name = args[:script].to_s
+          tool = SCRIPTS.fetch(name) do
+            raise ConsoleCapture::Failure, "no script named #{name.inspect}; the scripts are #{SCRIPTS.keys.join(", ")}"
+          end
+          tool.transform(root: tree.root, apply: operation == "apply_script")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `Search` query asks of the working tree: the lines of its text files that
+      # match a regular expression, so a reader never has to leave the launcher for `grep`.
+      #
+      # Directories that hold no source of their own (version control, build output, vendored
+      # packages, scratch space, sibling worktrees) are left out, and so is any file with a null
+      # byte in its first block, which is how a binary announces itself.
+      module Search
+        # Directory names that are never walked.
+        SKIPPED = %w[.git target node_modules tmp vendor worktrees].freeze
+
+        # The rows kept when `top` is not named.
+        DEFAULT_TOP = 200
+
+        # Searched when no path is named.
+        DEFAULT_PATHS = "."
+
+        # How much of a file is read to tell text from binary.
+        SNIFF_BYTES = 8192
+
+        module_function
+
+        # @param args [Hash] the query's arguments: `pattern`, `paths`, `top`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `path:line: text` row per match, in path order
+        # @raise [ConsoleCapture::Failure] when the pattern is not a regular expression
+        def report(args, tree)
+          matcher = compile(args.fetch(:pattern))
+          limit = args[:top] || DEFAULT_TOP
+          rows = []
+          files(tree, args[:paths] || DEFAULT_PATHS).each do |file|
+            matches(tree, file, matcher, limit, rows)
+            break if rows.length >= limit
+          end
+          rows.join("\n")
+        end
+
+        # @return [Regexp] the pattern, compiled
+        # @raise [ConsoleCapture::Failure] when it does not compile
+        def compile(pattern)
+          Regexp.new(pattern)
+        rescue RegexpError => e
+          raise ConsoleCapture::Failure, "not a regular expression: #{e.message}"
+        end
+
+        # @param limit [Integer] the most rows `rows` may hold
+        # @param rows [Array<String>] the rows so far; the matches of `file` are appended
+        def matches(tree, file, matcher, limit, rows)
+          File.foreach(tree.path(file), chomp: true).with_index(1) do |line, number|
+            break if rows.length >= limit
+            next unless line.valid_encoding? && matcher.match?(line)
+
+            rows << "#{file}:#{number}: #{line.strip}"
+          end
+        end
+
+        # @return [Array<String>] the text files under the named paths, relative to the root, sorted
+        def files(tree, paths)
+          named = paths.split(",").flat_map { |path| listing(tree, path) }
+          named.uniq.sort.select { |file| text?(tree, file) }
+        end
+
+        # @return [Array<String>] the files at one path: itself when a file, else all below it
+        def listing(tree, path)
+          return [path.delete_prefix("./")] if File.file?(tree.path(path))
+
+          below = Dir.glob("#{path.chomp("/")}/**/*", File::FNM_DOTMATCH, base: tree.root)
+          below.select { |entry| File.file?(tree.path(entry)) && walkable?(entry) }
+               .map { |entry| entry.delete_prefix("./") }
+        end
+
+        # @return [Boolean] whether no directory on the way to `entry` is one that is skipped
+        def walkable?(entry)
+          !entry.split("/")[0...-1].intersect?(SKIPPED)
+        end
+
+        # @return [Boolean] whether the file's first block holds no null byte
+        def text?(tree, file)
+          !File.binread(tree.path(file), SNIFF_BYTES).to_s.include?("\0")
+        end
+      end
+    end
+  end
+end