rubocop-dev_doc 0.20.1 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 41a73fb70d0abd2db9c0e14bbc073859f05cadec33494d35c3ef52b60007d8fc
4
- data.tar.gz: 5608f88d60896a43884829039c94667bcd4001a6d7802c05825478e19d007d42
3
+ metadata.gz: 1059b7ea3042b2063f1720a795b9e2c21f9a03c2f30294e2b1947c27f226df6c
4
+ data.tar.gz: 1f6b849f309dc6a9b054db65309069ba80d0d78e31f7a86e1e6640149d333955
5
5
  SHA512:
6
- metadata.gz: 255fbbcb74f4d773bda61f7e797e4b55c2d58f59fe1ed9afb8990a99a96a0b103b923732616db698ed74959bd5e1a9dad5345f53ced1f9f2de14d6198b309abc
7
- data.tar.gz: '060297a07336e974aa49f206b129892aa0f7c579709dd0d0a2f45130341e98e5606215e01c0aeb6f37b66b378b681902ffe3a295f8dd076a53593c9671dde062'
6
+ metadata.gz: ed1f6fdbd41240058bc10efda89b902f470e5f10fb774d95f7856f455fcf37a4c8b126996fbb3210289376d011407370e6e29d17f0b91a7788689a9d3c69b5d9
7
+ data.tar.gz: dfdacfbd3fbe5234292fd9e526c153f3c0284d2cf091ea7046201d0e9b0f7af63b63c261ebbd4810858a95280e908edcf680b595621afc4f3615943fc5de1c8f
data/config/default.yml CHANGED
@@ -465,6 +465,21 @@ DevDoc/Migration/RedundantReferenceIndex:
465
465
  - "db/migrate/*.rb"
466
466
  - "db/migrate/**/*.rb"
467
467
 
468
+ # No autocorrect: the fix is a rewrite onto the app model, or removing the
469
+ # backfill once it has run everywhere (best_practices 02_migration.md item 3) —
470
+ # neither is mechanical. Backs the AvoidRawSql "Migration backfills are NOT an
471
+ # exception" ruling: a migration-local model bypasses validations without
472
+ # writing SQL, so neither AvoidRawSql nor AvoidBypassingValidation sees it.
473
+ # Calibrated 2026-11-18 over four consumers' db/migrate: 12 offenses, 0
474
+ # unexpected — 2 files in linted ranges (both the flagged workaround shape),
475
+ # the other 10 in frozen or wholesale-excluded ranges.
476
+ DevDoc/Migration/AvoidLocalModel:
477
+ Description: "Never define an ActiveRecord model inside a migration — use the app model with `save!`."
478
+ Enabled: true
479
+ Include:
480
+ - "db/migrate/*.rb"
481
+ - "db/migrate/**/*.rb"
482
+
468
483
  # This cop is heuristic: it matches column names whose last segment is a known
469
484
  # monetary word. Enable it in your project's .rubocop.yml and extend MonetaryNames
470
485
  # if your domain uses different names. Disabled by default to avoid false positives.
@@ -3,6 +3,7 @@ require_relative 'lints/duplicate_snapshot'
3
3
  require_relative 'lints/enqueue_disable_naming'
4
4
  require_relative 'lints/external_io_boundary'
5
5
  require_relative 'lints/no_file_excludes'
6
+ require_relative 'lints/scheduled_jobs'
6
7
 
7
8
  module DevDoc
8
9
  module Test
@@ -29,6 +30,7 @@ module DevDoc
29
30
  base.include Lints::EnqueueDisableNaming
30
31
  base.include Lints::ExternalIoBoundary
31
32
  base.include Lints::NoFileExcludes
33
+ base.include Lints::ScheduledJobs
32
34
  end
33
35
  end
34
36
  end
@@ -0,0 +1,146 @@
1
+ module DevDoc
2
+ module Test
3
+ module Lints
4
+ # Runs glib-web's whole-class scheduled-job validation in the app's
5
+ # test suite, and refuses an app that keeps both a YAML schedule file
6
+ # and Ruby-declared Glib::ScheduledJob subclasses.
7
+ #
8
+ # ## Rationale
9
+ #
10
+ # Glib::ScheduledJob checks its own declarations (interval shapes,
11
+ # lock settings, cron-name clashes) in `validate_all!`, but nothing
12
+ # calls it outside Sidekiq's boot: a bad job class then sits silent
13
+ # until the next deploy. `test_scheduled_jobs_valid` runs the same
14
+ # check in CI, where it fails before the code reaches production.
15
+ #
16
+ # `test_single_schedule_source` guards the mechanical trap in
17
+ # sidekiq-cron's `load_from_hash!`: it first runs `destroy_removed_jobs`,
18
+ # which deletes every previously-registered `source == 'schedule'` job
19
+ # not present in the new hash. The YAML loader and the Ruby loader both
20
+ # use that source, so whichever runs second silently wipes the other's
21
+ # entries -- the app loses jobs at boot with no error anywhere. An app
22
+ # must pick one home for its schedule: entries on the job classes
23
+ # (`poll every:` / `run_once per:`) with the YAML file deleted, or stay
24
+ # on the YAML file with no Glib::ScheduledJob subclasses.
25
+ #
26
+ # ## Usage
27
+ #
28
+ # Include through the aggregator (DevDoc::Test::BestPracticeLints) in a
29
+ # single test class per project; apps without glib-web (or with no
30
+ # scheduled jobs yet) skip with their reason.
31
+ #
32
+ # See best_practices/backend/en/08_job.md#cron-schedule-frequency.
33
+ module ScheduledJobs
34
+ def test_scheduled_jobs_valid
35
+ base = scheduled_jobs_base
36
+ skip 'Glib::ScheduledJob is not defined -- glib-web missing or too old for this lint' unless base
37
+
38
+ scheduled_jobs_eager_load!
39
+ subclasses = scheduled_jobs_subclasses(base)
40
+ skip 'no Glib::ScheduledJob subclasses in this app' if subclasses.empty?
41
+
42
+ offenses = base.validate_all!
43
+ assert offenses.empty?, scheduled_jobs_valid_message(offenses)
44
+ end
45
+
46
+ def test_single_schedule_source
47
+ base = scheduled_jobs_base
48
+ skip 'Glib::ScheduledJob is not defined -- glib-web missing or too old for this lint' unless base
49
+
50
+ scheduled_jobs_eager_load!
51
+ subclasses = scheduled_jobs_subclasses(base)
52
+ yaml = scheduled_jobs_yaml_paths.find(&:exist?)
53
+
54
+ return unless yaml && !subclasses.empty?
55
+
56
+ flunk single_schedule_source_message(yaml)
57
+ end
58
+
59
+ private
60
+
61
+ # Overridable in specs: a stand-in class responding to descendants
62
+ # and validate_all!.
63
+ def scheduled_jobs_base
64
+ defined?(::Glib::ScheduledJob) ? ::Glib::ScheduledJob : nil
65
+ end
66
+
67
+ # Eager-load app/jobs so every job class exists before descendants is
68
+ # read (mirrors Glib::ScheduledJobs::Loader's own eager load).
69
+ def scheduled_jobs_eager_load!
70
+ return unless defined?(Rails) && Rails.respond_to?(:autoloaders)
71
+
72
+ main = Rails.autoloaders.main
73
+ return unless main.respond_to?(:eager_load_dir)
74
+
75
+ dir = Rails.root.join('app/jobs')
76
+ main.eager_load_dir(dir) if dir.exist?
77
+ end
78
+
79
+ # The classes the loader would register: concrete_subclasses (live,
80
+ # non-abstract) when the base provides it, so the lint counts exactly
81
+ # what boots -- an app holding only an abstract base beside a YAML
82
+ # file passes here exactly as it skips registration there. The plain
83
+ # descendants fallback covers glib-web versions before the method
84
+ # existed.
85
+ def scheduled_jobs_subclasses(base)
86
+ return base.concrete_subclasses if base.respond_to?(:concrete_subclasses)
87
+
88
+ base.respond_to?(:descendants) ? base.descendants : []
89
+ end
90
+
91
+ # The YAML schedule locations sidekiq-cron's own loader and the house
92
+ # convention both use -- the same candidate list
93
+ # Glib::ScheduledJobs::Loader refuses, so what fails at Sidekiq boot
94
+ # fails here too. Overridable in specs to point at tmp files.
95
+ def scheduled_jobs_yaml_paths
96
+ return [] unless defined?(Rails)
97
+
98
+ [
99
+ Rails.root.join('config', 'schedules.yml'),
100
+ Rails.root.join('config', 'schedule.yml')
101
+ ].concat(configured_schedule_candidates).uniq
102
+ end
103
+
104
+ # Sidekiq::Cron's configured schedule file and its .yml/.yaml siblings
105
+ # (the gem's own loader tries both spellings). The gem is absent from
106
+ # processes that never load it (dev-doc's own specs); there is then
107
+ # nothing configured to check. An absolute configured path never
108
+ # touches Rails.root, which keeps the derivation testable without a
109
+ # Rails boot.
110
+ def configured_schedule_candidates
111
+ return [] unless defined?(::Sidekiq::Cron)
112
+
113
+ configured = Sidekiq::Cron.configuration.cron_schedule_file.to_s
114
+ return [] if configured.empty?
115
+
116
+ base = Pathname.new(configured)
117
+ base = Rails.root.join(base) unless base.absolute?
118
+ candidates = [base.sub_ext('.yml'), base.sub_ext('.yaml')]
119
+ candidates.unshift(base) if base.to_s.end_with?('.yml', '.yaml')
120
+ # base already IS one of the two siblings when it spells .yml/.yaml
121
+ candidates.uniq
122
+ end
123
+
124
+ def scheduled_jobs_valid_message(offenses)
125
+ "Glib::ScheduledJob classes failed validation:\n" \
126
+ "#{offenses.map { |offense| " #{offense}" }.join("\n")}\n\n" \
127
+ 'Each concrete subclass must declare exactly one schedule (poll every: or run_once per:), ' \
128
+ 'keep the inherited lock defaults or change them through scheduled_lock (never a raw unique ' \
129
+ 'call -- it drops on_conflict: log), keep lock_ttl >= 2x the poll, set runtime_lock_ttl, ' \
130
+ 'keep the poll and runtime_lock_ttl under STALENESS_THRESHOLD, and use a unique cron name. ' \
131
+ "Fix the declarations in app/jobs. " \
132
+ 'See https://github.com/hgani/dev-doc/blob/main/best_practices/backend/en/08_job.md#cron-schedule-frequency'
133
+ end
134
+
135
+ def single_schedule_source_message(yaml)
136
+ "#{yaml} exists alongside Glib::ScheduledJob subclasses. sidekiq-cron's load_from_hash! runs " \
137
+ "destroy_removed_jobs, deleting every source == 'schedule' job not in the new hash, so one " \
138
+ 'loader wipes the other\'s entries at boot and the app silently loses jobs. Fix: move the YAML ' \
139
+ 'entries onto the job classes (poll every: / run_once per:) and delete the file, or remove the ' \
140
+ 'Glib::ScheduledJob subclasses and stay on the YAML schedule. ' \
141
+ 'See https://github.com/hgani/dev-doc/blob/main/best_practices/backend/en/08_job.md#cron-schedule-frequency'
142
+ end
143
+ end
144
+ end
145
+ end
146
+ end
@@ -0,0 +1,115 @@
1
+ module RuboCop
2
+ module Cop
3
+ module DevDoc
4
+ module Migration
5
+ # Never define an ActiveRecord model inside a migration file: a
6
+ # local model is the raw-SQL bypass without the SQL.
7
+ #
8
+ # ## Rationale
9
+ # The house ruling on migration backfills
10
+ # (`DevDoc/Rails/AvoidRawSql`, "Migration backfills are NOT an
11
+ # exception") rejects the "models can drift, so raw SQL is safer"
12
+ # argument: backfills go through the app model with `save!`, so
13
+ # validations run and callbacks fire. A model defined inside the
14
+ # migration — `Class.new(ActiveRecord::Base) { ... }` or a nested
15
+ # `class` — carries none of the app's validations or callbacks, so
16
+ # a `save!` on it bypasses validation exactly as raw SQL does,
17
+ # while tripping neither `DevDoc/Rails/AvoidRawSql` (no SQL
18
+ # string) nor `DevDoc/Rails/AvoidBypassingValidation` (`save!` is
19
+ # the sanctioned call). An ActiveRecord model defined in a
20
+ # migration file has essentially one purpose — querying or writing
21
+ # data around the app model — and that purpose is the bypass.
22
+ #
23
+ # ❌ A local class — `save!` on it skips the app's validations
24
+ # class MigrationUser < ActiveRecord::Base
25
+ # self.table_name = 'users'
26
+ # end
27
+ # MigrationUser.where(role: nil).find_each { |u| u.update!(role: 0) }
28
+ #
29
+ # ❌ An anonymous model — same bypass, no class name
30
+ # table_model = Class.new(ActiveRecord::Base) do
31
+ # self.table_name = 'users'
32
+ # end
33
+ #
34
+ # ✔️ The app model — validations run, callbacks fire
35
+ # User.where(role: nil).find_each do |user|
36
+ # user.role = 0
37
+ # user.save!
38
+ # end
39
+ #
40
+ # ## Exception
41
+ # None in ordinary code. The legitimate pressure behind local
42
+ # models is an old migration whose app model was later deleted or
43
+ # renamed, which fails on replay. The answer is to remove the
44
+ # backfill, not to rewrite it: once the migration has run in every
45
+ # environment that holds data, the backfill has nothing left to do
46
+ # (a replay runs before any data exists). Remove it, leaving a
47
+ # one-line comment saying why and when — never comment it out.
48
+ # `best_practices/backend/en/02_migration.md` item 3 carries the
49
+ # removal rule. The inline disable stays available, as for every
50
+ # DevDoc cop, but has no sanctioned case here.
51
+ #
52
+ # NOTE: This cop does not see a model built from non-literal
53
+ # construction — `Class.new(base)` with a non-constant base, a
54
+ # non-constant `Class` receiver (`klass = Class; klass.new(...)`)
55
+ # — or one subclassing a custom abstract class; review catches
56
+ # those.
57
+ #
58
+ # NOTE: This cop complements `DevDoc/Rails/AvoidRawSql` and
59
+ # `DevDoc/Rails/AvoidBypassingValidation`: those flag the raw or
60
+ # validation-bypassing write; this one flags the model definition
61
+ # the write would bypass them through.
62
+ #
63
+ # @example
64
+ # # bad
65
+ # class MigrationUser < ActiveRecord::Base; end
66
+ # table_model = Class.new(ApplicationRecord) { self.table_name = 'users' }
67
+ #
68
+ # # good — the app model, with its validations and callbacks
69
+ # User.where(role: nil).find_each { |u| u.save! }
70
+ class AvoidLocalModel < Base
71
+ MSG = 'Use the app model with `save!` here, not a model defined in the ' \
72
+ 'migration: a local model skips the app\'s validations and callbacks.'.freeze
73
+
74
+ RESTRICT_ON_SEND = %i[new].freeze
75
+
76
+ AR_BASES = %w[ActiveRecord::Base ApplicationRecord].freeze
77
+
78
+ def on_class(node)
79
+ superclass = node.parent_class
80
+ return unless superclass&.const_type?
81
+ return unless active_record_base?(superclass)
82
+
83
+ add_offense(superclass)
84
+ end
85
+
86
+ def on_send(node)
87
+ return unless class_new_with_ar_base?(node)
88
+
89
+ add_offense(node)
90
+ end
91
+
92
+ private
93
+
94
+ # `const_name` omits a leading cbase, so `::ActiveRecord::Base`
95
+ # and `ActiveRecord::Base` share one spelling and one comparison
96
+ # covers both. `ApplicationRecord` is included: subclassing the
97
+ # app's own base class is the same bypass with the app's
98
+ # connection.
99
+ def active_record_base?(const_node)
100
+ AR_BASES.include?(const_node.const_name)
101
+ end
102
+
103
+ def class_new_with_ar_base?(node)
104
+ receiver = node.receiver
105
+ return false unless receiver&.const_type?
106
+ return false unless receiver.const_name == 'Class'
107
+
108
+ argument = node.first_argument
109
+ argument&.const_type? && active_record_base?(argument)
110
+ end
111
+ end
112
+ end
113
+ end
114
+ end
115
+ end
@@ -109,6 +109,14 @@ module RuboCop
109
109
  # rather than bypassing validation — that's the signal, not an
110
110
  # obstacle.
111
111
  #
112
+ # A migration-local model (`Class.new(ActiveRecord::Base) { ... }`
113
+ # or a nested `class` inheriting from it) is the same bypass
114
+ # without the SQL: it carries none of the app's validations or
115
+ # callbacks, so a `save!` on it bypasses validation while tripping
116
+ # neither this cop nor `DevDoc/Rails/AvoidBypassingValidation`.
117
+ # `DevDoc/Migration/AvoidLocalModel` flags the model definition
118
+ # itself.
119
+ #
112
120
  # NOTE: Parameterized fragments are detected by the presence of
113
121
  # a `?` or `:name` placeholder plus at least one additional
114
122
  # argument. A `?` appearing in literal SQL that isn't a
@@ -1,5 +1,5 @@
1
1
  module RuboCop
2
2
  module DevDoc
3
- VERSION = "0.20.1".freeze
3
+ VERSION = "0.21.0".freeze
4
4
  end
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rubocop-dev_doc
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.20.1
4
+ version: 0.21.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - dev-doc contributors
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-11-18 00:00:00.000000000 Z
11
+ date: 2026-11-19 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: activesupport
@@ -103,6 +103,7 @@ files:
103
103
  - lib/dev_doc/test/lints/external_io_boundary.rb
104
104
  - lib/dev_doc/test/lints/http_driven_controller_tests.rb
105
105
  - lib/dev_doc/test/lints/no_file_excludes.rb
106
+ - lib/dev_doc/test/lints/scheduled_jobs.rb
106
107
  - lib/dev_doc/test/pseudo_i18n_crawler.rb
107
108
  - lib/rubocop-dev_doc.rb
108
109
  - lib/rubocop/cop/dev_doc/auth/adjacent_justification.rb
@@ -127,6 +128,7 @@ files:
127
128
  - lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb
128
129
  - lib/rubocop/cop/dev_doc/migration/avoid_conditional_schema_changes.rb
129
130
  - lib/rubocop/cop/dev_doc/migration/avoid_json_column.rb
131
+ - lib/rubocop/cop/dev_doc/migration/avoid_local_model.rb
130
132
  - lib/rubocop/cop/dev_doc/migration/avoid_non_null.rb
131
133
  - lib/rubocop/cop/dev_doc/migration/avoid_vague_column_names.rb
132
134
  - lib/rubocop/cop/dev_doc/migration/boolean_column_not_null.rb