gem_changelog_diff 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c1e8032c69ad427e1469a9620c6df00d3d401e83f939e6fd8c99335fb709fc8
-  data.tar.gz: 9d536f58e4148db45d1de19107cfc28270ab5ce92b892375cf6eae01e3ea5613
+  metadata.gz: d30e61b6a53988f812beaba85ab06f90dfbe3968a2b9c6fe036813c81e233ad8
+  data.tar.gz: e163dd6a353a7abf62a2fc02a841bf19854e8f5a427f194572e169a5f63384b8
 SHA512:
-  metadata.gz: 8e3c3547a707fa41cf491a35f66288f1fbe8210ee99d7742bcc918a5d9721298d9c75bdbe42bd68a77c5de535f1fe0899fc1beea269291adef2b80e27a9ded9a
-  data.tar.gz: 594f28bb073332585345ae5569c2c1298c4ca705df61ecd81e92f5cfd3c279110f13a5c34c18d543a20c75b7133d84cc011e5756116f331499644991a774ba73
+  metadata.gz: 5083b02d3caf6f4fdcc1f6695ff4f1189789069b44c34fb70ee8246ab5e909024ef2d342805077d0032cd298f7d5a57ec827961c1935063ab9b78015dc8e5dec
+  data.tar.gz: d5f330c0b92aeb969281928b976672a1d9c0cf9a886f1df8e2f37a84be03635426ce86e40709f22adaf7a59e0f2e0c4b3d18790decdf48275d99838ef0d813e6

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--output-dir doc
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-06-18
+
+### Added
+
+- YARD documentation on all public classes and methods
+- `CONTRIBUTING.md` with development setup, architecture overview, and PR requirements
+- `SECURITY.md` with vulnerability reporting instructions
+- API stability guarantee: semver contract begins at 1.0.0
+- `.yardopts` configuration and `yard` development dependency
+- `documentation_uri` in gemspec metadata
+- `gh auth token` as automatic token source for developers with GitHub CLI installed
+
 ## [0.9.0] - 2026-06-18
 
 ### Added
@@ -131,7 +143,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Plain text formatter for changelog output
 - Full end-to-end pipeline: detect → lookup → fetch → format
 
-[Unreleased]: https://github.com/eclectic-coding/gem_changelog_diff/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/gem_changelog_diff/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/eclectic-coding/gem_changelog_diff/releases/tag/v1.0.0
 [0.9.0]: https://github.com/eclectic-coding/gem_changelog_diff/releases/tag/v0.9.0
 [0.8.0]: https://github.com/eclectic-coding/gem_changelog_diff/releases/tag/v0.8.0
 [0.7.0]: https://github.com/eclectic-coding/gem_changelog_diff/releases/tag/v0.7.0

data/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/gem_changelog_diff.
+
+## Development Setup
+
+```bash
+git clone https://github.com/eclectic-coding/gem_changelog_diff.git
+cd gem_changelog_diff
+bin/setup
+```
+
+## Running Tests
+
+```bash
+bundle exec rake              # Run all checks (rubocop, bundler-audit, rspec)
+bundle exec rake spec         # Run tests only
+bundle exec rspec spec/path_spec.rb        # Run a single file
+bundle exec rspec spec/path_spec.rb:42     # Run a single example
+```
+
+Integration tests use VCR cassettes committed to the repo. To re-record:
+
+```bash
+GITHUB_TOKEN=ghp_... bundle exec rspec spec/integration/
+```
+
+## Linting
+
+```bash
+bundle exec rubocop           # Check style
+bundle exec rubocop -a        # Auto-correct
+```
+
+## Architecture
+
+The pipeline flows through these stages:
+
+1. **Detection** -- `Detector` runs `bundle outdated` (or `LockfileParser` reads `Gemfile.lock`) to find outdated gems
+2. **Resolution** -- `RubygemsClient` queries the RubyGems API, `UriResolver` extracts the GitHub slug
+3. **Fetching** -- `GithubClient` fetches releases from the GitHub API; `ChangelogParser` parses `CHANGELOG.md` as a fallback. `SourceResolver` orchestrates both
+4. **Concurrency** -- `ConcurrentFetcher` runs fetches in a thread pool
+5. **Formatting** -- `Formatters::Text`, `Json`, or `Markdown` render the output
+6. **CLI** -- `CLI` (Thor) ties everything together with flags, config, and exit codes
+
+## Branch Workflow
+
+All feature work lives on `feature/<version>-<scope>` branches. Every branch produces two commits:
+
+1. **Feature commit** -- implementation + specs. Run `bundle exec rake` and fix all failures before committing.
+2. **Docs commit** -- update `CHANGELOG.md`, remove shipped items from `ROADMAP.md`, update `README.md` if needed.
+
+## Pull Request Requirements
+
+- All CI checks must pass (lint, security audit, tests on Ruby 3.3, 3.4, and 4.0)
+- 100% line coverage required
+- RuboCop must report zero offenses

data/README.md

@@ -25,8 +25,10 @@ CLI that shows you the changelog diff for each gem before you `bundle update`, p
   - [Concurrency](#concurrency)
   - [Exit Codes](#exit-codes)
 - [Configuration File](#configuration-file)
+- [Stability](#stability)
 - [Development](#development)
 - [Contributing](#contributing)
+- [Security](#security)
 - [License](#license)
 
 ## Installation
@@ -73,7 +75,11 @@ export GITHUB_TOKEN=ghp_your_token
 gem_changelog_diff
 ```
 
-Token resolution priority: `--token` flag → `GITHUB_TOKEN` env → Rails credentials → config file.
+Token resolution priority: `--token` flag → `GITHUB_TOKEN` env → Rails credentials → `gh auth token` → config file.
+
+#### GitHub CLI
+
+If you have the [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`), the token is picked up automatically — no configuration needed.
 
 #### Rails Credentials
 
@@ -249,6 +255,14 @@ CLI flags always take priority over config file values.
 
 [Back to top](#gemchangelogdiff)
 
+## Stability
+
+Starting with version 1.0.0, this gem follows [Semantic Versioning](https://semver.org/). The public API is frozen — breaking changes require a major version bump.
+
+A future Bundler plugin (`bundler-changelog-diff`) may provide deeper integration, but the standalone CLI will remain the primary interface.
+
+[Back to top](#gemchangelogdiff)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -259,7 +273,13 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/gem_changelog_diff.
+Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/gem_changelog_diff. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+[Back to top](#gemchangelogdiff)
+
+## Security
+
+To report a security vulnerability, see [SECURITY.md](SECURITY.md).
 
 [Back to top](#gemchangelogdiff)
 

data/ROADMAP.md

@@ -2,16 +2,3 @@
 
 Feature roadmap for gem_changelog_diff. Each section is auto-pruned by `bin/release` when that version ships.
 
-## 1.0.0 -- Stable Release
-
-Public API is frozen. Semantic versioning contract begins.
-
-- API stability guarantee: breaking changes require a major version bump
-- YARD documentation on all public classes and methods
-- `CONTRIBUTING.md` with development setup, testing, and architecture overview
-- `SECURITY.md` with vulnerability reporting instructions
-- Document future Bundler plugin possibility (`bundler-changelog-diff`)
-
-**Dependencies:** `yard` (development)
-
----

data/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x     | Yes       |
+| < 1.0   | No        |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in gem_changelog_diff, please report it responsibly.
+
+**Email:** chuck@eclecticcoding.com
+
+Please include:
+
+- A description of the vulnerability
+- Steps to reproduce the issue
+- The potential impact
+
+**Expected response time:** You should receive an acknowledgment within 48 hours. A fix or mitigation plan will be communicated within 7 days.
+
+## Scope
+
+Security issues relevant to this gem include:
+
+- Command injection via gem names or user-supplied arguments
+- Credential leakage (GitHub tokens in logs, cached responses, or error messages)
+- Unsafe deserialization of cached data or API responses
+- Path traversal in file operations (cache, config, output)
+
+Issues related to the GitHub API, RubyGems API, or upstream dependencies should be reported to their respective maintainers.

data/lib/gem_changelog_diff/cache.rb

@@ -6,6 +6,7 @@ require "json"
 require "net/http"
 
 module GemChangelogDiff
+  # Disk-based HTTP response cache with ETag revalidation.
   class Cache
     DEFAULT_DIR = File.join(Dir.home, ".cache", "gem_changelog_diff")
     DEFAULT_TTL = 86_400
@@ -16,6 +17,10 @@ module GemChangelogDiff
       @enabled = enabled
     end
 
+    # Fetches a response, returning cached data when available.
+    # @param uri [URI::Generic] the request URI
+    # @param headers [Hash<String, String>] additional HTTP headers
+    # @return [Net::HTTPResponse, CachedResponse]
     def get(uri, headers: {})
       return fetch_from_network(uri, headers) unless @enabled
 
@@ -31,6 +36,8 @@ module GemChangelogDiff
       end
     end
 
+    # Deletes all cached data.
+    # @return [void]
     def clear
       FileUtils.rm_rf(@cache_dir)
     end
@@ -104,7 +111,10 @@ module GemChangelogDiff
     end
   end
 
+  # Lightweight stand-in for Net::HTTPResponse built from cached data.
   class CachedResponse
+    # @return [String] the response body
+    # @return [String] the HTTP status code
     attr_reader :body, :code
 
     def initialize(body, code)

data/lib/gem_changelog_diff/changelog_parser.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 
 module GemChangelogDiff
+  # Parses CHANGELOG.md files from GitHub repos as a fallback source.
   class ChangelogParser
     CONTENTS_URL = "https://api.github.com/repos/%<repo>s/contents/%<path>s"
     FILENAMES = %w[CHANGELOG.md CHANGES.md History.md NEWS.md].freeze
@@ -13,6 +14,12 @@ module GemChangelogDiff
       @cache = cache
     end
 
+    # Parses changelog entries between two versions from a repo's changelog file.
+    # @param repo [String] GitHub "owner/repo" slug
+    # @param current_version [String] currently locked version (exclusive)
+    # @param newest_version [String] target version (inclusive)
+    # @return [Array<Hash>] release hashes with :tag_name, :name, :published_at, :body
+    # @raise [NetworkError] on HTTP connection failures
     def entries_between(repo, current_version, newest_version)
       content = fetch_changelog(repo)
       return [] unless content

data/lib/gem_changelog_diff/cli.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "open3"
 require "thor"
 
 module GemChangelogDiff
+  # Thor-based command-line interface.
   class CLI < Thor
     def self.exit_on_failure?
       true
@@ -29,6 +31,7 @@ module GemChangelogDiff
     class_option :timeout, type: :numeric, desc: "Per-request timeout in seconds (default: 10)"
 
     desc "check [GEM...]", "Show changelog diffs for outdated gems"
+    # @param gem_names [Array<String>] optional gem names to filter
     def check(*gem_names)
       setup_environment
       gems = filter_gems(detect_gems, gem_names)
@@ -42,6 +45,9 @@ module GemChangelogDiff
     end
 
     desc "show GEM FROM_VERSION TO_VERSION", "Show changelog between two versions of a gem"
+    # @param gem_name [String] the gem to look up
+    # @param from_version [String] current version (exclusive)
+    # @param to_version [String] target version (inclusive)
     def show(gem_name, from_version, to_version)
       setup_environment
       gem = OutdatedGem.new(name: gem_name, current_version: from_version, newest_version: to_version)
@@ -97,6 +103,7 @@ module GemChangelogDiff
     def configure_token
       token = options[:token] || ENV.fetch("GITHUB_TOKEN", nil)
       token ||= rails_credentials_token
+      token ||= gh_cli_token
       token ||= GemChangelogDiff.configuration.github_token
       GemChangelogDiff.configuration.github_token = token if token
     end
@@ -106,6 +113,14 @@ module GemChangelogDiff
       GemChangelogDiff.configuration.request_timeout = timeout
     end
 
+    def gh_cli_token
+      output, status = Open3.capture2("gh", "auth", "token")
+      token = output.strip
+      token if status.success? && !token.empty?
+    rescue Errno::ENOENT
+      nil
+    end
+
     def rails_credentials_token
       return unless defined?(Rails) && Rails.application.respond_to?(:credentials)
 

data/lib/gem_changelog_diff/concurrent_fetcher.rb

@@ -3,11 +3,17 @@
 require "timeout"
 
 module GemChangelogDiff
+  # Thread pool for fetching multiple gems in parallel.
   class ConcurrentFetcher
     def initialize(concurrency: 4)
       @concurrency = concurrency
     end
 
+    # Processes items concurrently, returning results in order.
+    # @param items [Array] items to process
+    # @yield [item] block called for each item
+    # @return [Array] results in the same order as items
+    # @raise [NetworkError] if the total timeout is exceeded
     def fetch_all(items, &)
       return items.map(&) if @concurrency <= 1
 

data/lib/gem_changelog_diff/config_loader.rb

@@ -3,6 +3,7 @@
 require "yaml"
 
 module GemChangelogDiff
+  # Loads and merges YAML config from user and project locations.
   class ConfigLoader
     USER_CONFIG_DIR = File.join(Dir.home, ".config", "gem_changelog_diff")
     USER_CONFIG_PATH = File.join(USER_CONFIG_DIR, "config.yml")
@@ -12,6 +13,8 @@ module GemChangelogDiff
       @project_dir = project_dir
     end
 
+    # Loads config from user and project files, with project taking priority.
+    # @return [Hash<Symbol, Object>]
     def load
       user_config = load_file(USER_CONFIG_PATH)
       project_config = load_file(project_config_path)

data/lib/gem_changelog_diff/configuration.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # Holds runtime settings for the gem (token, cache, format, timeouts).
   class Configuration
+    # @return [String, nil] GitHub personal access token
+    # @return [Boolean] whether disk caching is enabled
+    # @return [Integer] cache time-to-live in seconds
+    # @return [String] default output format ("text", "json", "markdown")
+    # @return [Integer] number of concurrent fetch threads
+    # @return [Array<String>] gem names to skip
+    # @return [Boolean] whether to disable colored output
+    # @return [Integer] per-request HTTP timeout in seconds
+    # @return [Integer] total operation timeout in seconds
     attr_accessor :github_token, :cache_enabled, :cache_ttl,
                   :default_format, :concurrency, :ignore_gems, :no_color,
                   :request_timeout, :total_timeout
@@ -20,6 +30,9 @@ module GemChangelogDiff
       @total_timeout = 120
     end
 
+    # Applies a hash of settings, ignoring unknown keys and nil values.
+    # @param hash [Hash<Symbol, Object>] configuration key-value pairs
+    # @return [void]
     def apply(hash)
       hash.each do |key, value|
         public_send(:"#{key}=", value) if VALID_KEYS.include?(key) && !value.nil?
@@ -27,14 +40,21 @@ module GemChangelogDiff
     end
   end
 
+  # Returns the global configuration instance.
+  # @return [Configuration]
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Yields the global configuration for modification.
+  # @yieldparam config [Configuration]
+  # @return [void]
   def self.configure
     yield(configuration)
   end
 
+  # Resets the global configuration to defaults.
+  # @return [Configuration]
   def self.reset_configuration!
     @configuration = Configuration.new
   end

data/lib/gem_changelog_diff/detector.rb

@@ -3,9 +3,13 @@
 require "open3"
 
 module GemChangelogDiff
+  # Detects outdated gems by parsing `bundle outdated --parseable` output.
   class Detector
     PARSEABLE_REGEX = /\A(\S+)\s+\(newest\s+([^,]+),\s+installed\s+([^,)]+)/
 
+    # Runs bundle outdated and returns the list of outdated gems.
+    # @return [Array<OutdatedGem>]
+    # @raise [Error] if bundle outdated fails
     def detect
       output = run_bundle_outdated
       parse(output)

data/lib/gem_changelog_diff/errors.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # Raised when a gem's source repository cannot be found on GitHub.
   class RepoNotFoundError < Error; end
+
+  # Raised when the GitHub API returns an unexpected error response.
   class GitHubAPIError < Error; end
+
+  # Raised when the GitHub API rate limit is exceeded.
   class RateLimitError < GitHubAPIError; end
+
+  # Raised on HTTP connection failures (timeouts, DNS, SSL).
   class NetworkError < Error; end
 end

data/lib/gem_changelog_diff/exit_code.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # Process exit code constants for CLI commands.
   module ExitCode
     SUCCESS         = 0
     ERROR           = 1

data/lib/gem_changelog_diff/formatter.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # @deprecated Use {Formatters::Text} directly or {Formatters.build}.
   Formatter = Formatters::Text
 end

data/lib/gem_changelog_diff/formatters/base.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # Output formatters for rendering gem reports.
   module Formatters
+    # Builds a formatter instance for the given format name.
+    # @param format [String] "text", "json", or "markdown"
+    # @param color [Boolean] whether to enable ANSI colors
+    # @return [Text, Json, Markdown]
+    # @raise [ArgumentError] for unknown formats
     def self.build(format:, color: false)
       case format
       when "text" then Text.new(color: color)
@@ -11,11 +17,15 @@ module GemChangelogDiff
       end
     end
 
+    # Abstract base class for output formatters.
     class Base
       def initialize(color: false)
         @color = color
       end
 
+      # Formats gem reports into a string.
+      # @param _gem_reports [Array<Hash>] list of gem report hashes
+      # @return [String]
       def format(_gem_reports)
         raise NotImplementedError, "#{self.class}#format must be implemented"
       end

data/lib/gem_changelog_diff/formatters/json.rb

@@ -4,6 +4,7 @@ require "json"
 
 module GemChangelogDiff
   module Formatters
+    # JSON formatter for machine-readable output.
     class Json < Base
       def format(gem_reports)
         counts = summary_counts(gem_reports)

data/lib/gem_changelog_diff/formatters/markdown.rb

@@ -2,6 +2,7 @@
 
 module GemChangelogDiff
   module Formatters
+    # Markdown formatter for PR descriptions and documentation.
     class Markdown < Base
       def format(gem_reports)
         sections = gem_reports.map { |report| format_gem(report) }

data/lib/gem_changelog_diff/formatters/text.rb

@@ -4,6 +4,7 @@ require "tty-color"
 
 module GemChangelogDiff
   module Formatters
+    # Plain text formatter with optional ANSI color output.
     class Text < Base
       BOLD = "\e[1m"
       CYAN = "\e[36m"

data/lib/gem_changelog_diff/github_client.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 
 module GemChangelogDiff
+  # Fetches release notes from the GitHub Releases API with pagination.
   class GithubClient
     RELEASES_URL = "https://api.github.com/repos/%<repo>s/releases"
     RATE_LIMIT_WARNING_THRESHOLD = 10
@@ -13,6 +14,11 @@ module GemChangelogDiff
       @cache = cache
     end
 
+    # Returns releases between two versions, sorted newest first.
+    # @param repo [String] GitHub "owner/repo" slug
+    # @param current_version [String] currently locked version (exclusive)
+    # @param newest_version [String] target version (inclusive)
+    # @return [Array<Hash>] release hashes with :tag_name, :name, :published_at, :body
     def releases_between(repo, current_version, newest_version)
       gem_name = repo.split("/").last
       @active_matcher = TagMatcher.new(gem_name: gem_name)

data/lib/gem_changelog_diff/interactive.rb

@@ -3,11 +3,14 @@
 require "tty-prompt"
 
 module GemChangelogDiff
+  # Presents a multi-select prompt for choosing which gems to check.
   class Interactive
     def initialize(gems:)
       @gems = gems
     end
 
+    # Displays the selection prompt and returns chosen gems.
+    # @return [Array<OutdatedGem>]
     def select
       prompt = TTY::Prompt.new
       prompt.multi_select("Select gems to check:",

data/lib/gem_changelog_diff/lockfile_parser.rb

@@ -3,11 +3,16 @@
 require "bundler"
 
 module GemChangelogDiff
+  # Detects outdated gems by comparing Gemfile.lock specs to RubyGems.
   class LockfileParser
     def initialize(rubygems_client: RubygemsClient.new)
       @rubygems_client = rubygems_client
     end
 
+    # Parses the lockfile and returns gems with newer versions available.
+    # @param lockfile_path [String] path to Gemfile.lock
+    # @return [Array<OutdatedGem>]
+    # @raise [Error] if the lockfile is not found
     def detect(lockfile_path: "Gemfile.lock")
       content = File.read(lockfile_path)
       parser = Bundler::LockfileParser.new(content)

data/lib/gem_changelog_diff/outdated_gem.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # Immutable value object representing a gem with an available update.
+  # @!attribute [r] name
+  #   @return [String] the gem name
+  # @!attribute [r] current_version
+  #   @return [String] the currently locked version
+  # @!attribute [r] newest_version
+  #   @return [String] the latest available version
   OutdatedGem = Data.define(:name, :current_version, :newest_version)
 end

data/lib/gem_changelog_diff/rubygems_client.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 
 module GemChangelogDiff
+  # Queries the RubyGems.org API for gem metadata and source repository URLs.
   class RubygemsClient
     RUBYGEMS_API = "https://rubygems.org/api/v1/gems/%<name>s.json"
 
@@ -12,6 +13,9 @@ module GemChangelogDiff
       @uri_resolver = uri_resolver
     end
 
+    # Looks up the GitHub repository slug for a gem.
+    # @param gem_name [String]
+    # @return [String, nil] "owner/repo" slug, or nil if not found
     def repo_url(gem_name)
       data = fetch_gem_data(gem_name)
       return nil unless data
@@ -19,6 +23,9 @@ module GemChangelogDiff
       @uri_resolver.resolve(data)
     end
 
+    # Returns the latest version string for a gem from RubyGems.
+    # @param gem_name [String]
+    # @return [String, nil]
     def latest_version(gem_name)
       data = fetch_gem_data(gem_name)
       data&.dig("version")

data/lib/gem_changelog_diff/source_resolver.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # Fetches release notes, trying GitHub Releases first then changelog files.
   class SourceResolver
     def initialize(github_client: GithubClient.new, changelog_parser: ChangelogParser.new)
       @github_client = github_client
       @changelog_parser = changelog_parser
     end
 
+    # Returns release entries between two versions for a given repo.
+    # @param repo [String] GitHub "owner/repo" slug
+    # @param current_version [String] currently locked version (exclusive)
+    # @param newest_version [String] target version (inclusive)
+    # @return [Array<Hash>] release hashes with :tag_name, :name, :published_at, :body
     def resolve(repo, current_version, newest_version)
       releases = @github_client.releases_between(repo, current_version, newest_version)
       return releases unless releases.empty?

data/lib/gem_changelog_diff/tag_matcher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
+  # Extracts version strings from various Git tag formats.
   class TagMatcher
     STANDARD_PATTERN = /\A(?:release-)?v?(\d+\..+)\z/
 
@@ -8,6 +9,9 @@ module GemChangelogDiff
       @gem_name = gem_name
     end
 
+    # Parses a version string from a tag name.
+    # @param tag [String, nil] the Git tag name
+    # @return [String, nil] extracted version, or nil if unparseable
     def extract_version(tag)
       return nil if tag.nil? || tag.strip.empty?
 

data/lib/gem_changelog_diff/uri_resolver.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "uri"
 
 module GemChangelogDiff
+  # Resolves a gem's RubyGems metadata to a GitHub owner/repo slug.
   class UriResolver
     GITHUB_REGEX = %r{github\.com/([^/]+)/([^/]+)}
     NON_GITHUB_HOSTS = {
@@ -15,6 +16,10 @@ module GemChangelogDiff
     URI_FIELDS = %w[source_code_uri homepage_uri bug_tracker_uri].freeze
     MAX_REDIRECTS = 3
 
+    # Extracts a GitHub slug from gem metadata, following redirects.
+    # @param gem_data [Hash<String, Object>] RubyGems API response data
+    # @return [String, nil] "owner/repo" slug, or nil if not on GitHub
+    # @raise [RepoNotFoundError] if hosted on a non-GitHub platform
     def resolve(gem_data)
       uris = extract_uris(gem_data)
       return nil if uris.empty?

data/lib/gem_changelog_diff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GemChangelogDiff
-  VERSION = "0.9.0"
+  VERSION = "1.0.0"
 end

data/lib/gem_changelog_diff.rb

@@ -4,7 +4,9 @@ require_relative "gem_changelog_diff/version"
 require_relative "gem_changelog_diff/configuration"
 require_relative "gem_changelog_diff/config_loader"
 
+# CLI that shows changelog diffs for outdated gems before you bundle update.
 module GemChangelogDiff
+  # Base error class for all gem_changelog_diff errors.
   class Error < StandardError; end
 end
 

data/sig/gem_changelog_diff.rbs

@@ -317,6 +317,7 @@ module GemChangelogDiff
     def dry_run_output: (Array[OutdatedGem] gems) -> void
     def format_dry_run: (Array[OutdatedGem] gems) -> String
     def configure_timeout: () -> void
+    def gh_cli_token: () -> String?
     def rails_credentials_token: () -> String?
     def apply_interactive: (Array[OutdatedGem] gems) -> Array[OutdatedGem]
     def output_results: (Array[OutdatedGem] gems) -> Array[gem_report]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem_changelog_diff
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -76,12 +76,15 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
 - ".github/workflows/publish.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CLAUDE.md
+- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
 - ROADMAP.md
 - Rakefile
+- SECURITY.md
 - codecov.yml
 - exe/gem_changelog_diff
 - lib/gem_changelog_diff.rb
@@ -117,6 +120,7 @@ metadata:
   homepage_uri: https://github.com/eclectic-coding/gem_changelog_diff
   source_code_uri: https://github.com/eclectic-coding/gem_changelog_diff
   changelog_uri: https://github.com/eclectic-coding/gem_changelog_diff/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/gem_changelog_diff
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: