hecks 3.4.2 → 3.6.0

data/lib/hecks/cli/launcher_words.rb

@@ -0,0 +1,168 @@
+module Hecks
+  module CLI
+    # The launcher's `name=value` spellings of a subcommand's arguments, rewritten into the words
+    # the subcommand reads. `CLI` extends it.
+    module LauncherWords
+      # The launcher's flags that mean the same for every subcommand here: `--wait` (a subcommand
+      # exits with its own verdict, so waiting changes nothing) and `--confirm` (nothing here asks
+      # for one). Each may carry a Boolean word, as at the launcher.
+      GENERIC_FLAGS = ["--wait", "--confirm"].freeze
+
+      # A launcher word: `name=value`, where the name has no path characters.
+      NAME_VALUE = /\A[A-Za-z_][\w-]*=/
+
+      # The launcher's `name=value` spellings of a subcommand's positional arguments.
+      #
+      # `slots` lists, in positional order, the names that fill each place (`domain` before
+      # `aggregate`); `many` lets the first slot repeat and take a comma list; `exists` makes
+      # the first slot's values paths that must exist; `flags` and `options` are `--name`
+      # switches and `--name value` pairs; `ignored` names a launcher argument this form has no
+      # use for. A subcommand absent here (`run`, whose pairs are the verb's own, `mcp`, and
+      # `project_diagrams`, whose launcher form answers instead of writing) keeps its words.
+      LAUNCHER_FORMS = {
+        "docs"        => { slots: [%w[domain], %w[aggregate]], exists: true },
+        "narrate"     => { slots: [%w[domain], %w[aggregate]], exists: true },
+        "ir"          => { slots: [%w[domain]], flags: %w[translations meta], exists: true },
+        "stores"      => { slots: [%w[domain]], exists: true },
+        "model_check" => { slots: [%w[domains domain]], many: true, flags: %w[strict],
+                           options: %w[profile], ignored: %w[run] },
+        "smoke_test"  => { slots: [%w[subject domain]], ignored: %w[run] },
+        "project_cli" => { slots: [%w[domain]], many: true }
+      }.freeze
+
+      # Subcommands whose words are their own: `run`'s pairs and `mcp`'s flags are not the
+      # launcher's.
+      UNTOUCHED = %w[run mcp].freeze
+
+      # Subcommands whose `name=value` form is the launcher's own question, which answers
+      # differently from the positional form: `project_diagrams` writes files, the question prints.
+      LAUNCHER_ANSWERS = ["project_diagrams"].freeze
+
+      # Whether a command line is the launcher's own form of a subcommand that answers differently
+      # from its positional form, so the executable leaves it to the launcher.
+      #
+      # @param argv [Array<String>] the command line, subcommand first
+      # @return [Boolean]
+      def launcher_form?(argv)
+        LAUNCHER_ANSWERS.include?(argv.first) && argv.drop(1).any? { |word| word.match?(NAME_VALUE) }
+      end
+
+      # Rewrites the launcher's spellings into the subcommand's own: drops the generic flags and
+      # turns `name=value` words into the positionals and flags the subcommand reads.
+      #
+      # @param name [String] a key of `COMMANDS`
+      # @param rest [Array<String>] the words after the subcommand
+      # @return [Array(Array<String>, String)] the words to run with, and a refusal (nil when
+      #   there is none)
+      def launcher_words(name, rest)
+        return [rest, nil] if UNTOUCHED.include?(name)
+
+        require_relative "../doors/cli_door"
+        words = strip_generic(rest)
+        form  = LAUNCHER_FORMS[name]
+        return [words, nil] unless form && words.any? { |word| word.match?(NAME_VALUE) }
+
+        bind_launcher_words(form, words)
+      rescue Runtime::TypeMismatch => e
+        [nil, e.message]
+      end
+
+      # Binds the `name=value` words of `words` into the form's slots and flags.
+      # @api private
+      #
+      # @param form [Hash] an entry of `LAUNCHER_FORMS`
+      # @param words [Array<String>] the words after the subcommand, generic flags removed
+      # @return [Array(Array<String>, String)] the words to run with, and a refusal (nil when
+      #   there is none)
+      def bind_launcher_words(form, words)
+        slots, extra, refusal = bind_named_words(form, words)
+        return [nil, refusal] if refusal
+
+        missing = slots.first.find { |path| !File.exist?(path) } if form[:exists]
+        return [nil, "no such domain #{missing.inspect}"] if missing
+
+        [words.grep_v(NAME_VALUE) + extra + slots.flatten, nil]
+      end
+
+      # Sorts the `name=value` words of `words` into the form's positional slots and its flags.
+      # @api private
+      #
+      # @param form [Hash] an entry of `LAUNCHER_FORMS`
+      # @param words [Array<String>] the words after the subcommand, generic flags removed
+      # @return [Array(Array<Array<String>>, Array<String>, String)] the slot contents, the extra
+      #   flag words, and a refusal (nil when there is none)
+      def bind_named_words(form, words)
+        slots = Array.new(form[:slots].length) { [] }
+        extra = []
+        words.grep(NAME_VALUE).each do |word|
+          refusal = bind_word(form, word, slots, extra)
+          return [nil, nil, refusal] if refusal
+        end
+        [slots, extra, nil]
+      end
+
+      # Files one `name=value` word into its slot, or as a flag or option.
+      # @api private
+      #
+      # @return [String, nil] a refusal when the form takes no such argument
+      def bind_word(form, word, slots, extra)
+        key, value = word.split("=", 2)
+        key  = key.tr("-", "_")
+        slot = form[:slots].index { |names| names.include?(key) }
+        return bind_flag_or_option(form, key, value, extra) unless slot
+
+        slots[slot].concat(form[:many] ? value.split(",") : [value])
+        nil
+      end
+
+      # Appends the flag or option word for one `name=value` into `extra`.
+      # @api private
+      #
+      # @return [String, nil] a refusal when the form takes no such argument
+      def bind_flag_or_option(form, key, value, extra)
+        return add_flag(key, value, extra) if listed?(form, :flags, key)
+        return add_option(key, value, extra) if listed?(form, :options, key)
+        return if listed?(form, :ignored, key)
+
+        known = form[:slots].flatten + Array(form[:flags]) + Array(form[:options])
+        "no argument #{key.inspect} — this verb takes #{known.sort.join(", ")}"
+      end
+
+      # @api private
+      def listed?(form, kind, key) = Array(form[kind]).include?(key)
+
+      # @api private
+      def add_flag(key, value, extra)
+        extra << "--#{key.tr("_", "-")}" if Doors::CliDoor.boolean(value)
+        nil
+      end
+
+      # @api private
+      def add_option(key, value, extra)
+        extra.push("--#{key}", value)
+        nil
+      end
+
+      # Takes `--wait` and `--confirm`, each with an optional Boolean word, out of `words`.
+      # @api private
+      def strip_generic(words)
+        queue = words.dup
+        kept  = []
+        until queue.empty?
+          word = queue.shift
+          flag, value = word.split("=", 2)
+          next kept << word unless GENERIC_FLAGS.include?(flag)
+
+          Doors::CliDoor.boolean(value || generic_value(queue))
+        end
+        kept
+      end
+
+      # The Boolean word that follows a generic flag, or "true" when none does.
+      # @api private
+      def generic_value(queue)
+        Doors::CliDoor::BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
+      end
+    end
+  end
+end

data/lib/hecks/cli/model_check/examination.rb

@@ -0,0 +1,93 @@
+module Hecks
+  module CLI
+    module ModelCheck
+      # Examining booted domains: each one's findings against the allowlist, then the language's
+      # own chapters, printed as the check goes. `ModelCheck` extends it.
+      module Examination
+        # @api private
+        def examine_all(booted, options)
+          known_domains = booted.flat_map { |_, registry| registry.bluebooks.keys + registry.hecksagons.keys }.to_set
+          shared = { known_domains: known_domains, global_emitted_events: emitted_events_of(booted) }
+
+          booted.reduce(true) { |all_ok, (name, registry)| domain_passes?(name, registry, options, **shared) && all_ok }
+        end
+
+        # @api private
+        def emitted_events_of(booted)
+          booted.flat_map do |_, registry|
+            registry.bluebooks.values.flat_map { |chapter| Bluebook::ModelCheck.emitted_events(chapter) }
+          end.to_set
+        end
+
+        def domain_passes?(name, registry, options, known_domains:, global_emitted_events:)
+          puts "── #{name}"
+
+          scope = { known_domains: known_domains, global_emitted_events: global_emitted_events,
+                    rust_target: rust_target?(name, options.rust_dir), strict: options.strict, profile: options.profile }
+          chapters = registry.bluebooks.values
+          findings = chapters.flat_map do |chapter|
+            Bluebook::ModelCheck.call(chapter, hecksagon: registry.hecksagon(chapter.name), **scope)
+          end
+
+          remaining = without_allowlisted(name, findings) or return false
+          passes?(remaining, "   clean — #{chapters.size} chapter(s), no dead states, no unreachable protocol steps")
+        end
+
+        # Prints the allowlisted findings and answers the rest.
+        #
+        # @api private
+        # @return [Array, nil] the findings the domain's allowlist does not cover, or nil when the
+        #   allowlist holds entries that match nothing
+        def without_allowlisted(name, findings)
+          allowed = Bluebook::ModelCheck::ALLOWED_FINDINGS.fetch(name, [])
+          matched, remaining = findings.partition { |f| allowed.include?([f.kind, f.subject]) }
+          matched.each { |f| puts "   ALLOWLISTED  #{f}" }
+
+          stale = allowed - matched.map { |f| [f.kind, f.subject] }
+          return remaining if stale.empty?
+
+          puts "   STALE ALLOWLIST ENTRIES (no longer found — remove them): #{stale.inspect}"
+          nil
+        end
+
+        # Checked through `MetaValidator.grammar_registry`, the judged graph its
+        # conformance specs use, because any one grammar file booted alone is a
+        # fraction of the language.
+        def examine_language(options)
+          ok = true
+          ["Bluebook", "World"].each do |name|
+            chapter = Bluebook::MetaValidator.grammar_registry.bluebook(name)
+            next unless chapter
+
+            puts "── #{name} (the language itself)"
+            findings = Bluebook::ModelCheck.call(chapter, strict: options.strict, profile: options.profile)
+            ok = passes?(findings, "   clean — no dead states, no unreachable protocol steps") && ok
+          end
+          ok
+        end
+
+        # @api private
+        def passes?(findings, clean_line)
+          if findings.empty?
+            puts clean_line
+            return true
+          end
+
+          errors, warnings = findings.partition { |f| f.severity == :error }
+          puts "   #{errors.size} error(s), #{warnings.size} warning(s)"
+          findings.each { |f| puts "     #{f}" }
+          errors.empty?
+        end
+
+        # The repository-only fuzzing tooling is loaded lazily, only when there is a
+        # `rust/` to read.
+        def rust_target?(name, rust_dir)
+          return false unless rust_dir
+
+          require_relative "../../fuzzing/target_capabilities"
+          Fuzzing::TargetCapabilities.rust_feature?(name, rust_dir)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/model_check/sources.rb

@@ -0,0 +1,57 @@
+module Hecks
+  module CLI
+    module ModelCheck
+      # Boots a domain's source into a registry of its own, so the checks read IR and nothing runs.
+      # `ModelCheck` extends it.
+      module Sources
+        # The framework files a booted source needs loaded first, under `ModelCheck::HECKS_DIR`.
+        FRAMEWORK_FILES = [
+          "ports/persistence.port", "ports/extraction.port",
+          "adapters/driven/memory.adapter", "adapters/driven/prism.adapter"
+        ].freeze
+
+        # `root:` is the source's parent, so a member declaring
+        # `attaches ... from: :vendor` can vendor from it.
+        def boot(source)
+          root = File.directory?(source) ? File.dirname(source) : nil
+          registry = Runtime::Registry.new(root: root)
+          Hecks.with_registry(registry) { load_source(source) }
+          registry
+        end
+
+        # @api private
+        def load_source(source)
+          FRAMEWORK_FILES.each { |file| Kernel.load(File.join(HECKS_DIR, file)) }
+          folder = Adapters::Folder.new
+          if File.directory?(source)
+            folder.load_bluebooks(source)
+          else
+            folder.load_bluebooks(File.dirname(source), [File.basename(source)])
+          end
+
+          # A port attaches to its aggregate from the hecksagon, not the bluebook, so a
+          # deaf-policy check that skipped it would miss a policy reacting to an event
+          # nothing emits. Recording a bind builds IR only; no adapter resolves here. A chapter
+          # that ships its ports beside its bluebook (`<name>.ports.hecksagon`) is read with them.
+          hecksagons_of(source).each { |hecksagon| Kernel.load(hecksagon) if File.exist?(hecksagon) }
+        end
+
+        # @api private
+        def hecksagons_of(source)
+          return Dir.glob(File.join(source, "*.hecksagon")) if File.directory?(source)
+
+          [".hecksagon", ".ports.hecksagon"].map { |suffix| source.sub(/\.bluebook\z/, suffix) }
+        end
+
+        # The same rule `Corpus.bluebook_dir` applies.
+        def bluebook_dir(domain_path)
+          [File.join(domain_path, "bluebook"), domain_path].each do |dir|
+            files = Dir[File.join(dir, "*.bluebook")]
+            return File.dirname(files.first) unless files.empty?
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/model_check.rb

@@ -1,5 +1,7 @@
 require_relative "../../hecks"
 require_relative "../bluebook/model_check"
+require_relative "model_check/sources"
+require_relative "model_check/examination"
 
 module Hecks
   module CLI
@@ -20,6 +22,9 @@ module Hecks
       # `rust_dir` from the root (nil without one).
       Options = Struct.new(:strict, :profile, :rust_dir)
 
+      extend Sources
+      extend Examination
+
       module_function
 
       # Runs the model check `argv` describes and exits with its verdict.
@@ -36,25 +41,33 @@ module Hecks
         argv = argv.dup
         strict = !argv.delete("--strict").nil?
         argv.delete("--wait")
-        profile = take_profile(argv)
-        unless profile.nil? || Bluebook::ModelCheck::PROFILES.include?(profile)
-          warn "unknown profile #{profile.inspect} (known: #{Bluebook::ModelCheck::PROFILES.join(', ')})"
-          exit 2
-        end
+        options = Options.new(strict, known_profile(take_profile(argv)), root && File.join(root, "rust"))
+        finish(run_check(argv, options, program, root))
+      end
+
+      # @api private
+      def known_profile(profile)
+        return profile if profile.nil? || Bluebook::ModelCheck::PROFILES.include?(profile)
+
+        warn "unknown profile #{profile.inspect} (known: #{Bluebook::ModelCheck::PROFILES.join(", ")})"
+        exit 2
+      end
 
-        options = Options.new(strict, profile, root && File.join(root, "rust"))
-        ok = begin
-          if argv.any? then check_domains(argv, options)
-          elsif root then check_corpus(root, options)
-          else abort "usage: #{program} [--strict] [--profile client] <domain> [<domain> …]"
-          end
-        rescue Bluebook::DSL::Malformed => e
-          abort "#{program}: #{e.message}"
+      # @api private
+      def run_check(argv, options, program, root)
+        if argv.any? then check_domains(argv, options)
+        elsif root then check_corpus(root, options)
+        else abort "usage: #{program} [--strict] [--profile client] <domain> [<domain> …]"
         end
+      rescue Bluebook::DSL::Malformed => e
+        abort "#{program}: #{e.message}"
+      end
 
+      # @api private
+      def finish(clean)
         puts
-        puts ok ? "No dead states, no unreachable protocol steps." : "THE MODEL HAS FINDINGS."
-        exit(ok ? 0 : 1)
+        puts clean ? "No dead states, no unreachable protocol steps." : "THE MODEL HAS FINDINGS."
+        exit(clean ? 0 : 1)
       end
 
       def take_profile(argv)
@@ -86,125 +99,6 @@ module Hecks
         ok = examine_all(booted, options)
         examine_language(options) && ok
       end
-
-      # `root:` is the source's parent, so a member declaring
-      # `attaches ... from: :vendor` can vendor from it.
-      def boot(source)
-        root = File.directory?(source) ? File.dirname(source) : nil
-        registry = Runtime::Registry.new(root: root)
-        Hecks.with_registry(registry) { load_source(source) }
-        registry
-      end
-
-      # @api private
-      def load_source(source)
-        Kernel.load(File.join(HECKS_DIR, "ports/persistence.port"))
-        Kernel.load(File.join(HECKS_DIR, "ports/extraction.port"))
-        Kernel.load(File.join(HECKS_DIR, "adapters/driven/memory.adapter"))
-        Kernel.load(File.join(HECKS_DIR, "adapters/driven/prism.adapter"))
-        folder = Adapters::Folder.new
-        if File.directory?(source)
-          folder.load_bluebooks(source)
-        else
-          folder.load_bluebooks(File.dirname(source), [File.basename(source)])
-        end
-
-        # A port attaches to its aggregate from the hecksagon, not the bluebook, so a
-        # deaf-policy check that skipped it would miss a policy reacting to an event
-        # nothing emits. Recording a bind builds IR only; no adapter resolves here. A chapter
-        # that ships its ports beside its bluebook (`<name>.ports.hecksagon`) is read with them.
-        hecksagons = if File.directory?(source)
-                       Dir.glob(File.join(source, "*.hecksagon"))
-                     else
-                       [".hecksagon", ".ports.hecksagon"].map { |suffix| source.sub(/\.bluebook\z/, suffix) }
-                     end
-        hecksagons.each { |hecksagon| Kernel.load(hecksagon) if File.exist?(hecksagon) }
-      end
-
-      # @api private
-      def examine_all(booted, options)
-        known_domains = booted.flat_map { |_, registry| registry.bluebooks.keys + registry.hecksagons.keys }.to_set
-        global_emitted_events = booted.flat_map do |_, registry|
-          registry.bluebooks.values.flat_map { |chapter| Bluebook::ModelCheck.emitted_events(chapter) }
-        end.to_set
-
-        booted.reduce(true) do |all_ok, (name, registry)|
-          domain_passes?(name, registry, options,
-                         known_domains: known_domains, global_emitted_events: global_emitted_events) && all_ok
-        end
-      end
-
-      def domain_passes?(name, registry, options, known_domains:, global_emitted_events:)
-        puts "── #{name}"
-
-        rust_target = rust_target?(name, options.rust_dir)
-        chapters = registry.bluebooks.values
-        findings = chapters.flat_map do |chapter|
-          Bluebook::ModelCheck.call(chapter, hecksagon: registry.hecksagon(chapter.name), known_domains: known_domains,
-                                             global_emitted_events: global_emitted_events,
-                                             rust_target: rust_target,
-                                             strict: options.strict, profile: options.profile)
-        end
-
-        allowed = Bluebook::ModelCheck::ALLOWED_FINDINGS.fetch(name, [])
-        matched, findings = findings.partition { |f| allowed.include?([f.kind, f.subject]) }
-        matched.each { |f| puts "   ALLOWLISTED  #{f}" }
-
-        stale = allowed - matched.map { |f| [f.kind, f.subject] }
-        unless stale.empty?
-          puts "   STALE ALLOWLIST ENTRIES (no longer found — remove them): #{stale.inspect}"
-          return false
-        end
-
-        passes?(findings, "   clean — #{chapters.size} chapter(s), no dead states, no unreachable protocol steps")
-      end
-
-      # Checked through `MetaValidator.grammar_registry`, the judged graph its
-      # conformance specs use, because any one grammar file booted alone is a
-      # fraction of the language.
-      def examine_language(options)
-        ok = true
-        ["Bluebook", "World"].each do |name|
-          chapter = Bluebook::MetaValidator.grammar_registry.bluebook(name)
-          next unless chapter
-
-          puts "── #{name} (the language itself)"
-          findings = Bluebook::ModelCheck.call(chapter, strict: options.strict, profile: options.profile)
-          ok = passes?(findings, "   clean — no dead states, no unreachable protocol steps") && ok
-        end
-        ok
-      end
-
-      # @api private
-      def passes?(findings, clean_line)
-        if findings.empty?
-          puts clean_line
-          return true
-        end
-
-        errors, warnings = findings.partition { |f| f.severity == :error }
-        puts "   #{errors.size} error(s), #{warnings.size} warning(s)"
-        findings.each { |f| puts "     #{f}" }
-        errors.empty?
-      end
-
-      # The repository-only fuzzing tooling is loaded lazily, only when there is a
-      # `rust/` to read.
-      def rust_target?(name, rust_dir)
-        return false unless rust_dir
-
-        require_relative "../fuzzing/target_capabilities"
-        Fuzzing::TargetCapabilities.rust_feature?(name, rust_dir)
-      end
-
-      # The same rule `Corpus.bluebook_dir` applies.
-      def bluebook_dir(domain_path)
-        [File.join(domain_path, "bluebook"), domain_path].each do |dir|
-          files = Dir[File.join(dir, "*.bluebook")]
-          return File.dirname(files.first) unless files.empty?
-        end
-        nil
-      end
     end
   end
 end