hecks 3.5.0 → 3.6.0

data/lib/hecks/grammar/evolve/arguments.rb

@@ -0,0 +1,90 @@
+module Hecks
+  module Grammar
+    module Evolve
+      # The edits to ArgumentSeed rows: declare an argument, move it through its stations, and
+      # follow a keyword's respelling. Extended onto `Hecks::Grammar::Evolve`.
+      module Arguments
+        # What `propose_argument` fills in for the cells a caller leaves out.
+        ARGUMENT_DEFAULTS = { required: "false", at: "", named: "", fills: "", pairs_shape: nil }.freeze
+
+        # Declares a new, proposed argument row; pairs_shape marks a `pairs`
+        # argument that fills a whole key/value list, not a single field.
+        #
+        # @param keyword [String] the keyword the argument belongs to
+        # @param context [String] the context the keyword is written in
+        # @param kind [String] the argument's kind
+        # @param fields [Hash] optionally `required:`, `at:`, `named:`, `fills:` and `pairs_shape:`
+        #   cells, and `path:` naming the file(s) to edit
+        # @raise [Refusal] when the row is already declared, or no table owns the context
+        # @raise [ArgumentError] for any other keyword
+        def propose_argument(keyword:, context:, kind:, **fields)
+          check_fields!(fields, ARGUMENT_DEFAULTS.keys + [:path])
+          cells = ARGUMENT_DEFAULTS.merge(fields.except(:path))
+          refuse_declared_argument!(keyword, context, cells, fields[:path])
+          path = owner_path(context: context, word: keyword, paths: paths_for(fields[:path]))
+          append_member(path, context, "ArgumentSeed") { |indent| argument_member(indent, keyword, context, kind, cells) }
+        end
+
+        # @raise [Refusal] when a row with this identity already exists
+        def refuse_declared_argument!(keyword, context, cells, path)
+          identity = [keyword, context, cells[:at], cells[:named]]
+          return unless argument_rows(path).any? { |r| argument_identity(r) == identity }
+
+          raise Refusal, "#{describe_argument(keyword, context, cells[:at], cells[:named])} is " \
+                         "already declared — one row per (keyword, context, at, named)"
+        end
+
+        # @return [String] the new member row, spelled with `indent`
+        def argument_member(indent, keyword, context, kind, cells)
+          shape = cells[:pairs_shape].to_s.empty? ? "" : %(pairs_shape: "#{cells[:pairs_shape]}", )
+          [%(#{indent}member keyword: "#{keyword}", context: "#{context}", at: "#{cells[:at]}", ),
+           %(named: "#{cells[:named]}", kind: "#{kind}", required: "#{cells[:required]}", ),
+           %(fills: "#{cells[:fills]}", #{shape}status: "proposed"\n)].join
+        end
+
+        # @return [String] how a refusal names the argument row
+        def describe_argument(keyword, context, at, named)
+          "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect}"
+        end
+
+        # Rewrites a declared argument row's status: cell in place.
+        #
+        # @param where [Hash] optionally `at:` and `named:` (default `""`), and `path:`
+        def set_argument_status(keyword:, context:, to:, **where)
+          raise Refusal, "#{to.inspect} is not a station an argument's life admits" unless STATIONS.include?(to)
+
+          at = where.fetch(:at, "")
+          named = where.fetch(:named, "")
+          path = path_holding_argument(keyword, context, at, named, paths_for(where[:path]))
+          rewrite_member_rows(path, "ArgumentSeed", ->(line) { argument_row?(line, keyword, context, at, named) },
+                              "#{describe_argument(keyword, context, at, named)} is not declared") do |line|
+            restatus(line, to)
+          end
+        end
+
+        # 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|
+            original = read_source(candidate)
+            source = argument_blocks(original).reduce(original) do |text, block|
+              respell_argument_keyword(text, block, keyword, context, to)
+            end
+            write_source(candidate, source) if source != original
+          end
+        end
+
+        # @return [String] `text`, with the rows of `block` that belong to `keyword` respelled
+        def respell_argument_keyword(text, block, keyword, context, to)
+          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
+          updated == block ? text : text.sub(block, updated)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/grammar/evolve/keywords.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Grammar
+    module Evolve
+      # The edits to KeywordSeed rows: declare a word, move it through its stations, respell it.
+      # Extended onto `Hecks::Grammar::Evolve`.
+      module Keywords
+        # What `propose` fills in for the cells a caller leaves out.
+        KEYWORD_DEFAULTS = { body: "none", inner: "", opens: "", fills: "" }.freeze
+
+        # Declares a new, proposed keyword row in the syntax table that owns
+        # `context` (or the aggregate `opens` names, for a File-context word).
+        #
+        # @param word [String] the keyword
+        # @param context [String] the context the keyword is written in
+        # @param fields [Hash] optionally `body:`, `inner:`, `opens:` and `fills:` cells, and
+        #   `path:` naming the file(s) to edit
+        # @raise [Refusal] when the row is already declared, or no table owns the context
+        # @raise [ArgumentError] for any other keyword
+        def propose(word:, context:, **fields)
+          check_fields!(fields, KEYWORD_DEFAULTS.keys + [:path])
+          cells = KEYWORD_DEFAULTS.merge(fields.except(:path))
+          refuse_declared_keyword!(word, context, fields[:path])
+          path = owner_path(context: context, word: word, opens: cells[:opens], paths: paths_for(fields[:path]))
+          append_member(path, context, "KeywordSeed") { |indent| keyword_member(indent, word, context, cells) }
+        end
+
+        # @raise [Refusal] when a row for this word and context already exists
+        def refuse_declared_keyword!(word, context, path)
+          return unless keyword_rows(path).any? { |row| row[:word] == word && row[:context] == context }
+
+          raise Refusal, "#{context}.#{word} is already declared — one row per (word, context, form)"
+        end
+
+        # @return [String] the new member row, spelled with `indent`
+        def keyword_member(indent, word, context, cells)
+          %(#{indent}member word: "#{word}", context: "#{context}", body: "#{cells[:body]}", ) +
+            %(inner: "#{cells[:inner]}", opens: "#{cells[:opens]}", fills: "#{cells[:fills]}", status: "proposed"\n)
+        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 STATIONS.include?(to)
+
+          rewrite_member_rows(path_holding_keyword(word, context, paths_for(path)), "KeywordSeed",
+                              ->(line) { member_row?(line, word, context) },
+                              "#{context}.#{word} is not declared") { |line| restatus(line, to) }
+        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)
+          refuse_rename!(word, context, to, path)
+          paths = paths_for(path)
+          rewrite_member_rows(path_holding_keyword(word, context, paths), "KeywordSeed",
+                              ->(line) { member_row?(line, word, context) },
+                              "#{context}.#{word} is not declared") do |line|
+            line.sub(%(word: "#{word}"), %(word: "#{to}")).sub(/\n\z/, %(, was: "#{word}"\n))
+          end
+          cascade_argument_rename(keyword: word, context: context, to: to, path: paths)
+        end
+
+        # @raise [Refusal] unless the word is declared, not already respelled, and the new
+        #   spelling is free in its context
+        def refuse_rename!(word, context, to, path)
+          rows = keyword_rows(path)
+          row = rows.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]
+
+          refuse_living_word!(rows, context, to)
+        end
+
+        def refuse_living_word!(rows, context, to)
+          return unless rows.any? { |r| r[:word] == to && r[:context] == context }
+
+          raise Refusal, "#{context}.#{to} is already declared — a rename cannot land on a living word"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/grammar/evolve/seeds.rb

@@ -0,0 +1,172 @@
+module Hecks
+  module Grammar
+    module Evolve
+      # Reading the KeywordSeed and ArgumentSeed value-object blocks out of the syntax tables as
+      # text, and the row edits both kinds of row share. Extended onto `Hecks::Grammar::Evolve`.
+      module Seeds
+        # One `name: "value"` cell of a member row; the value may hold escaped quotes.
+        CELL = /(\w+): "((?:[^"\\]|\\.)*)"/
+
+        # Parses the Keyword one_of's member rows leniently off the text.
+        def keyword_rows(path = nil)
+          seed_rows(path, "KeywordSeed") do |row|
+            { word: row["word"], context: row["context"],
+              status: row.fetch("status", "admitted"), was: row["was"] }
+          end
+        end
+
+        # Parses the ArgumentSeed's member rows leniently off the text.
+        def argument_rows(path = nil)
+          seed_rows(path, "ArgumentSeed") do |row|
+            { 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
+
+        # @param path [String, Array<String>, nil] the files to read; nil reads every syntax table
+        # @param name [String] the seed value object, `"KeywordSeed"` or `"ArgumentSeed"`
+        # @yieldparam cells [Hash{String => String}] one member row's cells
+        # @return [Array<Hash>] what the block makes of each member row
+        # @raise [Refusal] when files were named and one declares no such value object
+        def seed_rows(path, name)
+          paths_for(path).flat_map do |candidate|
+            blocks = seed_blocks(read_source(candidate), name)
+            raise Refusal, "source declares no #{name} value object" if path && blocks.empty?
+
+            blocks.flat_map { |block| block.scan(/^\s*member (.+)$/).map { |(cells)| yield cells.scan(CELL).to_h } }
+          end
+        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
+
+        # 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]]
+
+        # 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? do |block|
+              block.lines.any? { |line| member_row?(line, word, context) }
+            end
+          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? { |line| argument_row?(line, keyword, context, at, named) }
+            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)
+          opening_path(context, opens, paths) || paths.find { |candidate| declares_context?(candidate, context) } ||
+            raise(Refusal, "no aggregate-local syntax table owns context #{context.inspect} for #{word}")
+        end
+
+        # @return [String, nil] the file declaring the aggregate a File-context word opens
+        def opening_path(context, opens, paths)
+          return unless context == "File" && !opens.to_s.empty?
+
+          paths.find { |candidate| read_source(candidate).match?(/^\s*aggregate "#{Regexp.escape(opens)}" do$/) }
+        end
+
+        def declares_context?(candidate, context)
+          source = read_source(candidate)
+          %w[KeywordSeed ArgumentSeed].any? do |seed|
+            seed_blocks(source, seed).any? { |block| block.include?(%(context: "#{context}")) }
+          end
+        end
+
+        # Appends a member row, at the end of the seed block owning `context`, as `proposed`;
+        # whoever admits it may move it to its group.
+        #
+        # @param path [String] the file holding the block
+        # @param context [String] the context whose block takes the row
+        # @param seed [String] `"KeywordSeed"` or `"ArgumentSeed"`
+        # @yieldparam indent [String] the whitespace the block's member rows start with
+        # @yieldreturn [String] the new row, newline included
+        def append_member(path, context, seed)
+          source = read_source(path)
+          block = seed_blocks(source, seed).find { |candidate| candidate.include?(%(context: "#{context}")) } ||
+                  seed_block(source, seed, required: true)
+          indent = block[/^(\s*)member /, 1] || "        "
+          closing = block.rindex(/^\s*end\s*$/)
+          write_source(path, source.sub(block, block[0...closing] + yield(indent) + block[closing..]))
+        end
+
+        # Rewrites, through the block, each line of the seed block holding the rows `matches` picks.
+        #
+        # @param path [String] the file holding the block
+        # @param seed [String] `"KeywordSeed"` or `"ArgumentSeed"`
+        # @param matches [#call] tells whether a line is one of the rows to rewrite
+        # @param missing [String] the refusal when no row matches
+        # @raise [Refusal] when no row matches
+        def rewrite_member_rows(path, seed, matches, missing)
+          source = read_source(path)
+          block = seed_blocks(source, seed).find { |candidate| candidate.lines.any?(&matches) }
+          raise Refusal, missing unless block
+
+          updated = block.lines.map { |line| matches.call(line) ? yield(line) : line }.join
+          write_source(path, source.sub(block, updated))
+        end
+
+        # Sets a row line's `status:` cell; admitted is the default and stays unspelled.
+        def restatus(line, to)
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        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)
+            closing = source.index(/^#{Regexp.escape(match[1])}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)
+
+        # 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
+end

data/lib/hecks/grammar/evolve.rb

@@ -1,10 +1,24 @@
+require_relative "evolve/seeds"
+require_relative "evolve/keywords"
+require_relative "evolve/arguments"
+
 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.
+    #
+    # The row readers and edits live in `Seeds`, `Keywords` and `Arguments`, extended onto this
+    # module; what is here is the reading and writing of the table files themselves.
     module Evolve
       class Refusal < StandardError; end
 
+      # The stations a word's or an argument's life admits.
+      STATIONS = %w[proposed admitted deprecated retired].freeze
+
+      extend Seeds
+      extend Keywords
+      extend Arguments
+
       module_function
 
       # Only consumes the next argv element as the value when it isn't itself
@@ -88,270 +102,15 @@ module Hecks
       # 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
+      # Refuses a keyword a call was not declared to take, as a method with those keywords would.
+      #
+      # @param fields [Hash] the keywords the caller passed
+      # @param allowed [Array<Symbol>] the keywords the call takes
+      # @raise [ArgumentError] naming the first keyword not in `allowed`
+      def check_fields!(fields, allowed)
+        unknown = fields.keys - allowed
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
       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