hecks 3.12.0 → 3.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beba8cd60d4c859286fa1121e3b382cc63e826e010dfd336714befa036dfad94
-  data.tar.gz: 16deb6ba2dd98c8d09385e77a9773f92ef12726d097e71601d2e3cfdbb83ae00
+  metadata.gz: 52208049da300a9004b163c5e48cfe5587711ad45a3cb4d17a5bd1aa4eca8567
+  data.tar.gz: 1788cde0c4a89814395a4be9b3396cc8b5fd823aa408da88534aae617afbd0f1
 SHA512:
-  metadata.gz: fe730368d2f8942c67a5510c5b8344bdad86f9aa0990515903e147da4fe71fbc6f17880ea2a1b26de4ffa0d24ad20c416455df58ee8a66617e1f832b2637e2b0
-  data.tar.gz: a41080c78fc7b1e9d43347fd4b965d6811c246baee7072214c5f7895564eccc94ce699b86bc739de0f3d7d7830fb8057e6bf2e0699496e201ffd057c7e6a39d5
+  metadata.gz: 5ad958aea6cbf148bf0164808eae59179ec03743f1591f193f85e196c9aa7c5a25376d9857ad3d42d57303c7af721811cddf11f776c88f48914f46c4522edc87
+  data.tar.gz: d1148d6aa2ced591c069816c3f17047d08d0aa902e03340dbd4b7c35c20be8eb0907bda11f00c746fdc8955ae0a9225aafe43e3b92715efb42df0f0d73c3b0a8

data/examples/pizzas/bluebook/pizzas.bluebook

@@ -14,7 +14,7 @@ Hecks.bluebook "Pizzas" do
     identified_by :name
 
     value_object "PizzaName" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a pizza is named") { !value.to_s.empty? }
     end
@@ -26,13 +26,13 @@ Hecks.bluebook "Pizzas" do
     end
 
     value_object "CustomerName" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a customer is named") { !value.to_s.empty? }
     end
 
     value_object "ToppingName" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a topping is named") { !value.to_s.empty? }
       # The pattern lets a form feed through; `.strip` is what sees past it.
@@ -46,7 +46,7 @@ Hecks.bluebook "Pizzas" do
     end
 
     value_object "Topping" do
-      attribute :name,   String, pattern: '[^ \t\n\r]'
+      attribute :name,   String, matches: :present
       attribute :amount, Integer
     end
 

data/lib/hecks/adapters/driven/script_runner.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "ScriptRunner" do
+  port "Script"
+end

data/lib/hecks/adapters/driven/script_runner.rb

@@ -0,0 +1,93 @@
+require "digest"
+require "json"
+
+module Hecks
+  module Adapters
+    # The `Script` port's adapter for a `Change`: it runs the scripts registered with it, in this
+    # process. A script is a name, a `plan` that says what it would do without doing it, and an
+    # `apply` that does it.
+    #
+    # `examine` plans a change and answers the plan with a digest of it. `perform` plans again and
+    # carries the change out only when the plan still has the digest that was confirmed, so what
+    # runs is what the person saw. A script that cannot be found, or whose plan or apply raises,
+    # refuses the change with its message.
+    class ScriptRunner
+      # A script: what it would do, and doing it. Both take the arguments as a Hash of String keys.
+      Script = Struct.new(:plan, :apply, keyword_init: true)
+
+      # Why a change was refused: an unknown script, a plan that moved, or the script's own failure.
+      class Refused < StandardError; end
+
+      class << self
+        # @return [Hash{String => Script}] the scripts this process can run, by name
+        def scripts = @scripts ||= {}
+
+        # @param name [String] the name a change asks for
+        # @param plan [#call] takes the arguments, returns the text of what the script would do
+        # @param apply [#call] takes the arguments, does it, returns the text of what happened
+        # @return [Script] the registered script
+        def register(name, plan:, apply:) = scripts[name.to_s] = Script.new(plan: plan, apply: apply)
+
+        # Forgets every registered script.
+        #
+        # @return [Hash] the empty registry
+        def reset! = @scripts = {}
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Plans the change.
+      #
+      # @param held [Hash] the record: `script` and `arguments`
+      # @return [Hash{Symbol => Hash}] `plan:` what the script would do, and `digest:` its
+      #   fingerprint
+      # @raise [Refused] when the script is unknown or its plan raises
+      def examine(**held)
+        name, args = request(held)
+        text = planned(name, args)
+        { plan: { value: text }, digest: { value: digest(name, args, text) } }
+      end
+
+      # Carries out a confirmed change if its plan has not moved.
+      #
+      # @param held [Hash] the record: `script`, `arguments` and `planned_digest`
+      # @return [Hash{Symbol => Hash}] `report:` what the script reported
+      # @raise [Refused] when the script is unknown, the plan has moved, or the script raises
+      def perform(**held)
+        name, args = request(held)
+        current = digest(name, args, planned(name, args))
+        raise Refused, "the plan moved since it was confirmed; plan it again" unless current == plain(held[:planned_digest])
+
+        { report: { value: run(name, :apply, args).to_s } }
+      end
+
+      private
+
+      def request(held) = [plain(held[:script]), arguments(held[:arguments])]
+
+      def planned(name, args) = run(name, :plan, args).to_s
+
+      def run(name, step, args)
+        script = self.class.scripts.fetch(name) { raise Refused, "no script is registered as #{name.inspect}" }
+        script.public_send(step).call(args)
+      rescue Refused
+        raise
+      rescue StandardError => e
+        raise Refused, "#{name} #{step} failed: #{e.message}"
+      end
+
+      # The digest stands for the script, its arguments and its plan, so none of them can change
+      # between confirming and applying.
+      def digest(name, args, text) = Digest::SHA256.hexdigest(JSON.generate([name, args.sort.to_h, text]))
+
+      def arguments(list) = Array(list).to_h { |pair| [plain(pair[:key]), plain(pair[:value])] }
+
+      def plain(cell) = cell.is_a?(Hash) && cell.key?(:value) ? cell[:value] : cell
+    end
+  end
+end

data/lib/hecks/adapters/driven.rb

@@ -27,3 +27,4 @@ require_relative "driven/governance_authorization"
 require_relative "driven/identity_registry"
 require_relative "driven/google_authentication"
 require_relative "driven/claude_code"
+require_relative "driven/script_runner"

data/lib/hecks/bluebook/dsl/attribute_collector.rb

@@ -17,7 +17,7 @@ module Hecks
         private_constant :UNSET
 
         ATTRIBUTE_FIELD_OPTIONS = %i[default optional pattern admits].freeze
-        ATTRIBUTE_OPTIONS = [*ATTRIBUTE_FIELD_OPTIONS, :one_of].freeze
+        ATTRIBUTE_OPTIONS = [*ATTRIBUTE_FIELD_OPTIONS, :one_of, :matches].freeze
         private_constant :ATTRIBUTE_FIELD_OPTIONS, :ATTRIBUTE_OPTIONS
 
         # Returns the attributes declared so far, minting the accumulating list on first use.
@@ -34,12 +34,12 @@ module Hecks
         # Declares one field on the owning construct; the type is a bare constant (ADR 0025).
         #
         #   attribute :op, String, admits: "Vocabulary::QueryComparator"
-        # `admits:` names an already-declared closed set as qualified text, checked on read.
-        # `one_of:` declares an inline closed set, meaningful only inside a `value_object`.
+        # `admits:` names a declared closed set as qualified text. `one_of:` declares an inline one.
         #
         # @param name [Symbol] the field's name
         # @param type [Module, ListOf, OneOf] a bare constant or a wrapper
-        # @param options [Hash] `default:`, `optional:`, `pattern:`, `admits:` or `one_of:`
+        # @param options [Hash] `default:`, `optional:`, `pattern:`, `matches:` (a `NamedPattern`),
+        #   `admits:` or `one_of:`
         # @return [void]
         # @raise [Malformed] on a duplicate name, a missing or quoted type, a disallowed pattern
         # @raise [ArgumentError] on any other keyword
@@ -86,7 +86,17 @@ module Hecks
             raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
           end
 
-          { default: nil, optional: false, pattern: nil, admits: nil, one_of: nil }.merge(options)
+          given = { default: nil, optional: false, pattern: nil, admits: nil, one_of: nil }.merge(options)
+          expand_matches(given)
+        end
+
+        # `matches: :name` stands for the pattern the language gives that name.
+        def expand_matches(given)
+          matches = given.delete(:matches)
+          return given unless matches
+          raise ArgumentError, "matches: and pattern: both state the pattern" if given[:pattern]
+
+          given.merge(pattern: NamedPattern.source(matches))
         end
 
         def typed_attribute(name, type, field_options)

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

@@ -37,19 +37,23 @@ module Hecks
         end
 
         # Dispatches every seed row into a fresh "Bluebook" instance and
-        # reads the result back.
+        # reads the result back. The table is memoized for the process, so it is built with no
+        # ambient caller: an enclosing `Hecks.as_caller` would have the language's own
+        # `Language`-role commands refused.
         def boot
-          bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
-          # `fresh_runtime`, not a new `Runtime::Registry` — the grammar
-          # registry already has "Bluebook" registered and its adapter
-          # ports already loaded.
-          runtime = MetaValidator.fresh_runtime
-
-          declare_syntax(runtime, bluebook)
-          admit_keywords(runtime, bluebook)
-          admit_arguments(runtime, bluebook)
-
-          read_back(runtime, bluebook)
+          Runtime::Caller.without do
+            bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
+            # `fresh_runtime`, not a new `Runtime::Registry` — the grammar
+            # registry already has "Bluebook" registered and its adapter
+            # ports already loaded.
+            runtime = MetaValidator.fresh_runtime
+
+            declare_syntax(runtime, bluebook)
+            admit_keywords(runtime, bluebook)
+            admit_arguments(runtime, bluebook)
+
+            read_back(runtime, bluebook)
+          end
         end
 
         # An Integer stays an Integer — `position` is `Position`-typed, so

data/lib/hecks/bluebook/meta_validator.rb

@@ -168,32 +168,39 @@ module Hecks
       end
 
       # The booted, self-judged language registry every ordinary bluebook is
-      # judged against — built once per process and memoized, with shadow parsing off: a caller
-      # inside `while_shadow_parsing` that is first to ask would otherwise memoize a grammar
-      # parsed in that mode, or fail to load it.
+      # judged against — built once per process and memoized, with shadow parsing off and no
+      # ambient caller bound. A caller inside `while_shadow_parsing` that is first to ask would
+      # otherwise memoize a grammar parsed in that mode, or fail to load it; one inside
+      # `Hecks.as_caller` would have the language's own `Language`-role commands refused, and the
+      # grammar would be memoized without the chapters those refusals dropped.
       #
       # @return [Runtime::Registry] the booted, fixpoint-judged language
       #   registry
       def self.grammar_registry
-        @grammar_registry ||= while_not_shadow_parsing do
-          registry = load_grammar_into(Runtime::Registry.new)
-          # Assigned before the fixpoint judge below, since judging re-enters
-          # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`
-          # would still be nil mid-evaluation, recursing forever.
-          @grammar_registry = registry
-          # The language now judges itself; every bluebook from here on is
-          # judged by that assembled graph, not the raw bootstrap one. Must
-          # run after load_grammar_into's ensure clears @bootstrapping.
-          while_forcing_fixpoint do
-            LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
-            load_attached_grammar_into(registry)
-          end
-          # Keyed on this registry's object identity, not a bare boolean, so
-          # a manual reset can never leave a stale "ready" from the previous
-          # cycle.
-          @grammar_ready_for = registry.object_id
-          registry
+        @grammar_registry ||= while_not_shadow_parsing { Runtime::Caller.without { build_grammar_registry } }
+      end
+
+      # The one-time build behind `grammar_registry`.
+      #
+      # @return [Runtime::Registry] the booted, fixpoint-judged language registry
+      def self.build_grammar_registry
+        registry = load_grammar_into(Runtime::Registry.new)
+        # Assigned before the fixpoint judge below, since judging re-enters
+        # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`
+        # would still be nil mid-evaluation, recursing forever.
+        @grammar_registry = registry
+        # The language now judges itself; every bluebook from here on is
+        # judged by that assembled graph, not the raw bootstrap one. Must
+        # run after load_grammar_into's ensure clears @bootstrapping.
+        while_forcing_fixpoint do
+          LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
+          load_attached_grammar_into(registry)
         end
+        # Keyed on this registry's object identity, not a bare boolean, so
+        # a manual reset can never leave a stale "ready" from the previous
+        # cycle.
+        @grammar_ready_for = registry.object_id
+        registry
       end
 
       # Whether `grammar_registry`'s memoized singleton has finished its

data/lib/hecks/bluebook/named_pattern.rb

@@ -0,0 +1,33 @@
+module Hecks
+  module Bluebook
+    # The patterns a bluebook names instead of spelling: `matches: :snake_name` says what
+    # `pattern: '^[a-z][a-z0-9_]*$'` does. A name stands for exactly its regex, so the IR, the
+    # generated Rust and the runtime check see the pattern and never the name.
+    #
+    # `rust/parser/src/build/named_pattern.rs` holds the same table; spec/named_pattern_spec.rb
+    # holds the two to each other.
+    module NamedPattern
+      # Name => the regex source it stands for, each the exact source the corpus spelled by hand.
+      TABLE = {
+        present:       '[^ \t\n\r]',
+        not_empty:     '[^\t\n\r]',
+        no_whitespace: '^[^ \t\n\r]+$',
+        snake_name:    "^[a-z][a-z0-9_]*$",
+        git_sha:       "^[0-9a-fA-F]{7,40}$",
+        digits:        "^[0-9]+$"
+      }.freeze
+
+      module_function
+
+      # @param name [Symbol, String] a name in `TABLE`
+      # @return [String] the regex source it stands for
+      # @raise [ArgumentError] when the name is not one the language gives
+      def source(name)
+        TABLE.fetch(name.to_sym) do
+          raise ArgumentError, "matches: #{name.inspect} is not a named pattern — " \
+                               "the names are #{TABLE.keys.map(&:inspect).join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook.rb

@@ -44,6 +44,7 @@ require_relative "bluebook/project_loader"
 
 require_relative "bluebook/dsl"
 require_relative "bluebook/pattern_subset"
+require_relative "bluebook/named_pattern"
 
 require_relative "bluebook/meta_validator"
 require_relative "bluebook/meta_validator/plan"

data/lib/hecks/cli/domain_stub.rb

@@ -96,7 +96,7 @@ module Hecks
               attribute :name, ExampleName
 
               value_object "ExampleName" do
-                attribute :value, String, pattern: '[^ \\t\\n\\r]'
+                attribute :value, String, matches: :present
               end
 
               # TODO: replace Create with the first thing that happens to an Example.

data/lib/hecks/cli/interview_aggregate.rb

@@ -6,8 +6,8 @@ module Hecks
     # The bluebook text of one accepted thing: its aggregate, with its value objects, commands and
     # lifecycle. `InterviewDraft` extends it, and supplies the naming and citing helpers it calls.
     module InterviewAggregate
-      # The pattern every generated string field carries: it refuses a blank value.
-      PATTERN = %q('[^ \t\n\r]').freeze
+      # The option every generated string field carries: it refuses a blank value.
+      PRESENT = "matches: :present".freeze
 
       # What stands in for a creating command nothing in the interview named.
       STUB_NOTE = "    # TODO: no action that creates was accepted; replace Create with the real one.".freeze
@@ -15,7 +15,7 @@ module Hecks
       # One accepted thing: what it is called and identified by, its fields, its transitions, the
       # actions that create it and the others.
       Shape = Struct.new(:name, :identifier, :type, :fields, :steps, :creating, :rest, keyword_init: true)
-      private_constant :PATTERN, :STUB_NOTE, :Shape
+      private_constant :PRESENT, :STUB_NOTE, :Shape
 
       # @api private
       def aggregate(interview, thing, actions)
@@ -66,7 +66,7 @@ module Hecks
       # @api private
       def type_lines(shape)
         ["    value_object #{shape.type.inspect} do",
-         "      attribute :value, String, pattern: #{PATTERN}", "    end",
+         "      attribute :value, String, #{PRESENT}", "    end",
          *InterviewShape.value_objects(shape.fields)]
       end