hecks 7.0.0 → 7.1.0

data/lib/hecks/pipeline/pipeline.bluebook

@@ -0,0 +1,251 @@
+# Pipeline: one change's passage from a planned Work row to a release, declared as its own
+# aggregate instead of read off six other domains. A Passage is keyed by the Work row's key, which
+# is also the branch a landing finishes, so the events the other domains already emit can find it.
+# Every stage is advanced by a policy reacting to one of those events; nothing here asks the
+# outside anything.
+#
+#   Tickets   Work.WorkPlanned        -> Plan      (planned)
+#   Tickets   Work.WorkStarted        -> Dispatch  (dispatched)
+#   Hecks     Landing.LandedWorkFound -> Land      (landed)
+#   Hecks     Integration.MainPushed  -> Push      (pushed), every landed passage at once
+#   Hecks     RedFlag.RedFlagRaised   -> Hold      (held), every pushed passage
+#   Hecks     RedFlag.RedFlagCleared  -> Verify    (verified), every pushed or held passage
+#   Hecks     PromotionRun.PromotionCompleted, promoted -> Promote (promoted), every verified passage
+#   Hecks     Release.Published       -> Release   (released), every promoted passage
+#
+# A push, a green run, a promotion and a release each cover every passage waiting at the stage
+# before, because main moves as one line: a commit pushed, verified or promoted carries everything
+# landed before it. Stalling is a mark, not a stage: a passage that sat too long where it is keeps
+# its stage and gains the reason, so the board can show it in place.
+
+Hecks.bluebook "Pipeline" do
+  vision "Every change is one passage, from the Work row that planned it to the release that shipped it, and where each one stands is a fact the pipeline itself holds."
+
+  supporting
+
+  aggregate "Passage" do
+    description "One change's journey through the pipeline: the stage it is at, what carried it there, and whether it has stalled."
+    created_by "Passage.plan!"
+
+    identified_by :change
+
+    attribute :change,  ChangeKey
+    attribute :title,   Title,    optional: true
+    attribute :session, Word,     optional: true
+    attribute :landed,  Word,     optional: true
+    attribute :pushed,  Word,     optional: true
+    attribute :flag,    Word,     optional: true
+    attribute :stalled, Reason,   optional: true
+
+    # The Work row's key, which the branch that lands it is named after.
+    value_object "ChangeKey" do
+      attribute :value, String, matches: :present
+      invariant("a passage is named by its change") { !value.to_s.empty? }
+    end
+
+    value_object "Title" do
+      attribute :value, String
+    end
+
+    # A session id, a commit, or a red flag's id.
+    value_object "Word" do
+      attribute :value, String, matches: :present
+    end
+
+    # Why a passage stalled; empty once it moved on.
+    value_object "Reason" do
+      attribute :value, String, default: ""
+    end
+
+    lifecycle :stage, default: "planned" do
+      mark :terminal, "released"
+      transition "Dispatch" => "dispatched", from: "planned"
+      transition "Land"     => "landed",     from: %w[planned dispatched]
+      transition "Push"     => "pushed",     from: "landed"
+      transition "Hold"     => "held",       from: "pushed"
+      transition "Verify"   => "verified",   from: %w[pushed held]
+      transition "Promote"  => "promoted",   from: "verified"
+      transition "Release"  => "released",   from: "promoted"
+    end
+
+    command "Plan" do
+      role "System"
+      goal "Open a passage for a Work row the moment it is planned"
+
+      attribute :change, ChangeKey, sets: true
+      attribute :title,  Title, optional: true, sets: true
+
+      emits PassagePlanned
+    end
+
+    command "Dispatch" do
+      role "System"
+      goal "Record the session a planned change was handed to"
+
+      reference_to Passage
+      attribute :session, Word, sets: true
+      sets :stalled, to: { value: "" }
+
+      emits PassageDispatched
+    end
+
+    command "Land" do
+      role "System"
+      goal "Record that the change's branch landed on local main"
+
+      reference_to Passage
+      sets :stalled, to: { value: "" }
+
+      emits PassageLanded
+    end
+
+    command "Push" do
+      role "System"
+      goal "Record the main commit that carried the landed change to the remote"
+
+      reference_to Passage
+      attribute :pushed, Word, sets: true
+      sets :stalled, to: { value: "" }
+
+      emits PassagePushed
+    end
+
+    command "Hold" do
+      role "System"
+      goal "Record that main went red while this change waits for a green run"
+
+      reference_to Passage
+      attribute :flag, Word, sets: true
+
+      emits PassageHeld
+    end
+
+    command "Verify" do
+      role "System"
+      goal "Record that a green run of main covers the pushed change"
+
+      reference_to Passage
+      sets :stalled, to: { value: "" }
+
+      emits PassageVerified
+    end
+
+    command "Promote" do
+      role "System"
+      goal "Record that stable moved past the verified change"
+
+      reference_to Passage
+      sets :stalled, to: { value: "" }
+
+      emits PassagePromoted
+    end
+
+    command "Release" do
+      role "System"
+      goal "Record that a published release carries the change"
+
+      reference_to Passage
+
+      emits PassageReleased
+    end
+
+    command "Stall" do
+      role "Maintainer"
+      goal "Mark a passage that has sat too long at its stage, with the reason, without moving it"
+
+      reference_to Passage
+      attribute :stalled, Reason, sets: true
+
+      emits PassageStalled
+    end
+
+    query "InFlight" do
+      description "Every passage that has not been released, oldest change first."
+      where(stage: { in: "planned,dispatched,landed,pushed,held,verified,promoted" })
+      order_by :change
+    end
+
+    query "AtStage" do
+      description "The passages standing at one stage."
+      attribute :stage, String
+      where(stage: :stage)
+      order_by :change
+    end
+
+    query "Landed" do
+      description "The passages on local main that no push has carried yet."
+      where(stage: "landed")
+      order_by :change
+    end
+
+    query "Pushed" do
+      description "The passages on the remote waiting for a green run of main, held by a red flag or not."
+      where(stage: { in: "pushed,held" })
+      order_by :change
+    end
+
+    query "Verified" do
+      description "The passages a green run covers that stable has not moved past."
+      where(stage: "verified")
+      order_by :change
+    end
+
+    query "Promoted" do
+      description "The passages on stable that no release has shipped."
+      where(stage: "promoted")
+      order_by :change
+    end
+
+    query "Stalled" do
+      description "Every passage marked as stalled, with the reason."
+      where(stalled: { ne: "" })
+      order_by :change
+    end
+  end
+
+  policy "PlanWhenWorkPlanned" do
+    on      "Work.WorkPlanned"
+    trigger Passage::Plan, with: { change: :work, title: :title }
+  end
+
+  policy "DispatchWhenWorkStarted" do
+    on      "Work.WorkStarted"
+    trigger Passage::Dispatch, with: { change: :work, session: :claimed_by }
+  end
+
+  policy "LandWhenWorkLanded" do
+    on      "Landing.LandedWorkFound"
+    trigger Passage::Land, with: { change: :branch }
+  end
+
+  policy "PushEveryLandedWhenMainPushed" do
+    on       "Integration.MainPushed"
+    for_each "Passage.Landed"
+    trigger  Passage::Push, with: { change: :change, pushed: :pushed }
+  end
+
+  policy "HoldEveryPushedWhenMainRed" do
+    on       "RedFlag.RedFlagRaised"
+    for_each "Passage.Pushed"
+    trigger  Passage::Hold, with: { change: :change, flag: :flag }
+  end
+
+  policy "VerifyEveryPushedWhenMainGreen" do
+    on       "RedFlag.RedFlagCleared"
+    for_each "Passage.Pushed"
+    trigger  Passage::Verify, with: { change: :change }
+  end
+
+  policy "PromoteEveryVerifiedWhenStableMoves" do
+    on       "PromotionRun.PromotionCompleted"
+    where    { promoted.value == true }
+    for_each "Passage.Verified"
+    trigger  Passage::Promote, with: { change: :change }
+  end
+
+  policy "ReleaseEveryPromotedWhenPublished" do
+    on       "Release.Published"
+    for_each "Passage.Promoted"
+    trigger  Passage::Release, with: { change: :change }
+  end
+end

data/lib/hecks/pipeline/pipeline.hecksagon

@@ -0,0 +1,17 @@
+# The Pipeline bluebook, bound so it boots standing alone (a behaviors or model_check boot of this
+# directory). It persists in Memory like every tooling domain and declares no port: every stage is
+# advanced by an event another domain already emits.
+Hecks.hecksagon "Pipeline" do
+  attaches "Governance"
+  persisted_by "Memory"
+
+  # The events that move a passage, as the Tickets and Hecks domains emit them.
+  %w[Tickets.WorkPlanned Tickets.WorkStarted Hecks.LandedWorkFound Hecks.MainPushed
+     Hecks.RedFlagRaised Hecks.RedFlagCleared Hecks.PromotionCompleted Hecks.Published]
+    .each { |event| subscribe event }
+end
+
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

data/lib/hecks/pipeline_board/adapters/cache.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "probe"
+
+module Hecks
+  module Adapters
+    module PipelineBoard
+      # Keeps each outside read for a few seconds, failures included, so a page polling every ten
+      # seconds cannot hammer `gh` or the disk.
+      class Cache
+        # @param ttl [Numeric] seconds an answer is kept
+        # @param clock [#call] the time in seconds; the monotonic clock when none is given
+        def initialize(ttl: 20, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          @ttl = ttl
+          @clock = clock
+          @held = {}
+          @lock = Mutex.new
+        end
+
+        # @param key [Object] what is read
+        # @return [Object] the held answer while it is fresh, else the block's; a block that raises
+        #   {Unavailable} is held as the failure and raised again until it expires
+        def fetch(key, &block)
+          @lock.synchronize do
+            kept = @held[key]
+            kept = @held[key] = [@clock.call, attempt(&block)] unless kept && fresh?(kept)
+            kept.last.is_a?(Unavailable) ? raise(kept.last) : kept.last
+          end
+        end
+
+        private
+
+        def fresh?(kept) = @clock.call - kept.first < @ttl
+
+        def attempt
+          yield
+        rescue Unavailable => e
+          e
+        end
+      end
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/pipeline_fill.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cache"
+
+module Hecks
+  module Adapters
+    # Reads `Dispatch.Fill` as a dry run: which planned rows it would start and which it skips and
+    # why, plus the load and cap it saw. It never passes `confirm`, so nothing starts.
+    class PipelineFill
+      HEADER = /\Aload ([\d.]+) \(limit ([\d.]+), (\d+) cpus\); cap (\d+), (\d+) started/
+      WOULD = /\Awould start (\S+): (.*)\z/
+      SKIPPED = /\A(\S+) skipped: (.*)\z/
+
+      # The JSON document the launcher prints, after any log lines.
+      JSON_BODY = /\{.*\}/m
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `runner:` stands in for the launcher (a callable taking the
+      #   arguments, answering its standard output), `ttl:` for how long the preview is kept
+      # @param root [String, nil] the checkout the launcher runs in
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @root = root || Dir.pwd
+        @runner = settings[:runner] || ->(*args) { PipelineBoard::Probe.run(*args, chdir: @root, seconds: 120) }
+        @cache = PipelineBoard::Cache.new(ttl: settings.fetch(:ttl, 60))
+      end
+
+      # @return [Hash] `load`, `limit`, `cap`, `started`, `would_start` (slug and title) and
+      #   `skipped` (slug and reason)
+      # @raise [PipelineBoard::Unavailable] when the launcher cannot answer
+      def preview
+        @cache.fetch(:fill) { parse(report) }
+      end
+
+      private
+
+      def report
+        out = @runner.call("exe/hecks", "Dispatch.Fill!", "repo.value=#{@root}", "budget_minutes.value=30", "--wait")
+        JSON.parse(out[JSON_BODY].to_s).dig("state", "report").to_s
+      rescue JSON::ParserError
+        raise PipelineBoard::Unavailable, "Dispatch.Fill printed no report"
+      end
+
+      def parse(text)
+        lines = text.lines.map(&:strip)
+        counts = HEADER.match(lines.first.to_s) or raise PipelineBoard::Unavailable, "unreadable fill report"
+        { load: counts[1].to_f, limit: counts[2].to_f, cap: counts[4].to_i, started: counts[5].to_i,
+          would_start: pairs(lines, WOULD, :slug, :title), skipped: pairs(lines, SKIPPED, :slug, :reason) }
+      end
+
+      def pairs(lines, pattern, first, second)
+        lines.filter_map { |line| (found = pattern.match(line)) && { first => found[1], second => found[2] } }
+      end
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/pipeline_git.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "cache"
+
+module Hecks
+  module Adapters
+    # The `Git` port's adapter: where local main stands against `origin/main`, what the push
+    # train's copy last pushed, and whether `stable` has caught up with main. It reads refs and
+    # never fetches, so it writes nothing, not even a remote-tracking ref.
+    class PipelineGit
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `git:` stands in for the program (a callable taking a directory
+      #   and the arguments, answering standard output), `train:` for the train's checkout,
+      #   `ttl:` for how long a read is kept
+      # @param root [String, nil] the checkout whose main is read
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @root = root || Dir.pwd
+        @git = settings[:git] || ->(dir, *args) { PipelineBoard::Probe.run("git", "-C", dir, *args) }
+        @train = settings.fetch(:train) { File.join(Dir.home, ".claude", "hecks-train") }
+        @cache = PipelineBoard::Cache.new(ttl: settings.fetch(:ttl, 15))
+      end
+
+      # @return [Hash] `ahead`, `behind` (local main against origin/main), `dirty` (changed files in
+      #   this checkout) and `sha`
+      # @raise [PipelineBoard::Unavailable] when git cannot answer
+      def local_main
+        behind, ahead = ask(@root, "rev-list", "--left-right", "--count", "origin/main...main").split.map(&:to_i)
+        { sha: short("main"), ahead: ahead, behind: behind, oldest_unpushed: oldest_unpushed,
+          dirty: ask(@root, "status", "--porcelain").lines.size }
+      end
+
+      # @return [Hash] the commit the train's checkout stands on: `sha`, `at`, and `pushed`
+      #   (whether origin/main holds it)
+      # @raise [PipelineBoard::Unavailable] when the train's checkout cannot be read
+      def train
+        sha, at = ask(@train, "log", "-1", "--format=%h %cI").split
+        { sha: sha, at: at, pushed: contains?("origin/main", sha) }
+      end
+
+      # @return [String, nil] when the oldest commit on local main that origin/main lacks was made
+      def oldest_unpushed = ask(@root, "log", "--format=%cI", "origin/main..main").lines.last&.strip
+
+      # @param shas [Array<String>] commits to date
+      # @return [Hash{String => String}] each known commit's short sha with when it was made
+      def commit_times(shas)
+        dated = ask(@root, "log", "-n", "600", "--format=%H %cI", "origin/main").lines.to_h(&:split)
+        shas.filter_map { |sha| (full = dated.keys.find { |key| key.start_with?(sha) }) && [sha, dated[full]] }.to_h
+      end
+
+      # The standing red flag of the repository, as its marker file holds it, or nil when main is
+      # not flagged.
+      #
+      # @return [Hash, nil] the flag: id, commit, raised_at, runs and checkins
+      def red_flag
+        common = ask(@root, "rev-parse", "--path-format=absolute", "--git-common-dir").strip
+        path = File.join(common, "hecks-red-flag.json")
+        JSON.parse(File.read(path)) if File.exist?(path)
+      end
+
+      # @return [Hash] `behind`, the commits on origin/main that stable lacks, and `sha`
+      # @raise [PipelineBoard::Unavailable] when git cannot answer
+      def stable
+        { sha: short("origin/stable"), behind: ask(@root, "rev-list", "--count", "origin/stable..origin/main").to_i }
+      end
+
+      private
+
+      def short(ref) = ask(@root, "rev-parse", "--short", ref).strip
+
+      def contains?(ref, sha)
+        ask(@root, "merge-base", "--is-ancestor", sha, ref)
+        true
+      rescue PipelineBoard::Unavailable
+        false
+      end
+
+      def ask(dir, *args) = @cache.fetch([dir, *args]) { @git.call(dir, *args) }
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/pipeline_github/runs.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Hecks
+  module Adapters
+    module PipelineBoard
+      # Turns `gh` run and job records into the rows the board shows. A settled run never changes,
+      # so its failed-job count is read once.
+      module PipelineRuns
+        RUN_FIELDS = "databaseId,headSha,startedAt,updatedAt,conclusion,status"
+
+        private
+
+        def rows(limit)
+          runs = read("run", "list", "--branch", self.class::BRANCH, "--workflow", self.class::WORKFLOW,
+                      "--limit", limit.to_s, "--json", RUN_FIELDS)
+          runs.reverse.map { |run| Thread.new { row(run) } }.map(&:value)
+        end
+
+        def row(run)
+          { id: run["databaseId"], sha: run["headSha"].to_s[0, 7], started: run["startedAt"],
+            wall_minutes: minutes(run["startedAt"], run["updatedAt"]), status: run["status"],
+            conclusion: run["conclusion"].to_s, failed_jobs: failed_jobs(run) }
+        end
+
+        # The jobs that failed, nil when GitHub would not list the run's jobs (so the board says so
+        # instead of counting zero).
+        def failed_jobs(run)
+          return counted(run) unless run["status"] == "completed"
+
+          @settled[run["databaseId"]] ||= counted(run)
+        rescue PipelineBoard::Unavailable
+          nil
+        end
+
+        def counted(run) = jobs_of(run["databaseId"]).count { |job| failed?(job) }
+
+        def failed?(job) = %w[failure timed_out cancelled startup_failure].include?(job["conclusion"])
+
+        def jobs_of(id) = read("run", "view", id.to_s, "--json", "jobs")["jobs"] || []
+
+        def slowest(limit)
+          done = read("run", "list", "--branch", self.class::BRANCH, "--workflow", self.class::WORKFLOW,
+                      "--status", "completed", "--limit", "1", "--json", RUN_FIELDS).first
+          return [] unless done
+
+          timed = jobs_of(done["databaseId"]).filter_map { |job| timed(job) }
+          timed.sort_by { |job| -job[:minutes] }.first(limit)
+        end
+
+        def timed(job)
+          return unless job["startedAt"] && job["completedAt"]
+
+          { name: job["name"], minutes: minutes(job["startedAt"], job["completedAt"]), conclusion: job["conclusion"].to_s }
+        end
+
+        def minutes(from, upto)
+          return 0.0 unless from && upto
+
+          ((Time.parse(upto) - Time.parse(from)) / 60.0).round(1)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/pipeline_github.adapter

@@ -0,0 +1,7 @@
+# Binds the `GitHub` port to `PipelineGitHub`, which answers `CiRuns` and `SlowestJobs` with CI as GitHub reports it.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/pipeline_board/adapters/pipeline_github"
+
+Hecks.adapter "PipelineGitHub" do
+  port "GitHub"
+end

data/lib/hecks/pipeline_board/adapters/pipeline_github.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "cache"
+require_relative "pipeline_github/runs"
+
+module Hecks
+  module Adapters
+    # The `GitHub` port's adapter: answers `CiRuns` and `SlowestJobs` with CI as GitHub reports it,
+    # read through `gh run list` and `gh run view`. It only reads, and keeps every read for a few
+    # seconds.
+    class PipelineGitHub
+      include PipelineBoard::PipelineRuns
+
+      WORKFLOW = "ci.yml"
+      BRANCH = "main"
+
+      # A release tag that names a version, such as `v7.0.0`.
+      VERSION_TAG = /\Av\d/
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `gh:` stands in for the program (a callable taking the arguments and
+      #   answering parsed JSON), `ttl:` for how long a read is kept
+      # @param root [String, nil] the checkout `gh` runs in
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @gh = settings[:gh] || ->(*args) { PipelineBoard::Probe.json("gh", *args, chdir: root) }
+        @cache = PipelineBoard::Cache.new(ttl: settings.fetch(:ttl, 20))
+        @settled = {}
+      end
+
+      # @param limit [Hash, Integer, nil] how many runs (20 when none is named)
+      # @return [Hash{Symbol => String}] `text:` the runs, oldest first, as JSON
+      # @raise [PipelineBoard::Unavailable] when `gh` cannot answer
+      def ci_runs(limit: nil)
+        { text: JSON.generate(rows(count(limit, 20))) }
+      end
+
+      # @param limit [Hash, Integer, nil] how many jobs (8 when none is named)
+      # @return [Hash{Symbol => String}] `text:` the last completed run's slowest jobs as JSON
+      # @raise [PipelineBoard::Unavailable] when `gh` cannot answer
+      def slowest_jobs(limit: nil)
+        { text: JSON.generate(slowest(count(limit, 8))) }
+      end
+
+      # @return [Hash, nil] the newest `v` release: `tag`, `published` and `published_at`
+      # @raise [PipelineBoard::Unavailable] when `gh` cannot answer
+      def latest_release
+        listed = read("release", "list", "--limit", "20", "--json", "tagName,isDraft,isPrerelease,publishedAt")
+        found = listed.find { |release| release["tagName"].to_s.match?(VERSION_TAG) }
+        raise PipelineBoard::Unavailable, "no v release found" unless found
+
+        { tag: found["tagName"], published: !found["isDraft"], published_at: found["publishedAt"] }
+      end
+
+      # @return [Hash, nil] the newest CI run on main, as {#ci_runs} rows are
+      # @raise [PipelineBoard::Unavailable] when `gh` cannot answer
+      def latest_run = rows(1).last
+
+      private
+
+      def count(value, default)
+        number = value.is_a?(Hash) ? value[:value] : value
+        number.to_i.positive? ? number.to_i : default
+      end
+
+      def read(*args) = @cache.fetch(args) { @gh.call(*args) }
+    end
+  end
+end

data/lib/hecks/pipeline_board/adapters/pipeline_jobs.adapter

@@ -0,0 +1,7 @@
+# Binds the `Jobs` port to `PipelineJobs`, which answers `Sessions` from each job's state file and `claude agents`.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/pipeline_board/adapters/pipeline_jobs"
+
+Hecks.adapter "PipelineJobs" do
+  port "Jobs"
+end