hecks 3.10.0 → 3.12.0

data/lib/hecks/grammar/expression_operators.json

@@ -1902,6 +1902,378 @@
           "value": ".unset?"
         }
       }
+    },
+    {
+      "verb": "Expression::Operator.Propose",
+      "args": {
+        "symbol": {
+          "value": ".strip"
+        },
+        "category": {
+          "value": "text"
+        },
+        "precedence": {
+          "value": 7
+        },
+        "arity": {
+          "value": 1
+        },
+        "grammar": {
+          "value": "inner"
+        },
+        "strategy": {
+          "value": "suffix_match"
+        },
+        "position": {
+          "value": 23
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": ".strip"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "a.strip"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": ".strip"
+        },
+        "target": {
+          "value": "rust"
+        },
+        "form": {
+          "value": "a.strip -> a without leading and trailing whitespace"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Admit",
+      "args": {
+        "symbol": {
+          "value": ".strip"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Propose",
+      "args": {
+        "symbol": {
+          "value": ".lstrip"
+        },
+        "category": {
+          "value": "text"
+        },
+        "precedence": {
+          "value": 7
+        },
+        "arity": {
+          "value": 1
+        },
+        "grammar": {
+          "value": "inner"
+        },
+        "strategy": {
+          "value": "suffix_match"
+        },
+        "position": {
+          "value": 24
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": ".lstrip"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "a.lstrip"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": ".lstrip"
+        },
+        "target": {
+          "value": "rust"
+        },
+        "form": {
+          "value": "a.lstrip -> a without leading whitespace"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Admit",
+      "args": {
+        "symbol": {
+          "value": ".lstrip"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Propose",
+      "args": {
+        "symbol": {
+          "value": ".rstrip"
+        },
+        "category": {
+          "value": "text"
+        },
+        "precedence": {
+          "value": 7
+        },
+        "arity": {
+          "value": 1
+        },
+        "grammar": {
+          "value": "inner"
+        },
+        "strategy": {
+          "value": "suffix_match"
+        },
+        "position": {
+          "value": 25
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": ".rstrip"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "a.rstrip"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": ".rstrip"
+        },
+        "target": {
+          "value": "rust"
+        },
+        "form": {
+          "value": "a.rstrip -> a without trailing whitespace"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Admit",
+      "args": {
+        "symbol": {
+          "value": ".rstrip"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Propose",
+      "args": {
+        "symbol": {
+          "value": "-"
+        },
+        "category": {
+          "value": "arithmetic"
+        },
+        "precedence": {
+          "value": 6
+        },
+        "arity": {
+          "value": 2
+        },
+        "grammar": {
+          "value": "inner"
+        },
+        "strategy": {
+          "value": "top_level_split"
+        },
+        "position": {
+          "value": 26
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": "-"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "a - b"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": "-"
+        },
+        "target": {
+          "value": "rust"
+        },
+        "form": {
+          "value": "a - b -> checked i64 arithmetic, refusing on overflow"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Admit",
+      "args": {
+        "symbol": {
+          "value": "-"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Propose",
+      "args": {
+        "symbol": {
+          "value": "*"
+        },
+        "category": {
+          "value": "arithmetic"
+        },
+        "precedence": {
+          "value": 7
+        },
+        "arity": {
+          "value": 2
+        },
+        "grammar": {
+          "value": "inner"
+        },
+        "strategy": {
+          "value": "top_level_split"
+        },
+        "position": {
+          "value": 27
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": "*"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "a * b"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": "*"
+        },
+        "target": {
+          "value": "rust"
+        },
+        "form": {
+          "value": "a * b -> checked i64 arithmetic, refusing on overflow"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Admit",
+      "args": {
+        "symbol": {
+          "value": "*"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Propose",
+      "args": {
+        "symbol": {
+          "value": "/"
+        },
+        "category": {
+          "value": "arithmetic"
+        },
+        "precedence": {
+          "value": 7
+        },
+        "arity": {
+          "value": 2
+        },
+        "grammar": {
+          "value": "inner"
+        },
+        "strategy": {
+          "value": "top_level_split"
+        },
+        "position": {
+          "value": 28
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": "/"
+        },
+        "target": {
+          "value": "ruby"
+        },
+        "form": {
+          "value": "a / b"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Render",
+      "args": {
+        "symbol": {
+          "value": "/"
+        },
+        "target": {
+          "value": "rust"
+        },
+        "form": {
+          "value": "a / b -> floor division on integers, refusing a zero divisor and overflow"
+        }
+      }
+    },
+    {
+      "verb": "Expression::Operator.Admit",
+      "args": {
+        "symbol": {
+          "value": "/"
+        }
+      }
     }
   ]
 }

data/lib/hecks/grammar/operators.rb

@@ -96,7 +96,9 @@ module Hecks
         [[evaluator::Or, "||", %i[left right]], [evaluator::And, "&&", %i[left right]],
          [evaluator::Not, "!", %i[node]], [evaluator::Compare, ->(node) { node.operator.symbol }, %i[left right]],
          [evaluator::Include, ".include?", %i[haystack needle]], [evaluator::Resolve, nil, %i[expr]],
-         [resolver::Addition, "+", %i[left right]], [resolver::Modulo, ".modulo", %i[receiver divisor]]]
+         [resolver::Addition, "+", %i[left right]], [resolver::Subtraction, "-", %i[left right]],
+         [resolver::Multiplication, "*", %i[left right]], [resolver::Division, "/", %i[left right]],
+         [resolver::Modulo, ".modulo", %i[receiver divisor]]]
       end
 
       # @return [Array<String>] operators found in the members of a Struct node; none for any

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

@@ -11,12 +11,12 @@ module Hecks
   module Adapters
     module Codebase
       # What Codebase's `CorpusRun` asks of the working tree: which committed domains have a Rust
-      # feature, what the language's IR holds, and the two doors that serve it.
+      # feature, what the language's IR holds, and the two servers that serve it.
       #
       # The questions are pure reads and run in this process, with the code `hecks rust_domains` and
       # `hecks ir_constructs` run (`Hecks::Corpus`, `Hecks::QueryIR`); the coverage question runs
       # `Hecks::RustBuild`'s coverage tool over each generated module, also in this process. The
-      # two doors run until they are closed: the query MCP server on stdio, and the forms app on a
+      # two servers run until they are closed: the query MCP server on stdio, and the forms app on a
       # local port.
       module CorpusTasks
         # Every operation this family carries out.
@@ -26,7 +26,7 @@ module Hecks
         DEFAULT_PORT = 4567
 
         class << self
-          # @return [#call, nil] serves the MCP door; `Hecks::QueryIrMcp.start` when nil. A spec
+          # @return [#call, nil] serves the MCP server; `Hecks::QueryIrMcp.start` when nil. A spec
           #   replaces it so no stdio has to be held.
           attr_accessor :mcp_server
 
@@ -41,14 +41,14 @@ module Hecks
 
         module_function
 
-        # Opens one of the doors.
+        # Opens one of the servers.
         #
         # @param operation [String] `serve_query_ir_mcp` or `present`
         # @param held [Hash] the `CorpusRun` record's fields: `port`
         # @param tree [Tree] the working tree, already known to be a hecks checkout
         # @param shell [#capture, nil] unused
-        # @return [String] a note that the door closed
-        # @raise [ConsoleCapture::Failure] when the MCP door refuses the process's setup
+        # @return [String] a note that the server closed
+        # @raise [ConsoleCapture::Failure] when the MCP server refuses the process's setup
         def call(operation, held, tree, shell: nil)
           _ = shell
           return serve_mcp if operation == "serve_query_ir_mcp"
@@ -78,14 +78,14 @@ module Hecks
         # @return [Hash] the same fields as plain values
         def plain(held) = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
 
-        # @return [String] a note that the MCP door closed
-        # @raise [ConsoleCapture::Failure] when the door refuses to start
+        # @return [String] a note that the MCP server closed
+        # @raise [ConsoleCapture::Failure] when the server refuses to start
         def serve_mcp
           server = CorpusTasks.mcp_server || ->(**options) { QueryIrMcp.start(**options) }
           server.call(argv: [])
-          "query ir mcp door closed"
+          "query ir mcp server closed"
         rescue SystemExit => e
-          raise ConsoleCapture::Failure, "the query ir mcp door refused to start (status #{e.status}); see stderr"
+          raise ConsoleCapture::Failure, "the query ir mcp server refused to start (status #{e.status}); see stderr"
         end
 
         # @param port [Integer] the port to listen on

data/lib/hecks/hecks/adapters/codebase/inspection/rubycritic.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Runs rubycritic with its git root taken from git.
+#
+# rubycritic finds the repository root by walking up to the first `.git` directory. A linked
+# worktree has a `.git` file instead, so inside one nested in its main checkout the walk passes the
+# worktree and stops at the main checkout's directory. Churn is then read from the wrong tree and
+# comes back 0 for every file. Asking git for the top level answers right in either layout.
+#
+# Started as a program by `Inspection`: `ruby rubycritic.rb <rubycritic arguments>`. Required, it
+# installs the churn fix and runs nothing, so it loads standalone like every other lib file.
+require "rubycritic/cli/application"
+
+module Hecks
+  module Adapters
+    module Codebase
+      module Inspection
+        # Gives rubycritic's churn the root git reports for the directory it runs in.
+        module GitToplevel
+          private
+
+          # @return [String] the top level of the working tree the current directory is in
+          def find_git_root
+            root = `git rev-parse --show-toplevel`.strip
+            root.empty? ? super : root
+          end
+        end
+      end
+    end
+  end
+end
+
+RubyCritic::SourceControlSystem::Git::Churn.prepend(Hecks::Adapters::Codebase::Inspection::GitToplevel)
+
+exit RubyCritic::Cli::Application.new(ARGV).execute if File.expand_path($PROGRAM_NAME) == File.expand_path(__FILE__)

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "tree"
+require_relative "../shell"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `InspectionRun` asks of the working tree: ranking its Ruby by complexity
+      # (flog), finding copied code (flay), listing design smells (reek), and writing the combined
+      # report with git churn (rubycritic).
+      #
+      # The tools take no exclude list of their own, so the files are listed here first and the
+      # ones `.rubocop.yml` excludes (generated output, vendored code) are left out: a finding in
+      # one belongs to its generator. Each tool then runs from the checkout's root through
+      # `bundle exec`, and what it printed is the report.
+      module Inspection
+        # Every operation this family carries out, one for each tool.
+        OPERATIONS = %w[flog flay reek rubycritic].freeze
+
+        # rubycritic starts through a launcher that finds the git root right inside a worktree.
+        RUBYCRITIC = ["ruby", File.join(__dir__, "inspection", "rubycritic.rb"), "--no-browser"].freeze
+
+        # The program and flags each operation starts, before the files.
+        PROGRAMS = { "flog"       => %w[flog --methods-only],
+                     "flay"       => %w[flay],
+                     "reek"       => %w[reek],
+                     "rubycritic" => RUBYCRITIC }.freeze
+
+        # The statuses that still mean the tool reported: reek ends 2 when it found smells.
+        REPORTING = { "reek" => [0, 2] }.freeze
+
+        # Searched when no path is named.
+        DEFAULT_PATHS = "lib"
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `InspectionRun` record's fields: `paths` and `top`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] starts the tool; a `Shell` when nil
+        # @return [String] what the tool printed, cut to `top` lines when that is named
+        # @raise [ConsoleCapture::Failure] when no Ruby file is named, or the tool is missing
+        #   or fails
+        def call(operation, held, tree, shell: nil)
+          args = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          files = ruby_files(tree, args[:paths] || DEFAULT_PATHS)
+          raise ConsoleCapture::Failure, "no Ruby file under #{args[:paths] || DEFAULT_PATHS}" if files.empty?
+
+          result = (shell || Shell.new).capture("bundle", "exec", *PROGRAMS.fetch(operation), *files,
+                                                chdir: tree.root)
+          shorten(report(operation, result), args[:top])
+        end
+
+        # @param operation [String] the tool's name
+        # @param result [Shell::Result] what the tool said
+        # @return [String] its output
+        # @raise [ConsoleCapture::Failure] when it ended in a status that is not a report
+        def report(operation, result)
+          return result.out if REPORTING.fetch(operation, [0]).include?(result.status.exitstatus)
+
+          raise ConsoleCapture::Failure,
+                "#{operation} ended with status #{result.status.exitstatus}: #{result.err}#{result.out}".strip
+        end
+
+        # @param text [String] a report
+        # @param top [Integer, nil] how many lines to keep
+        # @return [String] the first `top` lines, or the whole text
+        def shorten(text, top)
+          top ? text.lines.first(top).join : text
+        end
+
+        # The Ruby files under the named paths, less those the style config excludes.
+        #
+        # @param tree [Tree] the checkout
+        # @param paths [String] comma-separated files or directories, relative to the root
+        # @return [Array<String>] the files, relative to the root and sorted
+        def ruby_files(tree, paths)
+          excluded = exclusions(tree)
+          paths.split(",").flat_map { |path| listing(tree, path) }.uniq.sort.reject do |file|
+            excluded.any? { |glob| File.fnmatch?(glob, file, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+          end
+        end
+
+        # @return [Array<String>] the files at one path: itself when a file, else every `.rb` below
+        def listing(tree, path)
+          return [path] if File.file?(tree.path(path))
+
+          Dir.glob("#{path}/**/*.rb", base: tree.root)
+        end
+
+        # @return [Array<String>] the globs `.rubocop.yml` excludes from every cop
+        def exclusions(tree)
+          config = YAML.safe_load_file(tree.path(".rubocop.yml"), permitted_classes: [Symbol])
+          Array(config.dig("AllCops", "Exclude"))
+        end
+      end
+    end
+  end
+end

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

@@ -46,7 +46,8 @@ module Hecks
           none = { value: "none" }
           { operation: { value: operation }, version: { value: "0.0.0" }, client_version: { value: "0.0.0" },
             ir_version: { value: "0.0.0" }, ships_from: { path: "none" }, branch: none, head: none, release_lane: none,
-            tag_state: none, on_origin: { value: false }, clean: { value: false }, changelog: { value: false } }
+            tag_state: none, on_origin: { value: false }, clean: { value: false }, changelog: { value: false },
+            approved: { value: false } }
         end
 
         # Carries out an accepted request.

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

@@ -3,6 +3,7 @@
 require "json"
 require "hecks/release/runner"
 require "hecks/release/lane"
+require "hecks/release/approval"
 require_relative "tree"
 require_relative "../console_capture"
 
@@ -15,8 +16,9 @@ module Hecks
       # It reads the branch, the lane a release is cut from (the `Lane` row that feeds a tag),
       # whether `HEAD` is that lane's `origin/` branch (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.
+      # the version, whether the commit that set the version carries the owner's approval trailer,
+      # 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>[^"]+)"/
@@ -54,6 +56,7 @@ module Hecks
           fetch_origin!
           head = read("rev-parse", "HEAD")
           lane_facts(head).merge(clean:     flag(read("status", "--porcelain").empty?),
+                                 approved:  flag(approved?),
                                  tag_state: word(tag_state("v#{version}", head)))
         end
 
@@ -69,6 +72,13 @@ module Hecks
             on_origin: flag(head == read("rev-parse", "origin/#{lane}")) }
         end
 
+        # Whether the newest commit on this checkout that set the version names who approved the
+        # release in its message (the trailer the `Lane` row names).
+        def approved?
+          message = read("log", "--first-parent", "-1", "--format=%B", "-G^ *VERSION = ", "--", "lib/hecks/version.rb")
+          !Release::Approval.approver(message).nil?
+        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

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

@@ -7,6 +7,7 @@ require_relative "conformance"
 require_relative "regeneration"
 require_relative "gate"
 require_relative "style"
+require_relative "inspection"
 require_relative "codemods"
 require_relative "test_suite"
 require_relative "corpus_tasks"
@@ -181,7 +182,7 @@ module Hecks
 
       # The task families, each carrying out the operations it lists.
       FAMILIES = [Codebase::Language, Codebase::KernelTables, Codebase::Conformance, Codebase::Regeneration,
-                  Codebase::Gate, Codebase::Style, Codebase::Codemods, Codebase::TestSuite,
+                  Codebase::Gate, Codebase::Style, Codebase::Inspection, Codebase::Codemods, Codebase::TestSuite,
                   Codebase::CorpusTasks, Codebase::Publishing, Codebase::Promotion].freeze
       private_constant :FAMILIES
 

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

@@ -55,7 +55,7 @@ module Hecks
           return self.class.runner if self.class.runner
 
           require "rspec/core"
-          # A process that runs one example after another, as a resident door does, has to reset
+          # A process that runs one example after another, as a resident server does, has to reset
           # RSpec between runs: its reporter keeps the first run's output stream, so a later run
           # would write into that and answer an empty report.
           lambda do |args, err, out|