kettle-gha-pins 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b8c85ccd81571bf3a9bb1108fbe1edfbaaf1c777beec567590ae8bd04374f16
-  data.tar.gz: 901a2f1cee2404a9a711cb20bbfb5b5aafcf1246671c35f51612d202d887d130
+  metadata.gz: 5ee4e694080aa9ce9e860fdd085015793830efc399a8ff295dd3fb6fa9dcf4dc
+  data.tar.gz: d9b39c2192b77c942ffcf055abc30efd7a6ae6a78c8baf274776c1473bab179f
 SHA512:
-  metadata.gz: 853b5e757f54963d7c75edccd20529ed7196745636685f50980e855de27dc03be0262ef84918b3ec48b40c5dab3fae4a28236695a237ea75f96f7fcf23569b37
-  data.tar.gz: bb434ac6c8219892ea94fd09a2352954fa2c71ff658a32ff77a0d2a6292cecc30853e581f56802c539697b36abc0ec318e4fc1566d68c56823ec645f4728a4ca
+  metadata.gz: 90f1f8ccee7b91f7fb72d4459577f0e145565a8897463ac64afa765213fb90e90af4ba2b945148e61a3a4f67e0c4718fb5a2c751ddbfa8d74d13a8b5b0082f61
+  data.tar.gz: a8a087d884e121de676bb70eff44f5524368fe2890afab896ff18fcd775f78887d64b482a3e395cf576e4d39023f7daef93a02412012da8788669492f16c01d9

data/CHANGELOG.md

@@ -30,6 +30,21 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.2.0] - 2026-07-22
+
+- TAG: [v0.2.0][0.2.0t]
+- COVERAGE: 99.07% -- 849/857 lines in 8 files
+- BRANCH COVERAGE: 92.55% -- 348/376 branches in 8 files
+- 22.22% documented
+
+### Added
+
+- Added the shared `PersistentActionCache`, `GitHubClient`, and action ref
+  resolver API so GitHub Actions pin tools can reuse cache, network, and upgrade
+  planning behavior without shelling out to each other.
+- Added the `kettle-gha-pins` executable for scanning standard GitHub Actions
+  workflow YAML files and updating action refs to immutable SHAs.
+
 ## [0.1.0] - 2026-07-22
 
 - TAG: [v0.1.0][0.1.0t]
@@ -61,6 +76,8 @@ Please file a bug if you notice a violation of semantic versioning.
 - kettle-jem-template-20260720-005 - Generated README Support & Community rows
   now include a RubyForum help badge.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.1.0...v0.2.0
+[0.2.0t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.2.0
 [0.1.0]: https://github.com/kettle-dev/kettle-gha-pins/compare/c633526495c7db0a8721a94a71c3def0f3cc71bb...v0.1.0
 [0.1.0t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.1.0

data/README.md

@@ -21,14 +21,22 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
 
 ## 🌻 Synopsis <a href="https://discord.gg/3qme4XHNKN"><img alt="Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0" src="https://logos.galtzo.com/assets/images/galtzo-floss/avatar-128px.svg" width="8%" align="right"/></a> <a href="https://ruby-toolbox.com"><img alt="ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5" src="https://logos.galtzo.com/assets/images/ruby-lang/avatar-128px.svg" width="8%" align="right"/></a>
 
-`kettle-gha-pins` is the shared version-rubric library for kettle-dev GitHub
-Actions pin maintenance. It owns the deterministic rules for parsing action
-release tags, ordering equivalent release spellings, and selecting patch,
-minor, or major upgrade targets.
+`kettle-gha-pins` is the shared GitHub Actions pin maintenance library for
+kettle-dev tooling. It owns the action-release version rubric, persistent action
+metadata cache, GitHub release/tag/commit resolution client, and ref upgrade
+planner used by pin maintenance commands.
 
-The gem is intentionally small and API-focused. Command-line tools such as
+The gem is intentionally API-focused. Command-line tools such as
 `kettle-gha-sha-pins` and template maintenance scripts can depend on this gem
-instead of each carrying their own subtly different version comparison logic.
+instead of each carrying their own subtly different cache, network, and version
+comparison logic.
+
+For ordinary workflow pin maintenance, install this gem and run:
+
+```console
+kettle-gha-pins --check
+kettle-gha-pins --write --upgrade patch
+```
 
 ## 💡 Info you can shake a stick at
 
@@ -129,8 +137,8 @@ gem install kettle-gha-pins
 
 ## ⚙️ Configuration
 
-There is no global configuration for the library API. Callers pass release-tag
-data directly to `Kettle::Gha::Pins::VersionRubric`.
+There is no global configuration for the library API. Callers pass options to
+the client and cache objects they create.
 
 The shared upgrade policies are:
 
@@ -142,27 +150,37 @@ The shared upgrade policies are:
 Invalid upgrade levels normalize to `patch`, matching the historical
 `kettle-gha-sha-pins` default.
 
+`Kettle::Gha::Pins::PersistentActionCache.default_path` intentionally preserves
+the historical `kettle-gha-sha-pins` cache location so command-line tools can
+share action metadata without coupling to each other.
+
 ## 🔧 Basic Usage
 
 ```ruby
 require "kettle/gha/pins"
 
-versions = Kettle::Gha::Pins::VersionRubric.build_release_versions(
-  release_tags: ["v7.0.0"],
-  tag_shas: {
-    "v7" => "abc123...",
-    "v7.0.0" => "abc123..."
-  }
+cache = Kettle::Gha::Pins::PersistentActionCache.new(
+  path: Kettle::Gha::Pins::PersistentActionCache.default_path
+)
+
+client = Kettle::Gha::Pins::GitHubClient.new(
+  token: ENV["GITHUB_TOKEN"],
+  api_base: Kettle::Gha::Pins::API_BASE,
+  user_agent: "my-gha-pin-tool",
+  persistent_cache: cache
 )
 
-target = Kettle::Gha::Pins::VersionRubric.choose_upgrade_target(
-  "v6.5.0",
-  versions,
-  "major"
+versions_by_repo = {}
+plan = Kettle::Gha::Pins.resolve_action_plan(
+  cache: versions_by_repo,
+  client: client,
+  repo_ref: "codecov/codecov-action",
+  old_ref: "fb8b3582c8e4def4969c97caa2f19720cb33a72f",
+  upgrade_level: "major"
 )
 
-target[:tag]
-# => "v7.0.0"
+plan[:updates]
+# => {sha: "...", version: "7.0.0", reason: "upgrade_to_allowed_release"}
 ```
 
 When two version-equivalent tags point at the same SHA, the rubric keeps the
@@ -514,7 +532,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.085-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.857-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-gha-pins/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/exe/kettle-gha-pins

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$stdout.sync = true
+$stderr.sync = true
+
+script_basename = File.basename(__FILE__)
+
+begin
+  require "kettle/gha/pins"
+rescue LoadError
+  repo_lib = File.expand_path("../lib", __dir__)
+  $LOAD_PATH.unshift(repo_lib) unless $LOAD_PATH.include?(repo_lib)
+  begin
+    require "kettle/gha/pins"
+  rescue LoadError => e
+    warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+    warn("Hint: Install the kettle-gha-pins gem (`gem install kettle-gha-pins`) or add it to your Gemfile.")
+    exit(1)
+  end
+end
+
+begin
+  status = Kettle::Gha::Pins::CLI.new(ARGV).run!
+  exit(status)
+rescue => e
+  warn("#{script_basename}: unexpected error: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n"))
+  exit(1)
+end

data/lib/kettle/gha/pins/action_resolver.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Gha
+    module Pins
+      # Shared planning rules for converting and upgrading GitHub Action refs.
+      module ActionResolver
+        module_function
+
+        def resolve_action_plan(cache:, client:, repo_ref:, old_ref:, upgrade_level: DEFAULT_UPGRADE_LEVEL)
+          versions = if cache.key?(repo_ref)
+            cache.fetch(repo_ref)
+          else
+            cache[repo_ref] = client.versions_for_repo(repo_ref)
+          end
+
+          determine_upgrade_plan(
+            old_ref: old_ref,
+            repo_ref: repo_ref,
+            versions: versions,
+            upgrade_level: upgrade_level,
+            client: client
+          )
+        end
+
+        def determine_upgrade_plan(old_ref:, repo_ref:, versions:, upgrade_level:, client:)
+          level = VersionRubric.normalize_upgrade_level(upgrade_level)
+
+          current_ref = old_ref.to_s.strip
+          return {is_outdated: false, updates: nil, reason: nil, current_version: nil} if current_ref.empty?
+
+          available_versions = versions || []
+          latest = available_versions.first
+
+          current_sha = if SHA_RE.match?(current_ref) || WEAK_SHA_RE.match?(current_ref)
+            current_ref
+          else
+            client.commit_sha(repo_ref, current_ref)
+          end
+          parsed_current_ref = VersionRubric.parse(current_ref)
+          version_equivalent_entry = if parsed_current_ref
+            available_versions.find { |entry| entry[:version_obj] == parsed_current_ref }
+          end
+          matched_entry = matching_version_entry(available_versions, current_ref, current_sha, client, repo_ref)
+          unresolved_version_ref = false
+          if matched_entry.nil? && current_sha.to_s.empty? && version_equivalent_entry && non_sha?(current_ref)
+            matched_entry = version_equivalent_entry
+            unresolved_version_ref = true
+          end
+          current_version = matched_entry ? matched_entry[:version] : nil
+
+          updates = nil
+          reason = nil
+          is_outdated = false
+          latest_outdated = nil
+
+          if current_version
+            latest_outdated = VersionRubric.latest_outdated_target(current_version, available_versions)
+            target = VersionRubric.choose_upgrade_target(current_version, available_versions, level)
+            target_sha = target ? version_entry_sha(target, client, repo_ref) : nil
+            latest_outdated_sha = latest_outdated ? version_entry_sha(latest_outdated, client, repo_ref) : nil
+            if latest_outdated && stale_sha?(current_ref, latest_outdated_sha)
+              latest_outdated = latest_outdated.merge(sha: latest_outdated_sha)
+              is_outdated = true
+              reason = UPGRADE_REASON
+            end
+            if target && stale_sha?(current_ref, target_sha)
+              updates = {
+                sha: target_sha,
+                version: target[:version],
+                reason: UPGRADE_REASON
+              }
+              reason ||= UPGRADE_REASON
+            end
+            if updates.nil? && unresolved_version_ref
+              matched_sha = version_entry_sha(matched_entry, client, repo_ref)
+              if stale_sha?(current_ref, matched_sha)
+                updates = {
+                  sha: matched_sha,
+                  version: nil,
+                  reason: NON_SHA_REASON
+                }
+                latest_outdated ||= matched_entry.merge(sha: matched_sha)
+                is_outdated = true
+                reason ||= NON_SHA_REASON
+              end
+            end
+          elsif current_sha && non_sha?(current_ref)
+            if stale_sha?(current_ref, current_sha)
+              updates = {
+                sha: current_sha,
+                version: nil,
+                reason: NON_SHA_REASON
+              }
+              reason = NON_SHA_REASON
+            end
+          elsif current_sha
+            latest_sha = latest ? version_entry_sha(latest, client, repo_ref) : nil
+            if latest && stale_sha?(current_ref, latest_sha)
+              latest_outdated = latest.merge(sha: latest_sha)
+              updates = {
+                sha: latest_sha,
+                version: latest[:version],
+                reason: STALE_SHA_REASON
+              }
+              reason = STALE_SHA_REASON
+              is_outdated = true
+            end
+          end
+
+          {
+            is_outdated: is_outdated,
+            updates: updates,
+            reason: reason,
+            current_version: current_version,
+            latest_outdated: latest_outdated
+          }
+        end
+
+        def matching_version_entry(versions, current_ref, current_sha, client, repo_ref)
+          parsed = VersionRubric.parse(current_ref)
+          if parsed
+            direct = versions.find { |entry| entry[:tag] == current_ref }
+            return direct if direct
+          end
+
+          return nil unless current_sha
+
+          prefix = current_sha[0, 40]
+          versions.find do |entry|
+            sha = version_entry_sha(entry, client, repo_ref)
+            sha.to_s.start_with?(prefix)
+          end
+        end
+
+        def version_entry_sha(entry, client, repo_ref)
+          return nil unless entry
+          return entry[:sha] unless entry[:sha].to_s.empty?
+
+          sha = client.commit_sha(repo_ref, entry[:tag])
+          entry[:sha] = sha
+          sha
+        end
+
+        def short_sha?(candidate)
+          return false unless candidate
+
+          WEAK_SHA_RE.match?(candidate)
+        end
+
+        def non_sha?(candidate)
+          !SHA_RE.match?(candidate) && !WEAK_SHA_RE.match?(candidate)
+        end
+
+        def stale_sha?(current, latest)
+          return false if current.nil? || latest.nil?
+
+          current_down = current.downcase
+          latest_down = latest.downcase
+
+          if current_down.length < latest_down.length
+            !latest_down.start_with?(current_down)
+          else
+            current_down != latest_down
+          end
+        end
+      end
+
+      class << self
+        def resolve_action_plan(...)
+          ActionResolver.resolve_action_plan(...)
+        end
+
+        def determine_upgrade_plan(...)
+          ActionResolver.determine_upgrade_plan(...)
+        end
+
+        def matching_version_entry(...)
+          ActionResolver.matching_version_entry(...)
+        end
+
+        def version_entry_sha(...)
+          ActionResolver.version_entry_sha(...)
+        end
+
+        def short_sha?(...)
+          ActionResolver.short_sha?(...)
+        end
+
+        def non_sha?(...)
+          ActionResolver.non_sha?(...)
+        end
+
+        def stale_sha?(...)
+          ActionResolver.stale_sha?(...)
+        end
+      end
+    end
+  end
+end

data/lib/kettle/gha/pins/cache_progress.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ruby-progressbar"
+
+module Kettle
+  module Gha
+    module Pins
+      class CacheProgress
+        FORMAT = "%t %b %c/%C"
+        LENGTH = 30
+
+        def initialize(total:, cached_title:, live_title:, output:, enabled: true, skipped_title: nil)
+          @total = total.to_i
+          @cached_count = 0
+          @live_count = 0
+          @skipped_count = 0
+          @cached_bar = progress_bar(cached_title, output, enabled)
+          @live_bar = progress_bar(live_title, output, enabled)
+          @skipped_bar = skipped_title ? progress_bar(skipped_title, output, enabled) : nil
+        end
+
+        attr_reader :cached_count, :live_count, :skipped_count
+
+        def cached
+          @cached_count += 1
+          @cached_bar&.increment
+        end
+
+        def live
+          @live_count += 1
+          @live_bar&.increment
+        end
+
+        def skipped
+          @skipped_count += 1
+          @skipped_bar&.increment
+        end
+
+        private
+
+        def progress_bar(title, output, enabled)
+          return unless enabled
+          return unless @total.positive?
+
+          ProgressBar.create(title: title, total: @total, format: FORMAT, length: LENGTH, output: output)
+        end
+      end
+    end
+  end
+end