rubocop-dev_doc 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17a792c93018068695bb2c73dc023577864a51cbe29fc8962ba0d82f44784bd5
-  data.tar.gz: 260d22ceb74db21595f99e912a2bcbc4556718a30de5327fabf562b1174c84aa
+  metadata.gz: 163ac4a232d22f5d731e680d4ae882172570cdcf3085a07be7d6c3195223e365
+  data.tar.gz: a3eae8c77dcb707ddc4875be90255bea2fa33bcaeba370c7aff06436cd045661
 SHA512:
-  metadata.gz: 6df2aae2a244e306e2a659dfd2f258a5b057fbfa0dda9d6fbc25ef4169fd6c67acc3906e03df78057eb22b4337727c9992ef0bc2b3cd6e760a63edb30dfcfb3b
-  data.tar.gz: 05b1392296eb25d9625e3f755f2310a262b955ecef1e38d0448d25e6c99352351c5284a9e61a5d3361415e2c2a91e5ae9589fbea532b077babd856a55eb3fa8c
+  metadata.gz: a605681c5f22058138abe3d8bdcd1e12eb94073f74e02fde30bc1f1df0baa538022b69fe33c4f83279cfaed995e60e5c9a4936de43cad7a89f07105c4b6e7a24
+  data.tar.gz: 0e845bcf2236245a8c4b0289a02d7731e12c9ac0023732f6135127f02f436c78f349012b98bd18127e89cdb4e70736597c2fc5313229ed3faaf572294e847168

data/config/default.yml

@@ -3,88 +3,121 @@
 
 # Department-level settings: DocumentationBaseURL lets RuboCop construct per-cop
 # URLs automatically. DocumentationExtension matches the generated file format.
+DevDoc/Auth:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  DocumentationExtension: ".md"
+
 DevDoc/Migration:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
-  DocumentationExtension: '.md'
+  DocumentationExtension: ".md"
 
 DevDoc/Rails:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
-  DocumentationExtension: '.md'
+  DocumentationExtension: ".md"
 
 DevDoc/Route:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
-  DocumentationExtension: '.md'
+  DocumentationExtension: ".md"
 
 DevDoc/Style:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
-  DocumentationExtension: '.md'
+  DocumentationExtension: ".md"
+
+DevDoc/Test:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  DocumentationExtension: ".md"
 
 DevDoc/Migration/AvoidJsonColumn:
-  Description: 'Use `jsonb` instead of `json` for column types.'
+  Description: "Use `jsonb` instead of `json` for column types."
   Enabled: true
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Migration/RequireTimestamps:
-  Description: 'Always include `t.timestamps` in every `create_table` migration.'
+  Description: "Always include `t.timestamps` in every `create_table` migration."
   Enabled: false
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Migration/PreferBelongsTo:
-  Description: 'Use `t.belongs_to` instead of `t.references` for foreign keys.'
+  Description: "Use `t.belongs_to` instead of `t.references` for foreign keys."
   Enabled: true
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Migration/AvoidColumnDefault:
-  Description: 'Avoid setting `default:` in migrations; keep business logic in the application layer.'
+  Description: "Avoid setting `default:` in migrations; keep business logic in the application layer."
   Enabled: true
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+DevDoc/Migration/AvoidNonNull:
+  Description: "Avoid `null: false` on regular columns; keep presence rules in the application layer."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 # Intentionally global (no Include) — these patterns are risky in any file, not only migrations.
 # Add project-specific Exclude entries (e.g. db/seeds.rb, lib/tasks/**/*.rb) in your .rubocop.yml
 # for places where bulk operations are intentional and performance-critical.
 DevDoc/Migration/AvoidBypassingValidation:
-  Description: 'Avoid methods that bypass validations and callbacks (`update_column`, `update_all`, `insert_all`, etc.).'
+  Description: "Avoid methods that bypass validations and callbacks (`update_column`, `update_all`, `insert_all`, etc.)."
   Enabled: false
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
 
 DevDoc/Migration/DateColumnNaming:
-  Description: 'Date columns should end with `_on`; datetime columns should end with `_at`.'
+  Description: "Date columns should end with `_on`; datetime columns should end with `_at`."
   Enabled: true
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Migration/AvoidVagueColumnNames:
-  Description: 'Avoid vague column names like `status` or `group`. Use more specific names.'
+  Description: "Avoid vague column names like `status` or `group`. Use more specific names."
   Enabled: true
   VagueNames:
     - status
     - group
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Route/ResourcesRequireOnly:
-  Description: 'Always use `only:` or `except:` when defining `resources` or `resource` routes.'
+  Description: "Always use `only:` or `except:` when defining `resources` or `resource` routes."
   Enabled: true
   # RequireOnly: true (default) — only `only:` is accepted; `except:` is flagged.
   # RequireOnly: false — both `only:` and `except:` are accepted; only the bare form is flagged.
   RequireOnly: true
   Include:
-    - 'config/routes.rb'
-    - 'config/routes/**/*.rb'
+    - "config/routes.rb"
+    - "config/routes/**/*.rb"
+
+DevDoc/Rails/BangSaveInTransaction:
+  Description: "Use bang (`save!`/`update!`/`create!`) inside a `transaction` block, or check the return value."
+  Enabled: true
+
+DevDoc/Route/NoCustomActions:
+  Description: "Avoid custom `member`/`collection` actions; model them as RESTful sub-resources."
+  Enabled: true
+  Include:
+    - "config/routes.rb"
+    - "config/routes/**/*.rb"
+
+DevDoc/Route/ResourceNameNumber:
+  Description: "Use a plural name for `resources` and a singular name for `resource`."
+  Enabled: true
+  Include:
+    - "config/routes.rb"
+    - "config/routes/**/*.rb"
 
 DevDoc/Rails/NoDeliverLaterInTransaction:
-  Description: 'Avoid `deliver_later`/`perform_later` inside a `transaction` block; the job may use stale data.'
+  Description: "Avoid `deliver_later`/`perform_later` inside a `transaction` block; the job may use stale data."
   Enabled: true
   KnownAsyncWrappers:
     - send_verification_email!
@@ -93,26 +126,62 @@ DevDoc/Rails/NoDeliverLaterInTransaction:
     - send_unlock_instructions
 
 DevDoc/Rails/NoPerformLaterInModel:
-  Description: 'Avoid `perform_later` inside model files; use explicit methods called from the controller.'
+  Description: "Avoid `perform_later` inside model files; use explicit methods called from the controller."
   Enabled: true
   Include:
-    - 'app/models/**/*.rb'
+    - "app/models/**/*.rb"
 
 DevDoc/Rails/EnumMustBeSymbolized:
-  Description: 'Pair every `enum :foo` with `enum_symbolize :foo` so the reader returns a symbol.'
+  Description: "Pair every `enum :foo` with `enum_symbolize :foo` so the reader returns a symbol."
   Enabled: true
   Include:
-    - 'app/models/**/*.rb'
+    - "app/models/**/*.rb"
+
+DevDoc/Rails/EnumColumnNotNull:
+  Description: "Enum columns must be backed by a `null: false` database column."
+  Enabled: true
+  Include:
+    - "app/models/**/*.rb"
+
+DevDoc/Rails/NoBlockPredicateOnRelation:
+  Description: "Avoid block-form `count`/`reject`/`select`/`find`/`any?` on AR relations; push the predicate into SQL with `.where(...)` or a scope."
+  Enabled: true
+  Exclude:
+    - "spec/**/*"
+    - "test/**/*"
+    - "db/seeds.rb"
+    - "db/seeds/**/*.rb"
+    - "lib/tasks/**/*.rb"
+
+DevDoc/Style/NoUnscopedMethodDefinitions:
+  Description: "Define methods inside an explicit `module` or `class`; bare `def` outside a class/module body lands on `Object`."
+  Enabled: true
+  # SafeDSLReceivers: list of constant names whose `.new { }` blocks are safe
+  # (methods inside them do NOT land on Object). Struct, Class, Module are
+  # included by default.
+  SafeDSLReceivers: []
 
 DevDoc/Style/AvoidSend:
-  Description: 'Avoid `send`/`public_send` with an explicit receiver; prefer direct calls or safer alternatives.'
+  Description: "Avoid `send`/`public_send` with an explicit receiver; prefer direct calls or safer alternatives."
+  Enabled: true
+
+DevDoc/Style/RepeatedSafeNavigationReceiver:
+  Description: "Avoid using `&.` on the same receiver more than once in a method body — assign once and use `.` after."
+  Enabled: true
+
+DevDoc/Style/RepeatedBracketRead:
+  Description: "Avoid reading `obj[key]` more than once with the same receiver and key in a method body — assign once and reuse."
+  Enabled: true
+
+DevDoc/Style/MinimizeVariableScope:
+  Description: "Assign a variable inside the `if` condition that guards it, to keep its scope local to the branch."
   Enabled: true
 
 DevDoc/Style/AvoidHeadResponse:
-  Description: 'Avoid `head()` with error statuses; delegate error handling to Rails exceptions or model validations.'
+  Description: "Avoid `head()` with error statuses; delegate error handling to Rails exceptions or model validations."
   Enabled: true
   Include:
-    - 'app/controllers/**/*.rb'
+    - "app/controllers/**/*.rb"
   FlaggedStatuses:
     - not_found
     - unprocessable_entity
@@ -122,34 +191,41 @@ DevDoc/Style/AvoidHeadResponse:
     - conflict
     - gone
     - method_not_allowed
-    - '404'
-    - '422'
-    - '403'
-    - '401'
-    - '400'
-    - '409'
-    - '410'
-    - '405'
+    - "404"
+    - "422"
+    - "403"
+    - "401"
+    - "400"
+    - "409"
+    - "410"
+    - "405"
+
+DevDoc/Migration/AvoidConditionalSchemaChanges:
+  Description: "Avoid conditional schema helpers (`add_column_if_not_exists`, `column_exists?`, etc.) in migrations."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Migration/RequirePrimaryKey:
-  Description: 'Every `create_table` must have a primary key. Avoid `id: false`.'
+  Description: "Every `create_table` must have a primary key. Avoid `id: false`."
   Enabled: true
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Migration/NoCreateJoinTable:
-  Description: 'Avoid `create_join_table` — define an explicit join model with `has_many :through` instead.'
+  Description: "Avoid `create_join_table` — define an explicit join model with `has_many :through` instead."
   Enabled: true
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 # This cop is heuristic: it matches column names whose last segment is a known
 # monetary word. Enable it in your project's .rubocop.yml and extend MonetaryNames
 # if your domain uses different names. Disabled by default to avoid false positives.
 DevDoc/Migration/AmountColumnInCents:
-  Description: 'Monetary columns must be stored as integer cents with an `_in_cents` suffix.'
+  Description: "Monetary columns must be stored as integer cents with an `_in_cents` suffix."
   Enabled: false
   MonetaryNames:
     - amount
@@ -162,36 +238,134 @@ DevDoc/Migration/AmountColumnInCents:
     - discount
     - tax
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 DevDoc/Rails/AvoidRailsCallbacks:
-  Description: 'Avoid Rails callback DSL (`after_create`, `before_save`, etc.) — use explicit methods instead.'
+  Description: "Avoid Rails callback DSL (`after_create`, `before_save`, etc.) — use explicit methods instead."
   Enabled: true
   Include:
-    - 'app/models/**/*.rb'
+    - "app/models/**/*.rb"
 
 DevDoc/Rails/ApplicationRecordTransaction:
-  Description: 'Use `ApplicationRecord.transaction` instead of `SomeModel.transaction` outside model files.'
+  Description: "Use `ApplicationRecord.transaction` instead of `SomeModel.transaction` outside model files."
   Enabled: true
   Exclude:
-    - 'app/models/**/*.rb'
+    - "app/models/**/*.rb"
 
 DevDoc/Style/AvoidOptionsHash:
-  Description: 'Use keyword arguments instead of `**options` — typos raise `ArgumentError`; options hashes swallow them silently.'
+  Description: "Use keyword arguments instead of `**options` — typos raise `ArgumentError`; options hashes swallow them silently."
   Enabled: true
 
 DevDoc/Style/StringSymbolComparison:
-  Description: 'Comparing a known-string source (params, request.headers, ENV) to a symbol literal is always false.'
+  Description: "Comparing a known-string source (params, request.headers, ENV) to a symbol literal is always false."
+  Enabled: true
+
+DevDoc/Test/ResponseAssertEqual:
+  Description: "Controller tests that assert on `response.body` should also snapshot the full response with `response_assert_equal`."
+  # Enabled by default. A project adopting the gem with an existing backlog will
+  # see offenses immediately — fix them (preferred) or inline-`disable` the few
+  # that genuinely can't snapshot (non-JSON / non-deterministic responses).
   Enabled: true
+  Include:
+    - "test/controllers/**/*_test.rb"
 
 Rails/CreateTableWithTimestamps:
   Enabled: true
   Include:
-    - 'db/migrate/*.rb'
-    - 'db/migrate/**/*.rb'
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
 
 Rails/SkipsModelValidations:
   Enabled: true
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
+
+# Upstream cop stays off — its scalar-form autocorrect produces false positives
+# on optional query params (e.g. `params[:status]&.to_sym || :draft`).
+# Our narrower replacement below flags only the hash-form rewrite.
+Rails/StrongParametersExpect:
+  Enabled: false
+
+# Narrower replacement for Rails/StrongParametersExpect — flags only the
+# hash-form rewrite (`params.require(:foo).permit(...)` → `params.expect(foo: [...])`).
+# Does not flag scalar `params[:foo]` in any context.
+DevDoc/Rails/StrongParametersExpect:
+  Description: "Use `params.expect(foo: [...])` instead of `params.require(:foo).permit(...)`."
+  Enabled: true
+  Include:
+    - "app/controllers/**/*.rb"
+
+# `save!` / `update!` raise on persistence failure, which is what
+# we want in jobs/services/rake tasks — silent `false` returns
+# hide bugs. Excluded for controllers, which lean on `save`
+# returning false so `json_model_response` (and similar) can
+# render the form with errors instead of crashing to 500.
+Rails/SaveBang:
+  Enabled: true
+  Exclude:
+    - "app/controllers/**/*"
+
+Style/MissingElse:
+  Enabled: true
+  EnforcedStyle: case
+
+# Core default is `Max: 2`, which permits `a&.b&.c`. Tightened to `Max: 1`:
+# in `a&.b&.c`, the second `&.` is ambiguous — the reader can't tell whether
+# it's there because `b.c` can genuinely be nil on its own, or merely because
+# the first `&.` already short-circuits the chain when `a` is nil. Splitting
+# the chain (`if (b = a&.b); b.c; end`) makes each nullable source explicit.
+# See best_practices/backend/en/01a_defensive_programming.md #4.
+Style/SafeNavigationChainLength:
+  Enabled: true
+  Max: 1
+
+# `has_X?` reads more naturally than the cop's preferred `X?` in many cases —
+# `has_active_subscription?` vs `active_subscription?`, `has_assignee?(member)`
+# vs `assignee?(member)`. Disabled cross-project so individual `.rubocop.yml`
+# files don't have to repeat the same decision.
+DevDoc/Test/AvoidGlibTravelFreeze:
+  Description: "Avoid `glib_travel_freeze` in test files — use `glib_travel` instead."
+  Enabled: true
+  Include:
+    - "test/**/*.rb"
+    - "spec/**/*.rb"
+
+DevDoc/Test/AvoidUnitTest:
+  Description: "Prefer controller tests; unit tests (`< ActiveSupport::TestCase`) are a rare, justified exception."
+  Enabled: true
+  Include:
+    - "test/**/*.rb"
+    - "spec/**/*.rb"
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+# Enforces that every `has_many` / `has_one` declares a `dependent:` option.
+# Aligns with best_practices/backend/en/03_model.md #1 which prescribes
+# `dependent: :restrict_with_exception` as the default.
+Rails/HasManyOrHasOneDependent:
+  Enabled: true
+
+DevDoc/Auth/LoadResourceCurrentUserGuard:
+  Description: "Require a `return unless current_user` (or `assert_current_user_present`) guard before using `current_user` inside `glib_load_resource`, and forbid `current_user&.`."
+  Enabled: true
+  # LoadResourceMethodNames: list of method names where the guard rule applies.
+  # Extend if your project uses a different lifecycle hook name.
+  LoadResourceMethodNames:
+    - glib_load_resource
+  # CurrentUserAssertionMethodNames: calls that raise when current_user is nil
+  # (e.g. glib's assert_current_user_present). A call to one before the first
+  # current_user use satisfies the guard. Add custom assertion helpers here.
+  CurrentUserAssertionMethodNames:
+    - assert_current_user_present
+
+DevDoc/Auth/CurrentUserBranching:
+  Description: "Avoid branching on `current_user` / `user_signed_in?` in page-specific code. Use shared layouts or an inline disable with a reason for genuinely dual-state pages."
+  Enabled: true
+  Exclude:
+    - "app/policies/**/*.rb"
+    - "app/helpers/**/*.rb"
+    - "app/controllers/concerns/**/*.rb"
+    - "app/views/layouts/**/*"
+    - "app/controllers/application_controller.rb"

data/lib/dev_doc/test/best_practice_lints.rb

@@ -0,0 +1,31 @@
+require_relative 'lints/cron_schedule'
+require_relative 'lints/duplicate_snapshot'
+require_relative 'lints/no_file_excludes'
+
+module DevDoc
+  module Test
+    # Aggregator that pulls in every dev-doc best-practice lint as a set of
+    # Minitest `test_*` methods. Include this in a single test class in
+    # each project; new lints added here automatically apply to all
+    # consuming projects on the next `bundle update`.
+    #
+    # Per-project integration (one file, never needs editing):
+    #
+    #   # test/linters/best_practice_lints_test.rb
+    #   require 'dev_doc/test/best_practice_lints'
+    #
+    #   class BestPracticeLintsTest < ActiveSupport::TestCase
+    #     include DevDoc::Test::BestPracticeLints
+    #   end
+    #
+    # To opt out of a specific lint in a project, redefine the offending
+    # `test_*` method in that test class as a `skip 'reason'`.
+    module BestPracticeLints
+      def self.included(base)
+        base.include Lints::CronSchedule
+        base.include Lints::DuplicateSnapshot
+        base.include Lints::NoFileExcludes
+      end
+    end
+  end
+end