swagcov 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6982166b311ad4760552a4d9b867dd0933b08f67e27da868a5b679e3cf93e4f4
-  data.tar.gz: 27bf743505dd26ce0180e1cfb47cdaba3b08690b746a5577b47e9e3e0f821026
+  metadata.gz: 3102d52e8495c610e219ad58a32c75a3575cbd0460f1fddefdb5d427ff4e9f5e
+  data.tar.gz: 7f64fbc51d03dec663fea9dec838615f12d287d7f6a83f813e1f5411e6f11f8a
 SHA512:
-  metadata.gz: df6f5c0dcd71a4f71954f40c818a831584a964983790bbb25e9aa335f569453b41cd6d6d1a5dc092389dc061338e90e3a44907cbf2c77016f7e43faae0ac2ca6
-  data.tar.gz: e27a24e341a0fee8d7122c92e778543c9dd64de52b9b7ad74a60f60c808ac96aed4b779945f15221560803094fffe131ebedb72f5a4440b7ad5be54d6ad94034
+  metadata.gz: 233f4668cb3e3ffa15b8354543c17f6879d50e5d077cf9aa55ea3aeb3c7d0f0f42bd7de4a7d5383987268377734ba90ac737f7bd3e02bb17a0d337ab3f348a96
+  data.tar.gz: b420010ec3553036c2ea18ceb3d14d1f080b3af9ced0daa432a3d7a47d70a0d9beaee4baacc1dc0747df4701d7b447088177d27d8f415d7486480d89c73dffe0

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 ## main (unreleased)
 -
 
+## 0.11.0 (2025-05-13)
+### Enhancement
+- Add swagcov `version` option ([#134](https://github.com/smridge/swagcov/pull/134))
+  ```
+  swagcov -v
+  rake swagcov -- -v
+  ```
+
+### Refactor
+- Reduce `Metrics/AbcSize` for better maintainability ([#138](https://github.com/smridge/swagcov/pull/138), [#139](https://github.com/smridge/swagcov/pull/139), [#140](https://github.com/smridge/swagcov/pull/140))
+
+## 0.10.0 (2025-05-08)
+### Enhancement
+- Add executable for streamlined command line usage ([#120](https://github.com/smridge/swagcov/pull/120))
+  - The below options are now available:
+    ```
+    swagcov
+    swagcov --init
+    swagcov --todo
+    swagcov --help
+    ```
+  - **Note**: This is experimental as it may not work for all use cases. Use `rake swagcov` as a fallback
+- Add command line options to the existing `rake swagcov` task ([#121](https://github.com/smridge/swagcov/pull/121), [#122](https://github.com/smridge/swagcov/pull/122), [#123](https://github.com/smridge/swagcov/pull/123))
+  - The below options are now available:
+    ```
+    rake swagcov
+    rake swagcov -- --init
+    rake swagcov -- --todo
+    rake swagcov -- --help
+    ```
+  - **Note**: This refactor involved `BREAKING CHANGES`:
+    - `rake swagcov:generate_todo` is now `rake swagcov -- --todo`
+    - `rake swagcov:install` is now `rake swagcov -- --init`
+
 ## 0.9.0 (2025-05-07)
 ### Enhancement
 - Add support for `.json` OpenAPI file types ([#112](https://github.com/smridge/swagcov/pull/112), [#113](https://github.com/smridge/swagcov/pull/113))

data/README.md

@@ -9,31 +9,57 @@
 ![CodeQL Build](https://github.com/smridge/swagcov/actions/workflows/codeql-analysis.yml/badge.svg)
 [![Coverage Status](https://coveralls.io/repos/github/smridge/swagcov/badge.svg?branch=main)](https://coveralls.io/github/smridge/swagcov?branch=main)
 
-See OpenAPI documentation coverage report for Rails Routes.
+OpenAPI documentation coverage report for Rails Routes.
 
 ## Usages
 - See overview of different endpoints covered, missing and what you choose to ignore.
-- Add pass/fail to your build pipeline when missing Documentation Coverage.
-
-| `rake task` | `rails console` | Description |
-| :--- | :--- | :--- |
-| `rake swagcov` | `Swagcov::Command::ReportCoverage.new.run` | Check OpenAPI documentation coverage for Rails Route endpoints |
-| `rake swagcov:install` | `Swagcov::Command::GenerateDotfile.new.run` | Generate required `.swagcov.yml` config file |
-| `rake swagcov:generate_todo` | `Swagcov::Command::GenerateTodoFile.new.run` | Generate optional `.swagcov_todo.yml` config file |
+- Add pass/fail to your build pipeline when missing documentation coverage.
+
+### Usage Options
+`swagcov` can be used with a few different approachs.
+The approaches below are listed in the following order:
+- via executable
+- via rake task
+- via rails console
+
+#### View OpenAPI documentation coverage report for Rails Route endpoints
+- `swagcov`
+- `rake swagcov`
+- `Swagcov::Runner.new.run`
+
+#### Generate required `.swagcov.yml` config file
+- `swagcov --init`
+- `rake swagcov -- --init`
+- `Swagcov::Runner.new(args: ["--init"]).run`
+
+#### Generate optional `.swagcov_todo.yml` config file
+- `swagcov --todo`
+- `rake swagcov -- --todo`
+- `Swagcov::Runner.new(args: ["--todo"]).run`
+
+#### View `swagcov` version
+- `swagcov -v`
+- `rake swagcov -- -v`
+- `Swagcov::Runner.new(args: ["-v"]).run`
+
+#### View command line usage options
+- `swagcov --help`
+- `rake swagcov -- --help`
+- `Swagcov::Runner.new(args: ["--help"]).run`
 
 ## Ruby and Rails Version Support
 Versioning support from a test coverage perspective, see [tests.yml](/.github/workflows/tests.yml) for detail
 | `ruby -v` | `rails 4.2` | `rails 5.0` | `rails 5.1` | `rails 5.2` | `rails 6.0` | `rails 6.1` | `rails 7.0` | `rails 7.1` | `rails 7.2` | `rails 8.0` |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| `2.5` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
-| `2.6` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
-| `2.7` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
-| `3.0` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
-| `3.1` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| `3.2` | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `3.3` | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `3.4` | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `3.5` | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| ---       | ---         | ---         | ---         | ---         | ---         | ---         | ---         | ---         | ---         | ---         |
+| `2.5`     | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ❌          | ❌          | ❌          | ❌          |
+| `2.6`     | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ❌          | ❌          | ❌          | ❌          |
+| `2.7`     | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ❌          | ❌          |
+| `3.0`     | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ❌          | ❌          |
+| `3.1`     | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ❌          |
+| `3.2`     | ❌          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          |
+| `3.3`     | ❌          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          |
+| `3.4`     | ❌          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          |
+| `3.5`     | ❌          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          |
 
 ## Installation
 Add this line to your application's Gemfile:

data/exe/swagcov

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Experimental executable
+#
+# Booting rails approach should work for most applications
+# Rake task option as an alternative should always work as expected
+
+# Load logger before rails
+# Fix for booting rails 6.0-7.0 apps (uninitialized constant ActiveSupport::LoggerThreadSafeLevel::Logger)
+require "logger"
+
+require "swagcov"
+
+RAILS_APP_PATH = File.expand_path("config/application", Dir.pwd)
+
+def boot_rails_application!
+  require RAILS_APP_PATH
+  Rails.application.initialize!
+rescue LoadError, NoMethodError
+  warn "Unable to load Rails application, try running `rake swagcov` instead"
+  exit Swagcov::STATUS_ERROR
+end
+
+boot_rails_application!
+
+Swagcov::Runner.new(args: ARGV).run

data/lib/swagcov/command/report_version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Swagcov
+  module Command
+    class ReportVersion
+      def run
+        $stdout.puts ::Swagcov::Version::STRING
+
+        ::Swagcov::STATUS_SUCCESS
+      end
+    end
+  end
+end

data/lib/swagcov/coverage.rb

@@ -2,11 +2,11 @@
 
 module Swagcov
   class Coverage
-    attr_reader :dotfile
-
     def initialize dotfile: ::Swagcov::Dotfile.new, routes: ::Swagcov.project_routes
       @dotfile = dotfile
+      @openapi_files = ::Swagcov::OpenapiFiles.new(filepaths: @dotfile.docs_config)
       @routes = routes
+      @rails_version = ::Rails::VERSION::STRING
       @data = {
         covered: [],
         ignored: [],
@@ -19,14 +19,11 @@ module Swagcov
     end
 
     def collect
-      openapi_files = ::Swagcov::OpenapiFiles.new(filepaths: dotfile.docs_config)
-      rails_version = ::Rails::VERSION::STRING
-
       @routes.each do |route|
-        path = route.path.spec.to_s.chomp("(.:format)")
-        verb = rails_version > "5" ? route.verb : route.verb.inspect.gsub(%r{[$^/]}, "")
+        path = route_path(route)
+        verb = route_verb(route)
 
-        next if third_party_route?(route, path, rails_version)
+        next if third_party_route?(route, path)
 
         if dotfile.ignore_path?(path, verb: verb)
           update_data(:ignored, verb, path, "ignored")
@@ -49,10 +46,20 @@ module Swagcov
 
     private
 
-    def third_party_route? route, path, rails_version
+    attr_reader :dotfile, :openapi_files, :rails_version
+
+    def route_path route
+      route.path.spec.to_s.chomp("(.:format)")
+    end
+
+    def route_verb route
+      rails_version > "5" ? route.verb : route.verb.inspect.gsub(%r{[$^/]}, "")
+    end
+
+    def third_party_route? route, path
       # https://github.com/rails/rails/blob/48f3c3e201b57a4832314b2c957a3b303e89bfea/actionpack/lib/action_dispatch/routing/inspector.rb#L105-L107
       # Skips route paths like ["/rails/info/properties", "/rails/info", "/rails/mailers"]
-      internal_rails_route?(route, rails_version) ||
+      internal_rails_route?(route) ||
 
         # Skips routes like "/sidekiq"
         route.verb.blank? ||
@@ -63,7 +70,7 @@ module Swagcov
         path.include?("/active_storage/") || path.include?("/action_mailbox/")
     end
 
-    def internal_rails_route? route, rails_version
+    def internal_rails_route? route
       if rails_version > "5"
         route.internal
       else

data/lib/swagcov/dotfile.rb

@@ -2,8 +2,8 @@
 
 module Swagcov
   class Dotfile
-    DEFAULT_CONFIG_FILE_NAME = ".swagcov.yml"
-    TODO_CONFIG_FILE_NAME = ".swagcov_todo.yml"
+    DEFAULT_CONFIG_FILE_NAME = ::ENV.fetch("SWAGCOV_DOTFILE", ".swagcov.yml")
+    TODO_CONFIG_FILE_NAME = ::ENV.fetch("SWAGCOV_TODOFILE", ".swagcov_todo.yml")
 
     def initialize basename: DEFAULT_CONFIG_FILE_NAME, todo_basename: TODO_CONFIG_FILE_NAME, skip_todo: false
       @dotfile = load_yaml(basename, required: true)

data/lib/swagcov/formatter/console.rb

@@ -33,10 +33,9 @@ module Swagcov
       end
 
       def min_path_width
-        strings =
-          data[:covered].map { |hash| hash[:path] } +
-          data[:ignored].map { |hash| hash[:path] } +
-          data[:uncovered].map { |hash| hash[:path] }
+        strings = []
+
+        %i[covered ignored uncovered].each { |key| data[key].each { |hash| strings << hash[:path] } }
 
         @min_path_width ||= strings.max_by(&:length)&.size.to_i + 1
       end

data/lib/swagcov/options.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Swagcov
+  class Options
+    def initialize args: ::ARGV
+      @args = args
+    end
+
+    def define
+      options = {}
+
+      ::OptionParser.new do |opts|
+        opts.banner = <<~MESSAGE
+          Usage:
+          * as executable: swagcov [options]
+          * as rake task: rake swagcov -- [options]
+        MESSAGE
+
+        opts.on("-i", "--init", "Generate required .swagcov.yml config file") do |opt|
+          options[:init] = opt
+        end
+
+        opts.on("-t", "--todo", "Generate optional .swagcov_todo.yml config file") do |opt|
+          options[:todo] = opt
+        end
+
+        opts.on("-v", "--version", "Display version") do |opt|
+          options[:version] = opt
+        end
+      end.parse!(@args)
+
+      options
+    rescue ::OptionParser::InvalidOption => e
+      warn e.message
+      warn "For usage information, use --help"
+      exit ::Swagcov::STATUS_ERROR
+    end
+  end
+end

data/lib/swagcov/runner.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Swagcov
+  class Runner
+    attr_reader :options
+
+    def initialize args: ::ARGV
+      @args = args
+      @options = ::Swagcov::Options.new(args: @args).define
+    end
+
+    def run
+      exit runner
+    end
+
+    private
+
+    def runner
+      return ::Swagcov::Command::GenerateDotfile.new.run if options[:init]
+      return ::Swagcov::Command::GenerateTodoFile.new.run if options[:todo]
+      return ::Swagcov::Command::ReportVersion.new.run if options[:version]
+
+      ::Swagcov::Command::ReportCoverage.new.run
+    end
+  end
+end

data/lib/swagcov/version.rb

@@ -2,6 +2,6 @@
 
 module Swagcov
   module Version
-    STRING = "0.9.0"
+    STRING = "0.11.0"
   end
 end

data/lib/swagcov.rb

@@ -5,13 +5,16 @@ require "rails"
 require "swagcov/command/generate_dotfile"
 require "swagcov/command/generate_todo_file"
 require "swagcov/command/report_coverage"
+require "swagcov/command/report_version"
 require "swagcov/core_ext/string"
 require "swagcov/formatter/console"
 require "swagcov/coverage"
 require "swagcov/dotfile"
 require "swagcov/errors"
 require "swagcov/openapi_files"
+require "swagcov/options"
 require "swagcov/railtie"
+require "swagcov/runner"
 require "swagcov/version"
 
 module Swagcov

data/lib/tasks/swagcov.rake

@@ -2,5 +2,6 @@
 
 desc "Check OpenAPI documentation coverage for Rails Route endpoints"
 task swagcov: :environment do
-  exit Swagcov::Command::ReportCoverage.new.run
+  args = ARGV.drop(2) # Remove "swagcov" and "--" to ignore standard rake arguments
+  Swagcov::Runner.new(args: args).run
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: swagcov
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Sarah Ridge
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -25,28 +25,31 @@ dependencies:
         version: '4.2'
 email:
 - sarahmarie@hey.com
-executables: []
+executables:
+- swagcov
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- exe/swagcov
 - lib/swagcov.rb
 - lib/swagcov/command/generate_dotfile.rb
 - lib/swagcov/command/generate_todo_file.rb
 - lib/swagcov/command/report_coverage.rb
+- lib/swagcov/command/report_version.rb
 - lib/swagcov/core_ext/string.rb
 - lib/swagcov/coverage.rb
 - lib/swagcov/dotfile.rb
 - lib/swagcov/errors.rb
 - lib/swagcov/formatter/console.rb
 - lib/swagcov/openapi_files.rb
+- lib/swagcov/options.rb
 - lib/swagcov/railtie.rb
+- lib/swagcov/runner.rb
 - lib/swagcov/version.rb
 - lib/tasks/swagcov.rake
-- lib/tasks/swagcov/generate_todo.rake
-- lib/tasks/swagcov/install.rake
 homepage: https://github.com/smridge/swagcov
 licenses:
 - MIT
@@ -72,5 +75,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.8
 specification_version: 4
-summary: OpenAPI documentation coverage for Rails Routes
+summary: OpenAPI documentation coverage report for Rails Route endpoints
 test_files: []

data/lib/tasks/swagcov/generate_todo.rake

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-namespace :swagcov do
-  desc "Generate optional .swagcov_todo.yml config file acting as a TODO list"
-  task generate_todo: :environment do
-    exit Swagcov::Command::GenerateTodoFile.new.run
-  end
-end

data/lib/tasks/swagcov/install.rake

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-namespace :swagcov do
-  desc "Generate required .swagcov.yml config file"
-  task install: :environment do
-    exit Swagcov::Command::GenerateDotfile.new.run
-  end
-end