swagcov 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a764a7d06c6d8217807646056aa78f72a0a1bec7c289c3eea9f1fc49fc118d44
-  data.tar.gz: a5b592e359fc41b8dbd7ddb692d7f8b656bba1474c5b397159a5b0a32a096040
+  metadata.gz: 5aaf6a7a919c70669dc24a129159b2ce961aa237495d57cfd1d94350bbad526f
+  data.tar.gz: e312bf832ceca1bc66017b131c958ab9f70ea4efddc32fac9bda0fcb369d7696
 SHA512:
-  metadata.gz: 1add2c26c08559ccc88a42739747676176b0c0d86e18c6086fceeaf82f44f418f1c63a7bb840a5d954be79a93d187d14a84a04a2e09059242bbeed27738beed7
-  data.tar.gz: c15c67b17352ffc5be4fa6b4ae585647f9b217eb5620d9f534e9b1ab8903dbd859bbe656dc473f5e046dfc5f5f69265eba4b1b27f6dce426aa1ff374ee8d2949
+  metadata.gz: 14de18f74737e418b16153aea8c9f107545b9445fc5956dd0617ddbae4a0ad78be83017d6df8f442724186d38fd44a47b8462d4dc7ce2590c2b7aae26aaff201
+  data.tar.gz: b22dc442442935535df66b494d9f24f4475517eb36468208d24a3ad3b43f49202eb6ada1679efc1657804ea2e789b62b8dac030009ad1bf282fc9b6b3cfa1853

data/README.md

@@ -1,5 +1,14 @@
 # Swagcov
-See coverage report for openapi docs for Rails Routes.
+[![Gem Version](https://img.shields.io/gem/v/swagcov)](https://rubygems.org/gems/swagcov)
+![Gem Downloads](https://img.shields.io/gem/dt/swagcov)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
+[![GitHub License](https://img.shields.io/github/license/smridge/swagcov.svg)](https://github.com/smridge/swagcov/blob/main/LICENSE)
+
+See 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.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -34,10 +43,9 @@ Create a `.swagcov.yml` in root of your Rails application.
     paths:
       ignore:
         - /v1/foobar/:token
-        - /sidekiq
   ```
 
-- Example `.swagcov.yml` Config File:
+- Full Example `.swagcov.yml` Config File:
   ```yml
   docs:
     paths:
@@ -49,7 +57,6 @@ Create a `.swagcov.yml` in root of your Rails application.
         - ^/v1
       ignore:
         - /v1/foobar/:token
-        - /sidekiq
   ```
 
 Execute:
@@ -57,6 +64,44 @@ Execute:
 bundle exec rake swagcov
 ```
 
+### Example configurations and output from running `bundle exec rake swagcov` from the root of your Rails Application:
+- All Routes (minimal configuration):
+  ```yml
+  docs:
+    paths:
+      - swagger.yaml
+  ```
+  <img src="https://raw.githubusercontent.com/smridge/swagcov/main/images/all-endpoints.png">
+
+
+- With `only` endpoint configuration:
+  ```yml
+  docs:
+    paths:
+      - swagger.yaml
+
+  routes:
+    paths:
+      only:
+        - ^/v2
+  ```
+  <img src="https://raw.githubusercontent.com/smridge/swagcov/main/images/only-endpoints.png">
+
+- With `ignore` and `only` endpoint configurations:
+  ```yml
+  docs:
+    paths:
+      - swagger/v1/swagger.yaml
+
+  routes:
+    paths:
+      only:
+        - ^/v2
+      ignore:
+        - /v2/users
+  ```
+  <img src="https://raw.githubusercontent.com/smridge/swagcov/main/images/ignore-and-only-endpoints.png">
+
 ## Development
 ```shell
 git clone git@github.com:smridge/swagcov.git
@@ -72,18 +117,39 @@ gem "swagcov", path: "../swagcov"
 bundle
 ```
 
+Run Tests
+```
+bundle exec rspec spec --exclude-pattern spec/sandbox_**/**/*_spec.rb
+```
+
+### Test via Sandbox Application
+- Go to any sandbox application within the `spec` directory
+  - For example, `cd spec/sandbox_5_2/`
+- Install the ruby version specified in `.ruby-version` file
+- Install gems: `bundle install`
+- Run tests: `bundle exec rspec spec`
+- Run `bundle exec rake swagcov`
+  - This will run against any changes made to your branch.
+
 ## Publish (internal)
 > Note: Publishing a new version of this gem is only meant for maintainers.
 - Ensure you have access to publish on [rubygems](https://rubygems.org/gems/swagcov).
 - Update [CHANGELOG](https://github.com/smridge/swagcov/blob/main/CHANGELOG.md).
 - Update [`VERSION`](https://github.com/smridge/swagcov/blob/main/lib/swagcov/version.rb).
+- Commit changes to `main` branch locally.
 - Run: `rake release`
   - This command builds the gem, creates a tag and publishes to rubygems, see [bundler docs](https://bundler.io/guides/creating_gem.html#releasing-the-gem).
 
 ## TODO
-- Add specs
-- Test against different rails versions
+- Create Rails 7 / Ruby 3.1 Sandbox
 - Add autogeneration of ignore paths
+- Add `CONTRIBUTING.md`
+- Add GitHub Action for linting
 
 ## Credit
 To [@lonelyelk](https://github.com/lonelyelk) for initial development!
+
+## Contributors
+<a href="https://github.com/smridge/swagcov/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=smridge/swagcov" />
+</a>

data/lib/swagcov/coverage.rb

@@ -2,37 +2,51 @@
 
 module Swagcov
   class Coverage
-    def initialize
+    attr_reader :total, :covered, :ignored, :routes_not_covered, :routes_covered, :routes_ignored
+
+    def initialize dotfile: Swagcov::Dotfile.new, routes: ::Rails.application.routes.routes
       @total = 0
       @covered = 0
       @ignored = 0
       @routes_not_covered = []
       @routes_covered = []
       @routes_ignored = []
+      @dotfile = dotfile
+      @routes = routes
     end
 
     def report
-      Rails.application.routes.routes.each do |route|
-        # 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"]
-        next if route.internal
+      collect_coverage
+      routes_output(@routes_covered, "green")
+      routes_output(@routes_ignored, "yellow")
+      routes_output(@routes_not_covered, "red")
 
-        # Skips routes like "/sidekiq"
-        next unless route.verb.present?
+      final_output
+
+      @total - @covered
+    end
 
+    private
+
+    attr_reader :dotfile
+
+    def collect_coverage
+      @routes.each do |route|
         path = route.path.spec.to_s.sub(/\(\.:format\)$/, "")
 
-        if ignore_path?(path)
+        next if third_party_route?(route, path)
+
+        if dotfile.ignore_path?(path)
           @ignored += 1
           @routes_ignored << { verb: route.verb, path: path, status: "ignored" }
           next
         end
 
-        next if only_path_mismatch?(path)
+        next if dotfile.only_path_mismatch?(path)
 
         @total += 1
-        regex = Regexp.new("#{path.gsub(%r{:[^/]+}, '\\{[^/]+\\}')}(\\.[^/]+)?$")
-        matching_keys = docs_paths.keys.select { |k| regex.match?(k) }
+        regex = Regexp.new("^#{path.gsub(%r{:[^/]+}, '\\{[^/]+\\}')}(\\.[^/]+)?$")
+        matching_keys = docs_paths.keys.grep(regex)
 
         if (doc = docs_paths.dig(matching_keys.first, route.verb.downcase))
           @covered += 1
@@ -41,57 +55,39 @@ module Swagcov
           @routes_not_covered << { verb: route.verb, path: path, status: "none" }
         end
       end
-
-      routes_output(@routes_covered, "green")
-      routes_output(@routes_ignored, "yellow")
-      routes_output(@routes_not_covered, "red")
-
-      final_output
-
-      exit @total - @covered
-    end
-
-    def dotfile
-      @dotfile ||= YAML.load_file(Rails.root.join(".swagcov.yml"))
     end
 
     def docs_paths
-      @docs_paths ||= Dir.glob(dotfile["docs"]["paths"]).reduce({}) do |acc, docspath|
-        acc.merge(YAML.load_file(docspath)["paths"])
+      @docs_paths ||= Dir.glob(dotfile.doc_paths).reduce({}) do |acc, docspath|
+        acc.merge(load_yaml(docspath))
       end
     end
 
-    private
-
-    def ignore_path? path
-      ignored_regex&.match?(path)
+    def load_yaml docspath
+      YAML.load_file(docspath)["paths"]
+    rescue Psych::SyntaxError
+      raise BadConfigurationError, "Malinformed openapi file (#{docspath})"
     end
 
-    def ignored_regex
-      @ignored_regex ||= path_config_regex(dotfile.dig("routes", "paths", "ignore"))
-    end
-
-    def only_path_mismatch? path
-      only_regex && !only_regex.match?(path)
-    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"]
+      route.internal ||
 
-    def only_regex
-      @only_regex ||= path_config_regex(dotfile.dig("routes", "paths", "only"))
-    end
-
-    def path_config_regex path_config
-      return unless path_config
-
-      config = path_config.map { |path| path.first == "^" ? path : "#{path}$" }
+        # Skips routes like "/sidekiq"
+        route.verb.blank? ||
 
-      /#{config.join('|')}/
+        # Exclude routes that are part of the rails gem that you would not write documentation for
+        # https://github.com/rails/rails/tree/main/activestorage/app/controllers/active_storage
+        # https://github.com/rails/rails/tree/main/actionmailbox/app/controllers/action_mailbox
+        path.include?("/active_storage/") || path.include?("/action_mailbox/")
     end
 
     def routes_output routes, status_color
       routes.each do |route|
         $stdout.puts(
           format(
-            "%<verb>10s    %<path>-90s    %<status>s",
+            "%<verb>10s %<path>-90s %<status>s",
             { verb: route[:verb], path: route[:path], status: route[:status].send(status_color) }
           )
         )

data/lib/swagcov/dotfile.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Swagcov
+  class BadConfigurationError < RuntimeError
+  end
+
+  class Dotfile
+    DEFAULT_CONFIG_FILE_NAME = ".swagcov.yml"
+
+    def initialize pathname: ::Rails.root.join(DEFAULT_CONFIG_FILE_NAME)
+      @dotfile = load_yaml(pathname)
+
+      raise BadConfigurationError, "Invalid config file (#{DEFAULT_CONFIG_FILE_NAME})" unless valid?
+    end
+
+    def ignore_path? path
+      ignored_regex&.match?(path)
+    end
+
+    def only_path_mismatch? path
+      only_regex && !only_regex.match?(path)
+    end
+
+    def doc_paths
+      dotfile.dig("docs", "paths")
+    end
+
+    private
+
+    attr_reader :dotfile
+
+    def load_yaml pathname
+      raise BadConfigurationError, "Missing config file (#{DEFAULT_CONFIG_FILE_NAME})" unless pathname.exist?
+
+      YAML.load_file(pathname)
+    rescue Psych::SyntaxError
+      raise BadConfigurationError, "Malinformed config file (#{DEFAULT_CONFIG_FILE_NAME})"
+    end
+
+    def ignored_regex
+      @ignored_regex ||= path_config_regex(dotfile.dig("routes", "paths", "ignore"))
+    end
+
+    def only_regex
+      @only_regex ||= path_config_regex(dotfile.dig("routes", "paths", "only"))
+    end
+
+    def path_config_regex path_config
+      return unless path_config
+
+      config = path_config.map { |path| path.first == "^" ? path : "^#{path}$" }
+
+      /#{config.join('|')}/
+    end
+
+    def valid?
+      dotfile && doc_paths
+    end
+  end
+end

data/lib/swagcov/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Swagcov
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/swagcov.rb

@@ -4,6 +4,7 @@ require "swagcov/version"
 
 if defined?(Rails)
   require "swagcov/railtie"
+  require "swagcov/dotfile"
   require "swagcov/coverage"
 end
 

data/lib/tasks/swagcove.rake

@@ -2,5 +2,5 @@
 
 desc "check documentation coverage for endpoints"
 task swagcov: :environment do
-  Swagcov::Coverage.new.report
+  exit Swagcov::Coverage.new.report
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagcov
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Sarah Ridge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-22 00:00:00.000000000 Z
+date: 2022-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 - sarahmarie@hey.com
@@ -79,6 +107,7 @@ files:
 - lib/swagcov.rb
 - lib/swagcov/core_ext/string.rb
 - lib/swagcov/coverage.rb
+- lib/swagcov/dotfile.rb
 - lib/swagcov/railtie.rb
 - lib/swagcov/version.rb
 - lib/tasks/swagcove.rake
@@ -90,6 +119,7 @@ metadata:
   homepage_uri: https://github.com/smridge/swagcov
   source_code_uri: https://github.com/smridge/swagcov
   changelog_uri: https://github.com/smridge/swagcov/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -105,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: Open API docs coverage for Rails Routes