Merge pull request #834 from varvet/kbs/code-janitoring

Code janitoring (docs, test structure, dev dependencies)

.github/workflows/main.yml

@@ -2,9 +2,8 @@ name: Main
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
   workflow_dispatch:
 
 permissions:
@@ -28,85 +27,125 @@ jobs:
       fail-fast: false
       matrix:
         ruby-version:
-          - '3.1'
-          - '3.2'
-          - '3.3'
-          - 'jruby-9.3.10' # oldest supported jruby
-          - 'jruby'
+          - "3.1"
+          - "3.2"
+          - "3.3"
+          - "jruby-9.3.10" # oldest supported jruby
+          - "jruby"
         include: # HEAD-versions
-          - ruby-version: 'head'
+          - ruby-version: "head"
             allow-failure: true
-          - ruby-version: 'jruby-head'
+          - ruby-version: "jruby-head"
             allow-failure: true
-          - ruby-version: 'truffleruby-head'
+          - ruby-version: "truffleruby-head"
             allow-failure: true
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        rubygems: latest
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: ${{ !startsWith(matrix.ruby-version, 'jruby') }}
-    - name: Bundler install (JRuby workaround)
-      if: ${{ startsWith(matrix.ruby-version, 'jruby') }}
-      run: |
-        gem install psych
-        bundle install
-    - name: Run tests
-      run: bundle exec rspec
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: latest
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: ${{ !startsWith(matrix.ruby-version, 'jruby') }}
+      - name: Bundler install (JRuby workaround)
+        if: ${{ startsWith(matrix.ruby-version, 'jruby') }}
+        run: |
+          gem install psych
+          bundle install
+      - name: Run tests
+        run: bundle exec rspec
 
   test:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        rubygems: latest
-        ruby-version: 'ruby'
-        bundler-cache: true
-    - name: "Download cc-test-reporter from codeclimate.com"
-      run: |
-        curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-        chmod +x ./cc-test-reporter
-    - name: "Report to Code Climate that we will send a coverage report."
-      run: ./cc-test-reporter before-build
-    - name: Run tests
-      run: bundle exec rspec
-      env:
-        COVERAGE: 1
-    - name: Upload code coverage to Code Climate
-      run: |
-        ./cc-test-reporter after-build \
-          --coverage-input-type simplecov \
-          ./coverage/.resultset.json
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: latest
+          ruby-version: "ruby"
+          bundler-cache: true
+      - name: "Download cc-test-reporter from codeclimate.com"
+        run: |
+          curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+          chmod +x ./cc-test-reporter
+      - name: "Report to Code Climate that we will send a coverage report."
+        run: ./cc-test-reporter before-build
+      - name: Run tests
+        run: bundle exec rspec
+        env:
+          COVERAGE: 1
+      - name: Upload coverage results
+        uses: actions/upload-artifact@v4
+        with:
+          include-hidden-files: true
+          name: coverage-results
+          path: coverage
+          retention-days: 1
+      - name: Upload code coverage to Code Climate
+        run: |
+          ./cc-test-reporter after-build \
+            --coverage-input-type simplecov \
+            ./coverage/.resultset.json
+
+  coverage-check:
+    permissions:
+      checks: write
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download coverage results
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-results
+          path: coverage
+      - uses: joshmfrankel/simplecov-check-action@be89e11889202cc59efb14aab2a7091622fa9aad
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          minimum_suite_coverage: 100
+          minimum_file_coverage: 100
+          coverage_json_path: coverage/simplecov-check-action.json
 
   rubocop:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        rubygems: default
-        ruby-version: 'ruby'
-        bundler-cache: false
-    - run: bundle install
-    - name: Run RuboCop
-      run: bundle exec rubocop
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: default
+          ruby-version: "ruby"
+          bundler-cache: false
+      - run: bundle install
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          rubygems: default
+          ruby-version: "ruby"
+          bundler-cache: false
+      - run: bundle install
+      - run: rake yard
 
   required-checks:
     runs-on: ubuntu-latest
     if: ${{ always() }}
     needs:
       - test
       - matrix-test
+      - docs
       - rubocop
     steps:
       - name: failure
         if: ${{ failure() || contains(needs.*.result, 'failure') }}
         run: exit 1
       - name: success
-        run: exit 0
+        run: exit 0

.rubocop.yml

@@ -36,6 +36,9 @@ Layout/CaseIndentation:
     - end
   IndentOneStep: true
 
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
 Layout/EndAlignment:
   EnforcedStyleAlignWith: variable
 

.yardopts

@@ -1 +1 @@
---api public --hide-void-return --markup markdown
+--no-private --private --protected --hide-void-return --markup markdown --fail-on-warning

lib/generators/pundit/install/install_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # @private
   module Generators
+    # @private
     class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
       def copy_application_policy
-        template "application_policy.rb", "app/policies/application_policy.rb"
+        template "application_policy.rb.tt", "app/policies/application_policy.rb"
       end
     end
   end

lib/generators/pundit/policy/policy_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy
-        template "policy.rb", File.join("app/policies", class_path, "#{file_name}_policy.rb")
+        template "policy.rb.tt", File.join("app/policies", class_path, "#{file_name}_policy.rb")
       end
 
       hook_for :test_framework

lib/generators/rspec/policy_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
+# @private
 module Rspec
+  # @private
   module Generators
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_spec
-        template "policy_spec.rb", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
+        template "policy_spec.rb.tt", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
       end
     end
   end

lib/generators/test_unit/policy_generator.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
+# @private
 module TestUnit
+  # @private
   module Generators
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_test
-        template "policy_test.rb", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
+        template "policy_test.rb.tt", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
       end
     end
   end

lib/pundit.rb

@@ -22,6 +22,7 @@ module Pundit
   SUFFIX = "Policy"
 
   # @api private
+  # @private
   module Generators; end
 
   # Error that will be raised when authorization has failed
@@ -70,7 +71,7 @@ def self.included(base)
   end
 
   class << self
-    # @see [Pundit::Context#authorize]
+    # @see Pundit::Context#authorize
     def authorize(user, record, query, policy_class: nil, cache: nil)
       context = if cache
         Context.new(user: user, policy_cache: cache)
@@ -81,22 +82,22 @@ def authorize(user, record, query, policy_class: nil, cache: nil)
       context.authorize(record, query: query, policy_class: policy_class)
     end
 
-    # @see [Pundit::Context#policy_scope]
+    # @see Pundit::Context#policy_scope
     def policy_scope(user, *args, **kwargs, &block)
       Context.new(user: user).policy_scope(*args, **kwargs, &block)
     end
 
-    # @see [Pundit::Context#policy_scope!]
+    # @see Pundit::Context#policy_scope!
     def policy_scope!(user, *args, **kwargs, &block)
       Context.new(user: user).policy_scope!(*args, **kwargs, &block)
     end
 
-    # @see [Pundit::Context#policy]
+    # @see Pundit::Context#policy
     def policy(user, *args, **kwargs, &block)
       Context.new(user: user).policy(*args, **kwargs, &block)
     end
 
-    # @see [Pundit::Context#policy!]
+    # @see Pundit::Context#policy!
     def policy!(user, *args, **kwargs, &block)
       Context.new(user: user).policy!(*args, **kwargs, &block)
     end