hecks 2.8.0 → 3.0.0

data/lib/hecks/grammar/evolve.rb

@@ -0,0 +1,336 @@
+module Hecks
+  module Grammar
+    # File surgery under `hecks word_status` and its siblings: reads and rewrites the
+    # aggregate-local KeywordSeed/ArgumentSeed rows as text, preserving the table's own formatting.
+    module Evolve
+      class Refusal < StandardError; end
+
+      module_function
+
+      # Only consumes the next argv element as the value when it isn't itself
+      # a flag, so `--foo --bar` doesn't swallow `--bar` as `--foo`'s value.
+      def option(argv, name, default = nil)
+        index = argv.index("--#{name}")
+        return default unless index
+
+        value = argv[index + 1]
+        value.nil? || value.start_with?("-") ? default : value
+      end
+
+      # Runs the block against an in-memory copy of the tables: every edit it makes is held, none
+      # is written, and later reads see the earlier edits.
+      #
+      # @yield the edits to rehearse
+      # @return [Hash{String => String}] each file the edits changed, with the text it would hold
+      def rehearse
+        @overlay = {}
+        yield
+        @overlay.dup
+      ensure
+        @overlay = nil
+      end
+
+      # @param path [String] a table file
+      # @return [String] its text: a rehearsed edit if one was made, else what the file holds
+      def read_source(path)
+        @overlay&.key?(path) ? @overlay[path] : File.read(path)
+      end
+
+      # @param path [String] a table file
+      # @param text [String] what it holds afterwards; held, not written, while rehearsing
+      # @return [Object] the text
+      def write_source(path, text)
+        @overlay ? (@overlay[path] = text) : File.write(path, text)
+      end
+
+      # Snapshots `paths` before running the block and restores every file
+      # if it raises, even partway through a multi-file write.
+      def restore_on_raise(paths)
+        snapshots = paths.to_h { |path| [path, File.read(path)] }
+        yield
+      rescue StandardError
+        snapshots.each { |path, content| File.write(path, content) }
+        raise
+      end
+
+      # Every syntax-table file declaring a KeywordSeed or ArgumentSeed value object.
+      def syntax_paths
+        Dir.glob(File.expand_path("../language/**/*.bluebook", __dir__)).select do |path|
+          source = read_source(path)
+          source.include?('value_object "KeywordSeed"') || source.include?('value_object "ArgumentSeed"')
+        end
+      end
+
+      # Narrow compatibility door for single-file callers; syntax_paths is normal.
+      def syntax_path = syntax_paths.first
+
+      # Resolves the file(s) a call should search or write.
+      def paths_for(path) = path ? Array(path) : syntax_paths
+
+      # Parses the Keyword one_of's member rows leniently off the text.
+      def keyword_rows(path = nil)
+        paths_for(path).flat_map do |candidate|
+          blocks = seed_blocks(read_source(candidate), "KeywordSeed")
+          raise Refusal, "source declares no KeywordSeed value object" if path && blocks.empty?
+
+          blocks.flat_map do |block|
+            block.scan(/^\s*member (.+)$/).map do |(cells)|
+              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
+              { word: row["word"], context: row["context"],
+                status: row.fetch("status", "admitted"), was: row["was"] }
+            end
+          end
+        end
+      end
+
+      # Declares a new, proposed keyword row in the syntax table that owns
+      # `context` (or the aggregate `opens` names, for a File-context word).
+      def propose(word:, context:, body: "none", inner: "", opens: "", fills: "", path: nil)
+        if keyword_rows(path).any? do |row|
+          row[:word] == word && row[:context] == context
+        end
+          raise Refusal,
+                "#{context}.#{word} is already declared — one row per (word, context, form)"
+        end
+
+        path = owner_path(context: context, word: word, opens: opens, paths: paths_for(path))
+        source = read_source(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.include?(%(context: "#{context}")) } || keyword_block(source)
+        indent = block[/^(\s*)member /, 1] || "        "
+        row = %(#{indent}member word: "#{word}", context: "#{context}", body: "#{body}", ) +
+              %(inner: "#{inner}", opens: "#{opens}", fills: "#{fills}", status: "proposed"\n)
+
+        # Appended at the end; whoever admits it may move it to its group.
+        closing = block.rindex(/^\s*end\s*$/)
+        updated = block[0...closing] + row + block[closing..]
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Rewrites a declared keyword row's status: cell in place.
+      def set_status(word:, context:, to:, path: nil)
+        raise Refusal, "#{to.inspect} is not a station a word's life admits" unless %w[proposed admitted deprecated
+                                                                                       retired].include?(to)
+
+        path = path_holding_keyword(word, context, paths_for(path))
+        source = read_source(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
+        rows   = block.lines.select { |line| member_row?(line, word, context) }
+        raise Refusal, "#{context}.#{word} is not declared" if rows.empty?
+
+        updated = block.lines.map do |line|
+          next line unless member_row?(line, word, context)
+
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          # Admitted is the default and stays unspelled in the row.
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        end.join
+
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Respells a keyword row (was: holds the old spelling) — one hop only;
+      # its Argument rows follow, row-aware (see cascade_argument_rename).
+      def rename(word:, context:, to:, path: nil)
+        row = keyword_rows(path).find { |r| r[:word] == word && r[:context] == context }
+        raise Refusal, "#{context}.#{word} is not declared" unless row
+        raise Refusal, "#{context}.#{word} was already #{row[:was]} — one rename hop, then eras" if row[:was]
+        if keyword_rows(path).any? do |r|
+          r[:word] == to && r[:context] == context
+        end
+          raise Refusal,
+                "#{context}.#{to} is already declared — a rename cannot land on a living word"
+        end
+
+        paths = paths_for(path)
+        path = path_holding_keyword(word, context, paths)
+        source = read_source(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
+        updated = block.lines.map do |line|
+          next line unless member_row?(line, word, context)
+
+          line.sub(%(word: "#{word}"), %(word: "#{to}"))
+              .sub(/\n\z/, %(, was: "#{word}"\n))
+        end.join
+        source = source.sub(block, updated)
+        write_source(path, source)
+
+        cascade_argument_rename(keyword: word, context: context, to: to, path: paths)
+      end
+
+      # Tells whether `line` is a KeywordSeed member row for (word, context).
+      def member_row?(line, word, context)
+        line =~ /^\s*member / && line.include?(%(word: "#{word}")) && line.include?(%(context: "#{context}"))
+      end
+
+      # Finds which syntax-table path declares a keyword row.
+      def path_holding_keyword(word, context, paths = syntax_paths)
+        paths.find do |candidate|
+          keyword_blocks(read_source(candidate)).any? { |block| block.lines.any? { |line| member_row?(line, word, context) } }
+        end || raise(Refusal, "#{context}.#{word} is not declared")
+      end
+
+      # Finds which syntax-table path declares an argument row.
+      def path_holding_argument(keyword, context, at, named, paths = syntax_paths)
+        paths.find do |candidate|
+          argument_blocks(read_source(candidate)).any? do |block|
+            block.lines.any? do |line|
+              argument_row?(line, keyword, context, at, named)
+            end
+          end
+        end || raise(Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not declared")
+      end
+
+      # Picks the owning file for a new row; opens names the aggregate for a File-context word.
+      def owner_path(context:, word:, opens: "", paths: syntax_paths)
+        if context == "File" && !opens.to_s.empty?
+          aggregate_path = paths.find { |candidate| read_source(candidate).match?(/^\s*aggregate "#{Regexp.escape(opens)}" do$/) }
+          return aggregate_path if aggregate_path
+        end
+
+        paths.find do |candidate|
+          source = read_source(candidate)
+          %w[KeywordSeed ArgumentSeed].any? do |seed|
+            seed_blocks(source, seed).any? { |block| block.include?(%(context: "#{context}")) }
+          end
+        end || raise(Refusal, "no aggregate-local syntax table owns context #{context.inspect} for #{word}")
+      end
+
+      # Every value_object "<name>" block's full source text, opener to closing end.
+      def seed_blocks(source, name)
+        opener = /^([ \t]*)value_object "#{Regexp.escape(name)}" do$/
+        source.to_enum(:scan, opener).map do
+          match = Regexp.last_match
+          start = match.begin(0)
+          indent = match[1]
+          closing = source.index(/^#{Regexp.escape(indent)}end\s*$/, match.end(0))
+          closing = source.index(/\n/, closing) + 1
+          source[start...closing]
+        end
+      end
+
+      # The first value_object "<name>" block's source text.
+      def seed_block(source, name, required: false)
+        block = seed_blocks(source, name).first
+        unless block
+          raise Refusal, "source declares no #{name} value object" if required
+
+          return
+        end
+        block
+      end
+
+      # First `end` after the opener is the block's own — member rows sit bare (ADR 0025).
+      def keyword_blocks(source) = seed_blocks(source, "KeywordSeed")
+
+      # The first KeywordSeed block's source text.
+      def keyword_block(source) = seed_block(source, "KeywordSeed", required: true)
+
+      # Parses the ArgumentSeed's member rows leniently off the text.
+      def argument_rows(path = nil)
+        paths_for(path).flat_map do |candidate|
+          blocks = seed_blocks(read_source(candidate), "ArgumentSeed")
+          raise Refusal, "source declares no ArgumentSeed value object" if path && blocks.empty?
+
+          blocks.flat_map do |block|
+            block.scan(/^\s*member (.+)$/).map do |(cells)|
+              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
+              { keyword: row["keyword"], context: row["context"], at: row["at"].to_s,
+                named: row["named"].to_s, kind: row["kind"], required: row["required"],
+                fills: row["fills"].to_s, status: row.fetch("status", "admitted") }
+            end
+          end
+        end
+      end
+
+      # Declares a new, proposed argument row; pairs_shape marks a `pairs`
+      # argument that fills a whole key/value list, not a single field.
+      def propose_argument(keyword:, context:, kind:, required: "false", at: "", named: "", fills: "",
+                           pairs_shape: nil, path: nil)
+        if argument_rows(path).any? { |r| argument_identity(r) == [keyword, context, at, named] }
+          raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is " \
+                         "already declared — one row per (keyword, context, at, named)"
+        end
+
+        path = owner_path(context: context, word: keyword, paths: paths_for(path))
+        source = read_source(path)
+        block  = argument_blocks(source).find do |candidate|
+          candidate.include?(%(context: "#{context}"))
+        end || argument_block(source)
+        indent = block[/^(\s*)member /, 1] || "        "
+        shape = pairs_shape.to_s.empty? ? "" : %(pairs_shape: "#{pairs_shape}", )
+        row = %(#{indent}member keyword: "#{keyword}", context: "#{context}", at: "#{at}", ) +
+              %(named: "#{named}", kind: "#{kind}", required: "#{required}", fills: "#{fills}", ) +
+              shape + %(status: "proposed"\n)
+
+        closing = block.rindex(/^\s*end\s*$/)
+        updated = block[0...closing] + row + block[closing..]
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Rewrites a declared argument row's status: cell in place.
+      def set_argument_status(keyword:, context:, to:, at: "", named: "", path: nil)
+        raise Refusal, "#{to.inspect} is not a station an argument's life admits" unless %w[proposed admitted deprecated
+                                                                                            retired].include?(to)
+
+        path = path_holding_argument(keyword, context, at, named, paths_for(path))
+        source = read_source(path)
+        block  = argument_blocks(source).find do |candidate|
+          candidate.lines.any? do |line|
+            argument_row?(line, keyword, context, at, named)
+          end
+        end
+        rows = block.lines.select { |line| argument_row?(line, keyword, context, at, named) }
+        if rows.empty?
+          raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not " \
+                         "declared"
+        end
+
+        updated = block.lines.map do |line|
+          next line unless argument_row?(line, keyword, context, at, named)
+
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        end.join
+
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Tells whether `line` is an ArgumentSeed row for this (keyword, context, at, named) tuple.
+      def argument_row?(line, keyword, context, at, named)
+        line =~ /^\s*member / &&
+          line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}")) &&
+          line.include?(%(at: "#{at}")) && line.include?(%(named: "#{named}"))
+      end
+
+      # The (keyword, context, at, named) identity tuple an argument row is keyed
+      # by — wider than a Keyword row's two-field key.
+      def argument_identity(row) = [row[:keyword], row[:context], row[:at], row[:named]]
+
+      # Row-aware rename cascade — updates only the argument rows that belong
+      # to the renamed keyword, not a blind gsub across the file.
+      def cascade_argument_rename(keyword:, context:, to:, path: nil)
+        paths_for(path).each do |candidate|
+          source = read_source(candidate)
+          original = source
+          argument_blocks(source).each do |block|
+            updated = block.lines.map do |line|
+              next line unless line =~ /^\s*member / &&
+                               line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}"))
+
+              line.sub(%(keyword: "#{keyword}"), %(keyword: "#{to}"))
+            end.join
+            source = source.sub(block, updated) if updated != block
+          end
+          write_source(candidate, source) if source != original
+        end
+      end
+
+      # ArgumentSeed blocks; see keyword_blocks for why the first bare end
+      # after the opener is already the block's own.
+      def argument_blocks(source) = seed_blocks(source, "ArgumentSeed")
+
+      # The first ArgumentSeed block's source text.
+      def argument_block(source) = seed_block(source, "ArgumentSeed", required: true)
+    end
+  end
+end

data/lib/hecks/grammar/expression.bluebook

@@ -6,21 +6,9 @@ Hecks.bluebook "Expression" do
   aggregate "Operator" do
     description "One admitted operation — its symbol, its precedence, and how it reads in every target that must evaluate it."
 
-    # WHAT IS NOT HERE, on purpose. The outer grammar
-    # has two rules that are not operators: parenthesization (a structural
-    # strip-and-recurse, no symbol of its own) and the bare-leaf fallback
-    # (whatever matches nothing else falls through to the inner grammar).
-    # Its inner grammar has three more: integer/float/string/bool/nil/
-    # array literals and the dotted-lookup fallback are TERMINAL
-    # productions — they recognize text, they do not combine operands,
-    # and they have nothing meaningful to render per target (a literal's
-    # spelling does not differ between targets the way an operation's
-    # might — `rust/src/kernel/expr.rs`'s own `Expr::Array` is a LEAF
-    # there too, for the identical reason, not routed through
-    # `OperatorCategory`).
-    # Forcing them into this shape would stretch `renderings` and the
-    # Arity invariant past what they mean. They stay declared only in
-    # prose — named here rather than silently left out.
+    # Not operators, so not declared here: parenthesization, the bare-leaf fallback,
+    # and the terminal literals and dotted lookup. They recognize text rather than
+    # combine operands, and a literal reads the same in every target.
     identified_by :symbol
 
     attribute :symbol,     OperatorSymbol
@@ -54,47 +42,34 @@ Hecks.bluebook "Expression" do
 
     value_object "Arity" do
       attribute :value, Integer
-      # WRITTEN ACROSS LINES ON PURPOSE, and this is the only predicate in the
-      # corpus that is. A CONTINUATION line is where extraction used to break:
-      # a naive line join reads `value > 0 && && value <= 3` — a different
-      # canonical form for the same source, waiting for the first multi-line
-      # rule anyone wrote. Every predicate here was kept on one line to dodge
-      # that. The join is continuation-aware now, so this case holds the fix:
-      # if it regresses, the canonical text of THIS invariant changes and the
-      # golden IR goes red.
+      # Written across lines on purpose: it pins continuation-aware line joining in
+      # extraction. If that regresses, this invariant's canonical text changes and
+      # the golden IR goes red.
       invariant("an operator takes one, two or three operands") do
         value > 0 &&
           value <= 3
       end
     end
 
-    # OUTER checks a leaf against `.include?`/comparators/`!` before falling
-    # through to INNER's arithmetic/dotted-lookup grammar — two stacked
-    # grammars. Which one an operator belongs
-    # to is not derivable from its symbol alone (`+` reads like it could be
-    # either), so it is its own column rather than inferred.
+    # The outer grammar checks `.include?`, comparators and `!` before falling through
+    # to the inner arithmetic and dotted-lookup grammar. The symbol alone does not say
+    # which one an operator belongs to, so it is its own column.
     value_object "Grammar" do
       attribute :value, String
       invariant("an operator belongs to one of the two stacked grammars") { !value.to_s.empty? }
     end
 
-    # HOW the check recognizes this operator's text, not WHERE it binds
-    # (that's precedence) or WHEN it's tried (that's position). Four shapes
-    # cover every admitted operator: split at a top-level occurrence
-    # (`||`, comparators), strip a leading marker (`!`), strip a trailing
-    # suffix (`.empty?`), or match a call-with-argument pattern
-    # (`.include?(needle)`).
+    # How the check recognizes an operator's text: split at a top-level occurrence
+    # (`||`), strip a leading marker (`!`) or trailing suffix (`.empty?`), or match a
+    # call pattern (`.include?(needle)`).
     value_object "Strategy" do
       attribute :value, String
       invariant("an operator names how its check recognizes it") { !value.to_s.empty? }
     end
 
-    # THE WITHIN-GRAMMAR CHECK ORDER — what precedence alone cannot say,
-    # since the six comparators all share one precedence tier and something
-    # still has to break the tie (grammar.md: `>=` before `<=` before `<`
-    # before `>` before `==` before `!=`, so `<` splitting does not fire
-    # inside `>=`). Scoped per `grammar`, mirroring Normalisation's own
-    # Position column below — each grammar starts its own count at 1.
+    # The check order within a grammar, counted from 1 per grammar. It breaks the tie
+    # precedence cannot: the six comparators share a tier, and `>=` must be tried
+    # before `>` so a split on `>` does not fire inside `>=`.
     value_object "Position" do
       attribute :value, Integer
       invariant("an operator sits somewhere in its grammar's check order") { value > 0 }

data/lib/hecks/grammar/translation.bluebook

@@ -18,12 +18,9 @@ Hecks.bluebook "Translation" do
       transition "Retire" => "retired",  from: "admitted"
     end
 
-    # THE CLOSED SET OF RULE KINDS — declared as members, not a hand-rolled
-    # OR-chain, so the set is data a conformance spec can hold the live
-    # builder to (spec/translation_vocabulary_conformance_spec.rb). Nine of
-    # these are TranslationAggregateBuilder's own rule methods ; "retired" is
-    # the edge-level declaration (TranslationBuilder#retired), in the set
-    # because it is one admitted way a shape survives — by not surviving.
+    # The closed set of rule kinds, kept as data so a conformance spec can hold the
+    # builder to it. All but "retired" are TranslationAggregateBuilder rule methods;
+    # "retired" is the edge-level declaration (TranslationBuilder#retired).
     value_object "Kind" do
       attribute :value, String,
                 one_of: ["rename", "move", "convert", "drop", "retype", "retired", "compute", "rekey",

data/lib/hecks/grammar.rb

@@ -1,32 +1,23 @@
 require "json"
 
-# The whole framework, deliberately: booting a grammar chapter exercises
-# the DSL, the meta-validator, and the runtime — and nothing the entry
-# point loads ever requires this file back, so the require is acyclic.
+# Loads the whole framework on purpose; nothing the entry point loads
+# requires this file back, so the require is acyclic.
 require_relative "../hecks"
 
 module Hecks
-  # The sublanguage grammar domains (grammar/*.bluebook) and the one boot
-  # path for reading them as data — the expression chapter replayed
-  # through its own admission ledger, so anything derived from it (the
-  # operator projections, the conformance specs) reads the set that
-  # actually survived the Admit gates, never a hand-copied list.
+  # The sublanguage grammar domains (grammar/*.bluebook) and the one boot path
+  # for reading them as data, replayed through the expression admission ledger.
   #
-  # Booted on call, never at require: the Prism adapter normalises every
-  # predicate through CanonicalForm while a bluebook loads, so the
-  # expression machinery cannot boot the chapter that configures it —
-  # this module exists precisely so generators and specs boot it in a
-  # scratch registry instead.
+  # Booted on call, never at require: the Prism adapter normalises predicates
+  # while a bluebook loads, so the expression machinery cannot boot its own chapter.
   module Grammar
     DIR    = File.expand_path("grammar", __dir__)
     LEDGER = File.join(DIR, "expression_operators.json")
 
     module_function
 
-    # Boot the expression chapter and replay the admission ledger through
-    # its real commands. A refused step raises — a generator running off
-    # a half-admitted ledger would project a table the gates never
-    # accepted.
+    # Boots the expression chapter and replays the admission ledger through
+    # its real commands; a refused step raises.
     #
     # @return [Runtime::Dispatcher] the dispatcher bound to the booted, replayed
     #   expression chapter
@@ -104,16 +95,9 @@ module Hecks
       registry.repository("Expression", aggregate).all
     end
 
-    # The operators the language stands on. Every guard and invariant in
-    # the language's own chapters — the meta-domain (Bluebook, World) and
-    # the grammar chapters beside this file — evaluates through the very
-    # operator table the ledger admits. An operator one of those
-    # predicates uses is self-bearing: retire it and the language can no
-    # longer read its own rules — found the hard way, as a projection
-    # missing `!=` that could not boot the chapter to fix itself. This
-    # derives the set, with a usage site per operator, so the generator
-    # and the conformance spec can refuse the retirement by name instead
-    # of wedging.
+    # The operators the language's own guards and invariants (Bluebook, World and
+    # the grammar chapters) evaluate through. Retiring one would leave the
+    # language unable to read its own rules, so callers refuse it by name.
     #
     # @return [Hash{String => Array<String>}] each self-bearing operator symbol
     #   mapped to the `"Chapter Aggregate.command"`/`"Chapter Aggregate::ValueObject"`
@@ -147,8 +131,7 @@ module Hecks
       sites.transform_values(&:uniq)
     end
 
-    # Every grammar/*.bluebook chapter, booted the same way the corpus
-    # boots them — each alone, in a scratch registry.
+    # Every grammar/*.bluebook chapter, each booted alone in a scratch registry.
     #
     # @return [Array<Class>] each grammar chapter, booted alone in its own scratch
     #   registry
@@ -167,9 +150,8 @@ module Hecks
       end
     end
 
-    # Which admitted operators one canonical text evaluates through —
-    # the evaluator's own parse, walked for its operator nodes, leaves
-    # walked for the resolver's arithmetic.
+    # Which admitted operators one canonical text evaluates through, found by
+    # walking the evaluator's own parse.
     #
     # @param canonical [String] canonical expression text to parse
     # @return [Array<String>] operator symbols the expression evaluates through, or
@@ -184,15 +166,8 @@ module Hecks
       walk_operators(node, evaluator).uniq
     end
 
-    # A recursive descent over a closed, declared set of AST node types
-    # (Evaluator's boolean/compare/include nodes, Resolver's arithmetic
-    # nodes, and the generic Struct fallback) — each branch does the
-    # same one thing (name the node's own operator, recurse into its
-    # children) and the branches don't interact, but the ABC score adds
-    # every branch's cost together. Splitting the case out per node type
-    # would trade one place that shows the whole operator vocabulary for
-    # several that each show a fragment, with no reduction in real
-    # complexity.
+    # One case over the closed set of AST node types, kept together so the whole
+    # operator vocabulary reads in one place.
     # @param node [Object] an evaluator/resolver AST node, or a Struct fallback
     # @param evaluator [Module] `Bluebook::Expression::Evaluator`, passed through
     #   so nested calls don't re-resolve the constant

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "ruby_child"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `CodemodRun` asks of the working tree: the mechanical rewrites of the
+      # example bluebooks.
+      #
+      # Each codemod is a script built on `Hecks::Codemod` (`lib/hecks/codemod.rb`), which reboots
+      # every bluebook it edits and puts the file back when the rewrite changes what the bluebook
+      # means. The script runs in a child process from the checkout's root. Unconfirmed it runs
+      # with `--dry-run`, which restores every file it touched, so tracked files stay changed only
+      # when the request is confirmed.
+      module Codemods
+        # Every operation this family carries out.
+        OPERATIONS = %w[hoist_local_givens drop_implicit_append_fields].freeze
+
+        # The script each operation runs.
+        SCRIPTS = { "hoist_local_givens"          => "codemod_hoist_local_givens",
+                    "drop_implicit_append_fields" => "codemod_implicit_append_fields" }.freeze
+
+        module_function
+
+        # Carries out one codemod.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `CodemodRun` record's fields: `confirm`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused: the codemod runs in this process
+        # @return [String] what the script found for each example, and whether it rewrote it
+        # @raise [ConsoleCapture::Failure] when the script ends badly
+        def call(operation, held, tree, shell: nil)
+          confirm = held[:confirm].is_a?(Hash) ? held[:confirm][:value] : held[:confirm]
+          child = RubyChild.new(tree)
+          return child.answer(SCRIPTS.fetch(operation)) if confirm == true
+
+          "dry run, nothing kept (add --confirm to rewrite):\n#{child.answer(SCRIPTS.fetch(operation), '--dry-run')}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "ruby_child"
+require "hecks/engine_agreement"
+require "hecks/doc/reference"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `ConformanceRun` asks of the working tree: the checks on the language
+      # itself.
+      #
+      # The query-engine check and the reference-docs check read the tree in this process, with the
+      # code the verbs run elsewhere, and write nothing. The argument-gate matrix boots several
+      # throwaway domains and replays them, so it runs in a child process; without `confirm` the
+      # script only reports, and with it the script rewrites the committed matrix and its fixtures.
+      module Conformance
+        # Every operation this family carries out.
+        OPERATIONS = %w[check_engine_agreement measure_doc_coverage argument_gate_matrix].freeze
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `ConformanceRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] what the check found
+        # @raise [ConsoleCapture::Failure] when the check finds a disagreement
+        def call(operation, held, tree, shell: nil)
+          case operation
+          when "check_engine_agreement" then engine_agreement(tree)
+          when "measure_doc_coverage" then doc_coverage(tree)
+          else gate_matrix(held, tree)
+          end
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] the clean verdict
+        # @raise [ConsoleCapture::Failure] with every problem, when the engines disagree
+        def engine_agreement(tree)
+          finding = EngineAgreement.check(root: tree.root)
+          return EngineAgreement.clean_line(finding) if finding.problems.empty?
+
+          raise ConsoleCapture::Failure, EngineAgreement.problem_lines(finding)
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] the clean verdict
+        # @raise [ConsoleCapture::Failure] with each word that lacks prose or an example
+        def doc_coverage(tree)
+          clean, report = Doc::Reference.coverage_report(tree.path("docs/implemented/reference"))
+          raise ConsoleCapture::Failure, report unless clean
+
+          report
+        end
+
+        # @param held [Hash] the record's fields; `confirm` makes the script write
+        # @param tree [Tree] the checkout
+        # @return [String] what the script printed: the rows kept and dropped, and what it wrote
+        # @raise [ConsoleCapture::Failure] when the script ends badly
+        def gate_matrix(held, tree)
+          confirm = held[:confirm].is_a?(Hash) ? held[:confirm][:value] : held[:confirm]
+          child = RubyChild.new(tree)
+          child.answer("argument_gate_matrix", *("--write" if confirm == true))
+        end
+      end
+    end
+  end
+end