hecks 2.9.0 → 3.0.0

data/lib/hecks/hecks/adapters/rust_workspace.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "find"
+require "securerandom"
+require_relative "../../version"
+
+module Hecks
+  module Adapters
+    # The Rust workspace a build writes into: the checkout's own `rust/` in a hecks checkout, or a
+    # copy of the packaged workspace inside the client's project.
+    #
+    # A build writes generated code and a Cargo feature into the workspace it is given, and Cargo
+    # writes `target/` beside it, so an installed gem's files must never be that workspace. The
+    # copy is keyed by gem version (`.hecks/rust/<version>/`): a domain built with one release
+    # compiles against that release's kernel, and a newer gem gets a fresh copy beside the old.
+    #
+    # A checkout is a working tree with `hecks.gemspec` beside `lib/`; the package never carries
+    # the gemspec, so an install cannot be mistaken for one.
+    class RustWorkspace
+      # The file whose presence beside `lib/` marks a hecks checkout.
+      CHECKOUT_MARKER = "hecks.gemspec"
+
+      # What a copy holds: the workspace manifest, the kernel and every crate a domain build uses.
+      PACKAGED = %w[Cargo.toml Cargo.lock project.rb project_rust_pipeline.rb project src codegen parser
+                    host build web lsp].freeze
+
+      # Left out of a copy: build output anywhere, the corpus tests, and the corpus domains.
+      SKIPPED = lambda do |relative|
+        relative.split("/").include?("target") || relative == "tests" || relative == "src/generated"
+      end
+
+      # The `[features]` table of a Cargo manifest, up to the next table.
+      FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*/
+
+      # Written into a copy once it is complete, so an interrupted copy is redone, not reused.
+      MARKER = ".hecks-workspace"
+
+      # Raised when there is no Rust workspace to build in.
+      class Unavailable < StandardError; end
+
+      # @return [String] the gem's root directory (where `lib/` and `rust/` live)
+      attr_reader :gem_root
+
+      # @param gem_root [String] the gem's root directory
+      # @param project_root [String] the client project a copy is made inside
+      # @param version [String] the gem version a copy is keyed by
+      def initialize(gem_root: File.expand_path("../../../..", __dir__), project_root: Dir.pwd,
+                     version: Hecks::VERSION)
+        @gem_root = gem_root
+        @project_root = project_root
+        @version = version
+      end
+
+      # @return [Boolean] whether the gem is a hecks checkout rather than an installed package
+      def checkout?
+        File.exist?(File.join(@gem_root, CHECKOUT_MARKER)) && Dir.exist?(File.join(@gem_root, "lib"))
+      end
+
+      # The workspace builds write into: the checkout's own `rust/`, or the versioned copy, made
+      # on first use.
+      #
+      # @return [String] the workspace directory
+      # @raise [Unavailable] if the install carries no Rust workspace to copy
+      def directory
+        return File.join(@gem_root, "rust") if checkout?
+
+        copy
+      end
+
+      # The environment a build child runs with. A checkout keeps its own defaults; a copy points
+      # Cargo's output at itself, so nothing is written into the gem.
+      #
+      # @return [Hash{String => String}] variables to set
+      # @raise [Unavailable] if the install carries no Rust workspace to copy
+      def environment
+        return {} if checkout?
+
+        dir = directory
+        { "HECKS_RUST_DIR" => dir, "CARGO_TARGET_DIR" => File.join(dir, "target") }
+      end
+
+      private
+
+      def copy
+        target = File.join(@project_root, ".hecks", "rust", @version)
+        return target if File.exist?(File.join(target, MARKER))
+
+        source = File.join(@gem_root, "rust")
+        unless File.exist?(File.join(source, "Cargo.toml"))
+          raise Unavailable, "this hecks #{@version} install carries no Rust workspace to build in"
+        end
+
+        publish(target) { |staging| build(source, staging) }
+      end
+
+      # Builds the copy in a staging directory beside the target and renames it into place, so a
+      # second process never sees, or deletes, a half-made copy; the loser of a race discards its
+      # own staging directory and uses the winner's.
+      def publish(target)
+        FileUtils.mkdir_p(File.dirname(target))
+        staging = "#{target}.tmp-#{Process.pid}-#{SecureRandom.hex(4)}"
+        yield staging
+        install(staging, target)
+      ensure
+        FileUtils.rm_rf(staging) if staging
+      end
+
+      # Only a directory without the marker, left by an older interrupted copy, is cleared away.
+      def install(staging, target)
+        File.rename(staging, target)
+        target
+      rescue Errno::ENOTEMPTY, Errno::EEXIST
+        return target if File.exist?(File.join(target, MARKER))
+
+        FileUtils.rm_rf(target)
+        File.rename(staging, target)
+        target
+      end
+
+      def build(source, staging)
+        FileUtils.mkdir_p(staging)
+        PACKAGED.each { |entry| copy_entry(source, staging, entry) }
+        clean_features(File.join(staging, "Cargo.toml"))
+        File.write(File.join(staging, MARKER), "#{@version}\n")
+      end
+
+      # The packaged manifest lists a feature per corpus domain, and `default` names one of them.
+      # None of those domains is in a copy, so the list starts empty and the generator adds the
+      # client's own.
+      def clean_features(manifest)
+        return unless File.exist?(manifest)
+
+        File.write(manifest, File.read(manifest).sub(FEATURES_TABLE, "[features]\ndefault = []\n"))
+      end
+
+      def copy_entry(source, target, entry)
+        from = File.join(source, entry)
+        return unless File.exist?(from)
+
+        Find.find(from) do |path|
+          relative = path.delete_prefix("#{source}/")
+          Find.prune if SKIPPED.call(relative)
+          destination = File.join(target, relative)
+          File.directory?(path) ? FileUtils.mkdir_p(destination) : FileUtils.cp(path, destination)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/shell.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/shell"
+
+Hecks.adapter "Shell" do
+  port "Shell"
+end

data/lib/hecks/hecks/adapters/shell.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module Adapters
+    # The `Shell` port's adapter: runs one program with its arguments and hands back what it said.
+    #
+    # It is the single place a Custodian adapter starts a subprocess through, so `Git` builds on it
+    # rather than calling `Open3` itself. The command is an argument list, never a string for a
+    # shell to split, so nothing a caller passes is interpreted.
+    class Shell
+      # What a program said and how it ended.
+      #
+      # @!attribute [r] out
+      #   @return [String] what it wrote to stdout
+      # @!attribute [r] err
+      #   @return [String] what it wrote to stderr
+      # @!attribute [r] status
+      #   @return [Process::Status] how it ended
+      Result = Struct.new(:out, :err, :status) do
+        # @return [Boolean] whether the program ended with status 0
+        def ok? = status.success?
+      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
+
+      # Runs a program and waits for it.
+      #
+      # @param command [Array<String>] the program, then its arguments
+      # @param env [Hash{String => String, nil}] variables to set for it; nil unsets one
+      # @param chdir [String, nil] the directory to run it in
+      # @return [Result] its output and status; a program that is not installed is a `Result` with
+      #   status 127 and its reason in `err`, not a raise
+      def capture(*command, env: {}, chdir: nil)
+        options = chdir ? { chdir: chdir } : {}
+        out, err, status = Open3.capture3(env, *command, **options)
+        Result.new(out, err, status)
+      rescue Errno::ENOENT => e
+        Result.new("", e.message, Struct.new(:success?, :exitstatus).new(false, 127))
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/terminal.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/terminal"
+
+Hecks.adapter "Terminal" do
+  port "Terminal"
+end

data/lib/hecks/hecks/adapters/terminal.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require "hecks/cli/console"
+
+module Hecks
+  module Adapters
+    # The `Terminal` port's adapter: the sessions an operator or a program drives through stdin and
+    # stdout, an IRB console (`open`) or the stdio MCP door (`serve`).
+    #
+    # The journal records that a session was opened and how it ended, not what was said in it.
+    # Each starts here and nowhere else; a caller that must not open a real session (a spec)
+    # replaces the launcher with `Terminal.launcher=` or the server with `Terminal.server=`.
+    class Terminal
+      class << self
+        # @return [#call, nil] starts the interactive session; IRB when nil
+        attr_accessor :launcher
+
+        # @return [#call, nil] serves MCP over stdio, given the arguments after the command;
+        #   `Hecks::CLI::Mcp.call` when nil
+        attr_accessor :server
+      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
+
+      # Boots the record's domain and drops into an interactive console; returns when the
+      # session ends.
+      #
+      # @param held [Hash] the `Operation` record: `subject` is the domain directory, or absent
+      #   for the bundled pizzas domain
+      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the session ended
+      def open(**held)
+        subject = held[:subject]
+        domain  = subject.is_a?(Hash) ? subject[:value] : subject
+        launcher = self.class.launcher
+        launcher ? CLI::Console.call(domain, launcher: launcher) : CLI::Console.call(domain)
+
+        { output: { value: "console session ended (#{domain || 'pizzas'})" } }
+      end
+
+      # Hands the process over to the MCP door until the client closes stdin. The door writes its
+      # JSON-RPC on stdout, so nothing here is captured, and the launcher's own answer follows
+      # only once the client is gone.
+      #
+      # @param held [Hash] the `Door` record: `stdio` (whether `--stdio` was given)
+      # @return [Hash{Symbol => Hash}] `output:` a one-line note that the door closed
+      # @raise [ConsoleCapture::Failure] when the process is not set up for stdio: the door
+      #   refused to start, and said why on stderr
+      def serve(**held)
+        argv = plain(held[:stdio]) ? ["--stdio"] : []
+        server = self.class.server
+        if server
+          server.call(argv)
+        else
+          require "hecks/cli/mcp"
+          CLI::Mcp.call(argv)
+        end
+
+        { output: { value: "mcp door closed" } }
+      rescue SystemExit => e
+        raise ConsoleCapture::Failure, "the mcp door refused to start (status #{e.status}); see stderr"
+      end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/codebase.behaviors

@@ -0,0 +1,172 @@
+Hecks.behaviors "Codebase" do
+  vision "A request to work on this repository is recorded, the tree is examined, and only a hecks checkout lets it through."
+
+  loads "hecks.bluebook", "custodian.bluebook", "codebase.bluebook", "context_map.hecksagon", "hecks.hecksagon", "environments/memory.world"
+
+  test "ProjectModel reports what the language projects, and keeps the answer" do
+    tests "ProjectModel", on: "LanguageRun"
+    input run: { value: "model" }
+    expect emits: %w[ProjectModelRequested LanguageExamined LanguageAccepted LanguageAnswered LanguageCompleted]
+  end
+
+  test "ProjectRefusalWording is a second name that carries out the same projection" do
+    tests "ProjectRefusalWording", on: "LanguageRun"
+    input run: { value: "wording" }
+    expect emits: %w[ProjectRefusalWordingRequested LanguageExamined LanguageAccepted LanguageAnswered LanguageCompleted]
+  end
+
+  test "Propose rehearses a new word and writes nothing without confirm" do
+    tests "Propose", on: "LanguageRun"
+    input word: { value: "no_such_word" }, context: { value: "Aggregate" }, run: { value: "propose" }
+    expect emits: %w[ProposeRequested LanguageExamined LanguageAccepted LanguageAnswered LanguageCompleted]
+  end
+
+  test "Propose refuses a body the language does not have" do
+    tests "Propose", on: "LanguageRun"
+    input word: { value: "no_such_word" }, context: { value: "Aggregate" }, body: { value: "everything" },
+          run: { value: "propose" }
+    expect refused: "must match"
+  end
+
+  test "Admit keeps a word that is not declared as a faulted request" do
+    tests "Admit", on: "LanguageRun"
+    input word: { value: "no_such_word" }, context: { value: "Aggregate" }, run: { value: "admit" }
+    expect emits: %w[AdmitRequested LanguageExamined LanguageAccepted LanguageRefused LanguageFaulted]
+  end
+
+  test "ProposeArgument refuses a kind of argument the language does not have" do
+    tests "ProposeArgument", on: "LanguageRun"
+    input word: { value: "no_such_word" }, context: { value: "Aggregate" }, kind: { value: "blob" },
+          run: { value: "argument" }
+    expect refused: "must match"
+  end
+
+  test "ProjectKernelCapabilities reports what the grammar projects, and keeps the answer" do
+    tests "ProjectKernelCapabilities", on: "KernelRun"
+    input run: { value: "kernel" }
+    expect emits: %w[ProjectKernelCapabilitiesRequested KernelExamined KernelAccepted KernelAnswered KernelCompleted]
+  end
+
+  test "MeasureKernelCoverage keeps a complete kernel as a completed measure" do
+    tests "MeasureKernelCoverage", on: "KernelRun"
+    input run: { value: "coverage" }
+    expect emits: %w[MeasureKernelCoverageRequested KernelExamined KernelAccepted KernelAnswered KernelCompleted]
+  end
+
+  test "CheckEngineAgreement keeps agreeing engines as a completed check" do
+    tests "CheckEngineAgreement", on: "ConformanceRun"
+    input run: { value: "engines" }
+    expect emits: %w[CheckEngineAgreementRequested ConformanceExamined ConformanceAccepted ConformanceAnswered
+                     ConformanceCompleted]
+  end
+
+  test "MeasureDocCoverage keeps a covered reference as a completed measure" do
+    tests "MeasureDocCoverage", on: "ConformanceRun"
+    input run: { value: "docs" }
+    expect emits: %w[MeasureDocCoverageRequested ConformanceExamined ConformanceAccepted ConformanceAnswered
+                     ConformanceCompleted]
+  end
+
+  test "ArgumentGateMatrix refuses a run that is not named" do
+    tests "ArgumentGateMatrix", on: "ConformanceRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "RegenerateCorpus refuses a run that is not named" do
+    tests "RegenerateCorpus", on: "RegenerationRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "CheckComments keeps a file with no violations as a completed check" do
+    tests "CheckComments", on: "StyleRun"
+    input paths: { value: "lib/hecks/canonical_json.rb" }, run: { value: "clean" }
+    expect emits: %w[CheckCommentsRequested StyleExamined StyleAccepted StyleAnswered StyleCompleted]
+  end
+
+  test "CheckComments refuses a list of paths that is not one" do
+    tests "CheckComments", on: "StyleRun"
+    input paths: { value: "lib, spec" }, run: { value: "paths" }
+    expect refused: "must match"
+  end
+
+  test "FixComments lists what it would rewrite, and writes nothing, without confirm" do
+    tests "FixComments", on: "StyleRun"
+    input paths: { value: "lib/hecks/canonical_json.rb" }, run: { value: "fix" }
+    expect emits: %w[FixCommentsRequested StyleExamined StyleAccepted StyleAnswered StyleCompleted]
+  end
+
+  test "CheckCommentsUnchanged refuses a ref with a space in it" do
+    tests "CheckCommentsUnchanged", on: "StyleRun"
+    input ref: { value: "not a ref" }, run: { value: "unchanged" }
+    expect refused: "must match"
+  end
+
+  test "Canonicalise keeps a file that is not there as a faulted request" do
+    tests "Canonicalise", on: "StyleRun"
+    input file: { value: "/tmp/hecks-behaviors-absent/file.json" }, run: { value: "canonical" }
+    expect emits: %w[CanonicaliseRequested StyleExamined StyleAccepted StyleRefused StyleFaulted]
+  end
+
+  test "HoistLocalGivens refuses a run that is not named" do
+    tests "HoistLocalGivens", on: "CodemodRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "RunSpecExample keeps a spec file that is not there as a faulted request" do
+    tests "RunSpecExample", on: "TestSuiteRun"
+    input file: { value: "spec/no_such_spec.rb" }, example: { value: "works" }, run: { value: "example" }
+    expect emits: %w[RunSpecExampleRequested TestSuiteExamined TestSuiteAccepted TestSuiteRefused TestSuiteFaulted]
+  end
+
+  test "StressConcurrency refuses a count of zero runs" do
+    tests "StressConcurrency", on: "TestSuiteRun"
+    input runs: { value: 0 }, run: { value: "stress" }
+    expect refused: "a count is positive"
+  end
+
+  test "RefreshRuntimeBaseline refuses a run that is not a number" do
+    tests "RefreshRuntimeBaseline", on: "TestSuiteRun"
+    input from_run: { value: "latest" }, run: { value: "baseline" }
+    expect refused: "must match"
+  end
+
+  test "RegenerateLegacyFixtures reports what it would rewrite, and rewrites nothing, without confirm" do
+    tests "RegenerateLegacyFixtures", on: "TestSuiteRun"
+    input run: { value: "fixtures" }
+    expect emits: %w[RegenerateLegacyFixturesRequested TestSuiteExamined TestSuiteAccepted TestSuiteAnswered
+                     TestSuiteCompleted]
+  end
+
+  test "SeedSemanticsCorpus refuses a fixture name that is not a file name" do
+    tests "SeedSemanticsCorpus", on: "TestSuiteRun"
+    input fixture: { value: "Not A Name" }, run: { value: "seed" }
+    expect refused: "must match"
+  end
+
+  test "Present refuses a port that is not one" do
+    tests "Present", on: "CorpusRun"
+    input port: { value: 70_000 }, run: { value: "present" }
+    expect refused: "a port is 1 to 65535"
+  end
+
+  test "ServeQueryIrMcp refuses a run that is not named" do
+    tests "ServeQueryIrMcp", on: "CorpusRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "Publish refuses a run that is not named" do
+    tests "Publish", on: "PublishingRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "PublishGem refuses a run that is not named" do
+    tests "PublishGem", on: "PublishingRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+end