hecks 3.11.0 → 3.13.0

data/lib/hecks/tools/lanes/prebuilt_workflow.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    module Lanes
+      # The workflow that builds and publishes one `PrebuiltBinary` row (ADR 0110): after a push to
+      # `main` that touches the row's crate, it builds the binary on the row's runner and, unless
+      # a release for that key already exists, publishes it with its sha256. What the key is and
+      # where a client looks is `Hecks::RustBuild::PrebuiltBinary`, not anything written here.
+      module PrebuiltWorkflow
+        module_function
+
+        # @param row [Hash{String => String}] a `PrebuiltBinary` row
+        # @return [String] the path of the workflow, relative to the checkout
+        def path(row) = ".github/workflows/publish-#{row["name"]}.yml"
+
+        # @param row [Hash{String => String}] a `PrebuiltBinary` row
+        # @return [String] the workflow
+        def text(row)
+          [*header(row), *trigger(row), *job(row)].join("\n") << "\n"
+        end
+
+        def header(row)
+          name = row["name"]
+          ["name: Publish #{name}", "",
+           "# Generated by hecks project_lanes from the PrebuiltBinary rows of the Vocabulary chapter. Do not hand-edit.",
+           "#",
+           "# Builds #{row["executable"]} from #{row["crate"]} for #{row["target"]} and publishes it as the release",
+           "# #{name}-<key>, where the key is a hash of the crate's build inputs. A client that needs the same",
+           "# bytes downloads it instead of compiling (Hecks::RustBuild::PrebuiltBinary); a key that already has a",
+           "# release is left alone, so a push that changed nothing the build reads publishes nothing."]
+        end
+
+        def trigger(row)
+          ["on:", "  push:", "    branches: [main]", "    paths:", "      - \"#{row["crate"]}/**\"",
+           "      - \".github/workflows/publish-#{row["name"]}.yml\"",
+           "      - \"lib/hecks/rust_build/prebuilt_binary.rb\"",
+           "  workflow_dispatch: {}", "",
+           "concurrency:", "  group: publish-#{row["name"]}", "  cancel-in-progress: false", "",
+           "permissions:", "  contents: write", ""]
+        end
+
+        def job(row)
+          ["jobs:", "  publish:", "    runs-on: #{row["runner"]}", "    timeout-minutes: 40", "    steps:",
+           "      - uses: actions/checkout@v4", "      - uses: ./.github/actions/setup-ruby", *key_step(row),
+           *build_steps(row), *release_step(row)]
+        end
+
+        def key_step(row)
+          ["      - name: Name the release", "        id: key", "        run: |",
+           "          key=$(bundle exec ruby -Ilib -rhecks/rust_build/prebuilt_binary -e \\",
+           "            'puts Hecks::RustBuild::PrebuiltBinary.key(ARGV.fetch(0))' #{row["crate"]})",
+           "          tag=#{row["name"]}-$key",
+           "          echo \"tag=$tag\" >> \"$GITHUB_OUTPUT\"",
+           "          if gh release view \"$tag\" > /dev/null 2>&1; then echo \"exists=true\" >> \"$GITHUB_OUTPUT\"; fi",
+           "        env:", "          GH_TOKEN: ${{ github.token }}"]
+        end
+
+        def build_steps(row)
+          ["      - name: Build #{row["executable"]}", "        if: steps.key.outputs.exists != 'true'",
+           "        working-directory: #{row["crate"]}", "        run: |",
+           "          rustup toolchain install stable --profile minimal",
+           "          rustup run stable cargo build --release --target #{row["target"]} --bin #{row["executable"]}"]
+        end
+
+        def release_step(row)
+          asset = "#{row["executable"]}-#{row["target"]}"
+          ["      - name: Publish the release", "        if: steps.key.outputs.exists != 'true'",
+           "        env:", "          GH_TOKEN: ${{ github.token }}", "          TAG: ${{ steps.key.outputs.tag }}",
+           "        run: |",
+           "          mkdir out",
+           "          cp #{row["crate"]}/target/#{row["target"]}/release/#{row["executable"]} out/#{asset}",
+           "          (cd out && sha256sum #{asset} > #{asset}.sha256)",
+           "          gh release create \"$TAG\" out/#{asset} out/#{asset}.sha256 --prerelease --target \"$GITHUB_SHA\" \\",
+           "            --title \"$TAG\" \\",
+           "            --notes \"#{row["executable"]} for #{row["target"]}, built from #{row["crate"]} at $GITHUB_SHA.\""]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/lanes.rb

@@ -78,5 +78,6 @@ require_relative "lanes/rows"
 require_relative "lanes/ruleset"
 require_relative "lanes/workflow"
 require_relative "lanes/watch_workflow"
+require_relative "lanes/prebuilt_workflow"
 require_relative "lanes/files"
 require_relative "lanes/live"

data/lib/hecks/tools/oidc_manifests.rb

@@ -6,7 +6,8 @@ require_relative "../tools"
 module Hecks
   module Tools
     # Projects each domain's OIDC client and scope manifest (`Hecks::Projections::OIDC`) into an
-    # `oidc.json` beside the domain.
+    # `oidc.json` beside the domain, or into one `<chapter>.oidc.json` for each chapter of a
+    # directory that holds several.
     #
     # A domain that has no bluebook is skipped and one that cannot be projected is reported, so a
     # sweep over the whole checkout carries on past either. `hecks deploy
@@ -45,20 +46,57 @@ module Hecks
            .uniq.sort
       end
 
+      # Projects one manifest for each chapter the directory holds.
+      #
       # @param root [String] the checkout
       # @param path [String] a domain directory, relative to `root`
       # @return [void]
       def project(root, path)
-        runtime = Hecks.boot(File.join(root, path), install_driving: false)
-        name    = runtime.registry.bluebooks.keys.first
-        return warn("  #{path}: no bluebook found — skipped") unless name
+        registry = Hecks.boot(File.join(root, path), install_driving: false).registry
+        return warn("  #{path}: no bluebook found — skipped") if registry.bluebooks.empty?
 
-        write_manifest(runtime.registry, name, File.join(root, path, "oidc.json"))
-        puts "  #{path}/oidc.json  <-  #{name}"
+        project_chapters(registry, root, path)
       rescue StandardError => e
         warn "  #{path}: cannot project — #{e.message.lines.first.strip}"
       end
 
+      # The chapters a directory declares: those with a `.bluebook` file under it. A chapter it
+      # only attaches (Governance, for one) is loaded from elsewhere and has its own directory's
+      # manifest.
+      #
+      # @param registry [Hecks::Runtime::Registry] the booted registry of the directory
+      # @param directory [String] the directory that was booted
+      # @return [Array<String>] the chapter names, in load order; the first loaded when none has a
+      #   recorded source
+      def chapters_of(registry, directory)
+        under = "#{File.expand_path(directory)}/"
+        own = registry.bluebooks.keys.select do |name|
+          Array(registry.bluebook_sources[name]).any? { |source| File.expand_path(source).start_with?(under) }
+        end
+        own.empty? ? registry.bluebooks.keys.first(1) : own
+      end
+
+      # @param registry [Hecks::Runtime::Registry] the booted registry of the directory
+      # @param root [String] the checkout
+      # @param path [String] the domain directory, relative to `root`
+      # @return [void]
+      def project_chapters(registry, root, path)
+        names = chapters_of(registry, File.join(root, path))
+        names.each do |name|
+          file = file_for(names, name)
+          write_manifest(registry, name, File.join(root, path, file))
+          puts "  #{path}/#{file}  <-  #{name}"
+        end
+      end
+
+      # A domain of one chapter keeps `oidc.json`; a directory of several chapters, such as the
+      # framework members, gets one manifest each, so none of them stands for the others.
+      #
+      # @param names [Array<String>] every chapter the directory holds
+      # @param name [String] the chapter the manifest is for
+      # @return [String] the manifest's file name: `oidc.json`, or `<chapter>.oidc.json`
+      def file_for(names, name) = names.one? ? "oidc.json" : "#{Naming.snake(name)}.oidc.json"
+
       # @param registry [Hecks::Runtime::Registry] the booted registry
       # @param name [String] the bluebook to project
       # @param out [String] where the manifest goes

data/lib/hecks/tools/release_only.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "hecks/vocabulary"
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Decides whether a commit is only a release bump on a base that is fully certified, so CI may
+    # inherit the base's certification instead of running the suite again.
+    #
+    # The files a bump edits, and which of their lines it may change, are the `ReleaseFile` rows of
+    # the Vocabulary chapter. A change is a release bump when it touches at least one file, every
+    # file it touches is a row, and every line it adds or removes in a file matches that row's
+    # `lines` pattern (an empty pattern admits any line). Whether the base is certified is read
+    # from the base commit's own check runs: every `RequiredCheck` row that is not marked
+    # `runs: always` must have its latest run on the base succeed or be skipped.
+    #
+    # Every case that cannot be confirmed answers "not a release bump", so the suite runs.
+    module ReleaseOnly
+      GREEN = %w[success skipped].freeze
+
+      module_function
+
+      # @param changes [Hash{String => Array<String>}] each changed path to the lines it adds or
+      #   removes
+      # @param files [Array<Hash{String => String}>] the `ReleaseFile` rows
+      # @return [Boolean] whether the change touches only release files, and only their release
+      #   lines
+      def release_only?(changes, files: Hecks::Vocabulary.rows("ReleaseFile"))
+        return false if changes.empty?
+
+        by_path = files.to_h { |row| [row.fetch("path"), row.fetch("lines", "")] }
+        changes.all? { |path, lines| by_path.key?(path) && lines_allowed?(lines, by_path.fetch(path)) }
+      end
+
+      # @param lines [Array<String>] the changed lines of one file
+      # @param pattern [String] the row's `lines` regex, empty for any line
+      # @return [Boolean] whether every changed line matches
+      def lines_allowed?(lines, pattern)
+        return true if pattern.to_s.empty?
+
+        regex = Regexp.new(pattern)
+        lines.all? { |line| line.match?(regex) }
+      end
+
+      # @param runs [Array<Hash{String => String}>] the base commit's check runs: `name`,
+      #   `conclusion` and `started_at`
+      # @param required [Array<Hash{String => String}>] the `RequiredCheck` rows
+      # @return [Boolean] whether every check that must be inherited has a green latest run
+      def certified?(runs, required: Hecks::Vocabulary.rows("RequiredCheck"))
+        latest = latest_runs(runs)
+        inherited = required.reject { |row| row["runs"] == "always" }.map { |row| row.fetch("name") }
+        inherited.all? { |name| GREEN.include?(latest[name].to_h["conclusion"]) }
+      end
+
+      # @return [Hash{String => Hash}] each check's most recently started run
+      def latest_runs(runs)
+        runs.group_by { |run| run["name"] }.transform_values { |group| group.max_by { |run| run["started_at"].to_s } }
+      end
+
+      # @param base [String] the commit the change is measured against
+      # @param head [String] the commit under test
+      # @param root [String] the checkout
+      # @return [Hash{String => Array<String>}, nil] each changed path to its changed lines, or nil
+      #   when git could not say
+      def changes(base, head, root:)
+        out, _err, status = Open3.capture3("git", "-C", root, "diff", "-U0", "--no-color", base, head)
+        status.success? ? parse(out) : nil
+      end
+
+      # @param diff [String] `git diff -U0` output
+      # @return [Hash{String => Array<String>}] each changed path to the lines it adds or removes
+      def parse(diff)
+        found = Hash.new { |hash, key| hash[key] = [] }
+        path = nil
+        diff.each_line do |line|
+          path = file_of(line.chomp) || path
+          found[path] << line[1..].chomp if path && content_line?(line)
+        end
+        found.to_h
+      end
+
+      # @return [String, nil] the path a `+++` or `---` header names, nil for any other line
+      def file_of(line)
+        return line.delete_prefix("+++ b/") if line.start_with?("+++ b/")
+
+        line.delete_prefix("--- a/") if line.start_with?("--- a/")
+      end
+
+      # @return [Boolean] whether the line is an added or removed line, not a header
+      def content_line?(line)
+        line.match?(/\A[+-]/) && !line.start_with?("+++ ", "--- ")
+      end
+
+      # @param repository [String] `owner/name`
+      # @param sha [String] the commit whose check runs are read
+      # @param env [Hash{String => String}] carries `GH_TOKEN` for the API call
+      # @return [Array<Hash{String => String}>, nil] the check runs, or nil when the API failed
+      def check_runs(repository, sha, env: ENV)
+        path = "repos/#{repository}/commits/#{sha}/check-runs?per_page=100"
+        jq = ".check_runs[] | {name, conclusion, started_at}"
+        out, _err, status = Open3.capture3(env.to_h.slice("GH_TOKEN"), "gh", "api", path, "--paginate", "--jq", jq)
+        status.success? ? out.lines.map { |line| JSON.parse(line) } : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/tools/site_routes/templates.rb

@@ -27,22 +27,19 @@ module Hecks
           regions = Projector.call(:site_cdn, bluebook: site.chapter, options: { table: site.table, edge: edge })
           relative = template || edge.setting.template
           source = template_source(root, template, relative)
-          text = rewritten(File.read(source), regions, relative, edge)
+          text = rewritten(File.read(source), regions, relative)
           { destination(source, out, template, relative) => text }
         end
 
         # @param text [String] the template
         # @param regions [Hash{String => String}] each region's name to the block that goes in it
         # @param relative [String] the template's name, for a message
-        # @param edge [Projections::Site::Edge] the checked edge
         # @return [String] the template with each region rewritten
-        # @raise [SystemExit] when a region is missing, or a listener_rules region is left behind
-        #   by an edge with no load balancer
-        def rewritten(text, regions, relative, edge)
-          if !edge.alb? && Projections::Site::Regions.region?(text, "listener_rules")
-            abort "project_site: #{relative} has a BEGIN/END GENERATED site_cdn listener_rules region, " \
-                  "and the Edge row says alb: false; remove the region"
-          end
+        # @raise [SystemExit] when a region is missing, or a listener_rules or edge_functions region
+        #   is left behind by an edge that has no load balancer or no EdgeFunction row
+        def rewritten(text, regions, relative)
+          refuse_leftover(text, regions, relative, "listener_rules", "the Edge row says alb: false")
+          refuse_leftover(text, regions, relative, "edge_functions", "the project declares no EdgeFunction rows")
           regions.reduce(text) do |current, (name, block)|
             unless Projections::Site::Regions.region?(current, name)
               abort "project_site: #{relative} has no BEGIN/END GENERATED site_cdn #{name} region"
@@ -52,6 +49,13 @@ module Hecks
           end
         end
 
+        # Refuses a region the edge does not use, so the stale text in it is removed by hand.
+        def refuse_leftover(text, regions, relative, name, reason)
+          return if regions.key?(name) || !Projections::Site::Regions.region?(text, name)
+
+          abort "project_site: #{relative} has a BEGIN/END GENERATED site_cdn #{name} region, and #{reason}; remove the region"
+        end
+
         # @return [Hash] nothing, after refusing a template named for a project with no edge
         def missing_edge(template)
           abort "project_site: --template names #{template}, but the project declares no Edge rows" if template

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.11.0".freeze
+  VERSION = "3.13.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -51,6 +51,7 @@ module Hecks
       ].freeze,
       "CiGate" => [
         {"name"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"before_sha", "label"=>"does this change touch lib/hecks/runtime/**?"}.freeze,
+        {"name"=>"release_only", "workflow"=>"ci.yml", "mode"=>"release_only", "pattern"=>"", "push"=>"before_sha", "label"=>"is this change only a release bump on a certified base?"}.freeze,
         {"name"=>"postgres_io_relevant_changed", "workflow"=>"ci-postgres-io-parallel.yml", "mode"=>"skips_unless", "pattern"=>"^(docs/|editors/|release/|deploy/|\\.claude/|\\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"skip", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
       ].freeze,
       "Comparison" => [
@@ -134,6 +135,9 @@ module Hecks
         {"name"=>"replace"}.freeze,
         {"name"=>"scale_call"}.freeze
       ].freeze,
+      "PrebuiltBinary" => [
+        {"name"=>"host", "crate"=>"rust/host", "executable"=>"bootstrap", "target"=>"x86_64-unknown-linux-gnu", "runner"=>"ubuntu-24.04"}.freeze
+      ].freeze,
       "Primitive" => [
         {"name"=>"String"}.freeze,
         {"name"=>"Integer"}.freeze,
@@ -363,6 +367,15 @@ module Hecks
         {"refusal"=>"AttributeAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it in a translation (backfill :{field}, default: ...), or declare it optional: true"}.freeze,
         {"refusal"=>"ProjectionAbsent", "site"=>"absent_read", "template"=>"{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"}.freeze
       ].freeze,
+      "ReleaseFile" => [
+        {"path"=>"lib/hecks/version.rb", "lines"=>"^\\s*VERSION = \"[0-9]+\\.[0-9]+\\.[0-9]+\"\\.freeze$"}.freeze,
+        {"path"=>"CHANGELOG.md", "lines"=>""}.freeze,
+        {"path"=>"README.md", "lines"=>"^(\\*\\*Status:\\*\\* )?Current release: `[0-9]+\\.[0-9]+\\.[0-9]+`"}.freeze,
+        {"path"=>"Gemfile.lock", "lines"=>"^    hecks \\([0-9]+\\.[0-9]+\\.[0-9]+\\)$"}.freeze,
+        {"path"=>"rust/host/HECKS_RELEASE", "lines"=>"^[0-9]+\\.[0-9]+\\.[0-9]+$"}.freeze,
+        {"path"=>"packages/hecks-client/package.json", "lines"=>"^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"}.freeze,
+        {"path"=>"packages/hecks-client/package-lock.json", "lines"=>"^\\s*\"version\": \"[0-9]+\\.[0-9]+\\.[0-9]+\",?$"}.freeze
+      ].freeze,
       "RequiredCheck" => [
         {"name"=>"rspec"}.freeze,
         {"name"=>"checks"}.freeze,
@@ -372,7 +385,8 @@ module Hecks
         {"name"=>"rspec_rust_parser"}.freeze,
         {"name"=>"rspec_rust_codegen"}.freeze,
         {"name"=>"rspec_rust_host"}.freeze,
-        {"name"=>"rspec_fuzzing"}.freeze
+        {"name"=>"rspec_fuzzing"}.freeze,
+        {"name"=>"release_consistency", "runs"=>"always"}.freeze
       ].freeze,
       "RetiredScript" => [
         {"script"=>"ir", "section"=>"Custodian", "aggregate"=>"Introspection", "verb"=>"ir"}.freeze,