spm_version_updates 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 922e9383223719cafb033ce65ca8b710013bc1654217973443b1b1b99eead693
-  data.tar.gz: b6a5fa439183d0cfcb8192b050565020b8f314e18f573d88b8e4ce40fb619bfb
+  metadata.gz: 53afb3742bddcef276c343767b4570a4d428cefe7560ba2460d461dfcf66c3c1
+  data.tar.gz: bde5dd5228e9c7ae5188efa42ef0343bc1def8b45bb22f16a9ce343fb9f94e4e
 SHA512:
-  metadata.gz: cc90410091871b58726de87d0f8e992e3abf08c75799dc1901c1afd893ca5736f39c02076b136523a3ba437a5796e51cf196abcd728e513b4e1e27dd9332945f
-  data.tar.gz: a7329c84f09b9615cf25872e4e3181694b306e717dc978b36b8edbd8334543339f68d4bd2402ae84c15e425cad2005e6ace00475c41598c36ca81309f1f3f95a
+  metadata.gz: 80f629e2ef3cc2c5a2162a61cedf485948bbd88616451d666b82776fc4034744cd2b9cb8d78c2c02628446f32027206e9d1913b0fe495ca51cf53619b599ede1
+  data.tar.gz: 50adb15cd7e1703487bc386a7f0bc81d022698d172ece4008b20ab33b9602c578bf33622a5a26340c713d1e02a5fd5af2d0d7fb9ec2db8fbcfe083ba8f3ace0a

data/README.md

@@ -42,6 +42,92 @@ Behavior is configurable through accessors on `SpmChecker` — for example
 `report_pre_releases`, `ignore_repos`, and allow-host restrictions. See the
 class documentation for the full list.
 
+## Errors
+
+Everything the gem raises descends from one of two roots (defined in
+`lib/spm_version_updates/errors.rb`), so callers can rescue by failure
+category instead of enumerating concrete classes:
+
+- **`SpmVersionUpdates::Error < StandardError`**
+  - **`FileNotFoundError`** — a required file is missing:
+    - `ManifestParser::CouldNotFindManifest` — a `Package.swift` path does
+      not exist.
+    - `ManifestParser::CouldNotFindResolvedFile` — an expected
+      `Package.resolved` is missing in manifest mode; the message names the
+      missing file(s). Raised rather than silently reporting incomplete
+      results.
+    - `XcodeParser::CouldNotFindResolvedFile` — no `Package.resolved` was
+      found in the Xcode workspace locations.
+  - **`ParseError`** — a file exists but could not be read:
+    - `PackageResolved::MalformedFileError` — a corrupt or unrecognized
+      `Package.resolved`.
+  - **`NetworkError`** — git lookup failures:
+    - `GitOperations::LsRemoteError` — `git ls-remote` failed after bounded
+      retries (unreachable host, authentication failure). Messages are
+      credential-redacted.
+  - **`PolicyError`** — security-gate violations:
+    - `SpmChecker::DisallowedRepositoryHost` — `allow_hosts` is configured
+      and a dependency's host is not on the list. Raised before git is
+      contacted.
+- **`SpmVersionUpdates::ConfigurationError < ArgumentError`** — invalid
+  caller-supplied configuration: `ManifestParser::ManifestPathMustBeSet`,
+  `XcodeParser::XcodeprojPathMustBeSet`, `allow_hosts` entries that don't
+  parse as hostnames, and every invalid repo-rules YAML shape. It inherits
+  `ArgumentError` (not `Error`) so existing callers that rescue
+  `ArgumentError` keep working — rescue it alongside
+  `SpmVersionUpdates::Error` when catching everything the gem raises:
+
+```ruby
+begin
+  checker.check_manifests(["Modules/Package.swift"])
+rescue SpmVersionUpdates::ConfigurationError, SpmVersionUpdates::Error => error
+  abort(error.message)
+end
+```
+
+## Continuing past per-dependency failures
+
+By default, the first failed git lookup or malformed `Package.resolved`
+raises and aborts the run. Two optional handlers turn those into callbacks so
+the remaining dependencies keep being checked:
+
+```ruby
+# Called as (package, error) instead of raising GitOperations::LsRemoteError.
+# A dependency shared by several manifests is reported only once per run.
+checker.lookup_failure_handler = ->(package, error) {
+  puts("Skipping #{package.name}: #{error.message}")
+}
+
+# Called as (resolved_path, error) instead of raising
+# PackageResolved::MalformedFileError; the file's pins are skipped.
+checker.malformed_resolved_handler = ->(path, error) {
+  puts("Ignoring #{path}: #{error.message}")
+}
+```
+
+## Parse warnings
+
+A `.package(...)` declaration whose version requirement isn't recognized (or
+that has unbalanced parentheses) is skipped rather than guessed at. Each skip
+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"])
+
+checker.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".
+  puts(record["message"])
+  puts(ParseWarning.describe_reason(record))  # the reason as a readable phrase
+  puts(ParseWarning.issue_link(record))       # pre-filled GitHub new-issue URL
+end
+```
+
+The snippet is redacted and shown in the report only — it is never embedded
+in the issue URL, where it could leak private repository URLs.
+
 ## License
 
 MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/spm_version_updates/allow_host_normalizer.rb

@@ -4,6 +4,7 @@ require_relative "git_host_normalizer"
 require_relative "git_operations"
 
 # Normalizes user-provided allow-host entries into hostnames.
+# @api private
 class AllowHostNormalizer
   MALFORMED_SCHEME_PATTERN = %r{\A[a-z][a-z0-9+\-.]*//}i
 

data/lib/spm_version_updates/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Category base classes for every error raised by spm_version_updates, so
+# callers can rescue by failure kind instead of enumerating each concrete
+# class. The concrete classes (e.g. ManifestParser::CouldNotFindManifest)
+# keep their existing names and namespaces; only their superclasses point
+# here.
+module SpmVersionUpdates
+  # Base class for all errors raised by spm_version_updates.
+  class Error < StandardError; end
+
+  # Invalid user-supplied configuration or inputs. Inherits ArgumentError (not
+  # Error) so existing callers that rescue ArgumentError keep working; rescue
+  # it alongside Error when catching everything this gem raises.
+  class ConfigurationError < ArgumentError; end
+
+  # A required file (manifest, Package.resolved) could not be found.
+  class FileNotFoundError < Error; end
+
+  # A file exists but could not be parsed.
+  class ParseError < Error; end
+
+  # git or network lookup failures.
+  class NetworkError < Error; end
+
+  # Policy violations, e.g. a repository host blocked by allow-hosts.
+  class PolicyError < Error; end
+end

data/lib/spm_version_updates/fail_on_threshold.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "errors"
 require_relative "update_severity"
 
 # Parses fail-on inputs and evaluates whether reported updates should fail.
@@ -34,7 +35,7 @@ module FailOnThreshold
     return ANY if normalized == "true"
     return normalized if UpdateSeverity.threshold?(normalized)
 
-    raise(ArgumentError, "#{input_name} must be false, true, major, minor, or patch")
+    raise(SpmVersionUpdates::ConfigurationError, "#{input_name} must be false, true, major, minor, or patch")
   end
 
   def self.build_message(threshold, count)

data/lib/spm_version_updates/git_host_normalizer.rb

@@ -4,6 +4,7 @@ require "ipaddr"
 require "uri"
 
 # Extracts and normalizes hostnames from common git remote URL forms.
+# @api private
 module GitHostNormalizer
   HOST_PATTERN = /\A[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\z/i
   BRACKETED_IPV6_PATTERN = /\A\[(?<address>[^\]]+)\](?::\d+)?\z/

data/lib/spm_version_updates/git_operations.rb

@@ -2,6 +2,7 @@
 
 require "open3"
 require_relative "credential_redactor"
+require_relative "errors"
 require_relative "git_host_normalizer"
 require_relative "semver"
 
@@ -16,7 +17,7 @@ module GitOperations
   TAG_REF_PATTERNS = ["[0-9]*.[0-9]*", "v[0-9]*.[0-9]*"].freeze
 
   # Raised when git cannot complete a remote reference lookup.
-  class LsRemoteError < StandardError; end
+  class LsRemoteError < SpmVersionUpdates::NetworkError; end
 
   # Removes protocol and trailing .git from a repo URL
   # @param   [String] repo_url The URL of the repository

data/lib/spm_version_updates/manifest_parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "errors"
 require_relative "git_operations"
 require_relative "package_resolved"
 
@@ -31,20 +32,26 @@ module ManifestParser
   # scheme-bearing `repository_url` is retained for git operations.
   #
   # @param  [String] manifest_path The path to a `Package.swift` file
+  # @yield  [Hash] optionally receives `{ reason:, snippet: }` for each
+  #         `.package(...)` declaration that had to be skipped, so callers can
+  #         surface parse warnings instead of dropping dependencies silently
   # @raise  [ManifestPathMustBeSet] if the manifest_path is blank
   # @raise  [CouldNotFindManifest] if the file does not exist
   # @return [Hash<String, Hash>] normalized URL => { "repository_url", "requirement" }
-  def self.get_packages(manifest_path)
+  def self.get_packages(manifest_path, &on_skip)
     raise(ManifestPathMustBeSet) if manifest_path.nil? || manifest_path.empty?
     raise(CouldNotFindManifest, manifest_path) unless File.exist?(manifest_path)
 
     content = strip_comments(File.read(manifest_path))
-    package_calls(content).each_with_object({}) { |call, packages|
+    package_calls(content, &on_skip).each_with_object({}) { |call, packages|
       url = call[/\burl\s*:\s*"([^"]+)"/, 1]
       next if url.nil? # local package (path:) or otherwise unrecognized
 
       requirement = requirement_for(call)
-      next if requirement.nil?
+      if requirement.nil?
+        on_skip&.call({ reason: "unrecognized_requirement", snippet: call })
+        next
+      end
 
       packages[GitOperations.trim_repo_url(url)] = { "repository_url" => url, "requirement" => requirement }
     }
@@ -69,15 +76,21 @@ module ManifestParser
   # Extract the argument body of each `.package( ... )` call, honoring nested
   # parentheses (e.g. `.upToNextMajor(from: "1.0.0")`) and string literals.
   #
+  # An unclosed call cannot be skipped safely (there is no closing paren to
+  # resume after), so scanning stops there; the skip callback says so.
+  #
   # @param  [String] content The (comment-stripped) manifest source
   # @return [Array<String>]
-  def self.package_calls(content)
+  def self.package_calls(content, &on_skip)
     calls = []
     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)
-      break if close_index.nil?
+      if close_index.nil?
+        on_skip&.call({ reason: "unbalanced_parentheses", snippet: content[marker_index, 300] })
+        break
+      end
 
       calls << content[(open_index + 1)...close_index]
       search_start = close_index + 1
@@ -245,14 +258,26 @@ module ManifestParser
                        :skip_block_comment
 
   # Raised when manifest mode is invoked without a manifest path.
-  class ManifestPathMustBeSet < StandardError
+  class ManifestPathMustBeSet < SpmVersionUpdates::ConfigurationError
+    def initialize(message = "package-manifest-paths must be set")
+      super
+    end
   end
 
   # Raised when a configured Package.swift manifest is missing.
-  class CouldNotFindManifest < StandardError
+  class CouldNotFindManifest < SpmVersionUpdates::FileNotFoundError
+    def initialize(path)
+      super("Could not find Package.swift manifest: #{path}")
+    end
   end
 
   # Raised when manifest mode cannot find an expected Package.resolved file.
-  class CouldNotFindResolvedFile < StandardError
+  class CouldNotFindResolvedFile < SpmVersionUpdates::FileNotFoundError
+    def initialize(paths)
+      super(
+        "Could not find any Package.resolved file (looked in: #{paths}). " \
+        "Commit a Package.resolved next to each manifest or set package-resolved-paths."
+      )
+    end
   end
 end

data/lib/spm_version_updates/package_resolved.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "errors"
 require_relative "git_operations"
 
 # Parsing for `Package.resolved` files.
@@ -10,7 +11,7 @@ require_relative "git_operations"
 # and the Swift package manifest source mode.
 module PackageResolved
   # Raised when a `Package.resolved` file exists but is not valid JSON.
-  class MalformedFileError < StandardError
+  class MalformedFileError < SpmVersionUpdates::ParseError
     attr_reader :path
 
     def initialize(path, parse_message)

data/lib/spm_version_updates/parse_warning.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "credential_redactor"
+
+# Builds the structured records used to report `.package(...)` declarations
+# that the manifest parser had to skip, plus the pre-filled GitHub issue link
+# shown alongside them. The manifest snippet is redacted and shown in the
+# report only — never embedded in the issue URL, where it could leak private
+# repository URLs through logs or referrer headers.
+module ParseWarning
+  ISSUE_URL = "https://github.com/hbmartin/github-action-spm_version_updates/issues/new"
+  SNIPPET_LIMIT = 200
+
+  REASONS = {
+    "unrecognized_requirement" => "its version requirement was not recognized",
+    "unbalanced_parentheses" => "it has unbalanced parentheses, so the remainder of this manifest was not scanned"
+  }.freeze
+
+  # @param reason [String] a REASONS key
+  # @param source [String] the manifest path the declaration came from
+  # @param snippet [String] the raw declaration text (redacted and truncated here)
+  # @return [Hash] type / reason / source / snippet / message, string-keyed
+  def self.record(reason:, source:, snippet:)
+    reason = reason.to_s
+    {
+      "type" => "parse_warning",
+      "reason" => reason,
+      "source" => source,
+      "snippet" => truncated_snippet(snippet),
+      "message" => message_for(reason, source)
+    }
+  end
+
+  # A GitHub new-issue URL pre-filled with everything except the manifest
+  # content, which the template asks the reporter to paste in themselves.
+  # @param record [Hash] a {record} hash
+  # @return [String]
+  def self.issue_link(record)
+    reason = record["reason"]
+    query = URI.encode_www_form(
+      title: "Manifest parse failure: #{reason}",
+      body: issue_body(reason)
+    )
+    "#{ISSUE_URL}?#{query}"
+  end
+
+  # @param record [Hash] a {record} hash
+  # @return [String] the reason as a readable phrase
+  def self.describe_reason(record)
+    reason = record["reason"]
+    REASONS.fetch(reason, reason)
+  end
+
+  def self.message_for(reason, source)
+    "Could not parse a `.package(...)` declaration in #{source} because " \
+      "#{REASONS.fetch(reason, reason)}. Updates for the affected " \
+      "dependency were not checked. If this is valid Swift, please open an issue."
+  end
+
+  def self.truncated_snippet(snippet)
+    redacted = CredentialRedactor.redact(snippet.to_s.strip).to_s
+    return redacted if redacted.length <= SNIPPET_LIMIT
+
+    "#{redacted[0, SNIPPET_LIMIT]}…"
+  end
+
+  def self.issue_body(reason)
+    <<~BODY
+      A `.package(...)` declaration in my `Package.swift` could not be parsed (reason: #{reason}).
+
+      Please paste the declaration below (remove any credentials or private URLs first):
+
+      ```swift
+      (paste the .package(...) declaration here)
+      ```
+    BODY
+  end
+
+  private_class_method :message_for, :truncated_snippet, :issue_body
+end

data/lib/spm_version_updates/repository_update_rules.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "errors"
 require_relative "git_operations"
 require_relative "semver"
 require_relative "update_severity"
@@ -63,13 +64,13 @@ class RepositoryUpdateRules
     yaml_config = YAML.safe_load_file(path, permitted_classes: [], permitted_symbols: [], aliases: false) || {}
     from_hash(yaml_config, source: path)
   rescue Psych::Exception => error
-    raise(ArgumentError, "repo-rules YAML is invalid in #{path}: #{error.message}")
+    raise(SpmVersionUpdates::ConfigurationError, "repo-rules YAML is invalid in #{path}: #{error.message}")
   end
 
   def self.from_hash(config = {}, source: "repo rules", **keyword_config)
     effective_config = keyword_config.empty? ? config : keyword_config
     effective_config ||= {}
-    raise(ArgumentError, "#{source} must contain a YAML mapping") unless effective_config.kind_of?(Hash)
+    raise(SpmVersionUpdates::ConfigurationError, "#{source} must contain a YAML mapping") unless effective_config.kind_of?(Hash)
 
     new(parse_repositories(repositories_from(effective_config, source), source))
   end
@@ -84,7 +85,7 @@ class RepositoryUpdateRules
     repositories.each_with_object({}).with_index(1) { |(entry, rules), index|
       rule = parse_entry(entry, "#{source} repositories[#{index}]")
       normalized_url = rule.normalized_url
-      raise(ArgumentError, "duplicate repo-rules entry for #{normalized_url}") if rules.key?(normalized_url)
+      raise(SpmVersionUpdates::ConfigurationError, "duplicate repo-rules entry for #{normalized_url}") if rules.key?(normalized_url)
 
       rules[normalized_url] = rule
     }
@@ -99,8 +100,8 @@ class RepositoryUpdateRules
 
   def self.validated_file_path(path)
     path = path.to_s.strip
-    raise(ArgumentError, "repo-rules-path was set but no file path was provided") if path.empty?
-    raise(ArgumentError, "repo-rules-path file does not exist: #{path}") unless File.file?(path)
+    raise(SpmVersionUpdates::ConfigurationError, "repo-rules-path was set but no file path was provided") if path.empty?
+    raise(SpmVersionUpdates::ConfigurationError, "repo-rules-path file does not exist: #{path}") unless File.file?(path)
 
     path
   end
@@ -109,13 +110,13 @@ class RepositoryUpdateRules
     string_keys = config.transform_keys(&:to_s)
     validate_keys!(string_keys, VALID_YAML_KEYS.fetch(:root), "#{source} root")
     repositories = string_keys.compact.fetch(yaml_key(:repositories), [])
-    raise(ArgumentError, "#{source} repositories must be a list") unless repositories.kind_of?(Array)
+    raise(SpmVersionUpdates::ConfigurationError, "#{source} repositories must be a list") unless repositories.kind_of?(Array)
 
     repositories
   end
 
   def self.rule_entry_from(entry, source)
-    raise(ArgumentError, "#{source} must be a mapping") unless entry.kind_of?(Hash)
+    raise(SpmVersionUpdates::ConfigurationError, "#{source} must be a mapping") unless entry.kind_of?(Hash)
 
     entry.transform_keys(&:to_s).tap { |string_keys| validate_keys!(string_keys, VALID_YAML_KEYS.fetch(:entry), source) }
   end
@@ -124,7 +125,7 @@ class RepositoryUpdateRules
     normalized_url = normalized_url_for(required_value(string_keys, yaml_key(:url), source))
     ignore_until = parse_ignore_until(string_keys, source)
     allowed_updates = parse_allowed_updates(string_keys, source)
-    raise(ArgumentError, "#{source} must set #{yaml_key(:ignore_until)} or #{yaml_key(:allowed_updates)}") unless ignore_until || allowed_updates
+    raise(SpmVersionUpdates::ConfigurationError, "#{source} must set #{yaml_key(:ignore_until)} or #{yaml_key(:allowed_updates)}") unless ignore_until || allowed_updates
 
     { normalized_url:, ignore_until:, allowed_updates: }
   end
@@ -133,19 +134,19 @@ class RepositoryUpdateRules
     unknown = values.keys - allowed
     return if unknown.empty?
 
-    raise(ArgumentError, "#{source} contains unknown key(s): #{unknown.join(', ')}")
+    raise(SpmVersionUpdates::ConfigurationError, "#{source} contains unknown key(s): #{unknown.join(', ')}")
   end
 
   def self.required_value(values, key, source)
     value = values[key].to_s.strip
-    raise(ArgumentError, "#{source} #{key} must be set") if value.empty?
+    raise(SpmVersionUpdates::ConfigurationError, "#{source} #{key} must be set") if value.empty?
 
     value
   end
 
   def self.normalized_url_for(value)
     normalized = GitOperations.trim_repo_url(value)
-    raise(ArgumentError, "repo-rules url must normalize to a repository URL") if normalized.empty?
+    raise(SpmVersionUpdates::ConfigurationError, "repo-rules url must normalize to a repository URL") if normalized.empty?
 
     normalized
   end
@@ -155,7 +156,7 @@ class RepositoryUpdateRules
     return unless values.key?(key)
 
     semver(values[key].to_s.strip).tap { |version|
-      raise(ArgumentError, "#{source} #{key} must be a semantic version") unless version
+      raise(SpmVersionUpdates::ConfigurationError, "#{source} #{key} must be a semantic version") unless version
     }
   end
 
@@ -166,7 +167,7 @@ class RepositoryUpdateRules
     value = values[key].to_s.strip.downcase
     return value if SEVERITY_RANK.key?(value)
 
-    raise(ArgumentError, "#{source} #{key} must be patch, minor, or major")
+    raise(SpmVersionUpdates::ConfigurationError, "#{source} #{key} must be patch, minor, or major")
   end
 
   def self.record_value(record, key)

data/lib/spm_version_updates/semver.rb

@@ -2,6 +2,8 @@
 
 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.
   class Semver

data/lib/spm_version_updates/spm_checker.rb

@@ -2,9 +2,11 @@
 
 require_relative "allow_host_normalizer"
 require_relative "credential_redactor"
+require_relative "errors"
 require_relative "git_operations"
 require_relative "manifest_parser"
 require_relative "package_resolved"
+require_relative "parse_warning"
 require_relative "repository_update_rules"
 require_relative "semver"
 require_relative "spm_package_context"
@@ -18,13 +20,18 @@ class SpmChecker
   VERSION_TAG_WORKER_COUNT = 8
 
   # Raised when allow-hosts blocks a repository before git is contacted.
-  class DisallowedRepositoryHost < StandardError; end
+  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
 
+  # 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
+
   attr_accessor :allow_hosts,
                 :check_branches,
                 :check_revisions,
@@ -60,6 +67,7 @@ class SpmChecker
     @allow_hosts = []
     @warnings = []
     @warning_details = []
+    @parse_warnings = []
     @version_tags_cache = {}
     @version_tag_lookup_errors = {}
     @reported_lookup_failures = {}
@@ -110,14 +118,17 @@ class SpmChecker
     puts("Found resolved versions for #{resolved_versions.size} packages")
 
     manifest_paths.each { |manifest_path|
-      remote_packages = ManifestParser.get_packages(manifest_path)
-      check_packages(remote_packages, resolved_versions, manifest_path)
+      check_packages(manifest_packages(manifest_path), resolved_versions, manifest_path)
     }
     @warnings
   end
 
   private
 
+  def manifest_packages(manifest_path)
+    ManifestParser.get_packages(manifest_path) { |skip| record_parse_warning(skip, manifest_path) }
+  end
+
   def normalize_ignore_repos
     @ignore_repos = Array(@ignore_repos).map { |repo| GitOperations.trim_repo_url(repo) }
   end
@@ -127,7 +138,7 @@ class SpmChecker
     @allow_hosts = raw_allow_hosts.filter_map { |host| AllowHostNormalizer.normalize(host) }
     return unless invalid_allow_hosts_configuration?(raw_allow_hosts)
 
-    raise(ArgumentError, "allow-hosts was configured, but no entries could be parsed as hostnames")
+    raise(SpmVersionUpdates::ConfigurationError, "allow-hosts was configured, but no entries could be parsed as hostnames")
   end
 
   def configured_allow_hosts
@@ -141,6 +152,13 @@ class SpmChecker
   def clear_warnings
     @warnings.clear
     @warning_details.clear
+    @parse_warnings.clear
+  end
+
+  def record_parse_warning(skip, manifest_path)
+    record = ParseWarning.record(**skip, source: manifest_path)
+    @parse_warnings << record
+    puts("WARNING: #{record['message']}")
   end
 
   def warn_for_empty_xcode_project(remote_packages, resolved_versions, xcodeproj_path)

data/lib/spm_version_updates/version.rb

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

data/lib/spm_version_updates/version_tag_fetcher.rb

@@ -3,6 +3,7 @@
 require_relative "git_operations"
 
 # Fetches git tag versions concurrently for cache-key/repository URL lookup pairs.
+# @api private
 class VersionTagFetcher
   # Thread-safe result/error accumulator shared by fetcher workers.
   FetchState = Struct.new(:mutex, :results, :errors, keyword_init: true) {

data/lib/spm_version_updates/xcode_parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "errors"
 require_relative "git_operations"
 require_relative "package_resolved"
 require_relative "xcode_project_package_reader"
@@ -62,10 +63,16 @@ module XcodeParser
   private_class_method :find_packages_resolved_file
 
   # Raised when Xcode project mode is invoked without a project path.
-  class XcodeprojPathMustBeSet < StandardError
+  class XcodeprojPathMustBeSet < SpmVersionUpdates::ConfigurationError
+    def initialize(message = "Invalid Xcode project path")
+      super
+    end
   end
 
   # Raised when an Xcode project does not have a Package.resolved file.
-  class CouldNotFindResolvedFile < StandardError
+  class CouldNotFindResolvedFile < SpmVersionUpdates::FileNotFoundError
+    def initialize(message = "Could not find a Package.resolved file for the Xcode project")
+      super
+    end
   end
 end

data/lib/spm_version_updates.rb

@@ -2,11 +2,13 @@
 
 require_relative "spm_version_updates/allow_host_normalizer"
 require_relative "spm_version_updates/credential_redactor"
+require_relative "spm_version_updates/errors"
 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/package_resolved"
+require_relative "spm_version_updates/parse_warning"
 require_relative "spm_version_updates/repository_link"
 require_relative "spm_version_updates/repository_update_rules"
 require_relative "spm_version_updates/semver"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spm_version_updates
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Harold Martin
@@ -36,11 +36,13 @@ files:
 - lib/spm_version_updates.rb
 - lib/spm_version_updates/allow_host_normalizer.rb
 - lib/spm_version_updates/credential_redactor.rb
+- lib/spm_version_updates/errors.rb
 - lib/spm_version_updates/fail_on_threshold.rb
 - 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/package_resolved.rb
+- lib/spm_version_updates/parse_warning.rb
 - lib/spm_version_updates/repository_link.rb
 - lib/spm_version_updates/repository_update_rules.rb
 - lib/spm_version_updates/semver.rb