hecks 2.9.0 → 3.0.0

data/lib/hecks/rust_build/coverage.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "tmpdir"
+require_relative "../rust_build"
+
+module Hecks
+  module RustBuild
+    # Reports whether each construct in a domain's IR has a real, routed implementation under
+    # `<workspace>/src/generated/<domain>` (ADR 0054a).
+    #
+    #   Coverage.call([domain, "--codegen=ruby|rust"])
+    #   Coverage.call(["--check-allowlist"])
+    #
+    # Ground truth is the generated module's `ir.json` and its `manifest.json`; a construct in the
+    # IR that the manifest omits is a synthetic `unaccounted` finding. The exit status is 1 when a
+    # gap remains that the allowlist does not excuse.
+    module Coverage
+      USAGE = "usage: hecks rust_coverage <generated-module-name> [--codegen=ruby|rust]  " \
+              "(e.g. pizzas, banking, governance, identity)\n       hecks rust_coverage --check-allowlist"
+
+      # Deliberate, documented gaps only, matched by kind, gap class and construct (never a regex
+      # over `reason` prose). The list only shrinks: `--check-allowlist` fails once a rule excuses
+      # no gap anywhere.
+      ALLOWLIST = [].freeze
+
+      module_function
+
+      # @param argv [Array<String>] the generated module's name and optional `--codegen=` flag,
+      #   or `--check-allowlist`
+      # @return [Integer] 0 when nothing is a gap, 1 otherwise
+      # @raise [Failure] when the module, its `ir.json` or its manifest is missing
+      def call(argv)
+        flags, positional = argv.partition { |arg| arg.start_with?("--codegen") }
+        codegen = flags.empty? ? "ruby" : flags.last.delete_prefix("--codegen=")
+        raise Failure, "--codegen must be `ruby` or `rust` (got #{flags.last.inspect})" unless %w[ruby rust].include?(codegen)
+
+        target = positional.first or raise Failure, USAGE
+        return check_allowlist if target == "--check-allowlist"
+
+        report(target, codegen)
+      end
+
+      def rust_dir = RustBuild.rust_dir
+
+      def generated_root = File.join(rust_dir, "src/generated")
+
+      # Entity-scoped query ids at any depth (`Domain::Aggregate.Entity.Query`); mirrors the
+      # generator's own entity query entries.
+      def entity_query_ids(owner_id, entities)
+        entities.flat_map do |entity|
+          entity_id = "#{owner_id}.#{entity.fetch(:name)}"
+          entity.fetch(:queries, []).map { |q| "#{entity_id}.#{q.fetch(:name)}" } +
+            entity_query_ids(entity_id, entity.fetch(:entities, []))
+        end
+      end
+
+      # The [kind, id] pairs the IR implies, independent of the manifest.
+      def expected_from_ir(payload)
+        domain_name = payload.fetch(:name)
+        expected = payload.fetch(:aggregates).flat_map { |aggregate| aggregate_constructs(domain_name, aggregate) }
+        payload.fetch(:read_models).each { |rm| expected << [:read_model, "#{domain_name}::#{rm.fetch(:name)}"] }
+        payload.fetch(:policies).each { |p| expected << [:policy, "#{domain_name}::#{p.fetch(:name)}"] }
+        payload.fetch(:process_managers).each { |pm| expected << [:process_manager, "#{domain_name}::#{pm.fetch(:name)}"] }
+        # An `ir.json` from before the `lineage` key existed has none: nothing to expect.
+        payload.fetch(:lineage, {}).fetch(:capable_aggregates, []).each do |aggregate|
+          expected << [:lineage_aggregate, "#{domain_name}::#{aggregate.fetch(:name)}"]
+        end
+        expected
+      end
+
+      def aggregate_constructs(domain_name, aggregate)
+        id = "#{domain_name}::#{aggregate.fetch(:name)}"
+        found = [[:aggregate, id]]
+        aggregate.fetch(:commands).each { |c| found << [:command, "#{id}.#{c.fetch(:name)}"] }
+        aggregate.fetch(:queries).each { |q| found << [:query, "#{id}.#{q.fetch(:name)}"] }
+        entity_query_ids(id, aggregate.fetch(:entities)).each { |query_id| found << [:query, query_id] }
+        aggregate.fetch(:entities).each do |entity|
+          entity_id = "#{id}.#{entity.fetch(:name)}"
+          found << [:entity, entity_id]
+          entity.fetch(:commands).each { |c| found << [:entity_command, "#{entity_id}.#{c.fetch(:name)}"] }
+        end
+        aggregate.fetch(:ports).each do |port|
+          port.fetch(:operations).each { |op| found << [:port_operation, "#{id}.#{port.fetch(:name)}.#{op.fetch(:name)}"] }
+        end
+        found
+      end
+
+      # Parses a generated module's `ir.json` and `manifest.json`, adding a synthetic `unaccounted`
+      # finding for any IR construct the manifest omits.
+      def coverage_findings(mod_dir)
+        ir_path = File.join(mod_dir, "ir.json")
+        File.exist?(ir_path) or raise Failure, "#{ir_path}: missing — this generated tree predates ir.json " \
+                                               "(hecks project_rust writes it now); re-run hecks project_rust for this domain"
+        ir = JSON.parse(File.read(ir_path), symbolize_names: true)
+        manifest_path = File.join(mod_dir, "manifest.json")
+        File.exist?(manifest_path) or raise Failure, "#{manifest_path}: missing — re-run hecks project_rust for this " \
+                                                     "domain to write it"
+        manifest = JSON.parse(File.read(manifest_path), symbolize_names: true)
+        [ir, manifest + unaccounted_findings(ir, manifest)]
+      end
+
+      def allowlist_rule_matches?(rule, finding)
+        rule[:kind] == finding[:kind].to_s &&
+          rule[:gap_class] == finding[:gap_class].to_s &&
+          rule[:construct] == finding[:construct].to_s
+      end
+
+      def allowlisted(finding) = ALLOWLIST.find { |rule| allowlist_rule_matches?(rule, finding) }
+
+      # A synthetic finding for each expected construct with no manifest entry at all: a gap in
+      # the manifest writer itself.
+      def unaccounted_findings(payload, manifest)
+        ids = Hash.new { |hash, kind| hash[kind] = Set.new }
+        manifest.each { |entry| ids[entry[:kind].to_sym] << entry[:id] }
+        expected_from_ir(payload).reject { |kind, id| ids[kind].include?(id) }.map do |kind, id|
+          { kind: kind.to_s, id: id, generated: false, gap_class: "unaccounted", construct: "unaccounted",
+            reason: "expected per ir.json, but manifest.json has NO entry for it at all — not even a " \
+                    "recorded skip; the generator's own accounting missed this construct entirely" }
+        end
+      end
+
+      # A real functional gap: not generated, or generated but unrouted.
+      def functional_gap?(finding) = finding[:generated] == false || finding[:routed] == false
+
+      # Every rule must still excuse a real gap somewhere under `src/generated/`.
+      def check_allowlist
+        gaps = Dir.glob(File.join(generated_root, "*/ir.json")).flat_map do |ir_path|
+          coverage_findings(File.dirname(ir_path))[1].select { |finding| functional_gap?(finding) }
+        end
+        stale = ALLOWLIST.reject { |rule| gaps.any? { |finding| allowlist_rule_matches?(rule, finding) } }
+        if stale.empty?
+          puts "hecks rust_coverage --check-allowlist: all #{ALLOWLIST.size} rules still excuse a real gap"
+          return 0
+        end
+        stale.each do |rule|
+          warn "STALE ALLOWLIST RULE: #{rule.slice(:kind, :gap_class, :construct)} matches no gap in any generated " \
+               "module — the gap it excused is gone; delete the rule"
+        end
+        1
+      end
+
+      def report(domain, codegen)
+        mod_dir = File.join(generated_root, domain)
+        Dir.exist?(mod_dir) or raise Failure, "#{mod_dir}: no such generated module — run hecks project_rust first, " \
+                                              "or check rust/src/generated/ for the actual directory name"
+        return print_report(domain, mod_dir) unless codegen == "rust"
+
+        Dir.mktmpdir("rust-coverage-codegen-") do |scratch|
+          print_report(domain, regenerated(mod_dir, domain, scratch))
+        end
+      end
+
+      # Regenerates the domain's manifest through `hecks-codegen` into a scratch directory. `cargo
+      # run` rather than a fixed target path, so `CARGO_TARGET_DIR` and rust-toolchain.toml apply.
+      def regenerated(mod_dir, domain, scratch)
+        ir_path = File.join(mod_dir, "ir.json")
+        File.exist?(File.join(mod_dir, "manifest.json")) or raise Failure, "#{mod_dir}: no committed manifest.json — " \
+                                                                           "re-run hecks project_rust for this domain to write it"
+        out_dir = File.join(scratch, domain)
+        output, status = Open3.capture2e("cargo", "run", "--quiet", "--", "domain", ir_path, domain, domain, out_dir,
+                                         chdir: File.join(rust_dir, "codegen"))
+        status.success? or raise Failure, "hecks-codegen domain failed for #{domain}:\n#{output}"
+        # `hecks-codegen domain` writes no ir.json sidecar; the cross-check reads the committed IR
+        # the generator was just handed.
+        FileUtils.cp(ir_path, File.join(out_dir, "ir.json"))
+        out_dir
+      end
+
+      def print_report(domain, mod_dir)
+        ir, findings = coverage_findings(mod_dir)
+        # A construct is implemented only when generated and routed (where routing applies): a
+        # `dispatch_*` that compiles but nothing can call is not working.
+        implemented, remainder = findings.partition { |f| f[:generated] && f[:routed] != false }
+        deferred, gap = remainder.partition { |f| allowlisted(f) }
+        puts "=" * 72
+        puts "hecks rust_coverage #{domain}  (source: manifest.json)"
+        puts "=" * 72
+        puts "#{ir.fetch(:name)} — #{findings.size} constructs accounted for " \
+             "(#{implemented.size} implemented, #{deferred.size} deferred, #{gap.size} GAP)"
+        print_bucket("IMPLEMENTED", implemented) unless implemented.empty?
+        print_deferred(deferred)
+        print_gaps(gap)
+        puts
+        gap.empty? ? 0 : 1
+      end
+
+      def print_bucket(label, entries)
+        puts "\n#{label} (#{entries.size})"
+        sorted(entries).each { |entry| print_entry(entry) }
+      end
+
+      def print_deferred(deferred)
+        puts "\nDEFERRED (#{deferred.size}) — on the allowlist, with its cited reason"
+        sorted(deferred).each do |entry|
+          puts "  [#{entry[:kind]}] #{entry[:id]}"
+          puts "      allowlist: #{allowlisted(entry)[:doc]}"
+        end
+      end
+
+      def print_gaps(gap)
+        puts "\nGAP (#{gap.size}) — missing, and NOT on the allowlist: a real, actionable finding"
+        sorted(gap).each { |entry| print_entry(entry) }
+      end
+
+      def print_entry(entry)
+        line = "  [#{entry[:kind]}] #{entry[:id]}"
+        line += " (#{entry[:gap_class]})" if entry[:gap_class]
+        puts line
+        puts "      #{entry[:reason]}" if entry[:reason]
+      end
+
+      def sorted(entries) = entries.sort_by { |entry| [entry[:kind].to_s, entry[:id]] }
+    end
+  end
+end

data/lib/hecks/rust_build/native_build.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "open3"
+
+module Hecks
+  module RustBuild
+    # Builds the native binary for one generated domain's Cargo feature, once per workspace.
+    #
+    # Examples interleave, and alternating `--features` builds forces a full recompile each time,
+    # so a built binary is cached per `[rust_dir, feature, sources]`, where `sources` is a digest of
+    # the workspace's Rust sources and manifests. Regenerating the domain changes the digest, so the
+    # next call rebuilds instead of answering with a stale binary or a stale failure.
+    module NativeBuild
+      # Raised when a declared feature fails to build; nil is reserved for "feature not declared".
+      class BuildFailed < StandardError; end
+
+      @cache = {}
+
+      class << self
+        # @return [Hash{Array => String, BuildFailed, nil}] each build's answer, keyed by
+        #   `[rust_dir, feature, sources_digest]`
+        attr_reader :cache
+      end
+
+      module_function
+
+      # Builds the binary for `domain_feature` once per (rust_dir, feature, sources) and
+      # memoizes the result.
+      #
+      # @param domain_feature [String] the Cargo feature, a domain's directory basename
+      # @param rust_dir [String] the workspace to build in
+      # @return [String, nil] the pinned binary, or nil when Cargo.toml declares no such feature
+      # @raise [BuildFailed] when the build fails (memoized too)
+      def build_rust_for(domain_feature, rust_dir)
+        cache = NativeBuild.cache
+        key = [rust_dir, domain_feature, sources_digest(rust_dir)]
+        if cache.key?(key)
+          raise cache[key] if cache[key].is_a?(BuildFailed)
+
+          return cache[key]
+        end
+
+        manifest = File.read(File.join(rust_dir, "Cargo.toml"))
+        return cache[key] = nil unless manifest =~ /^#{Regexp.escape(domain_feature)}\s*=\s*\[\]/
+
+        begin
+          cache[key] = build_and_pin(domain_feature, rust_dir)
+        rescue BuildFailed => e
+          cache[key] = e
+          raise
+        end
+      end
+
+      # Fingerprints what a build reads: every `.rs`, `.toml` and `Cargo.lock` file under the
+      # workspace outside `target/`, by path, size and modification time.
+      #
+      # @param rust_dir [String] the workspace
+      # @return [String] a hex digest that changes when any of those files does
+      def sources_digest(rust_dir)
+        digest = Digest::SHA256.new
+        Dir.glob(File.join(rust_dir, "**", "*.{rs,toml}"), File::FNM_DOTMATCH).sort.each do |path|
+          digest_file(digest, path, rust_dir)
+        end
+        lock = File.join(rust_dir, "Cargo.lock")
+        digest_file(digest, lock, rust_dir) if File.file?(lock)
+        digest.hexdigest
+      end
+
+      def digest_file(digest, path, rust_dir)
+        relative = path.delete_prefix("#{rust_dir}/")
+        return if relative.start_with?("target/") || !File.file?(path)
+
+        stat = File.stat(path)
+        digest << "#{relative}\0#{stat.size}\0#{stat.mtime.to_i}.#{stat.mtime.nsec}\n"
+      end
+
+      # Holds an exclusive flock from `cargo build` through the copy-out: parallel sweeps share
+      # `target/debug/rust`, and another build could overwrite it before it is pinned. The lock
+      # file is left on disk.
+      #
+      # @param domain_feature [String] the Cargo feature
+      # @param rust_dir [String] the workspace to build in
+      # @return [String] the binary, pinned to `target/debug/rust-<feature>`
+      # @raise [BuildFailed] when the build fails or leaves no binary
+      def build_and_pin(domain_feature, rust_dir)
+        lock_path = File.join(rust_dir, "target", ".build_rust_for.lock")
+        FileUtils.mkdir_p(File.dirname(lock_path))
+
+        File.open(lock_path, File::CREAT | File::RDWR) do |lock|
+          lock.flock(File::LOCK_EX)
+          command = ["cargo", "build", "--no-default-features", "--features", domain_feature]
+          cargo(command, rust_dir, domain_feature)
+          pin(rust_dir, domain_feature, command)
+        end
+      end
+
+      def cargo(command, rust_dir, domain_feature)
+        _stdout, stderr, status = Open3.capture3(*command, chdir: rust_dir)
+        return if status.success?
+
+        raise BuildFailed, "`#{command.join(' ')}` failed in #{rust_dir} (exit #{status.exitstatus}) — " \
+                           "#{domain_feature} is declared in Cargo.toml, so this is a build failure, " \
+                           "not a missing feature:\n#{stderr}"
+      rescue SystemCallError => e
+        raise BuildFailed, "`#{command.join(' ')}` could not run in #{rust_dir}: #{e.message}"
+      end
+
+      # `cargo build` always writes the same path; it is pinned per feature while the lock is held.
+      def pin(rust_dir, domain_feature, command)
+        binary = File.join(rust_dir, "target", "debug", "rust")
+        unless File.executable?(binary)
+          raise BuildFailed, "`#{command.join(' ')}` succeeded in #{rust_dir} but left no executable at #{binary}"
+        end
+
+        pinned = File.join(rust_dir, "target", "debug", "rust-#{domain_feature}")
+        FileUtils.cp(binary, pinned)
+        File.chmod(0o755, pinned)
+        pinned
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/project_rust/root_mod.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Hecks
+  module RustBuild
+    class ProjectRust
+      # Writes `src/generated/mod.rs`: a `pub mod` per generated directory, the feature-gated
+      # `active` re-export of the selected domain, and a `compile_error!` for each pair of
+      # non-default domain features enabled together.
+      class RootMod
+        # @param file [IO] where the module is written
+        # @param directories [Array<String>] every directory under `src/generated`
+        # @param domains [Array<String>] the directories that carry their own `merged.rs`
+        # @param default [String] the domain this run generated, whose feature is the default
+        def initialize(file, directories, domains, default)
+          @file = file
+          @directories = directories
+          @domains = domains
+          @default = default
+        end
+
+        # @return [void]
+        def write
+          banner
+          modules
+          active_notes
+          reexports
+          conflict_guards
+        end
+
+        private
+
+        def banner
+          @file.puts "// GENERATED by hecks project_rust — re-run it to refresh this list."
+          @file.puts "//"
+          @file.puts "// BUG#25 — every DOMAIN (an entry in `domains`, below: a directory"
+          @file.puts "// carrying its own merged.rs and therefore its own Cargo feature) is"
+          @file.puts "// declared behind that SAME feature, so a broken or absent domain's"
+          @file.puts "// generated code is never even compiled into a build that selects a"
+          @file.puts "// DIFFERENT domain — `cargo build --features waybill` used to pull in"
+          @file.puts "// every OTHER domain's `pub mod` unconditionally, so one domain's own"
+          @file.puts "// non-compiling generated code (a `has_many` field, before this fix)"
+          @file.puts "// broke every feature's build, not just its own. A shared FRAMEWORK"
+          @file.puts "// chapter (governance/identity — no merged.rs of its own, so absent"
+          @file.puts "// from `domains`) stays unconditional: it has no single feature of its"
+          @file.puts "// own to gate behind, and is compiled in by whichever domain(s) attach"
+          @file.puts "// it via `uses_framework`."
+        end
+
+        def modules
+          @directories.each do |name|
+            @file.puts "#[cfg(feature = #{name.inspect})]" if @domains.include?(name)
+            @file.puts "pub mod #{name};"
+          end
+        end
+
+        def active_notes
+          @file.puts
+          @file.puts "// `active` is whichever ONE domain's own merged Store/dispatch table"
+          @file.puts "// is selected by Cargo feature (rust/Cargo.toml, kept in sync with this"
+          @file.puts "// list by hecks project_rust) — kernel/cli.rs imports"
+          @file.puts "// `crate::generated::active::{dispatch_by_name, Store, ...}` unchanged"
+          @file.puts "// no matter which domain that resolves to."
+          @file.puts "//"
+          @file.puts "// DOMAIN FEATURES ARE MUTUALLY EXCLUSIVE (R5) — Cargo has no native"
+          @file.puts "// concept of that, and `default = [#{@default.inspect}]` in"
+          @file.puts "// Cargo.toml stays enabled unless a build passes"
+          @file.puts "// `--no-default-features`, so a plain `cargo build --features banking`"
+          @file.puts "// used to enable BOTH the default domain's feature and banking's,"
+          @file.puts "// producing two `pub use ... as active;` imports and a hard E0252."
+          @file.puts "// Fixed two ways below, entirely mechanically from `domains`/"
+          @file.puts "// `target_mod_name` (this run's new default) — never hand-maintained:"
+          @file.puts "//"
+          @file.puts "//   1. THE DEFAULT DOMAIN'S OWN re-export backs off whenever any OTHER"
+          @file.puts "//      domain feature is also enabled, so it never contends for `active`"
+          @file.puts "//      by accident — `cargo build --features banking` (still implicitly"
+          @file.puts "//      carrying the default feature) now resolves to banking alone,"
+          @file.puts "//      same as if `--no-default-features` had been passed explicitly."
+          @file.puts "//   2. Two NON-default domain features enabled TOGETHER (a genuine,"
+          @file.puts "//      not-accidental conflict — nothing makes that combination"
+          @file.puts "//      meaningful) still fail the build, but with an explicit"
+          @file.puts "//      `compile_error!` naming both features instead of a cryptic"
+          @file.puts "//      \"defined multiple times\"."
+        end
+
+        def reexports
+          @domains.each do |name|
+            other_domains = @domains - [name]
+            if name == @default && !other_domains.empty?
+              guard = other_domains.map { |o| "feature = #{o.inspect}" }.join(", ")
+              @file.puts "#[cfg(all(feature = #{name.inspect}, not(any(#{guard}))))]"
+            else
+              @file.puts "#[cfg(feature = #{name.inspect})]"
+            end
+            @file.puts "pub use #{name}::merged as active;"
+          end
+        end
+
+        def conflict_guards
+          non_default_domains = @domains - [@default]
+          if non_default_domains.size > 1
+            @file.puts
+            @file.puts "// Explicit conflict guard — see point 2 above. Only fires when TWO"
+            @file.puts "// non-default domain features are both turned on; the default"
+            @file.puts "// domain's own feature never reaches here (point 1 already excludes"
+            @file.puts "// it whenever any other domain feature is present)."
+            non_default_domains.combination(2).each do |a, b|
+              @file.puts "#[cfg(all(feature = #{a.inspect}, feature = #{b.inspect}))]"
+              # Plain `a`/`b`/`domains.join` here, never `.inspect` — this whole
+              # line already sits inside one Rust string literal
+              # (`compile_error!("...")`), and `.inspect`'s own quoted form
+              # would nest unescaped double quotes and produce invalid Rust.
+              @file.puts "compile_error!(\"domain features are mutually exclusive — enable only one of: #{@domains.join(', ')} " \
+                         "(both #{a} and #{b} are enabled)\");"
+            end
+          end
+        end
+      end
+    end
+  end
+end