hecks 3.4.2 → 3.6.0

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -1,6 +1,7 @@
 require "digest"
 require "fileutils"
 require_relative "../../cache_dir"
+require_relative "syntax_boot/disk_cache"
 
 module Hecks
   module Bluebook
@@ -10,6 +11,8 @@ module Hecks
       #
       #   SyntaxBoot.call # => { keywords: [...], arguments: [...] }
       module SyntaxBoot
+        extend DiskCache
+
         module_function
 
         # Memoized per grammar-registry chapter set (identity, not a "ready"
@@ -33,73 +36,6 @@ module Hecks
           result
         end
 
-        # `equal?`, not `==` — chapter identity, not value equality, is the
-        # fact this cache key tracks.
-        def same_chapters?(cached, current)
-          cached.size == current.size &&
-            cached.zip(current).all? do |(cached_name, cached_chapter), (name, chapter)|
-              cached_name == name && cached_chapter.equal?(chapter)
-            end
-        end
-
-        # Cross-process persistence for the same build `call` already memoizes
-        # in-process, keyed by chapter name (not identity, which means nothing
-        # across processes) plus a content hash of every grammar file `boot`
-        # can read from — so a source edit anywhere in that set misses the
-        # cache rather than silently serving a stale table.
-        def cache_dir = Hecks::CacheDir.path("hecks_syntax_boot_cache")
-
-        def disk_cache_enabled? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
-
-        # Fails toward a real boot, never toward a wrong table: a missing
-        # file, a corrupt blob, or a permission error just misses the cache.
-        def read_disk_cache(chapters)
-          return nil unless disk_cache_enabled?
-
-          path = disk_cache_path(chapters)
-          return nil unless File.exist?(path)
-
-          Marshal.load(File.binread(path)) # rubocop:disable Security/MarshalLoad -- own process-local cache, never external input
-        rescue StandardError
-          nil
-        end
-
-        # Writes to a PID-suffixed temp file and renames it into place, so a
-        # concurrent writer's rename can only overwrite with identical
-        # content, never leave a torn file for a concurrent reader.
-        def write_disk_cache(chapters, result)
-          return unless disk_cache_enabled?
-
-          path = disk_cache_path(chapters)
-          FileUtils.mkdir_p(cache_dir)
-          tmp_path = "#{path}.#{Process.pid}.tmp"
-          File.binwrite(tmp_path, Marshal.dump(result))
-          File.rename(tmp_path, path)
-        rescue StandardError
-          nil
-        end
-
-        def disk_cache_path(chapters)
-          File.join(cache_dir, "#{disk_cache_key(chapters)}.marshal")
-        end
-
-        def disk_cache_key(chapters)
-          names = chapters.map { |name, _chapter| name }
-          Digest::SHA256.hexdigest("#{names.join(',')}:#{grammar_content_digest}:#{VerdictCache.code_digest}")
-        end
-
-        # The key also carries `VerdictCache.code_digest` (all of `lib/`), so an
-        # edit to Ruby that builds or judges the grammar misses too.
-        #
-        # Covers every chapter's grammar files, not just the core ones —
-        # coarser than strictly necessary, but under-covering this set would
-        # let a stale table survive a real grammar edit.
-        def grammar_content_digest
-          files = (MetaValidator::GRAMMAR_FILES + MetaValidator::WORLD_GRAMMAR + MetaValidator::HECKSAGON_GRAMMAR +
-                    Dir.glob(File.join(MetaValidator::ATTACHED_GRAMMAR_DIR, "*.bluebook"))).sort
-          Digest::SHA256.hexdigest(files.map { |file| File.read(file) }.join("\0"))
-        end
-
         # Dispatches every seed row into a fresh "Bluebook" instance and
         # reads the result back.
         def boot
@@ -147,44 +83,44 @@ module Hecks
                            with: { bluebook: bluebook.hecks_name, name: v(syntax.hecks_name) })
         end
 
+        # Each Keyword seed column and how it is offered: `v` for a required cell, `optional` for
+        # one whose "" means "not given".
+        KEYWORD_COLUMNS = {
+          word: :v, context: :v, body: :v, inner: :v, opens: :v, fills: :v,
+          was: :optional, resolves_via: :optional, disambiguator: :optional, calls: :optional
+        }.freeze
+
+        # The same, for each Argument seed column.
+        ARGUMENT_COLUMNS = {
+          keyword: :v, context: :v, at: :optional, named: :optional, kind: :v, required: :v, fills: :v,
+          selects: :optional, pair_key_fills: :optional, pair_value_fills: :optional,
+          pairs_shape: :optional, variadic: :optional, minimum: :optional,
+          coerce: :optional, blank_message: :optional
+        }.freeze
+
+        def admit_keywords(runtime, bluebook) = admit(runtime, bluebook, "Keyword", KEYWORD_COLUMNS)
+
+        # Same `to: "Syntax"` append shape `admit_keywords` uses, one type over.
+        def admit_arguments(runtime, bluebook) = admit(runtime, bluebook, "Argument", ARGUMENT_COLUMNS)
+
         # `to: "Syntax"` appends onto the record `declare_syntax` already
         # opened; putting the receiver in the payload instead would make
         # `Syntax.Keyword` look like a fresh identity to mint, colliding
         # with that row.
-        def admit_keywords(runtime, bluebook)
-          all_rows(bluebook, "KeywordSeed").each_with_index do |row, index|
-            runtime.dispatch("Bluebook::Syntax.Keyword", to:   "Syntax",
-                                                         with: { position: v(index),
-                                     word: v(row[:word]), context: v(row[:context]), body: v(row[:body]),
-                                     inner: v(row[:inner]), opens: v(row[:opens]), fills: v(row[:fills]),
-                                     was: optional(row[:was]),
-                                     resolves_via: optional(row[:resolves_via]),
-                                     disambiguator: optional(row[:disambiguator]),
-                                     calls: optional(row[:calls]) })
+        def admit(runtime, bluebook, kind, columns)
+          all_rows(bluebook, "#{kind}Seed").each_with_index do |row, index|
+            runtime.dispatch("Bluebook::Syntax.#{kind}", to: "Syntax", with: seed_payload(row, index, columns))
 
             next unless row[:status].to_s == "deprecated"
 
-            runtime.dispatch("Bluebook::Syntax.Keyword.Deprecate", to: { aggregate: "Syntax", entity: index.to_s })
+            runtime.dispatch("Bluebook::Syntax.#{kind}.Deprecate", to: { aggregate: "Syntax", entity: index.to_s })
           end
         end
 
-        # Same `to: "Syntax"` append shape `admit_keywords` uses, one type over.
-        def admit_arguments(runtime, bluebook)
-          all_rows(bluebook, "ArgumentSeed").each_with_index do |row, index|
-            runtime.dispatch("Bluebook::Syntax.Argument", to:   "Syntax",
-                                                          with: { position: v(index),
-                                     keyword: v(row[:keyword]), context: v(row[:context]),
-                                     at: optional(row[:at]), named: optional(row[:named]),
-                                     kind: v(row[:kind]), required: v(row[:required]), fills: v(row[:fills]),
-                                     selects: optional(row[:selects]), pair_key_fills: optional(row[:pair_key_fills]),
-                                     pair_value_fills: optional(row[:pair_value_fills]),
-                                     pairs_shape: optional(row[:pairs_shape]), variadic: optional(row[:variadic]),
-                                     minimum: optional(row[:minimum]),
-                                     coerce: optional(row[:coerce]), blank_message: optional(row[:blank_message]) })
-
-            next unless row[:status].to_s == "deprecated"
-
-            runtime.dispatch("Bluebook::Syntax.Argument.Deprecate", to: { aggregate: "Syntax", entity: index.to_s })
+        # The walk index first, then each column offered the way `columns` says.
+        def seed_payload(row, index, columns)
+          columns.each_with_object({ position: v(index) }) do |(column, offering), payload|
+            payload[column] = send(offering, row[column])
           end
         end
 

data/lib/hecks/bluebook/meta_validator/translation_judge/rules.rb

@@ -0,0 +1,74 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      class TranslationJudge
+        # Offers each rule collection of one translated aggregate: renames, moves, converts,
+        # drops, retypes, computes, rekeys and backfills.
+        module Rules
+          private
+
+          def judge_renames(aggregate, name)
+            Hash(aggregate.renames).each do |from, to|
+              send_to("Translation::TranslationAggregate.AddRename", name, to:   name,
+                                                                           with: { from: v(from), to: v(to) })
+            end
+          end
+
+          def judge_moves(aggregate, name)
+            Array(aggregate.moves).each do |move|
+              send_to("Translation::TranslationAggregate.AddMove", name, to:   name,
+                                                                         with: { from: v(move.from), to: v(move.to) })
+            end
+          end
+
+          def judge_converts(aggregate, name)
+            Array(aggregate.converts).each do |convert|
+              send_to("Translation::TranslationAggregate.AddConvert", name, to:   name,
+                                                                            with: { from:   v(convert.from),
+                                                                                    to:     v(convert.to),
+                                                                                    values: v(convert.values.inspect) })
+            end
+          end
+
+          def judge_drops(aggregate, name)
+            Array(aggregate.drops).each do |dropped|
+              send_to("Translation::TranslationAggregate.AddDrop", name, to:   name,
+                                                                         with: { value: v(dropped) })
+            end
+          end
+
+          def judge_retypes(aggregate, name)
+            Array(aggregate.retypes).each do |retype|
+              send_to("Translation::TranslationAggregate.AddRetype", name, to:   name,
+                                                                           with: { from: v(retype.from), to: v(retype.to) })
+            end
+          end
+
+          def judge_computes(aggregate, name)
+            Array(aggregate.computes).each do |compute|
+              send_to("Translation::TranslationAggregate.AddCompute", name, to:   name,
+                                                                            with: { from: v(compute.from),
+                                                                                    to:   v(compute.to),
+                                                                                    sql:  v(compute.sql) })
+            end
+          end
+
+          def judge_rekeys(aggregate, name)
+            Array(aggregate.rekeys).each do |rekey|
+              send_to("Translation::TranslationAggregate.AddRekey", name, to:   name,
+                                                                          with: { sql: v(rekey.sql) })
+            end
+          end
+
+          def judge_backfills(aggregate, name)
+            Array(aggregate.backfills).each do |backfill|
+              send_to("Translation::TranslationAggregate.AddBackfill", name, to:   name,
+                                                                             with: { name:    v(backfill.name),
+                                                                                     default: v(backfill.default.inspect) })
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/translation_judge.rb

@@ -1,9 +1,13 @@
+require_relative "translation_judge/rules"
+
 module Hecks
   module Bluebook
     module MetaValidator
       # Offers a built translation (a `translations/*.bluebook` edge) to the language that
       # describes translations. Field names follow the `Translation` structs, not the DSL builder.
       class TranslationJudge
+        include Rules
+
         attr_reader :refusals
 
         # @param translation [Bluebook::Translation] the built translation to judge
@@ -36,18 +40,25 @@ module Hecks
         end
 
         def judge!
+          declare_translation
+          retire_aggregates
+
+          Array(@translation.aggregates).each { |aggregate| judge_aggregate(@translation, aggregate) }
+        end
+
+        def declare_translation
           t = @translation
           send_to("Translation::Translation.Declare", t.domain,
                   with: { domain: v(t.domain), from: v(t.from), to: v(t.to) })
+        end
 
+        def retire_aggregates
+          t = @translation
           # Translation's identity is composite, so `id:` must be computed, not a bare field.
           translation_id = Naming.identity([t.domain, t.from, t.to])
           Array(t.retired).each do |name|
-            send_to("Translation::Translation.Retire", t.domain, to:   translation_id,
-                                                                 with: { value: v(name) })
+            send_to("Translation::Translation.Retire", t.domain, to: translation_id, with: { value: v(name) })
           end
-
-          Array(t.aggregates).each { |aggregate| judge_aggregate(t, aggregate) }
         end
 
         # Declares the aggregate, then adds each rule collection. Only Declare-before-Add is
@@ -75,67 +86,6 @@ module Hecks
           send_to("Translation::TranslationAggregate.Declare", name,
                   with: { translation_ref: parent, name: v(name), was: v(aggregate.was) })
         end
-
-        def judge_renames(aggregate, name)
-          Hash(aggregate.renames).each do |from, to|
-            send_to("Translation::TranslationAggregate.AddRename", name, to:   name,
-                                                                         with: { from: v(from), to: v(to) })
-          end
-        end
-
-        def judge_moves(aggregate, name)
-          Array(aggregate.moves).each do |move|
-            send_to("Translation::TranslationAggregate.AddMove", name, to:   name,
-                                                                       with: { from: v(move.from), to: v(move.to) })
-          end
-        end
-
-        def judge_converts(aggregate, name)
-          Array(aggregate.converts).each do |convert|
-            send_to("Translation::TranslationAggregate.AddConvert", name, to:   name,
-                                                                          with: { from:   v(convert.from),
-                                                                                  to:     v(convert.to),
-                                                                                  values: v(convert.values.inspect) })
-          end
-        end
-
-        def judge_drops(aggregate, name)
-          Array(aggregate.drops).each do |dropped|
-            send_to("Translation::TranslationAggregate.AddDrop", name, to:   name,
-                                                                       with: { value: v(dropped) })
-          end
-        end
-
-        def judge_retypes(aggregate, name)
-          Array(aggregate.retypes).each do |retype|
-            send_to("Translation::TranslationAggregate.AddRetype", name, to:   name,
-                                                                         with: { from: v(retype.from), to: v(retype.to) })
-          end
-        end
-
-        def judge_computes(aggregate, name)
-          Array(aggregate.computes).each do |compute|
-            send_to("Translation::TranslationAggregate.AddCompute", name, to:   name,
-                                                                          with: { from: v(compute.from),
-                                                                                  to:   v(compute.to),
-                                                                                  sql:  v(compute.sql) })
-          end
-        end
-
-        def judge_rekeys(aggregate, name)
-          Array(aggregate.rekeys).each do |rekey|
-            send_to("Translation::TranslationAggregate.AddRekey", name, to:   name,
-                                                                        with: { sql: v(rekey.sql) })
-          end
-        end
-
-        def judge_backfills(aggregate, name)
-          Array(aggregate.backfills).each do |backfill|
-            send_to("Translation::TranslationAggregate.AddBackfill", name, to:   name,
-                                                                           with: { name:    v(backfill.name),
-                                                                                   default: v(backfill.default.inspect) })
-          end
-        end
       end
     end
   end

data/lib/hecks/bluebook/meta_validator/verdict_cache/tagging.rb

@@ -0,0 +1,63 @@
+module Hecks
+  module Bluebook
+    module MetaValidator
+      module VerdictCache
+        # The tagged-JSON encoding verdicts are stored in: what JSON would lose (a symbol, a
+        # hash's key types and order) is tagged so it round-trips exactly.
+        module Tagging
+          # Encodes plain data as JSON-safe data, tagging what JSON would lose:
+          # a symbol is `{"$s" => name}`, a hash is `{"$h" => [[key, value], ...]}`
+          # (pair order is hash order).
+          #
+          # @param obj [Object] Hash, Array, String, Symbol, Integer, nil, true or false
+          # @return [Object] the tagged form
+          # @raise [ArgumentError] for any other class
+          def encode(obj)
+            case obj
+            when Symbol then { "$s" => obj.to_s }
+            when Hash then { "$h" => obj.map { |key, value| [encode(key), encode(value)] } }
+            when Array then obj.map { |item| encode(item) }
+            when *SCALARS then encode_scalar(obj)
+            else raise ArgumentError, "unencodable #{obj.class}"
+            end
+          end
+
+          # The classes JSON carries as they are, a string once its encoding is checked.
+          SCALARS = [String, Integer, NilClass, TrueClass, FalseClass].freeze
+
+          # @param obj [String, Integer, nil, true, false] a scalar
+          # @return [Object] `obj`, when JSON carries it back unchanged
+          # @raise [ArgumentError] for a string that is not valid text
+          def encode_scalar(obj)
+            plain = !obj.is_a?(String) || (obj.valid_encoding? && (obj.ascii_only? || obj.encoding == Encoding::UTF_8))
+            raise ArgumentError, "unencodable string" unless plain
+
+            obj
+          end
+
+          # The inverse of `encode`.
+          #
+          # @param obj [Object] the tagged form
+          # @return [Object] the original data
+          def decode(obj)
+            case obj
+            when Array then obj.map { |item| decode(item) }
+            when Hash then decode_tagged(obj)
+            else obj
+            end
+          end
+
+          # @param obj [Hash] a one-entry hash tagged `$s` or `$h`
+          # @return [Symbol, Hash] what the tag stands for
+          # @raise [ArgumentError] for any other hash
+          def decode_tagged(obj)
+            return obj["$s"].to_sym if obj.size == 1 && obj.key?("$s")
+            return obj["$h"].to_h { |key, value| [decode(key), decode(value)] } if obj.size == 1 && obj.key?("$h")
+
+            raise ArgumentError, "untagged hash"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/verdict_cache.rb

@@ -3,6 +3,7 @@ require "fileutils"
 require "json"
 require_relative "../../cache_dir"
 require_relative "../../version"
+require_relative "verdict_cache/tagging"
 
 module Hecks
   module Bluebook
@@ -12,7 +13,7 @@ module Hecks
       #
       # Only chapter verdicts live here; `Assembly.call` still runs every boot
       # and a miss judges as a cold process does. The file name carries a digest
-      # of the judging code (every file under `lib/`, the Ruby and Hecks
+      # of the judging code (`lib/` outside `CONSUMER_TREES`, the Ruby and Hecks
       # versions, `FORMAT`); each entry is keyed by the chapter IR's SHA-256.
       # The file is tagged JSON, never `Marshal`, read only from a private,
       # user-owned directory: a forged "no refusals" entry would skip validation.
@@ -20,11 +21,20 @@ module Hecks
       #   VerdictCache.record(key, held)
       #   VerdictCache.flush  # also runs at process exit
       module VerdictCache
+        extend Tagging
+
         module_function
 
         # Bumped when the encoding or the entry shape changes.
         FORMAT = 1
 
+        # The subtrees of `lib/` that read the language and never judge it: they
+        # project, serve or deploy from a chapter, and nothing the judge runs
+        # calls into them. An edit there leaves every verdict as it was, so
+        # their files stay out of the key. Paths are relative to `lib/hecks`.
+        CONSUMER_TREES = %r{\A/hecks/(?:bench|cli|codemod|deploy|doc|doors|fuzzing|projections|
+                            quality_control|release)(?:/|\.rb\z)}x
+
         # Files older than this that do not match the current code digest are
         # pruned on write.
         STALE_AFTER = 60 * 60
@@ -45,7 +55,8 @@ module Hecks
         def path = File.join(dir, "verdicts-#{code_digest}.json")
 
         # A digest of everything that decides a verdict: each file under
-        # `lib/` (path and bytes), the Ruby and Hecks versions and `FORMAT`.
+        # `lib/` outside `CONSUMER_TREES` (path and bytes), the Ruby and Hecks
+        # versions and `FORMAT`.
         # Computed once per process, at first use, which is when the judging
         # code was loaded.
         #
@@ -60,14 +71,20 @@ module Hecks
         def digest_of(lib)
           state = Digest::SHA256.new
           state << "#{FORMAT}\0#{RUBY_VERSION}\0#{Hecks::VERSION}\0"
-          Dir.glob(File.join(lib, "**", "*"), File::FNM_DOTMATCH).sort.each do |file|
-            next unless File.file?(file)
-
+          judging_files(lib).each do |file|
             state << file.delete_prefix(lib) << "\0" << File.binread(file) << "\0"
           end
           state.hexdigest
         end
 
+        # @param lib [String] the directory whose files decide a verdict
+        # @return [Array<String>] every file under it outside `CONSUMER_TREES`, sorted
+        def judging_files(lib)
+          Dir.glob(File.join(lib, "**", "*"), File::FNM_DOTMATCH).sort.select do |file|
+            File.file?(file) && !file.delete_prefix(lib).match?(CONSUMER_TREES)
+          end
+        end
+
         # Loads the stored verdicts, once per process; later calls return an
         # empty hash so a caller that resets its own memo re-judges for real.
         #
@@ -193,44 +210,6 @@ module Hecks
           end
         end
 
-        # Encodes plain data as JSON-safe data, tagging what JSON would lose:
-        # a symbol is `{"$s" => name}`, a hash is `{"$h" => [[key, value], ...]}`
-        # (pair order is hash order).
-        #
-        # @param obj [Object] Hash, Array, String, Symbol, Integer, nil, true or false
-        # @return [Object] the tagged form
-        # @raise [ArgumentError] for any other class
-        def encode(obj)
-          case obj
-          when Symbol then { "$s" => obj.to_s }
-          when Hash then { "$h" => obj.map { |key, value| [encode(key), encode(value)] } }
-          when Array then obj.map { |item| encode(item) }
-          when String
-            plain = obj.valid_encoding? && (obj.ascii_only? || obj.encoding == Encoding::UTF_8)
-            raise ArgumentError, "unencodable string" unless plain
-
-            obj
-          when Integer, nil, true, false then obj
-          else raise ArgumentError, "unencodable #{obj.class}"
-          end
-        end
-
-        # The inverse of `encode`.
-        #
-        # @param obj [Object] the tagged form
-        # @return [Object] the original data
-        def decode(obj)
-          case obj
-          when Array then obj.map { |item| decode(item) }
-          when Hash
-            if obj.size == 1 && obj.key?("$s") then obj["$s"].to_sym
-            elsif obj.size == 1 && obj.key?("$h") then obj["$h"].to_h { |key, value| [decode(key), decode(value)] }
-            else raise ArgumentError, "untagged hash"
-            end
-          else obj
-          end
-        end
-
         # Registers the exit hook once per process.
         #
         # @return [void]

data/lib/hecks/bluebook/meta_validator/world_judge.rb

@@ -34,10 +34,7 @@ module Hecks
 
         def judge!
           domain = @world.domain
-          send_to("World::World.Declare", domain, domain: v(domain),
-                  realm: v(@world.realm), latest: v(@world.latest),
-                  default_database: v(@world.default_database),
-                  default_adapter: v(@world.default_adapter))
+          declare_world(domain)
 
           Hash(@world.settings).each do |verb, values|
             # the DSL records each binding twice — once by verb, once by
@@ -48,6 +45,13 @@ module Hecks
           end
         end
 
+        def declare_world(domain)
+          send_to("World::World.Declare", domain, domain: v(domain),
+                  realm: v(@world.realm), latest: v(@world.latest),
+                  default_database: v(@world.default_database),
+                  default_adapter: v(@world.default_adapter))
+        end
+
         def judge_wiring(domain, verb, values)
           # Must match Wiring's own `identified_by do world; verb.value end`
           # derivation exactly, or a later `Wiring.Set` could never find it.