hecks 2.7.0 → 2.9.0

data/lib/hecks/bluebook/value_object.rb

@@ -5,48 +5,25 @@ module Hecks
   module Bluebook
     Invariant = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
-    # A value object — a declaration holder, never instantiated.
-    #
-    # `ValueObjectBuilder` returns an anonymous subclass whose singleton
-    # carries the declaration : attributes, invariants, members. Nothing ever
-    # calls `.new` on one — coercion builds `Runtime::Value` wrappers, and
-    # invariants run as canonical text through the Evaluator. The runtime
-    # reaches a shape through `aggregate.value_object(name)`, the IR's own
-    # finder ; there is no constant nesting and no second index.
-    #
-    # `to_h` does not move. It is a byte-for-byte contract pinned by the
-    # golden fixtures, so it keeps spelling the short declared name, which
-    # is what `hecks_name` carries. Declarations in the graph, strings in the
-    # export.
+    # A value object: a declaration holder, never instantiated.
+    # `ValueObjectBuilder` returns a subclass carrying attributes, invariants and members;
+    # reach one through `aggregate.value_object(name)`.
+    # `to_h` spells the short declared name (`hecks_name`), a contract pinned by golden fixtures.
     class ValueObject
       extend Construct
-      # Extended, not included — this construct is a class, so its
-      # emission is a class method. See Hecks::IR's own note on
-      # the two shapes.
+      # Extended, not included: this construct is a class, so emission is a class method.
       extend Hecks::IR
       extend Behaviour::ValueObject
 
       emits_ir(
         name:       :hecks_name,
         attributes: many(:attributes),
-        # `ast:` — a JSON-serializable rendering of the same predicate
-        # `canonical` already spells as text, alongside it rather than
-        # replacing it (`canonical` stays the human-facing/doctest-facing
-        # form; parsing it back would just re-derive what `ast` already
-        # states directly). Ground truth and the full reasoning:
-        # `Expression::AstJson`'s own header — built for `rust/host`'s
-        # own mint-time invariant check (`reference_validate.rs`), which
-        # has no kernel crate to parse `canonical` with.
+        # `ast` sits beside `canonical` because rust/host's mint-time invariant check
+        # has no kernel crate to parse `canonical` with (see `Expression::AstJson`).
         invariants: -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         closed_set: :closed_set?,
-        # The field name is stringified, never the value. A `member` row can
-        # hold any of the scalar types an attribute declares — `Integer 84`
-        # (`StatementFrequency#retention_months`, statements.bluebook), not
-        # only `String` — and stringifying it on the way out would erase
-        # that: `84` and `"84"` (a member some other row might legitimately
-        # spell as text) would become indistinguishable once they reached
-        # `to_h`. The declared name still moves (`field.to_s`) — that half
-        # was never a Ruby object with a type to lose.
+        # Only the field name is stringified: a member value can be an Integer, and
+        # stringifying it would make `84` and `"84"` indistinguishable in `to_h`.
         members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value] } } }
       )
 
@@ -57,10 +34,8 @@ module Hecks
         # the bluebook declares and the thing Ruby holds are one object.
         #
         # @param name [String, Symbol] the value object's declared type name
-        # @param attributes [Array<Bluebook::Attribute>] the value object's declared
-        #   fields
-        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every
-        #   instance of this value object
+        # @param attributes [Array<Bluebook::Attribute>] the value object's declared fields
+        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every instance
         # @param members [Array<Hash{Symbol => Object}>] the declared `one_of` members, one
         #   row of field values per member
         # @param closed_set [Boolean] whether a `one_of` was declared, even with no

data/lib/hecks/bluebook.rb

@@ -1,36 +1,19 @@
-# Hecks::Bluebook
-#
-# Everything a .bluebook file becomes on its way to running: the expression
-# language (expression/), the model itself (the chapter class plus
-# everything it declares), the assembly that turns
-# declarations back into that graph (assembly.rb + assembly/), the authoring
-# DSL (dsl/), and the meta-validator that judges a chapter against the
-# language's own grammar (meta_validator.rb + meta_validator/).
-#
-# The require order below matters: expression and IR load first (pure
-# declarations), assembly's collaborators load before its face, and the DSL
-# loads before the meta-validator that its builders call at build time.
+# Everything a .bluebook file becomes on its way to running: expression language, model,
+# assembly, authoring DSL and meta-validator.
 
 module Hecks
-  # Declared as a class, not a module — `Hecks::Bluebook` is a
-  # chapter (bluebook/chapter.rb carries its body). Everything a chapter
-  # declares nests under it, as do the ways to build one (`DSL`) and to
-  # judge one (`MetaValidator`). Reopening this anywhere must say `class`.
+  # `Hecks::Bluebook` is a class defined in bluebook/chapter.rb; reopen it with `class`.
   module Bluebook
   end
 end
 
-# What the chapter's own files lean on at class-body level (`extend
-# Construct`, the assembly's QuerySpecification marks) — required here
-# because those files' contents are frozen and cannot say so themselves.
+# Required here because the chapter's frozen files lean on these at class-body level.
+# Load order: expression and IR first, assembly's collaborators before its face, DSL last.
 require_relative "construct"
 require_relative "literal"
 require_relative "query_specification"
 
 require_relative "bluebook/expression"
-# **The model itself** — the chapter class's own body first, then everything
-# a chapter declares. Order matters only for reading: each is a bag of
-# declarations with no load-time cross-references.
 require_relative "bluebook/chapter"
 require_relative "bluebook/reference"
 require_relative "bluebook/attribute"

data/lib/hecks/cache_dir.rb

@@ -0,0 +1,84 @@
+require "etc"
+require "fileutils"
+require "tmpdir"
+
+module Hecks
+  # The one place the runtime's own scratch files live, outside the gem: an
+  # installed gem is read-only, and a checkout's `tmp/` isn't this library's to assume.
+  #
+  # A candidate root is used only if it is private to the current user, since the
+  # syntax-boot cache it holds is read back with `Marshal.load`.
+  module CacheDir
+    module_function
+
+    # The directory a named piece of scratch state lives in.
+    #
+    # @param name [String] the subdirectory, such as `"storehouse"`
+    # @return [String] the absolute path of `name` under the cache root; the
+    #   directory itself is created by whoever writes to it
+    def path(name)
+      File.join(root, name)
+    end
+
+    # The cache root, resolved once per process.
+    #
+    # @return [String] the absolute path of the directory every `path` lives under
+    def root
+      @root ||= resolve
+    end
+
+    # Forgets the resolved root so the next call resolves again.
+    #
+    # @return [void]
+    def reset!
+      @root = nil
+    end
+
+    # Picks the cache root from the environment.
+    #
+    # @param env [Hash{String => String}] the environment to read
+    #   `XDG_CACHE_HOME` and `HOME` from
+    # @param tmpdir [String] the system temp directory
+    # @param uid [Integer] the current user id, used in the temp fallback's name
+    # @return [String] the absolute path of the first candidate that is a
+    #   private directory owned by this user, else a per-process directory
+    def resolve(env: ENV, tmpdir: Dir.tmpdir, uid: Process.uid)
+      candidates(env, tmpdir, uid).each do |candidate|
+        return candidate if private_dir?(candidate)
+      end
+      Dir.mktmpdir("hecks-", tmpdir)
+    rescue StandardError
+      File.join(tmpdir, "hecks-#{uid}")
+    end
+
+    # The roots to try, most preferred first.
+    #
+    # @param env [Hash{String => String}] the environment
+    # @param tmpdir [String] the system temp directory
+    # @param uid [Integer] the current user id
+    # @return [Array<String>] absolute candidate paths
+    def candidates(env, tmpdir, uid)
+      xdg  = env["XDG_CACHE_HOME"].to_s
+      home = env["HOME"].to_s
+      list = []
+      list << File.join(xdg, "hecks") if File.absolute_path?(xdg)
+      list << File.join(home, ".cache", "hecks") if File.absolute_path?(home)
+      list << File.join(tmpdir, "hecks-#{uid}")
+    end
+    private_class_method :candidates
+
+    # Creates `dir` if needed and says whether it is private to this user.
+    #
+    # @param dir [String] the candidate directory
+    # @return [Boolean] true when `dir` is a directory owned by this user that
+    #   no other user can write to; false on any failure
+    def private_dir?(dir)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      stat = File.stat(dir)
+      stat.directory? && stat.owned? && stat.mode.nobits?(0o022) && File.writable?(dir)
+    rescue StandardError
+      false
+    end
+    private_class_method :private_dir?
+  end
+end

data/lib/hecks/cli/document.rb

@@ -0,0 +1,86 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/docs`, `bin/narrate`, `hecks docs` and `hecks narrate`:
+    # one domain's document, projected from its own bluebook, to stdout.
+    #
+    # Nothing is written for the caller: redirect it, so git decides whether it drifted.
+    module Document
+      # Build output and other trees under a root that hold no domain a caller means.
+      # Matched against the path relative to the root, because a substring test
+      # against an absolute path tests wherever somebody happened to clone.
+      IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
+
+      module_function
+
+      # Prints `projection` for the domain and optional aggregate `argv` names.
+      #
+      # @param argv [Array<String>] an optional domain directory, then an optional
+      #   aggregate name
+      # @param projection [Symbol] `:docs` or `:narrate`
+      # @param program [String] the name the usage message calls this command by
+      # @param root [String] the directory whose domains are listed when no domain
+      #   is found
+      # @return [void]
+      # @raise [SystemExit] when no domain is found, it cannot boot, it loads no
+      #   bluebook, or the aggregate does not exist
+      def call(argv, projection:, program:, root:)
+        here = Adapters::Folder.new.domain_root
+        path, aggregate = target(argv, here)
+        refuse_without_domain(program, root) unless path
+
+        begin
+          runtime = Hecks.boot(path, install_facade: false)
+        rescue StandardError => e
+          abort "cannot read #{path}: #{e.message.lines.first.strip}"
+        end
+
+        # The domain's own chapter, not a framework member it attached: insertion
+        # order, the same distinction `Runtime::Loader.dispatcher_for` draws.
+        bluebook = runtime.registry.bluebooks.values.first
+        abort "#{path} loaded no bluebook" unless bluebook
+
+        begin
+          puts Projector.call(projection, bluebook: bluebook, options: aggregate ? { aggregate: aggregate } : {})
+        rescue Runtime::NotFound => e
+          abort e.message
+        end
+      end
+
+      # Lists every directory under `root` that `Hecks.boot` would accept.
+      #
+      # Found by their wiring, not their chapters: a `.hecksagon` says this is a
+      # domain, while most `.bluebook` files (era translations, grammar, fixtures) are not.
+      #
+      # @param root [String] the directory to search under
+      # @return [Array<String>] domain directory paths relative to `root`,
+      #   deduplicated and sorted
+      def domains(root)
+        Dir.glob(File.join(root, "**/*.hecksagon"))
+           .map    { |path| File.basename(File.dirname(path)) == "bluebook" ? File.dirname(path, 2) : File.dirname(path) }
+           .map    { |path| path.delete_prefix("#{root}/") }
+           .grep_v(IGNORED)
+           .uniq.sort
+      end
+
+      # @api private
+      def target(argv, here)
+        if argv.empty?              then [here, nil]
+        elsif argv.length > 1       then [argv[0], argv[1]]
+        elsif File.directory?(argv[0]) then [argv[0], nil]
+        else [here, argv[0]]
+        end
+      end
+
+      # @api private
+      def refuse_without_domain(program, root)
+        warn "usage: #{program} [domain-path] [aggregate]"
+        warn ""
+        warn "No bluebook here — #{Dir.pwd} is not inside a domain. Name one:"
+        domains(root).each { |candidate| warn "  #{candidate}" }
+        exit 1
+      end
+    end
+  end
+end

data/lib/hecks/cli/ir.rb

@@ -0,0 +1,45 @@
+require_relative "../../hecks"
+# ADR 0033 — a domain wired to PostgresEra needs this plugin loaded
+# explicitly; the era/lineage subsystem does not load with core.
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `bin/ir` and `hecks ir`: a booted domain's IR as JSON, the
+    # same `to_h` the golden specs pin and `StorageShape` hashes into an era.
+    module Ir
+      module_function
+
+      # Prints the IR `argv` asks for.
+      #
+      # `--meta` prints the language's own IR, reached through
+      # `Bluebook::MetaValidator.grammar_registry`, the real boot sequence, so it
+      # can't drift from what `MetaValidator` loads.
+      #
+      # @param argv [Array<String>] a domain path and `--translations`, or `--meta`
+      # @param program [String] the name the usage message calls this command by
+      # @param default_domain [String, nil] the domain booted when `argv` names none;
+      #   nil makes a domain argument required
+      # @return [void]
+      # @raise [SystemExit] when no domain is named and there is no default
+      def call(argv, program:, default_domain: nil)
+        argv = argv.dup
+        if argv.delete("--meta")
+          require_relative "../bluebook/meta_validator"
+          puts Projector::Exporter.json(Bluebook::MetaValidator.grammar_registry)
+          return
+        end
+
+        translations_only = argv.delete("--translations")
+        domain = argv.shift || default_domain or abort "usage: #{program} <domain> [--translations] | #{program} --meta"
+        runtime = Hecks.boot(domain)
+
+        if translations_only
+          puts Projector::Exporter.translations_json(runtime.registry)
+        else
+          puts Projector::Exporter.json(runtime.registry)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/mcp.rb

@@ -0,0 +1,31 @@
+require_relative "../mcp_stdio_guard"
+
+module Hecks
+  module CLI
+    # The command behind `bin/hecks_mcp_door` and `hecks mcp`: the MCP door onto the
+    # storehouse bus, over stdio only.
+    #
+    # This file loads nothing but `McpStdioGuard`, so the transport check runs
+    # before the framework does.
+    module Mcp
+      # The server name the guard's refusals and warnings carry.
+      SERVER = "hecks-mcp-door".freeze
+
+      module_function
+
+      # Refuses any transport but stdio, then serves JSON-RPC requests from stdin
+      # until it closes.
+      #
+      # @param argv [Array<String>] the arguments after the command; only `--stdio`
+      #   is accepted
+      # @return [void]
+      # @raise [SystemExit] with `McpStdioGuard::EXIT_STATUS` when the process is not
+      #   set up for stdio
+      def call(argv)
+        McpStdioGuard.enforce_stdio!(server: SERVER, argv: argv)
+        require_relative "mcp_door"
+        McpDoor.serve
+      end
+    end
+  end
+end