swagcov 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8b15b82b2a87742868a94cd6964469cb4aff857259d3752fe258e595f0dcfc1
-  data.tar.gz: cc35beef6a1b53c6f418337d1a59b48ce7d5152e1abf9746a0847fda08721bfc
+  metadata.gz: 8f7e8120c6da2d859ae0712f523ee0586e9e800c842594ef89c7fdaed3a28ee0
+  data.tar.gz: c884efd95e1dc61fba493ba731633087baf546612a00a83489f3d4abc7c38cff
 SHA512:
-  metadata.gz: 4c1c0133c991c4dea09e0120aa54eab71b59746c5a9ec4e1718a2fc21d86802dec7b51039bfde1638fd9055932d1fc93a958285400fa9cb777378e5c02e91851
-  data.tar.gz: 00c4c6b3508b19cb0f2c89debfc920c6aa234a4e9ec5142a11cc5995fed34d255eb70000e482d47c50a7d4f88ab026b27592b7cd1f143add31d777c48898533a
+  metadata.gz: d000402186ba36251cbdc689374979e863dce7b23f154837eba4e177bc484de337bf4928cc8d547bd71d20b7db323ab08cc378590871b2502c72a2398b8749e6
+  data.tar.gz: 74144d434fd8ba835564b3fc92a9a63b318b74c438390213a9cd62cfba0705666464d3363d3d732eff05b46ddacb9105547352310ffeb7e166e5a5834efccba3

data/CHANGELOG.md

@@ -2,6 +2,35 @@
 ## main (unreleased)
 -
 
+## 0.10.0 (2025-05-08)
+### Enhancement
+- Added 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
+- Added 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))
+- Update rake task descriptions ([#114](https://github.com/smridge/swagcov/pull/114))
+- Improve performance of OpenAPI response key matching for route paths ([#115](https://github.com/smridge/swagcov/pull/115))
+
 ## 0.8.1 (2025-04-29)
 ### Fix
 - Performance of coverage output by memoizing path string length ([#108](https://github.com/smridge/swagcov/pull/108))

data/README.md

@@ -9,17 +9,32 @@
 ![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.
+- Add pass/fail to your build pipeline when missing documentation coverage.
 
-| `rake task` | `rails console` | Description |
-| :--- | :--- | :--- |
-| `rake swagcov` | `Swagcov::Command::ReportCoverage.new.run` | Check documentation coverage |
-| `rake swagcov:install` | `Swagcov::Command::GenerateDotfile.new.run` | Install required `.swagcov.yml` config file |
-| `rake swagcov:generate_todo` | `Swagcov::Command::GenerateTodoFile.new.run` | Generate `.swagcov_todo.yml` |
+**Check OpenAPI documentation coverage for Rails Route endpoints**
+| `executable    ` | `rake task             ` | `rails console                             ` |
+| :---             | :---                     | :---                                         |
+| `swagcov`        | `rake swagcov`           | `Swagcov::Command::ReportCoverage.new.run`   |
+
+**Generate required `.swagcov.yml` config file**
+| `executable    ` | `rake task             ` | `rails console                             ` |
+| :---             | :---                     | :---                                         |
+| `swagcov --init` | `rake swagcov -- --init` | `Swagcov::Command::GenerateDotfile.new.run`  |
+
+
+**Generate optional `.swagcov_todo.yml` config file**
+| `executable    ` | `rake task             ` | `rails console                             ` |
+| :---             | :---                     | :---                                         |
+| `swagcov --todo` | `rake swagcov -- --todo` | `Swagcov::Command::GenerateTodoFile.new.run` |
+
+**See command line usage options**
+| `executable    ` | `rake task             ` | `rails console                             ` |
+| :---             | :---                     | :---                                         |
+| `swagcov --help` | `rake swagcov -- --help` | n/a |
 
 ## Ruby and Rails Version Support
 Versioning support from a test coverage perspective, see [tests.yml](/.github/workflows/tests.yml) for detail
@@ -51,11 +66,12 @@ Create a `.swagcov.yml` in root of your Rails application. Alternatively, run:
 bundle exec rake swagcov:install
 ```
 
-- Add the paths of your `openapi` yml files (**required**):
+- Add the paths of your OpenAPI `.yml` and/or `.json` files (**required**):
   ```yml
   docs:
     paths:
       - swagger.yaml
+      - swagger.json
   ```
 
 - Add `only` routes (**optional**) :

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/generate_dotfile.rb

@@ -19,10 +19,11 @@ module Swagcov
           dotfile,
           <<~YAML
             ## Required field:
-            # List your OpenAPI documentation files
+            # List your OpenAPI documentation file(s) (accepts json or yaml)
             docs:
               paths:
                 - swagger.yaml
+                - swagger.json
 
             ## Optional fields:
             # routes:

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/openapi_files.rb

@@ -5,13 +5,14 @@ module Swagcov
     def initialize filepaths:
       @filepaths = filepaths
       @openapi_paths = load_yamls
+      @openapi_path_keys = @openapi_paths.keys
     end
 
     def find_response_keys path:, route_verb:
       # replace :id with {id}
       regex = ::Regexp.new("^#{path.gsub(%r{:[^/]+}, '\\{[^/]+\\}')}?$")
 
-      matching_paths_key = @openapi_paths.keys.grep(regex).first
+      matching_paths_key = @openapi_path_keys.grep(regex).first
       matching_request_method_key = @openapi_paths.dig(matching_paths_key, route_verb.downcase)
 
       matching_request_method_key["responses"].keys.map(&:to_s).sort if matching_request_method_key
@@ -26,8 +27,8 @@ module Swagcov
     end
 
     def load_yaml filepath
-      ::YAML.load_file(filepath)["paths"]
-    rescue ::Psych::SyntaxError
+      ::YAML.load_file(filepath)["paths"] # loads yaml or json
+    rescue ::Psych::SyntaxError, ::JSON::ParserError
       raise ::Swagcov::Errors::BadConfiguration, "Malformed openapi file (#{filepath})"
     end
   end

data/lib/swagcov/options.rb

@@ -0,0 +1,37 @@
+# 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
+      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,18 @@
+# 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 ::Swagcov::Command::GenerateDotfile.new.run if options[:init]
+      exit ::Swagcov::Command::GenerateTodoFile.new.run if options[:todo]
+      exit ::Swagcov::Command::ReportCoverage.new.run
+    end
+  end
+end

data/lib/swagcov/version.rb

@@ -2,6 +2,6 @@
 
 module Swagcov
   module Version
-    STRING = "0.8.1"
+    STRING = "0.10.0"
   end
 end

data/lib/swagcov.rb

@@ -11,7 +11,9 @@ 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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-desc "check documentation coverage for endpoints"
+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.8.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Sarah Ridge
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -25,13 +25,15 @@ 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
@@ -42,11 +44,11 @@ files:
 - 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 +74,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 todo config file"
-  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 "create config file"
-  task install: :environment do
-    exit Swagcov::Command::GenerateDotfile.new.run
-  end
-end