rubocop-dev_doc 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32fcdd022e9dde952826050d447d83e9fa7f9bf1cfaf7caaaddda3309e392a3b
-  data.tar.gz: e6775d4b37a1d763966c25eb3b2bf7926026b2ba2fdeae6d11fc05ae9d2ba46e
+  metadata.gz: cd15873d6ee53104760162aa0e5cced9dd69ef1297a70a014dd5643b9404703c
+  data.tar.gz: 25d0fa51436912d008625752269ff09ef93e78c14d6d1a941295c6afa47795b4
 SHA512:
-  metadata.gz: fb0572fc498d052e2f49d45490c37ddfcfa349d5a4e17b199159537b713cb5206ee828ffa96d5466c5e386e8da7713a22b5d3e51eca9daf228041be278fbe014
-  data.tar.gz: a96d7bcdb8c34f3b0ab557a8bee46ef6ce91028174728cf06efa7df2943dafe7b67a47b9dff813260f2c824c6d7b1094bb6bc69c15bcb63fbf1c2f0bfab62333
+  metadata.gz: 516d5742aa468568e3884d779649164761f982391be0c5f7e5df474d64a933cf71148fe1fddb433c5cf1cd577debd7aadcb16bf22893963d721a3661a1f0fff0
+  data.tar.gz: 69a643cf2335d6c7bb365a4a2f8513e9a66d09a6cddb2bec5e44df861ebcb906de51d17fbbd1b591388c651c2f1cb662de5e5a887df7f11db3c9885e9d6ae597

data/config/default.yml

@@ -1,81 +1,366 @@
 # Default configuration for rubocop-dev_doc cops.
-# Cops are enabled by default; disable them in your project's .rubocop.yml if needed.
+# Cops are disabled by default; enable them in your project's .rubocop.yml.
+
+# 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"
+
+DevDoc/Rails:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  DocumentationExtension: ".md"
+
+DevDoc/Route:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  DocumentationExtension: ".md"
+
+DevDoc/Style:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  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.'
-  Enabled: true
+  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/AvoidUpdateColumn:
-  Description: 'Avoid `update_column`/`update_all`/`update_columns`; they bypass validations and callbacks.'
+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'
+    - "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.)."
+  Enabled: false
+  Exclude:
+    - "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!
+    - send_reset_password_instructions
+    - send_confirmation_instructions
+    - 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"
+
+DevDoc/Rails/EnumMustBeSymbolized:
+  Description: "Pair every `enum :foo` with `enum_symbolize :foo` so the reader returns a symbol."
+  Enabled: true
+  Include:
+    - "app/models/**/*.rb"
+
+DevDoc/Rails/EnumColumnNotNull:
+  Description: "Enum columns must be backed by a `null: false` database column."
   Enabled: true
   Include:
-    - 'app/models/**/*.rb'
+    - "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()` responses; 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
+    - forbidden
+    - unauthorized
+    - bad_request
+    - conflict
+    - gone
+    - method_not_allowed
+    - "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`."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+DevDoc/Migration/NoCreateJoinTable:
+  Description: "Avoid `create_join_table` — define an explicit join model with `has_many :through` instead."
+  Enabled: true
+  Include:
+    - "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."
+  Enabled: false
+  MonetaryNames:
+    - amount
+    - price
+    - balance
+    - cost
+    - fee
+    - total
+    - subtotal
+    - discount
+    - tax
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+DevDoc/Rails/AvoidRailsCallbacks:
+  Description: "Avoid Rails callback DSL (`after_create`, `before_save`, etc.) — use explicit methods instead."
+  Enabled: true
+  Include:
+    - "app/models/**/*.rb"
+
+DevDoc/Rails/ApplicationRecordTransaction:
+  Description: "Use `ApplicationRecord.transaction` instead of `SomeModel.transaction` outside model files."
+  Enabled: true
+  Exclude:
+    - "app/models/**/*.rb"
+
+DevDoc/Style/AvoidOptionsHash:
+  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."
+  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"
+
+Rails/SkipsModelValidations:
+  Enabled: true
+  Exclude:
+    - "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` 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
+
+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