spm_version_updates 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53afb3742bddcef276c343767b4570a4d428cefe7560ba2460d461dfcf66c3c1
-  data.tar.gz: bde5dd5228e9c7ae5188efa42ef0343bc1def8b45bb22f16a9ce343fb9f94e4e
+  metadata.gz: f7d008830011f3c063859526406f0ff3cb686dc80990d87bc3c684289f9eb833
+  data.tar.gz: 5257644ec20b9e1798a2f5072609173cb5892ace8bf1ea8bcfe3240dcc2a8b3b
 SHA512:
-  metadata.gz: 80f629e2ef3cc2c5a2162a61cedf485948bbd88616451d666b82776fc4034744cd2b9cb8d78c2c02628446f32027206e9d1913b0fe495ca51cf53619b599ede1
-  data.tar.gz: 50adb15cd7e1703487bc386a7f0bc81d022698d172ece4008b20ab33b9602c578bf33622a5a26340c713d1e02a5fd5af2d0d7fb9ec2db8fbcfe083ba8f3ace0a
+  metadata.gz: 38899d7c7a51654d7574625ac1bc2581f1817771f656c94bf4d24103dc861e1b162539295402c62be7c9f1138867a7161dc57f0f9a7ce1e8e586fb275bb794b3
+  data.tar.gz: 308cf9c70aaf5ea5ba120188d2dcb0df36a2d28d3cb9f671a01a71f92e935c9f82a7c29facc06013b6f6388bc9c69e7d137a37c3779f156ea6edb3d04fcd886f

data/README.md

@@ -23,18 +23,17 @@ require "spm_version_updates"
 
 checker = SpmChecker.new
 
-# Manifest mode: check one or more Package.swift files (a Package.resolved
-# next to each manifest is used automatically when present).
-warnings = checker.check_manifests(["path/to/Package.swift"])
+# Manifest mode: check one or more Package.swift files.
+result = checker.check_manifests(["path/to/Package.swift"])
 
 # Xcode mode: check the packages referenced by an Xcode project.
-# warnings = checker.check_for_updates("path/to/App.xcodeproj")
+# result = checker.check_for_updates("path/to/App.xcodeproj")
 
-warnings.each { |warning| puts warning }
+result.updates.each { |update| puts update["message"] }
 
-# Structured details (repository URL, current/available version, severity,
-# suggested update command, ...) for each warning:
-checker.warning_details.each { |detail| p detail }
+# String-keyed details include repository URL, current/available version,
+# suggested update command, source, and related report fields.
+result.updates.each { |update| p update }
 ```
 
 Behavior is configurable through accessors on `SpmChecker` — for example
@@ -113,9 +112,9 @@ is recorded on the checker — separate from update warnings, so update counts
 and fail-on thresholds are unaffected:
 
 ```ruby
-checker.check_manifests(["Modules/Package.swift"])
+result = checker.check_manifests(["Modules/Package.swift"])
 
-checker.parse_warnings.each do |record|
+result.parse_warnings.each do |record|
   # String-keyed hash: "type" ("parse_warning"), "reason", "source"
   # (the manifest path), "snippet" (credential-redacted, truncated),
   # and a human-readable "message".

data/lib/spm_version_updates/fail_on_threshold.rb

@@ -7,13 +7,8 @@ require_relative "update_severity"
 module FailOnThreshold
   ANY = "any"
 
-  def self.from_inputs(explicit_fail_on, legacy_fail_on)
-    input_name, value = [
-      ["fail-on", explicit_fail_on],
-      ["fail-on-updates", legacy_fail_on],
-      ["fail-on-updates", "false"],
-    ].find { |_name, candidate| candidate }
-    normalize(value, input_name)
+  def self.from_input(value)
+    normalize(value)
   end
 
   def self.failure_message(threshold, reporter)
@@ -29,13 +24,13 @@ module FailOnThreshold
     UpdateSeverity.count_at_or_above(reporter.severity_counts, threshold)
   end
 
-  def self.normalize(value, input_name)
-    normalized = value.downcase
-    return nil if ["false", "none"].include?(normalized)
-    return ANY if normalized == "true"
+  def self.normalize(value)
+    normalized = value.to_s.strip.downcase
+    return nil if ["", "false", "none"].include?(normalized)
+    return ANY if ["true", ANY].include?(normalized)
     return normalized if UpdateSeverity.threshold?(normalized)
 
-    raise(SpmVersionUpdates::ConfigurationError, "#{input_name} must be false, true, major, minor, or patch")
+    raise(SpmVersionUpdates::ConfigurationError, "fail-on must be false, true, any, major, minor, or patch")
   end
 
   def self.build_message(threshold, count)

data/lib/spm_version_updates/manifest_parser.rb

@@ -21,6 +21,123 @@ require_relative "package_resolved"
 # `"revision"`) so the same comparison logic can be reused for both modes.
 module ManifestParser
   PACKAGE_CALL = ".package("
+  # Raw body and byte offsets for a direct `.package(...)` declaration.
+  PackageCallSpan = Struct.new(:body, :body_start, :body_end, keyword_init: true)
+
+  # Navigates a normal Swift double-quoted string literal.
+  class StringLiteral
+    def initialize(content, index)
+      @content = content
+      @index = index
+      @cursor = index
+    end
+
+    def copy_to(output)
+      output << @content[@index...skip_index]
+      skip_index
+    end
+
+    def skip_index
+      @cursor = @index + 1
+      @cursor = next_cursor until finished?
+      finish_index
+    end
+
+    private
+
+    def finished?
+      @cursor >= @content.length || @content[@cursor] == '"'
+    end
+
+    def next_cursor
+      @content[@cursor] == "\\" ? @cursor + 2 : @cursor + 1
+    end
+
+    def finish_index
+      @cursor >= @content.length ? @cursor : @cursor + 1
+    end
+  end
+  private_constant :StringLiteral
+
+  # Navigates a Swift raw string literal such as #"..."# or #"""..."""#.
+  class RawStringLiteral
+    def initialize(content, index)
+      @content = content
+      @index = index
+      @hash_count = leading_hash_count
+      @quote_count = quote_count
+    end
+
+    def literal?
+      @hash_count.positive? && @quote_count.positive?
+    end
+
+    def copy_to(output)
+      output << @content[@index...skip_index]
+      skip_index
+    end
+
+    def skip_index
+      length = @content.length
+      index = @index + @hash_count + @quote_count
+      index += 1 until index >= length || ends_at?(index)
+      [index + @quote_count + @hash_count, length].min
+    end
+
+    private
+
+    def leading_hash_count
+      index = @index
+      index += 1 while @content[index] == "#"
+      index - @index
+    end
+
+    def quote_count
+      quote_index = @index + @hash_count
+      return 3 if @content[quote_index, 3] == '"""'
+      return 1 if @content[quote_index] == '"'
+
+      0
+    end
+
+    def ends_at?(index)
+      @content[index, @quote_count] == '"' * @quote_count &&
+        @content[(index + @quote_count), @hash_count] == "#" * @hash_count
+    end
+  end
+  private_constant :RawStringLiteral
+
+  # Finds `.package(` markers while skipping Swift string literals.
+  class PackageCallFinder
+    def initialize(content)
+      @content = content
+    end
+
+    def next_from(search_start)
+      index = search_start
+      while index < @content.length
+        return index if package_call_at?(index)
+
+        index = next_index(index)
+      end
+      nil
+    end
+
+    private
+
+    def package_call_at?(index)
+      @content[index, PACKAGE_CALL.length] == PACKAGE_CALL
+    end
+
+    def next_index(index)
+      raw_string = RawStringLiteral.new(@content, index)
+      return raw_string.skip_index if raw_string.literal?
+      return StringLiteral.new(@content, index).skip_index if @content[index] == '"'
+
+      index + 1
+    end
+  end
+  private_constant :PackageCallFinder
 
   # Find the direct SPM dependencies declared in a `Package.swift` manifest.
   #
@@ -44,6 +161,15 @@ module ManifestParser
 
     content = strip_comments(File.read(manifest_path))
     package_calls(content, &on_skip).each_with_object({}) { |call, packages|
+      if call.include?("\\(")
+        on_skip&.call({ reason: "unsupported_string_interpolation", snippet: call })
+        next
+      end
+      if call.match?(/#+"/)
+        on_skip&.call({ reason: "unsupported_raw_string", snippet: call })
+        next
+      end
+
       url = call[/\burl\s*:\s*"([^"]+)"/, 1]
       next if url.nil? # local package (path:) or otherwise unrecognized
 
@@ -73,6 +199,15 @@ module ManifestParser
     File.join(File.dirname(manifest_path), "Package.resolved")
   end
 
+  # Extract raw source spans for `.package(...)` calls. Offsets are byte indexes
+  # into the original content and point to the call body, excluding outer parens.
+  #
+  # @param [String] content raw manifest source
+  # @return [Array<PackageCallSpan>]
+  def self.package_call_spans(content)
+    package_spans(content).map { |span| PackageCallSpan.new(**span) }
+  end
+
   # Extract the argument body of each `.package( ... )` call, honoring nested
   # parentheses (e.g. `.upToNextMajor(from: "1.0.0")`) and string literals.
   #
@@ -82,20 +217,42 @@ module ManifestParser
   # @param  [String] content The (comment-stripped) manifest source
   # @return [Array<String>]
   def self.package_calls(content, &on_skip)
+    package_spans(content, &on_skip).map { |span| span[:body] }
+  end
+
+  def self.package_spans(content, &on_skip)
     calls = []
+    scan_package_spans(content, on_skip) { |span| calls << span }
+    calls
+  end
+
+  def self.scan_package_spans(content, on_skip)
     search_start = 0
-    while (marker_index = content.index(PACKAGE_CALL, search_start))
-      open_index = marker_index + PACKAGE_CALL.length - 1
-      close_index = matching_paren(content, open_index)
-      if close_index.nil?
-        on_skip&.call({ reason: "unbalanced_parentheses", snippet: content[marker_index, 300] })
-        break
-      end
+    while (marker_index = next_package_call(content, search_start))
+      span = package_span(content, marker_index, on_skip)
+      break unless span
 
-      calls << content[(open_index + 1)...close_index]
-      search_start = close_index + 1
+      yield(span)
+      search_start = span[:body_end] + 1
     end
-    calls
+  end
+
+  def self.package_span(content, marker_index, on_skip)
+    open_index = marker_index + PACKAGE_CALL.length - 1
+    close_index = matching_paren(content, open_index)
+    return unbalanced_package_span(content, marker_index, on_skip) unless close_index
+
+    body_start = open_index + 1
+    { body: content[body_start...close_index], body_start:, body_end: close_index }
+  end
+
+  def self.unbalanced_package_span(content, marker_index, on_skip)
+    on_skip&.call({ reason: "unbalanced_parentheses", snippet: content[marker_index, 300] })
+    nil
+  end
+
+  def self.next_package_call(content, search_start)
+    PackageCallFinder.new(content).next_from(search_start)
   end
 
   # Map the body of a `.package(...)` call to an Xcodeproj-style requirement.
@@ -156,17 +313,15 @@ module ManifestParser
     depth = 0
     index = open_index
     length = content.length
-    in_string = false
     while index < length
       char = content[index]
-      if in_string
-        if char == "\\"
-          index += 2
-          next
-        end
-        in_string = false if char == '"'
+      raw_string = RawStringLiteral.new(content, index)
+      if raw_string.literal?
+        index = raw_string.skip_index
+        next
       elsif char == '"'
-        in_string = true
+        index = StringLiteral.new(content, index).skip_index
+        next
       elsif char == "("
         depth += 1
       elsif char == ")"
@@ -190,7 +345,10 @@ module ManifestParser
     while index < length
       char = content[index]
       nxt = content[index + 1]
-      if char == '"'
+      raw_string = RawStringLiteral.new(content, index)
+      if raw_string.literal?
+        index = raw_string.copy_to(output)
+      elsif char == '"'
         index = copy_string_literal(content, index, output)
       elsif char == "/" && nxt == "/"
         index += 1 while index < length && content[index] != "\n"
@@ -209,21 +367,7 @@ module ManifestParser
   #
   # @return [Integer]
   def self.copy_string_literal(content, index, output)
-    length = content.length
-    output << content[index] # opening quote
-    index += 1
-    while index < length
-      char = content[index]
-      output << char
-      if char == "\\"
-        output << content[index + 1] if index + 1 < length
-        index += 2
-        next
-      end
-      index += 1
-      break if char == '"'
-    end
-    index
+    StringLiteral.new(content, index).copy_to(output)
   end
 
   # Return the index just past the closing `*/` of a block comment. Swift block
@@ -249,7 +393,11 @@ module ManifestParser
   end
 
   private_class_method :package_calls,
-                       :requirement_for,
+                       :package_spans,
+                       :scan_package_spans,
+                       :package_span,
+                       :unbalanced_package_span,
+                       :next_package_call,
                        :version_range_requirement,
                        :increment_patch_version,
                        :matching_paren,

data/lib/spm_version_updates/manifest_updater.rb

@@ -0,0 +1,481 @@
+# frozen_string_literal: true
+
+require_relative "git_operations"
+require_relative "manifest_parser"
+require_relative "semver"
+
+# Rewrites supported Package.swift dependency requirements for update records.
+module ManifestUpdater
+  SUPPORTED_KINDS = %w(exactVersion upToNextMajorVersion upToNextMinorVersion versionRange).freeze
+
+  # Result of rewriting one manifest's dependency declarations.
+  Result = Struct.new(:content, :applied, :skipped, :changed, keyword_init: true) {
+    def changed?
+      changed
+    end
+  }
+
+  def self.rewrite(content, updates)
+    Rewriter.new(content, updates).rewrite
+  end
+
+  def self.update_file(manifest_path, updates)
+    original = File.read(manifest_path)
+    result = rewrite(original, updates)
+    File.write(manifest_path, result.content) if result.changed?
+    result
+  end
+
+  # Normalized update input used by the private rewrite pipeline.
+  class UpdateRecord
+    def initialize(attributes)
+      @attributes = attributes.to_h.transform_keys(&:to_s)
+    end
+
+    def kind
+      value("requirement_kind")
+    end
+
+    def type
+      value("type")
+    end
+
+    def normalized_url
+      value("normalized_url")
+    end
+
+    def available_version
+      value("available_version")
+    end
+
+    def applied_entry
+      @attributes.merge("available_version" => available_version)
+    end
+
+    def skipped_entry(reason)
+      @attributes.merge("reason" => reason)
+    end
+
+    private
+
+    def value(key)
+      @attributes[key]
+    end
+  end
+  private_constant :UpdateRecord
+
+  # Collects the rewrite outcome while package declarations are scanned.
+  class RewriteChanges
+    attr_reader :edits, :applied, :skipped
+
+    def initialize
+      @edits = []
+      @applied = []
+      @skipped = []
+    end
+
+    def apply(update, edits)
+      @edits.concat(edits)
+      @applied << update.applied_entry
+    end
+
+    def skip(update, reason)
+      @skipped << update.skipped_entry(reason)
+    end
+  end
+  private_constant :RewriteChanges
+
+  # Success or failure from attempting to rewrite one update record.
+  RewritePlan = Struct.new(:edits, :reason, keyword_init: true) {
+    def self.success(edits)
+      new(edits:, reason: nil)
+    end
+
+    def self.failure(reason)
+      new(edits: [], reason:)
+    end
+
+    def failed?
+      reason
+    end
+  }
+  private_constant :RewritePlan
+
+  # Computes all declaration edits for one update record.
+  class EditPlanner
+    def initialize(update, spans)
+      @update = update
+      @spans = spans
+    end
+
+    def plan
+      return RewritePlan.failure("declaration_not_found") if matching_spans.empty?
+
+      plan_matching_spans
+    end
+
+    private
+
+    attr_reader :update
+
+    def matching_spans
+      @matching_spans ||= @spans.select { |span| SpanPackage.new(span).normalized_url == update.normalized_url }
+    end
+
+    def plan_matching_spans
+      attempts = matching_spans.map { |span| EditAttempt.new(update, span).plan }
+      attempts.find(&:failed?) || RewritePlan.success(attempts.flat_map(&:edits))
+    end
+  end
+  private_constant :EditPlanner
+
+  # Package metadata parsed from one declaration span.
+  class SpanPackage
+    def initialize(span)
+      @span = span
+    end
+
+    def normalized_url
+      GitOperations.trim_repo_url(url.value)
+    end
+
+    private
+
+    def url
+      UrlLiteral.new(@span.body)
+    end
+  end
+  private_constant :SpanPackage
+
+  # Reads a Package.swift dependency URL literal from one declaration body.
+  class UrlLiteral
+    def initialize(body)
+      @body = body
+    end
+
+    def value
+      @body[/\burl\s*:\s*"([^"]+)"/, 1]
+    end
+  end
+  private_constant :UrlLiteral
+
+  # Source body checks that determine whether a declaration can be safely edited.
+  class DeclarationBody
+    def initialize(body)
+      @body = body
+    end
+
+    def unsupported_syntax?
+      @body.include?("\\(") || @body.match?(/#+"/)
+    end
+  end
+  private_constant :DeclarationBody
+
+  # Attempts the single-span edit for one update and returns a rewrite plan.
+  class EditAttempt
+    def initialize(update, span)
+      @update = update
+      @span = span
+    end
+
+    def plan
+      return RewritePlan.failure("unsupported_syntax") if unsupported_syntax?
+      return RewritePlan.failure("requirement_mismatch") unless requirement_matches? && edit
+      return RewritePlan.failure("verification_failed") unless verifier.verified?
+
+      RewritePlan.success([edit])
+    end
+
+    private
+
+    attr_reader :update, :span
+
+    def unsupported_syntax?
+      DeclarationBody.new(span.body).unsupported_syntax?
+    end
+
+    def requirement_matches?
+      requirement && requirement["kind"] == update.kind
+    end
+
+    def requirement
+      @requirement ||= ManifestParser.requirement_for(span.body)
+    end
+
+    def edit
+      @edit ||= RequirementEdit.new(update, span).to_h
+    end
+
+    def verifier
+      EditVerifier.new(update, span, edit)
+    end
+  end
+  private_constant :EditAttempt
+
+  # Builds the byte-range replacement for one supported requirement.
+  class RequirementEdit
+    def initialize(update, span)
+      @update = update
+      @span = span
+    end
+
+    def to_h
+      return unless target && offset
+
+      body_start = span.body_start
+      {
+        start: body_start + offset[0],
+        finish: body_start + offset[1],
+        replacement: target
+      }
+    end
+
+    private
+
+    attr_reader :update, :span
+
+    def target
+      @target ||= TargetVersion.new(update, span.body).value
+    end
+
+    def offset
+      @offset ||= VersionLiteralLocator.new(span.body, update).offset
+    end
+  end
+  private_constant :RequirementEdit
+
+  # Chooses the target version, including range upper-bound expansion.
+  class TargetVersion
+    def initialize(update, body)
+      @update = update
+      @body = body
+    end
+
+    def value
+      return @update.available_version unless expand_range_maximum?
+
+      maximum_for_range
+    end
+
+    private
+
+    def expand_range_maximum?
+      @update.kind == "versionRange" && @update.type == "above_maximum"
+    end
+
+    def maximum_for_range
+      available_version = @update.available_version
+      return available_version if range.closed?
+
+      version = SpmVersionUpdates::Semver.new(available_version)
+      "#{version.major + 1}.0.0"
+    rescue ArgumentError
+      nil
+    end
+
+    def range
+      @range ||= VersionRangeLiteral.new(@body)
+    end
+  end
+  private_constant :TargetVersion
+
+  # Locates the version literal that should be replaced inside a declaration.
+  class VersionLiteralLocator
+    def initialize(body, update)
+      @body = body
+      @update = update
+    end
+
+    def offset
+      case @update.kind
+      when "exactVersion" then exact_offset
+      when "upToNextMajorVersion" then major_offset
+      when "upToNextMinorVersion" then minor_offset
+      when "versionRange" then range_offset
+      end
+    end
+
+    private
+
+    def exact_offset
+      first_capture([/\bexact\s*:\s*"([^"]+)"/, /\.exact\s*\(\s*"([^"]+)"/])
+    end
+
+    def major_offset
+      first_capture([/\.upToNextMajor\s*\(\s*from\s*:\s*"([^"]+)"/, /\bfrom\s*:\s*"([^"]+)"/])
+    end
+
+    def minor_offset
+      first_capture([/\.upToNextMinor\s*\(\s*from\s*:\s*"([^"]+)"/])
+    end
+
+    def range
+      @range ||= VersionRangeLiteral.new(@body)
+    end
+
+    def range_offset
+      @update.type == "above_maximum" ? range.maximum_offset : range.minimum_offset
+    end
+
+    def first_capture(patterns)
+      patterns.each { |pattern|
+        match = @body.match(pattern)
+        return match.offset(1) if match
+      }
+      nil
+    end
+  end
+  private_constant :VersionLiteralLocator
+
+  # Parsed Swift range literal for supported version-range requirements.
+  class VersionRangeLiteral
+    def initialize(body)
+      @match = body.match(/"([^"]+)"\s*(\.\.[.<])\s*"([^"]+)"/)
+    end
+
+    def closed?
+      operator == "..."
+    end
+
+    def minimum_offset
+      return unless @match
+
+      @match.offset(1)
+    end
+
+    def maximum_offset
+      return unless @match
+
+      @match.offset(3)
+    end
+
+    private
+
+    def operator
+      @match&.[](2)
+    end
+  end
+  private_constant :VersionRangeLiteral
+
+  # Verifies a generated edit still parses to the original requirement kind.
+  class EditVerifier
+    def initialize(update, span, edit)
+      @update = update
+      @span = span
+      @edit = edit
+    end
+
+    def verified?
+      return false unless edited_requirement_kind == @update.kind
+
+      edited_value == @edit[:replacement]
+    end
+
+    private
+
+    def edited_requirement_kind
+      ManifestParser.requirement_for(edited_body)&.fetch("kind", nil)
+    end
+
+    def edited_value
+      offset = VersionLiteralLocator.new(edited_body, @update).offset
+      offset && edited_body[offset[0]...offset[1]]
+    end
+
+    def edited_body
+      @edited_body ||= EditedBody.new(@span, @edit).value
+    end
+  end
+  private_constant :EditVerifier
+
+  # Applies one edit against a declaration body for verification.
+  class EditedBody
+    def initialize(span, edit)
+      @span = span
+      @edit = edit
+    end
+
+    def value
+      @value ||= @span.body.dup.tap { |body| body[relative_range] = @edit[:replacement] }
+    end
+
+    private
+
+    def relative_range
+      relative_start...relative_finish
+    end
+
+    def relative_start
+      @edit[:start] - @span.body_start
+    end
+
+    def relative_finish
+      @edit[:finish] - @span.body_start
+    end
+  end
+  private_constant :EditedBody
+
+  # Applies collected edits from right to left to preserve byte offsets.
+  class AppliedEdit
+    def initialize(attributes)
+      @attributes = attributes
+    end
+
+    def start
+      @attributes[:start]
+    end
+
+    def apply_to(content)
+      content[start...@attributes[:finish]] = @attributes[:replacement]
+    end
+  end
+  private_constant :AppliedEdit
+
+  # Applies collected edits from right to left to preserve byte offsets.
+  class EditApplier
+    def initialize(content, edits)
+      @content = content
+      @edits = edits.map { |edit| AppliedEdit.new(edit) }
+    end
+
+    def content
+      @edits.sort_by { |edit| -edit.start }
+        .each_with_object(@content.dup) { |edit, updated|
+        edit.apply_to(updated)
+      }
+    end
+  end
+  private_constant :EditApplier
+
+  # Stateful implementation kept private so the public API remains small.
+  class Rewriter
+    def initialize(content, updates)
+      @content = content
+      @updates = Array(updates).map { |update| UpdateRecord.new(update) }
+      @spans = ManifestParser.package_call_spans(content)
+      @changes = RewriteChanges.new
+    end
+
+    def rewrite
+      @updates.each { |update| rewrite_update(update) }
+      updated_content = EditApplier.new(@content, @changes.edits).content
+      Result.new(content: updated_content, applied: @changes.applied, skipped: @changes.skipped, changed: updated_content != @content)
+    end
+
+    private
+
+    def rewrite_update(update)
+      plan = rewrite_plan(update)
+      return @changes.skip(update, plan.reason) if plan.failed?
+
+      @changes.apply(update, plan.edits)
+    end
+
+    def rewrite_plan(update)
+      return RewritePlan.failure("unsupported_requirement_kind") unless SUPPORTED_KINDS.include?(update.kind)
+
+      EditPlanner.new(update, @spans).plan
+    end
+  end
+  private_constant :Rewriter
+end

data/lib/spm_version_updates/package_resolved.rb

@@ -27,13 +27,29 @@ module PackageResolved
   # @raise [MalformedFileError] if the file is not valid JSON
   # @return [Hash<String, String>] normalized repository URL => version or revision
   def self.versions_from(path)
+    pins_from(path).to_h { |pin| [pin["normalized_url"], pin["version"] || pin["revision"]] }
+  end
+
+  # Extract structured pins from a `Package.resolved` file.
+  #
+  # @param  [String] path The path to a `Package.resolved` file
+  # @raise [MalformedFileError] if the file is not valid JSON
+  # @return [Array<Hash>] pin records with normalized_url, repository_url,
+  #   version, and revision
+  def self.pins_from(path)
     contents = load_contents(path)
     pins = contents["pins"] || contents.dig("object", "pins") || []
-    pins.to_h { |pin|
-      [
-        GitOperations.trim_repo_url(pin["location"] || pin["repositoryURL"]),
-        pin.dig("state", "version") || pin.dig("state", "revision"),
-      ]
+    pins.map { |pin| pin_record(pin) }
+  end
+
+  def self.pin_record(pin)
+    repository_url = pin["location"] || pin["repositoryURL"]
+    state = pin["state"] || {}
+    {
+      "normalized_url" => GitOperations.trim_repo_url(repository_url),
+      "repository_url" => repository_url,
+      "version" => state["version"],
+      "revision" => state["revision"]
     }
   end
 
@@ -43,5 +59,6 @@ module PackageResolved
     raise(MalformedFileError.new(path, error.message))
   end
 
-  private_class_method :load_contents
+  private_class_method :load_contents,
+                       :pin_record
 end

data/lib/spm_version_updates/semver.rb

@@ -5,7 +5,7 @@ require "semverify"
 # Namespace for the core gem's published constants (gem version and the
 # {SpmVersionUpdates::Semver} value object).
 module SpmVersionUpdates
-  # SemVer value object used by both the GitHub Action and legacy Danger plugin.
+  # SemVer value object used by both the GitHub Action and Danger plugin.
   class Semver
     include Comparable
 

data/lib/spm_version_updates/spm_checker.rb

@@ -16,21 +16,166 @@ require_relative "version_tags_persistent_cache"
 require_relative "xcode_parser"
 
 # Core SPM version checking logic (migrated from Danger plugin)
+# rubocop:disable Metrics/ClassLength
 class SpmChecker
-  VERSION_TAG_WORKER_COUNT = 8
+  DEFAULT_VERSION_LOOKUP_WORKERS = 4
 
   # Raised when allow-hosts blocks a repository before git is contacted.
   class DisallowedRepositoryHost < SpmVersionUpdates::PolicyError; end
 
-  # Structured facts about each warning, used by the GitHub Action comment
-  # renderer. `check_for_updates` and `check_manifests` still return the legacy
-  # string warnings for compatibility with existing plugin-style callers.
-  attr_reader :warning_details
+  # Filters configured Package.resolved paths and reports missing files.
+  class ResolvedPathList
+    def initialize(paths, missing_handler)
+      @paths = paths
+      @missing_handler = missing_handler
+    end
+
+    def existing
+      return @paths if missing.empty?
+
+      raise(ManifestParser::CouldNotFindResolvedFile, missing.join(", ")) unless @missing_handler
+
+      @missing_handler.call(missing)
+      @paths - missing
+    end
+
+    private
+
+    def missing
+      @missing ||= @paths.reject { |path| File.exist?(path) }
+    end
+  end
+  private_constant :ResolvedPathList
+
+  # Converts resolved pins into the package and version maps consumed by checks.
+  class ResolvedPackageEntries
+    def initialize(path, malformed_handler)
+      @path = path
+      @malformed_handler = malformed_handler
+    end
+
+    def packages_and_versions
+      pins.each_with_object([{}, {}]) { |pin, (packages, versions)|
+        entry = ResolvedPinEntry.new(pin)
+        entry.add_to(packages, versions)
+      }
+    end
+
+    private
+
+    def pins
+      PackageResolved.pins_from(@path)
+    rescue PackageResolved::MalformedFileError => error
+      raise unless @malformed_handler
+
+      @malformed_handler.call(@path, error)
+      []
+    end
+  end
+  private_constant :ResolvedPackageEntries
+
+  # Normalized data derived from one Package.resolved pin.
+  class ResolvedPinEntry
+    def initialize(pin)
+      @pin = pin
+    end
+
+    def normalized_url
+      @pin["normalized_url"]
+    end
+
+    def package
+      {
+        "repository_url" => @pin["repository_url"],
+        "requirement" => requirement
+      }
+    end
+
+    def resolved_version
+      @pin["version"] || @pin["revision"]
+    end
+
+    def add_to(packages, versions)
+      packages[normalized_url] = package
+      versions[normalized_url] = resolved_version
+    end
+
+    private
+
+    def requirement
+      version = @pin["version"]
+      return { "kind" => "resolvedPin", "version" => version } if version
 
-  # ParseWarning records for `.package(...)` declarations the manifest parser
-  # had to skip. Kept separate from update warnings so reported update counts
-  # and fail-on thresholds are unaffected.
-  attr_reader :parse_warnings
+      { "kind" => "revision", "revision" => @pin["revision"] }
+    end
+  end
+  private_constant :ResolvedPinEntry
+
+  # Builds warning detail records while preserving explicit nil requirements.
+  class WarningDetailRecord
+    def initialize(message, package, detail)
+      @message = message
+      @package = package
+      @detail = detail
+    end
+
+    def to_h
+      with_optional_requirement(compacted_record)
+    end
+
+    private
+
+    def record
+      @detail.merge(message: @message, source: @package.source)
+    end
+
+    def compacted_record
+      record.compact
+    end
+
+    def with_optional_requirement(compacted)
+      return compacted unless record.key?(:suggested_requirement)
+
+      compacted.merge(suggested_requirement: record[:suggested_requirement])
+    end
+  end
+  private_constant :WarningDetailRecord
+
+  # Parses a package's resolved version for semantic comparisons.
+  class PackageSemver
+    def initialize(package)
+      @package = package
+    end
+
+    def value
+      resolved_version = @package.resolved_version
+      SpmVersionUpdates::Semver.new(resolved_version)
+    rescue ArgumentError => error
+      puts("Unable to extract semver from #{resolved_version} for #{@package.name} (#{error})")
+      nil
+    end
+  end
+  private_constant :PackageSemver
+
+  # Structured result from one checker run. Parse warnings stay separate from
+  # update records so counts and fail-on thresholds only consider real updates.
+  class Result
+    attr_reader :updates, :parse_warnings
+
+    def initialize(updates:, parse_warnings:)
+      @updates = normalize_records(updates)
+      @parse_warnings = normalize_records(parse_warnings)
+    end
+
+    private
+
+    def normalize_records(records)
+      Array(records).map { |record| record.to_h.transform_keys(&:to_s).compact.freeze }
+        .freeze
+    end
+  end
+
+  attr_reader :version_lookup_workers
 
   attr_accessor :allow_hosts,
                 :check_branches,
@@ -54,6 +199,12 @@ class SpmChecker
   # default), PackageResolved::MalformedFileError is raised.
   attr_accessor :malformed_resolved_handler
 
+  # Optional callable `(missing_paths)` invoked instead of raising when expected
+  # Package.resolved files are missing. Missing paths are dropped and packages
+  # without a resolved version keep the existing "Unable to locate..." behavior:
+  # no warning record is created and no version tags are fetched for them.
+  attr_accessor :missing_resolved_handler
+
   def self.redact_credentials(value)
     CredentialRedactor.redact(value)
   end
@@ -61,12 +212,12 @@ class SpmChecker
   def initialize
     @check_when_exact = @check_revisions = @report_above_maximum = @report_pre_releases = false
     @check_branches = true
-    @lookup_failure_handler = @malformed_resolved_handler = nil
+    @lookup_failure_handler = @malformed_resolved_handler = @missing_resolved_handler = nil
     @ignore_repos = []
     @repository_update_rules = RepositoryUpdateRules.empty
     @allow_hosts = []
-    @warnings = []
-    @warning_details = []
+    @version_lookup_workers = DEFAULT_VERSION_LOOKUP_WORKERS
+    @updates = []
     @parse_warnings = []
     @version_tags_cache = {}
     @version_tag_lookup_errors = {}
@@ -75,15 +226,19 @@ class SpmChecker
     @version_tags_cache_ttl_seconds = VersionTagsPersistentCache::DEFAULT_TTL_SECONDS
   end
 
+  def version_lookup_workers=(value)
+    workers = Integer(value.to_s, 10, exception: false)
+    raise(SpmVersionUpdates::ConfigurationError, "version_lookup_workers must be a positive integer") unless workers && workers >= 1
+
+    @version_lookup_workers = workers
+  end
+
   # Check for SPM updates using an Xcode project as the source of dependencies.
   #
   # @param   [String] xcodeproj_path The path to your Xcode project
-  # @return  [Array<String>] Array of warning messages
+  # @return  [Result] Structured update records and parse warnings
   def check_for_updates(xcodeproj_path)
-    clear_warnings
-    reset_version_tags_cache
-    normalize_ignore_repos
-    normalize_allow_hosts
+    prepare_run
 
     remote_packages = XcodeParser.get_packages(xcodeproj_path)
     resolved_versions = XcodeParser.get_resolved_versions(xcodeproj_path, &@malformed_resolved_handler)
@@ -91,7 +246,7 @@ class SpmChecker
     warn_for_empty_xcode_project(remote_packages, resolved_versions, xcodeproj_path)
 
     check_packages(remote_packages, resolved_versions)
-    @warnings
+    result
   end
 
   # Check for SPM updates using one or more `Package.swift` manifests as the
@@ -107,12 +262,9 @@ class SpmChecker
   #          `Package.resolved` paths. When omitted, a `Package.resolved` next to
   #          each manifest is used.
   # @raise [ManifestParser::CouldNotFindResolvedFile] if no resolved file exists
-  # @return  [Array<String>] Array of warning messages
+  # @return  [Result] Structured update records and parse warnings
   def check_manifests(manifest_paths, resolved_paths = nil)
-    clear_warnings
-    reset_version_tags_cache
-    normalize_ignore_repos
-    normalize_allow_hosts
+    prepare_run
 
     resolved_versions = merged_resolved_versions(manifest_paths, resolved_paths)
     puts("Found resolved versions for #{resolved_versions.size} packages")
@@ -120,11 +272,34 @@ class SpmChecker
     manifest_paths.each { |manifest_path|
       check_packages(manifest_packages(manifest_path), resolved_versions, manifest_path)
     }
-    @warnings
+    result
+  end
+
+  # Check for SPM updates using one or more `Package.resolved` files as the
+  # source of dependencies. Version pins are compared directly with available
+  # tags; revision-only pins are reported only when check_revisions is enabled.
+  #
+  # @param [Array<String>] resolved_paths Paths to one or more Package.resolved files
+  # @raise [SpmVersionUpdates::ConfigurationError] if no paths are supplied
+  # @return [Result] Structured update records and parse warnings
+  def check_resolved(resolved_paths)
+    prepare_run
+    paths = normalized_resolved_paths(resolved_paths)
+    raise(SpmVersionUpdates::ConfigurationError, "package-resolved-paths must be set") if paths.empty?
+
+    check_existing_resolved_paths(paths)
+    result
   end
 
   private
 
+  def prepare_run
+    clear_updates
+    reset_version_tags_cache
+    normalize_ignore_repos
+    normalize_allow_hosts
+  end
+
   def manifest_packages(manifest_path)
     ManifestParser.get_packages(manifest_path) { |skip| record_parse_warning(skip, manifest_path) }
   end
@@ -149,9 +324,12 @@ class SpmChecker
     raw_allow_hosts.any? && @allow_hosts.empty?
   end
 
-  def clear_warnings
-    @warnings.clear
-    @warning_details.clear
+  def result
+    Result.new(updates: @updates, parse_warnings: @parse_warnings)
+  end
+
+  def clear_updates
+    @updates.clear
     @parse_warnings.clear
   end
 
@@ -185,16 +363,23 @@ class SpmChecker
   #
   # @return [Hash<String, String>]
   def merged_resolved_versions(manifest_paths, resolved_paths)
-    paths = Array(resolved_paths).map(&:to_s).reject(&:empty?)
+    paths = normalized_resolved_paths(resolved_paths)
     paths = manifest_paths.map { |manifest| ManifestParser.default_resolved_path(manifest) } if paths.empty?
 
-    missing = paths.reject { |path| File.exist?(path) }
-    raise(ManifestParser::CouldNotFindResolvedFile, missing.join(", ")) unless missing.empty?
+    paths = existing_paths(paths)
 
     puts("Reading resolved packages from: #{paths}")
     paths.each_with_object({}) { |path, pins| pins.merge!(resolved_versions_from(path)) }
   end
 
+  def normalized_resolved_paths(paths)
+    Array(paths).map(&:to_s).reject(&:empty?)
+  end
+
+  def existing_paths(paths)
+    ResolvedPathList.new(paths, @missing_resolved_handler).existing
+  end
+
   def resolved_versions_from(path)
     PackageResolved.versions_from(path)
   rescue PackageResolved::MalformedFileError => error
@@ -204,6 +389,17 @@ class SpmChecker
     {}
   end
 
+  def packages_from_resolved(path)
+    ResolvedPackageEntries.new(path, @malformed_resolved_handler).packages_and_versions
+  end
+
+  def check_existing_resolved_paths(paths)
+    existing_paths(paths).each { |path|
+      remote_packages, resolved_versions = packages_from_resolved(path)
+      check_packages(remote_packages, resolved_versions, path)
+    }
+  end
+
   # Compare a set of declared dependencies against the resolved pins.
   #
   # Packages are keyed by their normalized repository URL, which is what we match
@@ -312,7 +508,7 @@ class SpmChecker
     persistent_cache = VersionTagsPersistentCache.new(directory: @version_tags_cache_dir, ttl_seconds: @version_tags_cache_ttl_seconds)
     results, errors = VersionTagFetcher.call(
       pending,
-      worker_limit: VERSION_TAG_WORKER_COUNT,
+      worker_limit: @version_lookup_workers,
       persistent_cache:,
       raise_on_error: !@lookup_failure_handler
     )
@@ -386,6 +582,8 @@ class SpmChecker
       warn_for_new_versions(package, available_versions, :minor)
     when "versionRange"
       warn_for_new_versions_range(package, available_versions)
+    when "resolvedPin"
+      warn_for_new_versions_pin(package, available_versions)
     else
       puts("Not processing dependency rule '#{kind}' for #{package.name} (#{self.class.redact_credentials(repository_url)})")
     end
@@ -399,13 +597,12 @@ class SpmChecker
   end
 
   def record_warning(message, package, record)
-    @warnings << [message, package.source_line].compact.join("\n")
-    @warning_details << record
+    @updates << record
     puts("WARNING: #{message}#{package.source_suffix}")
   end
 
   def warning_detail_record(message, package, detail)
-    detail.merge(message:, source: package.source).compact
+    WarningDetailRecord.new(message, package, detail).to_h
   end
 
   def warning_detail(type, package, available_version, note = nil)
@@ -506,6 +703,20 @@ class SpmChecker
     end
   end
 
+  def warn_for_new_versions_pin(package, available_versions)
+    resolved_version = PackageSemver.new(package).value
+    return unless resolved_version
+
+    newest_version = newest_reportable_version(available_versions)
+    return unless newest_version && newest_version > resolved_version
+
+    add_warning(
+      "Newer version of #{package.name}: #{newest_version}",
+      package,
+      warning_detail(:version, package, newest_version, "resolved pin")
+    )
+  end
+
   def warn_for_new_versions(package, available_versions, major_or_minor)
     name = package.name
     resolved_version_string = package.resolved_version
@@ -548,3 +759,4 @@ class SpmChecker
     )
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/spm_version_updates/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SpmVersionUpdates
-  VERSION = "1.2.0"
+  VERSION = "2.0.0"
 end

data/lib/spm_version_updates.rb

@@ -7,6 +7,7 @@ require_relative "spm_version_updates/fail_on_threshold"
 require_relative "spm_version_updates/git_host_normalizer"
 require_relative "spm_version_updates/git_operations"
 require_relative "spm_version_updates/manifest_parser"
+require_relative "spm_version_updates/manifest_updater"
 require_relative "spm_version_updates/package_resolved"
 require_relative "spm_version_updates/parse_warning"
 require_relative "spm_version_updates/repository_link"

data/spm_version_updates.gemspec

@@ -40,7 +40,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.metadata["rubygems_mfa_required"] = "true"
 
-  spec.add_runtime_dependency("semverify", "~> 0.3")
+  spec.add_dependency("semverify", "~> 0.3")
   # Xcode-project mode additionally requires the "xcodeproj" gem (loaded
   # lazily); manifest mode works without it.
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spm_version_updates
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Harold Martin
@@ -41,6 +41,7 @@ files:
 - lib/spm_version_updates/git_host_normalizer.rb
 - lib/spm_version_updates/git_operations.rb
 - lib/spm_version_updates/manifest_parser.rb
+- lib/spm_version_updates/manifest_updater.rb
 - lib/spm_version_updates/package_resolved.rb
 - lib/spm_version_updates/parse_warning.rb
 - lib/spm_version_updates/repository_link.rb