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 +4 -4
- data/config/default.yml +15 -0
- data/lib/dev_doc/test/best_practice_lints.rb +2 -0
- data/lib/dev_doc/test/lints/scheduled_jobs.rb +146 -0
- data/lib/rubocop/cop/dev_doc/migration/avoid_local_model.rb +115 -0
- data/lib/rubocop/cop/dev_doc/rails/avoid_raw_sql.rb +8 -0
- data/lib/rubocop/dev_doc/version.rb +1 -1
- metadata +4 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1059b7ea3042b2063f1720a795b9e2c21f9a03c2f30294e2b1947c27f226df6c
|
|
4
|
+
data.tar.gz: 1f6b849f309dc6a9b054db65309069ba80d0d78e31f7a86e1e6640149d333955
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
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.
|
|
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-
|
|
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
|