gem-guardian 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e343f954f0d514206e5bcc10d935a094d916ee1456cbb4774a113c909e879dc
-  data.tar.gz: 2230036e48e13af43b32090d1cbe4b933785b5407fda0f8376bebd41763615fe
+  metadata.gz: ed534bc229391d74fb2b3ee945127ad3690236f3c27d28fe1aaf28a909c19a8c
+  data.tar.gz: 4c30325c72ba731d6a9e5dc5e2f2ea3a08bf5147c8a29e02132f5bd9ec9fecac
 SHA512:
-  metadata.gz: 36bf27a64fb281d8e50a81a9efdadc5e83ee694e81e79cb46c36799f443568f917934001f10568a1f417740688cabd204aa26154fd791145416b7d25c3d837dc
-  data.tar.gz: 9e5331025935a3a5d007b2f684e59110cf0bbe79deaacb1e93b976aa06075ea9e52f7199c3ff92b2c90c5317b9da7c5eb03e796724b2966a1f23c37c738426e3
+  metadata.gz: e13ac5e36ffeb46ff9d2fa027d4a6af02b648389a9e7981a50ea9a28264aa32d8473ac2c07a748b002f24bb59339c10da138b405fa5ac9239346caec2e816fe9
+  data.tar.gz: ffcc44114da845142bff58537d06970479d2694d0a91c52ee21f00a3a0e695cc8d5f7ec8aee0fb8b296495dbd2078fd76b15944f17371330e03b532feb1d5ed4

data/.github/workflows/main.yml

@@ -17,7 +17,10 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '3.2.11'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+          - '4.0'
 
     steps:
       - uses: actions/checkout@v6
@@ -28,5 +31,23 @@ jobs:
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
-      - name: Run the default task
-        run: bundle exec rake
+      - name: Run the test suite
+        run: COVERAGE=true bundle exec rake test
+      - name: Validate RBS signatures
+        run: bundle exec rake rbs:validate
+
+  lint:
+    runs-on: ubuntu-latest
+    name: RuboCop
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+      - name: Run RuboCop
+        run: bundle exec rubocop

data/.github/workflows/pages.yml

@@ -0,0 +1,68 @@
+name: Deploy YARD docs to GitHub Pages
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build YARD documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Build YARD documentation
+        run: bundle exec yard doc
+
+      - name: Enforce YARD coverage
+        shell: bash
+        run: |
+          stats="$(bundle exec yard stats --no-progress --list-undoc)"
+          echo "$stats"
+
+          coverage="$(printf '%s\n' "$stats" | ruby -ne 'puts($1) if /([0-9]+(?:\.[0-9]+)?)% documented/ =~ $_')"
+
+          if [ -z "$coverage" ]; then
+            echo "Could not determine YARD documentation coverage."
+            exit 1
+          fi
+
+          ruby -e 'coverage = ARGV.fetch(0).to_f; abort("YARD documentation coverage #{coverage}% is below 95%") if coverage < 95.0' "$coverage"
+
+      - name: Disable Jekyll processing
+        run: touch doc/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Release gem to RubyGems.org
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://rubygems.org/gems/gem-guardian
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake
+      - name: Release gem to RubyGems.org
+        uses: rubygems/release-gem@v1

data/.gitignore

@@ -8,3 +8,4 @@
 /tmp/
 Gemfile.lock
 *.gem
+/.ignoreme/

data/.rubocop.yml

@@ -1,5 +1,17 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
 AllCops:
+  NewCops: disable
   TargetRubyVersion: 3.2
+  Exclude:
+    - 'coverage/**/*'
+    - 'doc/**/*'
+    - 'vendor/**/*'
+    - 'sig/**/*'
+    - 'tmp/**/*'
+    - 'test/**/*'
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/.yardopts

@@ -0,0 +1,7 @@
+--title "gem-guardian API Documentation"
+--protected
+--markup markdown
+--readme README.md
+'lib/**/*.rb'
+-
+--files CHANGELOG.md LICENSE.txt CODE_OF_CONDUCT.md

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## 0.1.0
+## [Unreleased]
+
+## [0.1.1] - 2026-06-12
+
+- Parse Bundler `CHECKSUMS` entries from `Gemfile.lock`.
+- Audit lockfiles for missing checksum coverage and report fallback verification.
+- Raise test coverage to 95%+ line and branch.
+- Curate `sig/` outputs so `rbs validate` passes cleanly.
+- Add GitHub Actions Ruby matrix for `3.2`, `3.3`, `3.4`, and `4.0`.
+- Run `rbs:validate` in CI.
+
+## [0.1.0] - 2026-06-12
 
 - Initial MVP codebase.
 - Verify explicit gems or all gems in `Gemfile.lock`.

data/Gemfile

@@ -4,12 +4,12 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "minitest", "~> 6.0"
 gem "pry", "~> 0.16.0"
 gem "rake", "~> 13.4"
-gem "minitest", "~> 6.0"
 gem "rubocop", "~> 1.87"
+gem "rubocop-minitest", "~> 0.39.1"
+gem "rubocop-rake", "~> 0.7.1"
 gem "simplecov", "~> 0.22.0"
 gem "steep", "~> 2.0"
 gem "yard", "~> 0.9.44"
-gem "rubocop-minitest", "~> 0.39.1"
-gem "rubocop-rake", "~> 0.7.1"

data/README.md

@@ -8,25 +8,25 @@
 
 Consumer-side integrity verification for Ruby gems.
 
-`gem-guardian` verifies downloaded `.gem` artifacts against the SHA256 checksum reported by RubyGems.org. It is intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.
+`gem-guardian` audits Bundler checksum coverage and, where needed, verifies `.gem` artifacts against the SHA256 checksum reported by RubyGems.org. It is intentionally small: no Bundler monkeypatching, no install hooks, and no custom publishing flow required.
 
 ## Why
 
-RubyGems.org displays SHA256 checksums for published gem artifacts, and modern Bundler can store checksums in `Gemfile.lock`. But there is still room for a simple consumer-side verification workflow that can be run explicitly in CI or locally.
+RubyGems.org displays SHA256 checksums for published gem artifacts, and Bundler 2.6 can store and enforce checksums in `Gemfile.lock`. That means the most useful v0.1.0 is not a parallel verifier, but an audit tool that tells you whether your bundle is actually protected.
 
-This MVP verifies:
+This v0.1.0 scope is:
 
 ```text
-Gemfile.lock / explicit gem version
+Gemfile.lock
     ↓
-RubyGems.org expected SHA256
+CHECKSUMS coverage audit
     ↓
-Downloaded .gem artifact
+RubyGems.org checksum comparison when needed
     ↓
-Local SHA256 comparison
+Actionable report for CI or local review
 ```
 
-This proves that the local artifact matches what RubyGems.org serves. It does **not** yet prove source provenance such as signed tag → CI build → published gem.
+This reports whether your lockfile is using Bundler checksum protection and whether any locked gems are missing expected checksum data. It does **not** yet prove source provenance such as signed tag → CI build → published gem.
 
 ## Installation
 
@@ -39,6 +39,27 @@ gem install ./gem-guardian-0.1.0.gem
 
 ## Usage
 
+Build and install the current release from a local checkout:
+
+```bash
+gem build gem-guardian.gemspec
+gem install ./gem-guardian-0.1.1.gem
+gem-guardian version
+```
+
+Show the built-in help:
+
+```bash
+gem-guardian help
+gem-guardian --help
+```
+
+Prepare a locked project for checksum auditing:
+
+```bash
+bundle lock --add-checksums
+```
+
 Verify all gems in `Gemfile.lock`:
 
 ```bash
@@ -64,6 +85,8 @@ Use a non-default lockfile:
 gem-guardian verify --lockfile path/to/Gemfile.lock
 ```
 
+When you verify a lockfile that already contains Bundler `CHECKSUMS`, `gem-guardian` reports coverage and compares the locked checksum to the downloaded artifact. When a checksum is missing, it falls back to RubyGems.org metadata and marks that verification accordingly.
+
 ## Exit codes
 
 - `0` — all verified artifacts matched
@@ -72,19 +95,19 @@ gem-guardian verify --lockfile path/to/Gemfile.lock
 
 ## MVP constraints
 
-- Uses RubyGems.org as the checksum source of truth.
-- Downloads artifacts from RubyGems.org `/downloads/<gem-file>.gem`.
+- Audits `Gemfile.lock` for Bundler `CHECKSUMS` coverage.
+- Uses RubyGems.org as a fallback checksum source when the lockfile is incomplete or an explicit gem is supplied.
+- Downloads artifacts from RubyGems.org `/downloads/<gem-file>.gem` only when verification is needed.
 - Caches downloaded artifacts under the system temp directory.
 - Does not integrate into Bundler install hooks.
 - Does not yet verify Sigstore, SLSA, GitHub Actions provenance, or signed git tags.
 
 ## Roadmap
 
-- `gem-guardian lock` to emit or update checksum metadata.
-- Support Bundler 2.6 `CHECKSUMS` sections as an offline expected-checksum source.
+- Machine-readable JSON output for CI.
 - Provenance verification for gems published through Trusted Publishing.
 - GitHub Release checksum/signature discovery.
-- Machine-readable JSON output for CI.
+- Signed tag and release attestation checks.
 
 
 ## License

data/Rakefile

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
@@ -29,7 +30,7 @@ namespace :rbs do
 
   desc "Validate curated RBS signatures with Steep"
   task :validate do
-    sh "bundle exec steep check"
+    sh "bundle exec rbs validate sig"
   end
 
   desc "Open diff between curated and generated signatures"

data/gem-guardian.gemspec

@@ -9,7 +9,9 @@ Gem::Specification.new do |spec|
   spec.email = ["kenneth.c.demanawa@gmail.com"]
 
   spec.summary = "Consumer-side integrity verification for Ruby gems."
-  spec.description = "Verifies Ruby gem artifacts against RubyGems SHA256 checksums using Gemfile.lock or explicit gem names."
+  spec.description = <<~DESC
+    Audits Bundler checksum coverage and verifies Ruby gem artifacts against RubyGems SHA256 checksums when needed.
+  DESC
   spec.homepage = "https://github.com/kanutocd/gem-guardian"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2"

data/lib/gem/guardian/artifact_store.rb

@@ -5,12 +5,16 @@ require "tmpdir"
 
 module Gem
   module Guardian
+    # Stores downloaded gem artifacts in a local cache directory.
     class ArtifactStore
+      # @param client [RubygemsClient] downloader used when the artifact is not cached
+      # @param cache_dir [String] directory where downloaded artifacts are stored
       def initialize(client:, cache_dir: File.join(Dir.tmpdir, "gem-guardian"))
         @client = client
         @cache_dir = cache_dir
       end
 
+      # Returns the local path for +dependency+, downloading it if needed.
       def path_for(dependency)
         FileUtils.mkdir_p(@cache_dir)
         path = File.join(@cache_dir, dependency.gem_filename)

data/lib/gem/guardian/checksum.rb

@@ -4,9 +4,11 @@ require "digest"
 
 module Gem
   module Guardian
+    # Local checksum helpers.
     module Checksum
       module_function
 
+      # Returns the SHA256 hex digest for the file at +path+.
       def sha256_file(path)
         Digest::SHA256.file(path).hexdigest
       end

data/lib/gem/guardian/cli.rb

@@ -1,60 +1,57 @@
 # frozen_string_literal: true
 
+# Namespace for gem-guardian CLI code.
 module Gem
+  # Command-line interface and output helpers.
   module Guardian
+    # Command-line entry point for gem-guardian.
     class CLI
+      # Starts the CLI with the provided argv.
       def self.start(argv)
         new(argv).run
       end
 
-      def initialize(argv, stdout: $stdout, stderr: $stderr)
+      def initialize(argv, stdout: $stdout, stderr: $stderr, verifier_class: Verifier,
+                     lockfile_parser_class: LockfileParser)
         @argv = argv.dup
         @stdout = stdout
         @stderr = stderr
+        @verifier_class = verifier_class
+        @lockfile_parser_class = lockfile_parser_class
+        @result_printer = ResultPrinter.new(stdout:)
       end
 
+      # Dispatches the requested subcommand and returns an exit status.
       def run
-        command = @argv.shift
+        dispatch(@argv.shift)
+      end
+
+      private
+
+      def dispatch(command)
         case command
-        when "verify"
-          verify
-        when "version", "--version", "-v"
-          @stdout.puts VERSION
-          0
-        when "help", "--help", "-h", nil
-          usage
-          0
+        when "verify" then verify
+        when "version", "--version", "-v" then print_version
+        when "help", "--help", "-h", nil then usage
         else
-          @stderr.puts "Unknown command: #{command}"
-          usage(@stderr)
-          2
+          unknown_command(command)
         end
       end
 
-      private
-
+      # Runs the verify subcommand.
       def verify
-        lockfile = option_value("--lockfile") || "Gemfile.lock"
-        gems = @argv
-        dependencies = if gems.empty?
-                         LockfileParser.new(lockfile).dependencies
-                       else
-                         gems.map { |spec| parse_gem_spec(spec) }
-                       end
-
-        if dependencies.empty?
-          @stderr.puts "No gems found to verify."
-          return 1
-        end
+        lockfile_data, dependencies = resolve_dependencies
+        return no_dependencies if dependencies.empty?
 
-        results = Verifier.new.verify_all(dependencies)
-        print_results(results)
-        results.all?(&:ok?) ? 0 : 1
+        results = verifier_for(lockfile_data).verify_all(dependencies)
+        print_verification_report(results, lockfile_data)
+        verification_exit_status(results, lockfile_data)
       rescue Error => e
         @stderr.puts e.message
         1
       end
 
+      # Parses a GEM:VERSION[:PLATFORM] spec string.
       def parse_gem_spec(spec)
         name, version, platform = spec.split(":", 3)
         raise Error, "Expected GEM:VERSION[:PLATFORM], got: #{spec}" if name.to_s.empty? || version.to_s.empty?
@@ -62,6 +59,50 @@ module Gem
         Dependency.new(name:, version:, platform: platform || "ruby")
       end
 
+      def resolve_dependencies
+        lockfile = option_value("--lockfile") || "Gemfile.lock"
+        return [nil, @argv.map { |spec| parse_gem_spec(spec) }] unless @argv.empty?
+
+        lockfile_data = @lockfile_parser_class.new(lockfile).parse
+        [lockfile_data, lockfile_data.dependencies]
+      end
+
+      def verifier_for(lockfile_data)
+        expected_checksums = lockfile_data&.sha256_checksums || {}
+        @verifier_class.new(expected_checksums:)
+      end
+
+      def print_verification_report(results, lockfile_data)
+        lockfile_mode = !lockfile_data.nil?
+        @result_printer.print_results(results, lockfile_mode:)
+        return unless lockfile_data
+
+        @result_printer.print_lockfile_coverage(lockfile_data)
+      end
+
+      def verification_exit_status(results, lockfile_data)
+        all_ok = results.all?(&:ok?)
+        all_covered = lockfile_data.nil? || lockfile_data.missing_checksum_dependencies.empty?
+        all_ok && all_covered ? 0 : 1
+      end
+
+      def no_dependencies
+        @stderr.puts "No gems found to verify."
+        1
+      end
+
+      def print_version
+        @stdout.puts VERSION
+        0
+      end
+
+      def unknown_command(command)
+        @stderr.puts "Unknown command: #{command}"
+        usage(@stderr)
+        2
+      end
+
+      # Returns and removes an option value from argv.
       def option_value(name)
         index = @argv.index(name)
         return unless index
@@ -73,39 +114,10 @@ module Gem
         value
       end
 
-      def print_results(results)
-        results.each do |result|
-          dependency = result.dependency
-          label = "#{dependency.name} #{dependency.version} #{dependency.platform}"
-          case result.status
-          when :ok
-            @stdout.puts "PASS #{label}"
-            @stdout.puts "     sha256 #{result.actual_sha256}"
-          when :mismatch
-            @stdout.puts "FAIL #{label}"
-            @stdout.puts "     expected #{result.expected_sha256}"
-            @stdout.puts "     actual   #{result.actual_sha256}"
-          else
-            @stdout.puts "ERROR #{label}"
-            @stdout.puts "      #{result.error.class}: #{result.error.message}"
-          end
-        end
-      end
-
-      def usage(io = @stdout)
-        io.puts <<~USAGE
-          gem-guardian #{VERSION}
-
-          Usage:
-            gem-guardian verify [--lockfile Gemfile.lock]
-            gem-guardian verify GEM:VERSION[:PLATFORM] [GEM:VERSION[:PLATFORM] ...]
-            gem-guardian version
-
-          Examples:
-            gem-guardian verify
-            gem-guardian verify sidekiq:8.0.8
-            gem-guardian verify nokogiri:1.18.9:x86_64-linux
-        USAGE
+      # Prints usage text.
+      def usage(_io = @stdout)
+        @result_printer.usage
+        0
       end
     end
   end

data/lib/gem/guardian/dependency.rb

@@ -2,7 +2,9 @@
 
 module Gem
   module Guardian
+    # A gem dependency identified by name, version, and platform.
     Dependency = Data.define(:name, :version, :platform) do
+      # Returns the canonical .gem filename for this dependency.
       def gem_filename
         platform_suffix = platform && platform != "ruby" ? "-#{platform}" : ""
         "#{name}-#{version}#{platform_suffix}.gem"

data/lib/gem/guardian/error.rb

@@ -2,9 +2,13 @@
 
 module Gem
   module Guardian
+    # Base error type for gem-guardian failures.
     Error = Class.new(StandardError)
+    # Raised when RubyGems does not expose a checksum for a gem version.
     ChecksumNotFound = Class.new(Error)
+    # Raised when downloading or writing a gem artifact fails.
     ArtifactFetchError = Class.new(Error)
+    # Raised when a lockfile cannot be read or parsed.
     LockfileError = Class.new(Error)
   end
 end

data/lib/gem/guardian/lockfile_parser.rb

@@ -2,34 +2,116 @@
 
 module Gem
   module Guardian
+    # Parses Gemfile.lock and exposes dependencies and checksum data.
     class LockfileParser
+      # Matches dependency lines in the specs section.
       GEM_LINE = /^ {4}([A-Za-z0-9_.-]+) \(([^)]+)\)/
+      # Matches checksum lines in the CHECKSUMS section.
+      CHECKSUM_LINE = /^ {2}([A-Za-z0-9_.-]+) \(([^)]+)\) (.+)$/
+      # Parsed lockfile data for the verify command.
+      LockfileData = Data.define(:dependencies, :checksums, :checksums_section_present) do
+        # Returns the checksum for +dependency+ and +algorithm+, if present.
+        def checksum_for(dependency, algorithm = "sha256")
+          checksums.fetch(dependency, {}).fetch(algorithm, nil)
+        end
+
+        # Returns a dependency => sha256 checksum map.
+        def sha256_checksums
+          checksums.each_with_object({}) do |(dependency, algorithms), memo|
+            digest = algorithms["sha256"]
+            memo[dependency] = digest if digest
+          end
+        end
+
+        # Returns dependencies that do not have a sha256 checksum.
+        def missing_checksum_dependencies
+          dependencies.reject { |dependency| sha256_checksums.key?(dependency) }
+        end
+
+        # Returns true if the lockfile contained a CHECKSUMS section.
+        def checksums_present?
+          checksums_section_present
+        end
+      end
 
       def initialize(path = "Gemfile.lock")
         @path = path
       end
 
-      def dependencies
+      # Parses the lockfile into dependencies and checksum metadata.
+      def parse
         raise LockfileError, "Lockfile not found: #{@path}" unless File.file?(@path)
 
-        specs_section = false
-        File.readlines(@path, chomp: true).filter_map do |line|
-          specs_section = true if line == "  specs:"
-          specs_section = false if specs_section && line.match?(/^[A-Z]/)
-          next unless specs_section
-
-          match = GEM_LINE.match(line)
-          next unless match
+        dependencies = []
+        checksums = {}
+        section = nil
 
-          name = match[1]
-          version_and_platform = match[2]
-          version, platform = split_version_and_platform(version_and_platform)
-          Dependency.new(name:, version:, platform:)
+        File.readlines(@path, chomp: true).each do |line|
+          section = section_for(line, section)
+          parse_specs_line(line, dependencies) if section == :specs
+          parse_checksums_line(line, checksums) if section == :checksums
         end
+
+        LockfileData.new(dependencies, checksums, checksums.any?)
+      end
+
+      # Returns the dependencies listed in the lockfile.
+      def dependencies
+        parse.dependencies
+      end
+
+      # Returns the raw checksum map extracted from the lockfile.
+      def checksums
+        parse.checksums
       end
 
       private
 
+      def section_for(line, current_section)
+        case line
+        when "  specs:"
+          :specs
+        when "CHECKSUMS"
+          :checksums
+        when /^[A-Z]/
+          nil
+        else
+          current_section
+        end
+      end
+
+      def parse_specs_line(line, dependencies)
+        match = GEM_LINE.match(line)
+        return unless match
+
+        name = match[1]
+        version_and_platform = match[2]
+        version, platform = split_version_and_platform(version_and_platform)
+        dependencies << Dependency.new(name:, version:, platform:)
+      end
+
+      def parse_checksums_line(line, checksums)
+        match = CHECKSUM_LINE.match(line)
+        return unless match
+
+        name = match[1]
+        version_and_platform = match[2]
+        checksum_blob = match[3]
+        version, platform = split_version_and_platform(version_and_platform)
+        dependency = Dependency.new(name:, version:, platform:)
+        checksums[dependency] ||= {}
+        register_checksum_pairs(checksums[dependency], checksum_blob)
+      end
+
+      def register_checksum_pairs(checksum_store, checksum_blob)
+        checksum_blob.split(",").each do |pair|
+          algorithm, digest = pair.split("=", 2).map(&:strip)
+          next if algorithm.to_s.empty? || digest.to_s.empty?
+
+          checksum_store[algorithm] = digest
+        end
+      end
+
       # Bundler renders native platforms as `1.2.3-x86_64-linux` in the spec line.
       # Ruby versions remain plain, for example `1.2.3`.
       def split_version_and_platform(value)

data/lib/gem/guardian/result_printer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Gem
+  module Guardian
+    # Formats verification results for human-readable CLI output.
+    class ResultPrinter
+      # @param stdout [IO] output stream for formatted messages
+      def initialize(stdout:)
+        @stdout = stdout
+      end
+
+      # Prints a collection of verification results.
+      def print_results(results, lockfile_mode:)
+        results.each do |result|
+          print_result(result, lockfile_mode:)
+        end
+      end
+
+      # Prints one verification result.
+      def print_result(result, lockfile_mode:)
+        label = result_label(result)
+        case result.status
+        when :ok then print_ok_result(result, label, lockfile_mode)
+        when :mismatch then print_mismatch_result(result, label)
+        else print_error_result(result, label)
+        end
+      end
+
+      # Prints a successful verification result.
+      def print_ok_result(result, label, lockfile_mode)
+        prefix = lockfile_mode && result.checksum_source == :rubygems ? "FALLBACK" : "PASS"
+        @stdout.puts "#{prefix} #{label}"
+        @stdout.puts "     sha256 #{result.actual_sha256}"
+        @stdout.puts "     source #{result.checksum_source}" if lockfile_mode && result.checksum_source
+      end
+
+      # Prints a checksum mismatch.
+      def print_mismatch_result(result, label)
+        @stdout.puts "FAIL #{label}"
+        @stdout.puts "     expected #{result.expected_sha256}"
+        @stdout.puts "     actual   #{result.actual_sha256}"
+      end
+
+      # Prints an unexpected verifier error.
+      def print_error_result(result, label)
+        @stdout.puts "ERROR #{label}"
+        @stdout.puts "      #{result.error.class}: #{result.error.message}"
+      end
+
+      # Prints lockfile checksum coverage.
+      def print_lockfile_coverage(lockfile_data)
+        covered = lockfile_data.dependencies.size - lockfile_data.missing_checksum_dependencies.size
+        total = lockfile_data.dependencies.size
+        @stdout.puts "CHECKSUMS coverage: #{covered}/#{total}"
+
+        lockfile_data.missing_checksum_dependencies.each do |dependency|
+          @stdout.puts "MISSING #{dependency.name} #{dependency.version} #{dependency.platform}"
+        end
+      end
+
+      # Prints the CLI usage text.
+      def usage
+        @stdout.puts(USAGE)
+      end
+
+      # CLI usage text.
+      USAGE = <<~USAGE.freeze
+        gem-guardian #{VERSION}
+
+        Usage:
+          gem-guardian verify [--lockfile Gemfile.lock]
+          gem-guardian verify GEM:VERSION[:PLATFORM] [GEM:VERSION[:PLATFORM] ...]
+          gem-guardian version
+
+        Examples:
+          gem-guardian verify
+        gem-guardian verify sidekiq:8.0.8
+        gem-guardian verify nokogiri:1.18.9:x86_64-linux
+      USAGE
+
+      private
+
+      def result_label(result)
+        dependency = result.dependency
+        "#{dependency.name} #{dependency.version} #{dependency.platform}"
+      end
+    end
+  end
+end

data/lib/gem/guardian/rubygems_client.rb

@@ -6,7 +6,9 @@ require "uri"
 
 module Gem
   module Guardian
+    # Reads checksum metadata from RubyGems.org and downloads gem artifacts.
     class RubygemsClient
+      # Default RubyGems.org endpoint used by the client.
       DEFAULT_HOST = "https://rubygems.org"
 
       def initialize(host: DEFAULT_HOST, http: Net::HTTP)
@@ -14,18 +16,19 @@ module Gem
         @http = http
       end
 
+      # Returns the expected SHA256 checksum for +dependency+.
       def expected_sha256(dependency)
-        versions = JSON.parse(get("/api/v1/versions/#{dependency.name}.json"))
-        version = versions.find do |item|
-          item["number"] == dependency.version && platform_matches?(item["platform"], dependency.platform)
+        version = matching_version(dependency)
+        sha = version && version_checksum(version)
+        if blank?(sha)
+          raise ChecksumNotFound,
+                "No SHA256 found for #{dependency.name} #{dependency.version} #{dependency.platform}"
         end
 
-        sha = version && (version["sha"] || version["sha256"] || version["checksum"])
-        raise ChecksumNotFound, "No SHA256 found for #{dependency.name} #{dependency.version} #{dependency.platform}" if blank?(sha)
-
         sha.downcase
       end
 
+      # Downloads the .gem file for +dependency+ into +destination+.
       def download_gem(dependency, destination)
         body = get("/downloads/#{dependency.gem_filename}")
         File.binwrite(destination, body)
@@ -36,6 +39,18 @@ module Gem
 
       private
 
+      def matching_version(dependency)
+        versions = JSON.parse(get("/api/v1/versions/#{dependency.name}.json"))
+        versions.find do |item|
+          item["number"] == dependency.version && platform_matches?(item["platform"], dependency.platform)
+        end
+      end
+
+      def version_checksum(version)
+        version["sha"] || version["sha256"] || version["checksum"]
+      end
+
+      # GETs +path+ from the configured host and returns the response body.
       def get(path)
         uri = URI("#{@host}#{path}")
         response = @http.get_response(uri)
@@ -44,12 +59,14 @@ module Gem
         raise Error, "GET #{uri} failed with #{response.code} #{response.message}"
       end
 
+      # Compares a RubyGems platform string with the requested platform.
       def platform_matches?(remote_platform, wanted_platform)
         normalized_remote = remote_platform.to_s.empty? ? "ruby" : remote_platform.to_s
         normalized_wanted = wanted_platform.to_s.empty? ? "ruby" : wanted_platform.to_s
         normalized_remote == normalized_wanted
       end
 
+      # Returns true when +value+ is nil or empty.
       def blank?(value)
         value.nil? || value.to_s.empty?
       end

data/lib/gem/guardian/verifier.rb

@@ -2,49 +2,63 @@
 
 module Gem
   module Guardian
-    VerificationResult = Data.define(:dependency, :expected_sha256, :actual_sha256, :artifact_path, :status, :error) do
+    # Result object for a single verification attempt.
+    VerificationResult = Data.define(:dependency, :expected_sha256, :actual_sha256, :artifact_path, :status, :error,
+                                     :checksum_source) do
+      # Returns true when the verification succeeded.
       def ok?
         status == :ok
       end
     end
 
+    # Verifies gem artifacts against an expected checksum source.
     class Verifier
-      def initialize(client: RubygemsClient.new, artifact_store: nil)
+      def initialize(client: RubygemsClient.new, artifact_store: nil, expected_checksums: {})
         @client = client
         @artifact_store = artifact_store || ArtifactStore.new(client: @client)
+        @expected_checksums = expected_checksums
       end
 
+      # Verifies one dependency and returns a VerificationResult.
       def verify(dependency)
-        expected = @client.expected_sha256(dependency)
-        artifact_path = @artifact_store.path_for(dependency)
-        actual = Checksum.sha256_file(artifact_path)
-        status = secure_compare(expected, actual) ? :ok : :mismatch
-
-        VerificationResult.new(
-          dependency:,
-          expected_sha256: expected,
-          actual_sha256: actual,
-          artifact_path:,
-          status:,
-          error: nil
-        )
+        expected, checksum_source = expected_sha256_for(dependency)
+        build_verification_result(dependency, expected, checksum_source)
       rescue StandardError => e
+        build_error_result(dependency, e)
+      end
+
+      # Verifies each dependency in +dependencies+.
+      def verify_all(dependencies)
+        dependencies.map { |dependency| verify(dependency) }
+      end
+
+      private
+
+      def build_verification_result(dependency, expected, checksum_source)
+        VerificationResult.new(**verification_attributes(dependency, expected, checksum_source))
+      end
+
+      def build_error_result(dependency, error)
         VerificationResult.new(
           dependency:,
           expected_sha256: nil,
           actual_sha256: nil,
           artifact_path: nil,
           status: :error,
-          error: e
+          error:,
+          checksum_source: nil
         )
       end
 
-      def verify_all(dependencies)
-        dependencies.map { |dependency| verify(dependency) }
+      def verification_attributes(dependency, expected, checksum_source)
+        artifact_path = @artifact_store.path_for(dependency)
+        actual = Checksum.sha256_file(artifact_path)
+        { dependency:, expected_sha256: expected, actual_sha256: actual, artifact_path:,
+          status: secure_compare(expected, actual) ? :ok : :mismatch, error: nil,
+          checksum_source: }
       end
 
-      private
-
+      # Constant-time comparison for checksum strings.
       def secure_compare(left, right)
         left = left.to_s
         right = right.to_s
@@ -52,6 +66,15 @@ module Gem
 
         left.bytes.zip(right.bytes).reduce(0) { |memo, (a, b)| memo | (a ^ b) }.zero?
       end
+
+      # Uses lockfile checksums first and falls back to RubyGems metadata.
+      def expected_sha256_for(dependency)
+        if @expected_checksums.key?(dependency)
+          [@expected_checksums.fetch(dependency), :lockfile]
+        else
+          [@client.expected_sha256(dependency), :rubygems]
+        end
+      end
     end
   end
 end

data/lib/gem/guardian/version.rb

@@ -2,6 +2,7 @@
 
 module Gem
   module Guardian
-    VERSION = "0.1.0"
+    # gem-guardian version.
+    VERSION = "0.1.1"
   end
 end

data/lib/gem/guardian.rb

@@ -1,3 +1,7 @@
+# Gem Guardian provides small, explicit verification and audit helpers for Ruby gems.
+#
+# The library is intentionally organized as a set of focused objects rather than a
+# framework so the CLI, tests, and signatures stay easy to reason about.
 # frozen_string_literal: true
 
 require_relative "guardian/version"
@@ -8,4 +12,5 @@ require_relative "guardian/lockfile_parser"
 require_relative "guardian/rubygems_client"
 require_relative "guardian/artifact_store"
 require_relative "guardian/verifier"
+require_relative "guardian/result_printer"
 require_relative "guardian/cli"

data/sig/gem/guardian/artifact_store.rbs

@@ -11,3 +11,12 @@ module Gem
     end
   end
 end
+module Gem
+  module Guardian
+    class ArtifactStore
+      def initialize: (client: RubygemsClient, ?cache_dir: String) -> void
+
+      def path_for: (Dependency dependency) -> String
+    end
+  end
+end

data/sig/gem/guardian/checksum.rbs

@@ -5,3 +5,10 @@ module Gem
     end
   end
 end
+module Gem
+  module Guardian
+    module Checksum
+      def self.sha256_file: (String path) -> String
+    end
+  end
+end

data/sig/gem/guardian/cli.rbs

@@ -27,3 +27,34 @@ module Gem
     end
   end
 end
+module Gem
+  module Guardian
+    class CLI
+      @argv: untyped
+
+      @stdout: untyped
+
+      @stderr: untyped
+
+      def self.start: (untyped argv) -> untyped
+
+      def initialize: (untyped argv, ?stdout: untyped, ?stderr: untyped, ?verifier_class: untyped, ?lockfile_parser_class: untyped) -> void
+
+      def run: () -> untyped
+
+      private
+
+      def verify: () -> untyped
+
+      def parse_gem_spec: (String spec) -> Dependency
+
+      def option_value: (String name) -> (String?)
+
+      def print_results: (untyped results, lockfile_mode: bool) -> void
+
+      def print_lockfile_coverage: (untyped lockfile_data) -> void
+
+      def usage: (?untyped io) -> void
+    end
+  end
+end

data/sig/gem/guardian/dependency.rbs

@@ -3,3 +3,16 @@ module Gem
     Dependency: untyped
   end
 end
+module Gem
+  module Guardian
+    class Dependency
+      attr_reader name: String
+
+      attr_reader version: String
+
+      attr_reader platform: String?
+
+      def gem_filename: () -> String
+    end
+  end
+end

data/sig/gem/guardian/error.rbs

@@ -9,3 +9,18 @@ module Gem
     LockfileError: untyped
   end
 end
+module Gem
+  module Guardian
+    class Error < StandardError
+    end
+
+    class ChecksumNotFound < Error
+    end
+
+    class ArtifactFetchError < Error
+    end
+
+    class LockfileError < Error
+    end
+  end
+end

data/sig/gem/guardian/lockfile_parser.rbs

@@ -17,3 +17,39 @@ module Gem
     end
   end
 end
+module Gem
+  module Guardian
+    class LockfileParser
+      GEM_LINE: ::Regexp
+      CHECKSUM_LINE: ::Regexp
+
+      class LockfileData
+        attr_reader dependencies: ::Array[Dependency]
+
+        attr_reader checksums: ::Hash[Dependency, ::Hash[String, String]]
+
+        attr_reader checksums_section_present: bool
+
+        def checksum_for: (Dependency dependency, ?String algorithm) -> String?
+
+        def sha256_checksums: () -> ::Hash[Dependency, String]
+
+        def missing_checksum_dependencies: () -> ::Array[Dependency]
+
+        def checksums_present?: () -> bool
+      end
+
+      def initialize: (?String path) -> void
+
+      def parse: () -> LockfileData
+
+      def dependencies: () -> ::Array[Dependency]
+
+      def checksums: () -> ::Hash[Dependency, ::Hash[String, String]]
+
+      private
+
+      def split_version_and_platform: (String value) -> ::Array[String]
+    end
+  end
+end

data/sig/gem/guardian/rubygems_client.rbs

@@ -23,3 +23,24 @@ module Gem
     end
   end
 end
+module Gem
+  module Guardian
+    class RubygemsClient
+      DEFAULT_HOST: String
+
+      def initialize: (?host: String, ?http: untyped) -> void
+
+      def expected_sha256: (Dependency dependency) -> String
+
+      def download_gem: (Dependency dependency, String destination) -> String
+
+      private
+
+      def get: (String path) -> String
+
+      def platform_matches?: (untyped remote_platform, untyped wanted_platform) -> bool
+
+      def blank?: (untyped value) -> bool
+    end
+  end
+end

data/sig/gem/guardian/verifier.rbs

@@ -19,3 +19,22 @@ module Gem
     end
   end
 end
+module Gem
+  module Guardian
+    VerificationResult: untyped
+
+    class Verifier
+      def initialize: (?client: RubygemsClient, ?artifact_store: ArtifactStore?, ?expected_checksums: ::Hash[Dependency, String]) -> void
+
+      def verify: (Dependency dependency) -> untyped
+
+      def verify_all: (::Array[Dependency] dependencies) -> ::Array[untyped]
+
+      private
+
+      def secure_compare: (String left, String right) -> bool
+
+      def expected_sha256_for: (Dependency dependency) -> ::Array[untyped]
+    end
+  end
+end

data/sig/gem/guardian/version.rbs

@@ -3,3 +3,8 @@ module Gem
     VERSION: "0.1.0"
   end
 end
+module Gem
+  module Guardian
+    VERSION: String
+  end
+end

data/sig/gem/guardian.rbs

@@ -0,0 +1,4 @@
+module Gem
+  module Guardian
+  end
+end

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: gem-guardian
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kenneth Demanawa
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Verifies Ruby gem artifacts against RubyGems SHA256 checksums using Gemfile.lock
-  or explicit gem names.
+description: 'Audits Bundler checksum coverage and verifies Ruby gem artifacts against
+  RubyGems SHA256 checksums when needed.
+
+  '
 email:
 - kenneth.c.demanawa@gmail.com
 executables:
@@ -20,9 +21,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
+- ".github/workflows/pages.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -40,6 +44,7 @@ files:
 - lib/gem/guardian/dependency.rb
 - lib/gem/guardian/error.rb
 - lib/gem/guardian/lockfile_parser.rb
+- lib/gem/guardian/result_printer.rb
 - lib/gem/guardian/rubygems_client.rb
 - lib/gem/guardian/verifier.rb
 - lib/gem/guardian/version.rb
@@ -62,7 +67,6 @@ metadata:
   source_code_uri: https://github.com/kanutocd/gem-guardian
   changelog_uri: https://github.com/kanutocd/gem-guardian/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -77,8 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Consumer-side integrity verification for Ruby gems.
 test_files: []