kettle-gha-pins 0.3.9 → 0.3.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40a359f61e73b1b17ee62829c001c9690844f8ccfb944b776ecb21cbd402b382
-  data.tar.gz: c5f15b58492474aefb12423903e34e3b4107f8e01dc92d964a0f0ad9c8320408
+  metadata.gz: e6eef00386a5fa9f57acdf295331f68f11293cf9d90ef09adbb666aac6a97d0c
+  data.tar.gz: 6b433ddcef3d0599c12e8496aa5a80df31f6bcaee358634fb04c167a5c36ac24
 SHA512:
-  metadata.gz: 786283e4de7a16524b78e7c30552a8622465d559df4edeb8cbfd1808dda7c3cd7c5ad730c19f5d3c35cc328c11cb9829f0fc056f531e787997961bb442ee97ca
-  data.tar.gz: c8d901235c8b8ebb5e9aae9fa0918a58965abdd1a61f612a76985df9068ddfa5aaac871e7ace466a2732a0a03821cb3352be232641e692283c4083287b8b4beb
+  metadata.gz: 7c6fa524d51f68f4ffb392195d77cb44f782b9ec65e05940915b4ac595e036768a7ed647eca7d7aefbd9da30adebb462fc3e5860f138e783559054257d215982
+  data.tar.gz: d7097d6af75ffc23901d1e9fa6208f7704c9f5d12e54aab125438b61088418056ccab1730ad06643945f1fd82052f62d2c315e555769e33535eb7cdd07fbcb50

data/CHANGELOG.md

@@ -30,6 +30,34 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.3.11] - 2026-08-10
+
+- TAG: [v0.3.11][0.3.11t]
+- COVERAGE: 97.00% -- 1033/1065 lines in 8 files
+- BRANCH COVERAGE: 85.60% -- 416/486 branches in 8 files
+- 25.93% documented
+
+### Fixed
+
+- Resolve large GitHub Actions annotated-tag inventories through a single Git exchange so stale cache reviews do not time out on repositories such as codecov/codecov-action.
+
+- Replace refreshed GitHub Actions cache inventories instead of retaining obsolete versions and forcing repeated refreshes.
+
+## [0.3.10] - 2026-08-09
+
+- TAG: [v0.3.10][0.3.10t]
+- COVERAGE: 98.08% -- 1022/1042 lines in 8 files
+- BRANCH COVERAGE: 88.03% -- 412/468 branches in 8 files
+- 26.17% documented
+
+### Added
+
+- Add JSON action inventory and cache review modes, strict offline pin resolution, and configurable action metadata TTL handling.
+
+### Fixed
+
+- Keep JSON action inventory and review parsing compatible with Ruby 2.5.
+
 ## [0.3.9] - 2026-08-05
 
 - TAG: [v0.3.9][0.3.9t]
@@ -282,7 +310,11 @@ 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.3.9...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.11...HEAD
+[0.3.11]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.10...v0.3.11
+[0.3.11t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.11
+[0.3.10]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.9...v0.3.10
+[0.3.10t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.10
 [0.3.9]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.8...v0.3.9
 [0.3.9t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.9
 [0.3.8]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.7...v0.3.8

data/README.md

@@ -155,6 +155,17 @@ cooldown window. The same default can be supplied with
 `KETTLE_GHA_PINS_COOLDOWN_DAYS`. The default is `0`, so checks remain strict
 unless a project opts into a warning window.
 
+The action metadata cache uses a one-day TTL by default. Set `--ttl DAYS` to
+change it; `--ttl 0` forces a refresh. `--offline` trusts the cache without
+checking TTL or contacting GitHub and fails if required repository metadata is
+missing.
+
+For family orchestration, `kettle-gha-pins --list --json` emits the action
+repositories used by a project without network access. A separate
+`kettle-gha-pins --review --input PATH` refreshes the repositories listed in
+that JSON and updates the shared cache. Review refreshes metadata independently
+of the selected major/minor/patch upgrade policy.
+
 `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.
@@ -188,6 +199,14 @@ plan[:updates]
 # => {sha: "...", version: "7.0.0", reason: "upgrade_to_allowed_release"}
 ```
 
+The family-oriented cache workflow is:
+
+```console
+kettle-gha-pins --list --json
+kettle-gha-pins --review --input pins.json
+kettle-gha-pins --offline --write --upgrade major
+```
+
 When two version-equivalent tags point at the same SHA, the rubric keeps the
 more explicit release spelling. For example, `v7` and `v7.0.0` pointing at the
 same commit canonicalize to `v7.0.0`; if they point at different SHAs, both
@@ -563,7 +582,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.977-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.065-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/lib/kettle/gha/pins/cli.rb

@@ -67,9 +67,13 @@ module Kettle
             user_agent: "kettle-gha-pins",
             upgrade: DEFAULT_UPGRADE_LEVEL,
             cache_path: ENV["KETTLE_GHA_SHA_PINS_CACHE"] || PersistentActionCache.default_path,
+            ttl_days: DEFAULT_CACHE_TTL_SECONDS / 86_400.0,
             cooldown_days: cooldown_days,
             clock: clock,
             refresh_cache: false,
+            offline: false,
+            mode: :project,
+            input: nil,
             reject_patterns: Set.new,
             progress: nil
           }
@@ -78,20 +82,43 @@ module Kettle
         def run!
           parse!
 
-          @options[:token] ||= gh_auth_token if @options[:api_base] == API_BASE
+          return list_workflows! if @options[:mode] == :list
+
+          client, persistent_cache = build_client
+          return review_cache!(client: client, persistent_cache: persistent_cache) if @options[:mode] == :review
+
+          run_project!(client: client)
+        rescue Error, GitHubClient::CacheMissError, GitHubClient::RefreshError => error
+          @err.puts("kettle-gha-pins: #{error.message}")
+          2
+        end
+
+        private
+
+        def build_client
+          @options[:token] ||= gh_auth_token if @options[:api_base] == API_BASE && !@options[:offline]
           persistent_cache = if @options[:cache_path].to_s.empty?
             nil
           else
-            PersistentActionCache.new(path: @options[:cache_path])
+            PersistentActionCache.new(
+              path: @options[:cache_path],
+              ttl_seconds: (@options[:ttl_days] * 86_400).to_i,
+              clock: @options[:clock]
+            )
           end
           client = GitHubClient.new(
             token: @options[:token],
             api_base: @options[:api_base],
             user_agent: @options[:user_agent],
             persistent_cache: persistent_cache,
-            refresh_cache: @options[:refresh_cache]
+            refresh_cache: @options[:refresh_cache],
+            offline: @options[:offline],
+            fail_on_refresh_error: @options[:mode] == :review
           )
+          [client, persistent_cache]
+        end
 
+        def run_project!(client:)
           state = {
             files_scanned: 0,
             files_with_changes: 0,
@@ -293,7 +320,79 @@ module Kettle
           0
         end
 
-        private
+        def list_workflows!
+          state = {files_scanned: 0, failures: 0, errors: []}
+          workflow_files = discover_workflow_files(@options[:root], @options[:reject_patterns])
+          workflows = load_workflows(workflow_files, state)
+          pins = workflows.flat_map do |workflow|
+            workflow.fetch(:uses_nodes).each_with_object([]) do |node, entries|
+              parsed = classify_action_ref(node[:value].to_s)
+              next unless parsed
+
+              action = parsed.fetch(:action)
+              entries << {
+                "repository" => "#{action[:owner]}/#{action[:repo]}",
+                "ref" => action[:ref],
+                "value" => parsed[:value],
+                "path" => workflow[:path],
+                "line" => node[:line].to_i + 1
+              }
+            end
+          end
+          repositories = pins.map { |pin| pin.fetch("repository") }.uniq.sort
+          puts JSON.pretty_generate(
+            "schema_version" => 1,
+            "root" => @options[:root],
+            "repositories" => repositories,
+            "pins" => pins
+          )
+          state[:failures].zero? ? 0 : 2
+        end
+
+        def review_cache!(client:, persistent_cache:)
+          raise Error, "--review requires a writable cache; do not use --cache-path \"\"" unless persistent_cache
+
+          repositories = review_repositories
+          refreshed = repositories.map do |repository|
+            versions = client.versions_for_repo(repository)
+            {
+              "repository" => repository,
+              "versions" => versions.length,
+              "cache" => client.last_versions_cache_hit ? "hit" : "refreshed"
+            }
+          end
+          puts JSON.pretty_generate(
+            "schema_version" => 1,
+            "mode" => "review",
+            "ttl_days" => @options[:ttl_days],
+            "repositories" => refreshed
+          )
+          0
+        end
+
+        def review_repositories
+          source = @options[:input].to_s
+          source = if source.empty? || source == "-"
+            $stdin.read
+          else
+            File.read(source)
+          end
+          payload = JSON.parse(source)
+          entries = if payload.is_a?(Array)
+            payload
+          elsif payload.is_a?(Hash)
+            payload["repositories"] || payload["actions"] || payload["pins"] || []
+          else
+            []
+          end
+          entries.each_with_object([]) do |entry, repositories|
+            value = entry.is_a?(Hash) ? (entry["repository"] || entry["action"] || entry["value"]) : entry
+            repository = value.to_s.split("@", 2).first
+            repositories << repository if repository.match?(%r{\A[^/\s]+/[^/\s]+\z})
+          end.uniq.sort
+        rescue JSON::ParserError => error
+          raise Error, "invalid review JSON: #{error.message}"
+        end
 
         def parse!
           parser = OptionParser.new do |opt|
@@ -328,6 +427,27 @@ module Kettle
             opt.on("--refresh-cache", "Bypass cached action release data and refresh discovered actions") do
               @options[:refresh_cache] = true
             end
+            opt.on("--ttl DAYS", Float, "Cache TTL in days (default: #{@options[:ttl_days]})") do |days|
+              Kernel.abort("Invalid --ttl value #{days.inspect}; use a non-negative number") if days.negative?
+
+              @options[:ttl_days] = days
+            end
+            opt.on("--offline", "Use only the persistent cache; fail on a cache miss") do
+              @options[:offline] = true
+            end
+            opt.on("--list", "List project action pins as JSON without network access") do
+              raise OptionParser::InvalidOption, "--list cannot be combined with --review" if @options[:mode] == :review
+
+              @options[:mode] = :list
+            end
+            opt.on("--review", "Refresh action metadata from JSON input and update the cache") do
+              raise OptionParser::InvalidOption, "--review cannot be combined with --list" if @options[:mode] == :list
+
+              @options[:mode] = :review
+            end
+            opt.on("--input PATH", "Review JSON input path, or - for stdin") do |path|
+              @options[:input] = path
+            end
             opt.on("--cache-path PATH", "Action release cache path (default: #{@options[:cache_path]})") do |path|
               @options[:cache_path] = path
             end
@@ -356,6 +476,9 @@ module Kettle
             end
           end
           parser.parse!(@argv)
+          if @options[:mode] == :review && @options[:offline]
+            raise OptionParser::InvalidOption, "--review cannot be combined with --offline"
+          end
         end
 
         def display_path(path)

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

@@ -2,6 +2,7 @@
 
 require "json"
 require "net/http"
+require "open3"
 require "timeout"
 require "uri"
 
@@ -10,12 +11,18 @@ module Kettle
     module Pins
       # Lightweight GitHub API client for commit and release SHA resolution.
       class GitHubClient
-        def initialize(token:, api_base:, user_agent:, persistent_cache: nil, refresh_cache: false, open_timeout: DEFAULT_HTTP_OPEN_TIMEOUT_SECONDS, read_timeout: DEFAULT_HTTP_READ_TIMEOUT_SECONDS, refresh_timeout: DEFAULT_HTTP_REFRESH_TIMEOUT_SECONDS)
+        ANNOTATED_TAG_GIT_FALLBACK_THRESHOLD = 4
+        class CacheMissError < Error; end
+        class RefreshError < Error; end
+
+        def initialize(token:, api_base:, user_agent:, persistent_cache: nil, refresh_cache: false, offline: false, fail_on_refresh_error: false, open_timeout: DEFAULT_HTTP_OPEN_TIMEOUT_SECONDS, read_timeout: DEFAULT_HTTP_READ_TIMEOUT_SECONDS, refresh_timeout: DEFAULT_HTTP_REFRESH_TIMEOUT_SECONDS)
           @token = token
           @api_base = api_base
           @user_agent = user_agent
           @persistent_cache = persistent_cache
           @refresh_cache = refresh_cache
+          @offline = offline
+          @fail_on_refresh_error = fail_on_refresh_error
           @open_timeout = open_timeout
           @read_timeout = read_timeout
           @refresh_timeout = refresh_timeout
@@ -34,15 +41,22 @@ module Kettle
             return @release_cache[repo_ref]
           end
 
+          if @offline
+            cached = @persistent_cache&.versions_for_repo(repo_ref, fresh: false)
+            raise CacheMissError, "offline cache miss for #{repo_ref}" if cached.nil?
+
+            @last_versions_cache_hit = true
+            @release_cache[repo_ref] = cached
+            return cached
+          end
+
           stale = nil
           unless @refresh_cache
             cached = @persistent_cache&.versions_for_repo(repo_ref, fresh: true)
             if cached
-              unless cache_requires_refresh?(repo_ref, cached)
-                @last_versions_cache_hit = true
-                @release_cache[repo_ref] = cached
-                return cached
-              end
+              @last_versions_cache_hit = true
+              @release_cache[repo_ref] = cached
+              return cached
             end
             stale = @persistent_cache&.versions_for_repo(repo_ref, fresh: false)
           end
@@ -50,10 +64,10 @@ module Kettle
           releases = nil
           Timeout.timeout(@refresh_timeout) do
             data = request_json("/repos/#{repo_ref}/releases?per_page=100")
-            return cached_versions(repo_ref, stale) unless data.is_a?(Array)
+            return refresh_failed!(repo_ref, stale, "invalid releases response") unless data.is_a?(Array)
 
             tag_shas = tag_ref_shas(repo_ref)
-            return cached_versions(repo_ref, stale) unless tag_shas
+            return refresh_failed!(repo_ref, stale, "invalid tag response") unless tag_shas
 
             releases = build_release_versions(data, tag_shas)
           end
@@ -61,7 +75,7 @@ module Kettle
           @release_cache[repo_ref] = releases
           releases
         rescue Timeout::Error
-          cached_versions(repo_ref, stale)
+          refresh_failed!(repo_ref, stale, "GitHub refresh timed out")
         end
 
         def commit_sha(repo_ref, ref, refresh: false)
@@ -71,13 +85,15 @@ module Kettle
           return @commit_cache[cache_key] if @commit_cache.key?(cache_key) && !refresh
 
           unless @refresh_cache || refresh
-            cached = @persistent_cache&.ref_sha(repo_ref, ref, fresh: true)
+            cached = @persistent_cache&.ref_sha(repo_ref, ref, fresh: !@offline)
             if cached
               @commit_cache[cache_key] = cached
               return cached
             end
           end
 
+          raise CacheMissError, "offline cache miss for #{repo_ref}@#{ref}" if @offline
+
           data = request_json("/repos/#{repo_ref}/commits/#{uri_encode(ref)}")
           sha = if data.is_a?(Hash)
             data.fetch("sha", "")[0, 40]
@@ -106,24 +122,10 @@ module Kettle
           versions
         end
 
-        # Release tags can be added or retargeted inside the cache TTL. Probe
-        # the latest release before trusting a cached inventory, and refresh
-        # only when that probe identifies a tag or target the cache lacks.
-        def cache_requires_refresh?(repo_ref, cached)
-          latest = request_json("/repos/#{repo_ref}/releases/latest")
-          return false unless latest.is_a?(Hash)
-
-          tag = latest["tag_name"].to_s
-          return false unless VersionRubric.parse(tag)
-
-          cached_entry = cached.find { |entry| entry[:tag].to_s == tag }
-          return true unless cached_entry
+        def refresh_failed!(repo_ref, stale, message)
+          return cached_versions(repo_ref, stale) unless @fail_on_refresh_error
 
-          latest_sha = commit_sha(repo_ref, tag, refresh: true)
-          cached_sha = cached_entry[:sha].to_s
-          return !latest_sha.to_s.empty? if cached_sha.empty?
-
-          !latest_sha.to_s.empty? && latest_sha != cached_sha
+          raise RefreshError, "#{message} for #{repo_ref}"
         end
 
         def build_release_versions(data, tag_shas)
@@ -150,7 +152,7 @@ module Kettle
           data = request_json("/repos/#{repo_ref}/git/matching-refs/tags/")
           return nil unless data.is_a?(Array)
 
-          data.each_with_object({}) do |entry, memo|
+          entries = data.each_with_object([]) do |entry, memo|
             ref = entry["ref"].to_s
             next unless ref.start_with?("refs/tags/")
 
@@ -160,16 +162,51 @@ module Kettle
             object = entry["object"]
             next unless object.is_a?(Hash)
 
-            sha = object["sha"].to_s[0, 40]
-            case object["type"]
+            memo << [tag, object["type"].to_s, object["sha"].to_s[0, 40]]
+          end
+          annotated_tag_shas = git_tag_ref_shas(repo_ref) if entries.count { |_, type, _| type == "tag" } > ANNOTATED_TAG_GIT_FALLBACK_THRESHOLD
+
+          entries.each_with_object({}) do |(tag, type, sha), memo|
+            case type
             when "commit"
               memo[tag] = sha
             when "tag"
-              memo[tag] = annotated_tag_commit_sha(repo_ref, sha)
+              memo[tag] = annotated_tag_shas&.fetch(tag, nil) || annotated_tag_commit_sha(repo_ref, sha)
             end
           end
         end
 
+        # The REST API exposes annotated tags as tag objects, requiring one
+        # additional request per tag to reach the commit. A single Git
+        # protocol exchange returns both tag objects and peeled commit refs,
+        # avoiding a refresh timeout for repositories with large tag histories.
+        def git_tag_ref_shas(repo_ref)
+          return unless @api_base.to_s.sub(%r{/\z}, "") == API_BASE
+
+          stdout, _stderr, status = Open3.capture3(
+            {"GIT_TERMINAL_PROMPT" => "0"},
+            "git",
+            "ls-remote",
+            "--tags",
+            "https://github.com/#{repo_ref}.git"
+          )
+          return unless status.success?
+
+          stdout.each_line.each_with_object({}) do |line, memo|
+            sha, ref = line.split
+            next unless SHA_RE.match?(sha.to_s)
+            next unless ref.to_s.start_with?("refs/tags/")
+
+            peeled = ref.end_with?("^{}")
+            tag = ref.sub(%r{\Arefs/tags/}, "").sub(/\^\{\}\z/, "")
+            next unless VersionRubric.parse(tag)
+
+            memo[tag] = sha if peeled || !memo.key?(tag)
+          end
+        rescue IOError, SystemCallError
+          nil
+        end
+
         def annotated_tag_commit_sha(repo_ref, tag_sha)
           return nil if tag_sha.to_s.empty?
 

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

@@ -54,8 +54,15 @@ module Kettle
           return if repo_ref.to_s.empty?
 
           action = data.fetch("actions")[repo_ref] ||= {}
-          stored_versions = action["versions"] ||= {}
-          refs = action["refs"] ||= {}
+          previous_versions = action["versions"] || {}
+          previous_tags = previous_versions.values.each_with_object([]) do |entry, tags|
+            tag = entry["tag"].to_s
+            tags << tag unless tag.empty?
+          end
+          stored_versions = {}
+          refs = (action["refs"] || {}).reject { |ref, _entry| previous_tags.include?(ref) }
+          action["versions"] = stored_versions
+          action["refs"] = refs
           timestamp = @clock.call.utc.iso8601
 
           versions.each do |entry|

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

@@ -6,7 +6,7 @@ module Kettle
       # Version namespace for this gem.
       module Version
         # Current gem version.
-        VERSION = "0.3.9"
+        VERSION = "0.3.11"
       end
       # Current gem version exposed at the traditional constant location.
       VERSION = Version::VERSION # Traditional Constant Location

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-gha-pins
 version: !ruby/object:Gem::Version
-  version: 0.3.9
+  version: 0.3.11
 platform: ruby
 authors:
 - Peter H. Boling
@@ -301,10 +301,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/kettle-dev/kettle-gha-pins
-  source_code_uri: https://github.com/kettle-dev/kettle-gha-pins/tree/v0.3.9
-  changelog_uri: https://github.com/kettle-dev/kettle-gha-pins/blob/v0.3.9/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-gha-pins/tree/v0.3.11
+  changelog_uri: https://github.com/kettle-dev/kettle-gha-pins/blob/v0.3.11/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-gha-pins/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-gha-pins/0.3.9
+  documentation_uri: https://www.rubydoc.info/gems/kettle-gha-pins/0.3.11
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-gha-pins/wiki
   news_uri: https://www.railsbling.com/tags/kettle-gha-pins