kettle-gha-pins 0.3.7 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e55947f165ea60fdf05e34f18bbd7af157e37c2e0da0c975a721ca6672da0b9f
-  data.tar.gz: eaaa403c59388d699bc50d0108ff1211d6249933dfd0304a5cd896980a3b646f
+  metadata.gz: 40a359f61e73b1b17ee62829c001c9690844f8ccfb944b776ecb21cbd402b382
+  data.tar.gz: c5f15b58492474aefb12423903e34e3b4107f8e01dc92d964a0f0ad9c8320408
 SHA512:
-  metadata.gz: 24b75d7754e3617cee6eb4178495de33b813e940b65b3a83c64201ad539edcaeb9038cec38b25bafe4f7f9a2510771e4c34d24282043b737b412066580627641
-  data.tar.gz: afceb46d10b46e25d008a125d3d724f3aec05fc3f468aa388aa0cc899b1f5aae6b64c2271651c74b7fd22da364766740098ec037a385b490453c5cd3a082b06d
+  metadata.gz: 786283e4de7a16524b78e7c30552a8622465d559df4edeb8cbfd1808dda7c3cd7c5ad730c19f5d3c35cc328c11cb9829f0fc056f531e787997961bb442ee97ca
+  data.tar.gz: c8d901235c8b8ebb5e9aae9fa0918a58965abdd1a61f612a76985df9068ddfa5aaac871e7ace466a2732a0a03821cb3352be232641e692283c4083287b8b4beb

data/CHANGELOG.md

@@ -30,6 +30,28 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.3.9] - 2026-08-05
+
+- TAG: [v0.3.9][0.3.9t]
+- COVERAGE: 98.36% -- 961/977 lines in 8 files
+- BRANCH COVERAGE: 89.95% -- 394/438 branches in 8 files
+- 25.71% documented
+
+### Fixed
+
+- Emit NDJSON progress events for family orchestration without replaying the full human report.
+
+## [0.3.8] - 2026-08-05
+
+- TAG: [v0.3.8][0.3.8t]
+- COVERAGE: 98.34% -- 945/961 lines in 8 files
+- BRANCH COVERAGE: 89.81% -- 388/432 branches in 8 files
+- 25.71% documented
+
+### Fixed
+
+- Refresh cached GitHub Action release data when a newer release tag is detected.
+
 ## [0.3.7] - 2026-08-05
 
 - TAG: [v0.3.7][0.3.7t]
@@ -260,7 +282,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.7...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.9...HEAD
+[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
+[0.3.8t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.8
 [0.3.7]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.6...v0.3.7
 [0.3.7t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.7
 [0.3.6]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.5...v0.3.6

data/README.md

@@ -563,7 +563,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.941-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.977-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/action_resolver.rb

@@ -115,7 +115,8 @@ module Kettle
             reason: reason,
             current_version: current_version,
             versions: available_versions,
-            latest_outdated: latest_outdated
+            latest_outdated: latest_outdated,
+            current_sha: current_sha
           }
         end
 

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

@@ -59,6 +59,7 @@ module Kettle
             dry_run: true,
             token: ENV["GITHUB_TOKEN"] || ENV["GH_TOKEN"],
             json: false,
+            events: false,
             validate: true,
             write: false,
             check: false,
@@ -104,8 +105,10 @@ module Kettle
           }
 
           progress_message("Discovering workflow files under #{display_path(@options[:root])}...")
+          emit_event("start", root: @options[:root])
           workflow_files = discover_workflow_files(@options[:root], @options[:reject_patterns])
           progress_message("Discovered #{workflow_files.length} workflow file(s).")
+          emit_event("workflows", total: workflow_files.length)
 
           workflows = load_workflows(workflow_files, state)
           action_count = workflows.sum { |workflow| workflow[:uses_nodes].count { |node| classify_action_ref(node[:value].to_s) } }
@@ -119,6 +122,7 @@ module Kettle
           )
           action_plan_cache = {}
 
+          completed_actions = 0
           workflows.each do |workflow|
             path = workflow.fetch(:path)
             text = workflow.fetch(:text)
@@ -134,6 +138,7 @@ module Kettle
                 action = parsed_ref[:action]
                 repo_ref = "#{action[:owner]}/#{action[:repo]}"
                 old_ref = action[:ref]
+                cached_before = action_plan_cache.key?(repo_ref)
                 upgrade_plan = resolve_action_plan(
                   cache: action_plan_cache,
                   client: client,
@@ -141,6 +146,16 @@ module Kettle
                   repo_ref: repo_ref,
                   old_ref: old_ref
                 )
+                completed_actions += 1
+                emit_event(
+                  "action",
+                  action_ref: repo_ref,
+                  path: path,
+                  line: node[:line] + 1,
+                  completed: completed_actions,
+                  total: action_count,
+                  cache: (cached_before || (client.respond_to?(:last_versions_cache_hit) && client.last_versions_cache_hit)) ? "hit" : "miss"
+                )
 
                 updates = nil
                 if upgrade_plan[:updates]
@@ -154,7 +169,8 @@ module Kettle
                   comment_update_version = VersionRubric.comment_update_version(
                     comment_version,
                     upgrade_plan[:current_version],
-                    known_versions: upgrade_plan.fetch(:versions, [])
+                    known_versions: upgrade_plan.fetch(:versions, []),
+                    resolved_sha: upgrade_plan[:current_sha]
                   )
                   if comment_update_version
                     updates = {
@@ -260,6 +276,15 @@ module Kettle
           end
           action_progress.stop
           progress_message("Action resolution checks: #{action_progress.cached_count} cached, #{action_progress.live_count} live.") if action_count.positive?
+          emit_event(
+            "summary",
+            files_scanned: state[:files_scanned],
+            changed_files: state[:changed_files].length,
+            updates: state[:updates],
+            failures: state[:failures],
+            cached: action_progress.cached_count,
+            live: action_progress.live_count
+          )
 
           print_report(state)
           return 2 unless state[:failures].zero?
@@ -309,6 +334,9 @@ module Kettle
             opt.on("--json", "Emit JSON report") do
               @options[:json] = true
             end
+            opt.on("--events", "Emit line-delimited JSON events") do
+              @options[:events] = true
+            end
             opt.on("--[no-]progress", "Show progress feedback on STDERR (default: on unless --json)") do |bool|
               @options[:progress] = bool
             end
@@ -383,7 +411,13 @@ module Kettle
         def progress_enabled?
           return @options[:progress] unless @options[:progress].nil?
 
-          !@options[:json]
+          !@options[:json] && !@options[:events]
+        end
+
+        def emit_event(action, payload = {})
+          return unless @options[:events]
+
+          puts JSON.generate({"event_version" => 1, "type" => "gha_sha_pins_#{action}", "action" => action}.merge(payload))
         end
 
         def progress_message(message)
@@ -857,8 +891,12 @@ module Kettle
             lines << "Recommended fix: kettle-gha-pins --write --upgrade #{@options[:upgrade]}"
           end
 
-          puts lines.join("
-")
+          output = lines.join("\n")
+          if @options[:events]
+            @err.puts output
+          else
+            puts output
+          end
         end
       end
     end

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

@@ -38,9 +38,11 @@ module Kettle
           unless @refresh_cache
             cached = @persistent_cache&.versions_for_repo(repo_ref, fresh: true)
             if cached
-              @last_versions_cache_hit = true
-              @release_cache[repo_ref] = cached
-              return cached
+              unless cache_requires_refresh?(repo_ref, cached)
+                @last_versions_cache_hit = true
+                @release_cache[repo_ref] = cached
+                return cached
+              end
             end
             stale = @persistent_cache&.versions_for_repo(repo_ref, fresh: false)
           end
@@ -62,13 +64,13 @@ module Kettle
           cached_versions(repo_ref, stale)
         end
 
-        def commit_sha(repo_ref, ref)
+        def commit_sha(repo_ref, ref, refresh: false)
           return nil if repo_ref.to_s.empty? || ref.to_s.empty?
 
           cache_key = "commit:#{repo_ref}:#{ref}"
-          return @commit_cache[cache_key] if @commit_cache.key?(cache_key)
+          return @commit_cache[cache_key] if @commit_cache.key?(cache_key) && !refresh
 
-          unless @refresh_cache
+          unless @refresh_cache || refresh
             cached = @persistent_cache&.ref_sha(repo_ref, ref, fresh: true)
             if cached
               @commit_cache[cache_key] = cached
@@ -104,6 +106,26 @@ 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
+
+          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
+        end
+
         def build_release_versions(data, tag_shas)
           release_dates = {}
           release_tags = data.each_with_object([]) do |release, memo|
@@ -143,7 +165,7 @@ module Kettle
             when "commit"
               memo[tag] = sha
             when "tag"
-              memo[tag] = nil
+              memo[tag] = annotated_tag_commit_sha(repo_ref, sha)
             end
           end
         end

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.7"
+        VERSION = "0.3.9"
       end
       # Current gem version exposed at the traditional constant location.
       VERSION = Version::VERSION # Traditional Constant Location

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

@@ -112,12 +112,17 @@ module Kettle
         #    the comment even when both values parse to version objects).
         # 2. Normalize equivalent spellings (v2, v2.0, v2.0.0...) to the most
         #    specific canonical form available for that SHA in known_versions.
-        def comment_update_version(comment_version, resolved_version, known_versions: [])
+        def comment_update_version(comment_version, resolved_version, resolved_sha: nil, known_versions: [])
           comment = parse(comment_version)
           resolved = parse(resolved_version)
           return nil unless comment && resolved
 
-          canonical = canonical_version_for(resolved_version, known_versions)
+          canonical = canonical_version_for(
+            resolved_version,
+            known_versions,
+            resolved_sha: resolved_sha,
+            comment_version: comment_version
+          )
           return nil if comment_version.to_s == canonical
 
           canonical
@@ -127,18 +132,40 @@ module Kettle
           versions.select { |entry| entry.fetch(:version_obj, nil) == version_obj }
         end
 
-        # When multiple release spellings resolve to the same SHA, prefer the
-        # most specific equivalent tag. If there is no known equivalent, fall
-        # back to the plain resolved version string.
-        def canonical_version_for(resolved_version, known_versions)
+        # Canonical spellings are version-specific and SHA-aware.
+        #
+        # - For SHA-tracked tags, prefer the most explicit spelling that resolves
+        #   to the same SHA as the currently resolved target.
+        # - If the resolved SHA is known but the currently-commented spellings
+        #   are tied to a different SHA, keep the in-file spelling when the
+        #   semantic version is unchanged, so we don't rewrite between aliases that
+        #   no longer represent the same object.
+        # - Otherwise fall back to the resolved version form.
+        def canonical_version_for(resolved_version, known_versions, resolved_sha: nil, comment_version: nil)
           resolved = parse(resolved_version)
           return resolved_version.to_s unless resolved
 
           equivalents = entries_for_semantic_version(known_versions, resolved)
+          if !resolved_sha.to_s.empty?
+            sha_matched_equivalents = equivalents.select do |entry|
+              entry.fetch(:sha).to_s == resolved_sha.to_s
+            end
+            equivalents = sha_matched_equivalents unless sha_matched_equivalents.empty?
+
+            if sha_matched_equivalents.empty? &&
+                comment_version &&
+                parse(comment_version) == resolved
+              return strip_leading_v(comment_version)
+            end
+          end
           preferred = equivalents.max_by { |entry| sort_key(entry) }
           preferred ? preferred[:version] : resolved.to_s
         end
 
+        def strip_leading_v(text)
+          text.to_s.sub(/\A[vV]/, "")
+        end
+
         def normalize_upgrade_level(level)
           normalized = level.to_s.downcase
           VALID_UPGRADE_LEVELS.include?(normalized) ? normalized : DEFAULT_UPGRADE_LEVEL

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-gha-pins
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.3.9
 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.7
-  changelog_uri: https://github.com/kettle-dev/kettle-gha-pins/blob/v0.3.7/CHANGELOG.md
+  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
   bug_tracker_uri: https://github.com/kettle-dev/kettle-gha-pins/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-gha-pins/0.3.7
+  documentation_uri: https://www.rubydoc.info/gems/kettle-gha-pins/0.3.9
   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