rubyzen-lint 0.3.0 → 0.4.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/CHANGELOG.md +16 -0
- data/README.md +27 -1
- data/lib/rubyzen/assertions/assert_zen_empty.rb +8 -3
- data/lib/rubyzen/assertions/assert_zen_false.rb +8 -3
- data/lib/rubyzen/assertions/assert_zen_true.rb +8 -3
- data/lib/rubyzen/collections/classes_collection.rb +8 -0
- data/lib/rubyzen/expectation_helpers.rb +30 -3
- data/lib/rubyzen/matchers/zen_empty_matcher.rb +13 -4
- data/lib/rubyzen/matchers/zen_false_matcher.rb +13 -4
- data/lib/rubyzen/matchers/zen_true_matcher.rb +13 -4
- data/lib/rubyzen/rule.rb +171 -0
- data/lib/rubyzen/version.rb +1 -1
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 40b1ca0286479fe9a2beb115960c65c9540ae2d9c4b4b3553e7ead435e2bbb88
|
|
4
|
+
data.tar.gz: 8d8e612170759162ea21501d31cdb9138327ffad70cd8fef493aaa11272950dc
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 3f874b3d62f96ddf06bc9b2471fa4ca55e07abf402198dafbdef25b89a8519706e6a478ed18c581ca27c11615d32408d72b1c3ef1a7baf551614cffb20a20cae
|
|
7
|
+
data.tar.gz: dd62e8468c935d7541ac8925255533ce10e95b8f3bc4d56c5378fce6b706182c58ad7332c8bbef7ed8bf96c76e9ce3b3291763487511e61998248cd5cc985e66
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.4.0]
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **`Rubyzen::Rule`** — a structured explanation of a lint rule (`description`, plus optional
|
|
8
|
+
`rationale`, `fix_hint`, `bad_example`, `good_example`), defined with a block DSL
|
|
9
|
+
(`Rubyzen::Rule.new do description '...' end`) or keywords. Pass it as `rule:` to any RSpec
|
|
10
|
+
matcher (`zen_empty(rule:)`, `zen_true(rule:) { }`, `zen_false(rule:) { }`) or Minitest assertion
|
|
11
|
+
(`assert_zen_empty(collection, rule:)`, …). The failure message then shows `RULE:`, `WHY:`,
|
|
12
|
+
`HOW TO FIX:`, `BAD:` and `GOOD:` sections ahead of the violations, giving developers and
|
|
13
|
+
AI agents the context needed to fix a violation.
|
|
14
|
+
- **`ClassesCollection#constants`** — the constant references and assignments across every class,
|
|
15
|
+
as a `ConstantsCollection` (e.g. `repos.constants.with_name('Singleton')`).
|
|
16
|
+
|
|
17
|
+
All additions are backward-compatible: plain string messages still work and take precedence over `rule:`.
|
|
18
|
+
|
|
3
19
|
## [0.3.0]
|
|
4
20
|
|
|
5
21
|
### Added
|
data/README.md
CHANGED
|
@@ -98,7 +98,33 @@ Rubyzen provides three checks for your architectural lint rules:
|
|
|
98
98
|
| `zen_true { \|item\| }` | `assert_zen_true(collection) { \|item\| }` | the block returns true for every element |
|
|
99
99
|
| `zen_false { \|item\| }` | `assert_zen_false(collection) { \|item\| }` | the block returns false for every element |
|
|
100
100
|
|
|
101
|
-
All three accept an `allowlist:` of exceptions that are permanently exempt from the rule, a `baseline:` of known existing violations (technical debt) to fix over time, and a
|
|
101
|
+
All three accept an `allowlist:` of exceptions that are permanently exempt from the rule, a `baseline:` of known existing violations (technical debt) to fix over time, and a `rule:` that contains the description of the rule, why it is enforced, and how to fix the violations.
|
|
102
|
+
|
|
103
|
+
## Adding context to failure messages
|
|
104
|
+
|
|
105
|
+
Instead of a plain string in the failure message of a lint rule, you can pass a `Rubyzen::Rule`. The failure then tells the reader what the rule requires, why it exists, and how to fix the violation. This helps AI agents understand and fix the violations more reliably:
|
|
106
|
+
|
|
107
|
+
```ruby
|
|
108
|
+
let(:rule) do
|
|
109
|
+
Rubyzen::Rule.new do
|
|
110
|
+
description 'Controllers do not contain if statements.'
|
|
111
|
+
rationale <<~TEXT
|
|
112
|
+
Controllers only orchestrate; business logic belongs in a Service.
|
|
113
|
+
TEXT
|
|
114
|
+
fix_hint 'Move the condition into a Service and call it from the controller.'
|
|
115
|
+
bad_example <<~RUBY
|
|
116
|
+
return error(:forbidden) if profile.banned?
|
|
117
|
+
RUBY
|
|
118
|
+
good_example <<~RUBY
|
|
119
|
+
Services::Profiles::Update.new.call(profile:)
|
|
120
|
+
RUBY
|
|
121
|
+
end
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
it 'controllers have no if statements' do
|
|
125
|
+
expect(controllers.all_methods.if_statements).to zen_empty(rule:, baseline: ['LegacyController'])
|
|
126
|
+
end
|
|
127
|
+
```
|
|
102
128
|
|
|
103
129
|
## Run your lint rules
|
|
104
130
|
|
|
@@ -7,7 +7,9 @@ module Rubyzen
|
|
|
7
7
|
# pattern (e.g., no controllers call +.where+ directly).
|
|
8
8
|
#
|
|
9
9
|
# @param collection [Enumerable] a Rubyzen collection of declarations
|
|
10
|
-
# @param message [String, nil] optional custom failure message
|
|
10
|
+
# @param message [String, nil] optional custom failure message (takes precedence over +rule:+)
|
|
11
|
+
# @param rule [Rubyzen::Rule, nil] rule whose description, rationale, fix hint and examples
|
|
12
|
+
# are shown in the failure message
|
|
11
13
|
# @param allowlist [Array<String>, nil] items to permanently ignore
|
|
12
14
|
# @param baseline [Array<String>, nil] known violations for gradual adoption
|
|
13
15
|
# @return [true] when the assertion passes
|
|
@@ -18,9 +20,12 @@ module Rubyzen
|
|
|
18
20
|
#
|
|
19
21
|
# @example With a baseline for gradual adoption
|
|
20
22
|
# assert_zen_empty(violations, baseline: ['LegacyController'])
|
|
21
|
-
|
|
23
|
+
#
|
|
24
|
+
# @example With a rule that explains the failure (see {Rubyzen::Rule})
|
|
25
|
+
# assert_zen_empty(controllers.all_methods.if_statements, rule: NO_IFS_IN_CONTROLLERS)
|
|
26
|
+
def assert_zen_empty(collection, message: nil, rule: nil, allowlist: nil, baseline: nil)
|
|
22
27
|
@failure_message = nil
|
|
23
|
-
|
|
28
|
+
assign_failure_explanation(message, rule)
|
|
24
29
|
@classified_items = classify_items(collection, allowlist: allowlist, baseline: baseline)
|
|
25
30
|
|
|
26
31
|
violations = @classified_items[:violations]
|
|
@@ -4,7 +4,9 @@ module Rubyzen
|
|
|
4
4
|
# Minitest counterpart of the +zen_false+ matcher).
|
|
5
5
|
#
|
|
6
6
|
# @param collection [Enumerable] a Rubyzen collection of declarations
|
|
7
|
-
# @param message [String, nil] optional custom failure message
|
|
7
|
+
# @param message [String, nil] optional custom failure message (takes precedence over +rule:+)
|
|
8
|
+
# @param rule [Rubyzen::Rule, nil] rule whose description, rationale, fix hint and examples
|
|
9
|
+
# are shown in the failure message
|
|
8
10
|
# @param allowlist [Array<String>, nil] items to permanently ignore
|
|
9
11
|
# @param baseline [Array<String>, nil] known violations for gradual adoption
|
|
10
12
|
# @yield [item] block that should return false for each item
|
|
@@ -17,11 +19,14 @@ module Rubyzen
|
|
|
17
19
|
#
|
|
18
20
|
# @example With a baseline for gradual adoption
|
|
19
21
|
# assert_zen_false(classes, baseline: ['LegacyModel']) { |k| k.lines_of_code > 200 }
|
|
20
|
-
|
|
22
|
+
#
|
|
23
|
+
# @example With a rule that explains the failure (see {Rubyzen::Rule})
|
|
24
|
+
# assert_zen_false(models, rule: NO_STATIC_MODEL_METHODS) { |m| m.class_methods.any? }
|
|
25
|
+
def assert_zen_false(collection, message: nil, rule: nil, allowlist: nil, baseline: nil, &block)
|
|
21
26
|
raise ArgumentError, 'assert_zen_false requires a block' unless block
|
|
22
27
|
|
|
23
28
|
@failure_message = nil
|
|
24
|
-
|
|
29
|
+
assign_failure_explanation(message, rule)
|
|
25
30
|
failing_items = Array(collection).filter { |item| block.call(item) }
|
|
26
31
|
@classified_items = classify_items(failing_items, allowlist: allowlist, baseline: baseline)
|
|
27
32
|
|
|
@@ -4,7 +4,9 @@ module Rubyzen
|
|
|
4
4
|
# Minitest counterpart of the +zen_true+ matcher).
|
|
5
5
|
#
|
|
6
6
|
# @param collection [Enumerable] a Rubyzen collection of declarations
|
|
7
|
-
# @param message [String, nil] optional custom failure message
|
|
7
|
+
# @param message [String, nil] optional custom failure message (takes precedence over +rule:+)
|
|
8
|
+
# @param rule [Rubyzen::Rule, nil] rule whose description, rationale, fix hint and examples
|
|
9
|
+
# are shown in the failure message
|
|
8
10
|
# @param allowlist [Array<String>, nil] items to permanently ignore
|
|
9
11
|
# @param baseline [Array<String>, nil] known violations for gradual adoption
|
|
10
12
|
# @yield [item] block that should return true for each item
|
|
@@ -17,11 +19,14 @@ module Rubyzen
|
|
|
17
19
|
#
|
|
18
20
|
# @example With a custom failure message
|
|
19
21
|
# assert_zen_true(services, message: 'All services must inherit from BaseService') { |s| s.superclass_name == 'BaseService' }
|
|
20
|
-
|
|
22
|
+
#
|
|
23
|
+
# @example With a rule that explains the failure (see {Rubyzen::Rule})
|
|
24
|
+
# assert_zen_true(repos, rule: REPOS_IN_REPOS_MODULE) { |r| r.top_level_module == 'Repos' }
|
|
25
|
+
def assert_zen_true(collection, message: nil, rule: nil, allowlist: nil, baseline: nil, &block)
|
|
21
26
|
raise ArgumentError, 'assert_zen_true requires a block' unless block
|
|
22
27
|
|
|
23
28
|
@failure_message = nil
|
|
24
|
-
|
|
29
|
+
assign_failure_explanation(message, rule)
|
|
25
30
|
failing_items = Array(collection).filter { |item| !block.call(item) }
|
|
26
31
|
@classified_items = classify_items(failing_items, allowlist: allowlist, baseline: baseline)
|
|
27
32
|
|
|
@@ -24,6 +24,14 @@ module Rubyzen
|
|
|
24
24
|
AttributesCollection.new(all_attributes)
|
|
25
25
|
end
|
|
26
26
|
|
|
27
|
+
# Returns all constant references and assignments across every class.
|
|
28
|
+
#
|
|
29
|
+
# @return [ConstantsCollection]
|
|
30
|
+
def constants
|
|
31
|
+
all_constants = flat_map(&:constants)
|
|
32
|
+
ConstantsCollection.new(all_constants)
|
|
33
|
+
end
|
|
34
|
+
|
|
27
35
|
# Returns all macro invocations across every class.
|
|
28
36
|
#
|
|
29
37
|
# @return [MacrosCollection]
|
|
@@ -154,12 +154,36 @@ module Rubyzen
|
|
|
154
154
|
sections.join("\n")
|
|
155
155
|
end
|
|
156
156
|
|
|
157
|
+
# Sets the +@custom_message+ and +@rule+ read by {#message_for_failure}.
|
|
158
|
+
# A {Rubyzen::Rule} passed as the message is treated as the rule.
|
|
159
|
+
#
|
|
160
|
+
# @param message [String, Rubyzen::Rule, nil] the custom failure message
|
|
161
|
+
# @param rule [Rubyzen::Rule, nil] the rule explaining the failure
|
|
162
|
+
# @raise [ArgumentError] if the rule is neither +nil+ nor a {Rubyzen::Rule}
|
|
163
|
+
# @return [void]
|
|
164
|
+
def assign_failure_explanation(message, rule)
|
|
165
|
+
message_rule = message if message.is_a?(Rubyzen::Rule)
|
|
166
|
+
rule ||= message_rule
|
|
167
|
+
unless rule.nil? || rule.is_a?(Rubyzen::Rule)
|
|
168
|
+
raise ArgumentError, "Expected rule: to be a Rubyzen::Rule, got #{rule.class}. " \
|
|
169
|
+
'Pass a plain String as the message instead.'
|
|
170
|
+
end
|
|
171
|
+
|
|
172
|
+
@custom_message = message_rule ? nil : message
|
|
173
|
+
@rule = rule
|
|
174
|
+
end
|
|
175
|
+
|
|
157
176
|
# Formats the failure message by combining the base message with
|
|
158
|
-
# custom messages and classified item details (violations, stale entries).
|
|
177
|
+
# custom messages, the rule, and classified item details (violations, stale entries).
|
|
178
|
+
#
|
|
179
|
+
# Precedence: a custom message replaces the base message; otherwise a rule's
|
|
180
|
+
# {Rubyzen::Rule#message} does. The details are appended in every case. When
|
|
181
|
+
# there are no details (e.g. a missing block or a failed negation), the base
|
|
182
|
+
# message follows the rule so the reason for the failure is not lost.
|
|
159
183
|
#
|
|
160
184
|
# Works unchanged in both RSpec matchers and Minitest assertions, since it
|
|
161
185
|
# only reads instance variables set by the caller (+@failure_message+,
|
|
162
|
-
# +@custom_message+, +@classified_items+).
|
|
186
|
+
# +@custom_message+, +@rule+, +@classified_items+).
|
|
163
187
|
#
|
|
164
188
|
# @param base_message [String] the default failure message
|
|
165
189
|
# @return [String] formatted failure message
|
|
@@ -168,7 +192,10 @@ module Rubyzen
|
|
|
168
192
|
|
|
169
193
|
details = formatted_matcher_groups
|
|
170
194
|
|
|
171
|
-
if @
|
|
195
|
+
if !@custom_message && @rule
|
|
196
|
+
reason = details.nil? || details.empty? ? base_message : details
|
|
197
|
+
"#{@rule.message}\n\n#{reason}"
|
|
198
|
+
elsif @custom_message
|
|
172
199
|
if details && !details.empty?
|
|
173
200
|
"#{@custom_message}\n#{details}"
|
|
174
201
|
else
|
|
@@ -7,7 +7,9 @@
|
|
|
7
7
|
# # Used in architectural lint rules to verify that no items match
|
|
8
8
|
# # a forbidden pattern (e.g., no controllers call +.where+ directly).
|
|
9
9
|
# #
|
|
10
|
-
# # @param custom_message [String, nil] optional failure message
|
|
10
|
+
# # @param custom_message [String, nil] optional failure message (takes precedence over +rule:+)
|
|
11
|
+
# # @param rule [Rubyzen::Rule, nil] rule whose description, rationale, fix hint and examples
|
|
12
|
+
# # are shown in the failure message
|
|
11
13
|
# # @param allowlist [Array<String>, nil] items to permanently ignore
|
|
12
14
|
# # @param baseline [Array<String>, nil] known violations for gradual adoption
|
|
13
15
|
# #
|
|
@@ -16,17 +18,24 @@
|
|
|
16
18
|
# #
|
|
17
19
|
# # @example With baseline for gradual adoption
|
|
18
20
|
# # expect(violations).to zen_empty(baseline: ['LegacyController'])
|
|
19
|
-
#
|
|
21
|
+
# #
|
|
22
|
+
# # @example With a rule that explains the failure (see {Rubyzen::Rule})
|
|
23
|
+
# # expect(controllers.all_methods.if_statements).to zen_empty(rule: NO_IFS_IN_CONTROLLERS)
|
|
24
|
+
# def zen_empty(custom_message = nil, rule: nil, allowlist: nil, baseline: nil); end
|
|
20
25
|
# end
|
|
21
26
|
# end
|
|
22
|
-
RSpec::Matchers.define :zen_empty do |custom_message=nil, allowlist: nil, baseline: nil|
|
|
27
|
+
RSpec::Matchers.define :zen_empty do |custom_message=nil, rule: nil, allowlist: nil, baseline: nil|
|
|
23
28
|
include Rubyzen::ExpectationHelpers
|
|
24
29
|
|
|
25
30
|
match do |subject_collection|
|
|
26
31
|
options = custom_message.is_a?(Hash) ? custom_message : {}
|
|
27
32
|
resolved_allowlist = allowlist || options[:allowlist] || options['allowlist']
|
|
28
33
|
resolved_baseline = baseline || options[:baseline] || options['baseline']
|
|
29
|
-
|
|
34
|
+
positional_message = custom_message unless custom_message.is_a?(Hash)
|
|
35
|
+
assign_failure_explanation(
|
|
36
|
+
options[:message] || options['message'] || positional_message,
|
|
37
|
+
rule || options[:rule] || options['rule']
|
|
38
|
+
)
|
|
30
39
|
|
|
31
40
|
@classified_items = classify_items(
|
|
32
41
|
subject_collection,
|
|
@@ -6,7 +6,9 @@
|
|
|
6
6
|
# # Supports +allowlist:+ and +baseline:+ for gradual adoption, matching items
|
|
7
7
|
# # where the block returns true against exception lists.
|
|
8
8
|
# #
|
|
9
|
-
# # @param custom_message [String, nil] optional failure message
|
|
9
|
+
# # @param custom_message [String, nil] optional failure message (takes precedence over +rule:+)
|
|
10
|
+
# # @param rule [Rubyzen::Rule, nil] rule whose description, rationale, fix hint and examples
|
|
11
|
+
# # are shown in the failure message
|
|
10
12
|
# # @param allowlist [Array<String>, nil] items to permanently ignore
|
|
11
13
|
# # @param baseline [Array<String>, nil] known violations for gradual adoption
|
|
12
14
|
# # @yield [item] block that should return false for each item
|
|
@@ -16,17 +18,24 @@
|
|
|
16
18
|
# #
|
|
17
19
|
# # @example With a baseline for gradual adoption
|
|
18
20
|
# # expect(classes).to zen_false(baseline: ['LegacyModel']) { |k| k.lines_of_code > 200 }
|
|
19
|
-
#
|
|
21
|
+
# #
|
|
22
|
+
# # @example With a rule that explains the failure (see {Rubyzen::Rule})
|
|
23
|
+
# # expect(models).to zen_false(rule: NO_STATIC_MODEL_METHODS) { |m| m.class_methods.any? }
|
|
24
|
+
# def zen_false(custom_message = nil, rule: nil, allowlist: nil, baseline: nil, &block); end
|
|
20
25
|
# end
|
|
21
26
|
# end
|
|
22
|
-
RSpec::Matchers.define :zen_false do |custom_message=nil, allowlist: nil, baseline: nil|
|
|
27
|
+
RSpec::Matchers.define :zen_false do |custom_message=nil, rule: nil, allowlist: nil, baseline: nil|
|
|
23
28
|
include Rubyzen::ExpectationHelpers
|
|
24
29
|
|
|
25
30
|
match do |subject_collection|
|
|
26
31
|
options = custom_message.is_a?(Hash) ? custom_message : {}
|
|
27
32
|
resolved_allowlist = allowlist || options[:allowlist] || options['allowlist']
|
|
28
33
|
resolved_baseline = baseline || options[:baseline] || options['baseline']
|
|
29
|
-
|
|
34
|
+
positional_message = custom_message unless custom_message.is_a?(Hash)
|
|
35
|
+
assign_failure_explanation(
|
|
36
|
+
options[:message] || options['message'] || positional_message,
|
|
37
|
+
rule || options[:rule] || options['rule']
|
|
38
|
+
)
|
|
30
39
|
@offenders = []
|
|
31
40
|
|
|
32
41
|
if block_arg != nil
|
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
# module Matchers
|
|
4
4
|
# # Asserts that a block returns true for every item in a collection.
|
|
5
5
|
# #
|
|
6
|
-
# # @param custom_message [String, nil] optional failure message
|
|
6
|
+
# # @param custom_message [String, nil] optional failure message (takes precedence over +rule:+)
|
|
7
|
+
# # @param rule [Rubyzen::Rule, nil] rule whose description, rationale, fix hint and examples
|
|
8
|
+
# # are shown in the failure message
|
|
7
9
|
# # @param allowlist [Array<String>, nil] items to permanently ignore
|
|
8
10
|
# # @param baseline [Array<String>, nil] known violations for gradual adoption
|
|
9
11
|
# # @yield [item] block that should return true for each item
|
|
@@ -13,17 +15,24 @@
|
|
|
13
15
|
# #
|
|
14
16
|
# # @example With a custom failure message
|
|
15
17
|
# # expect(services).to zen_true("All services must inherit from BaseService") { |s| s.superclass_name == 'BaseService' }
|
|
16
|
-
#
|
|
18
|
+
# #
|
|
19
|
+
# # @example With a rule that explains the failure (see {Rubyzen::Rule})
|
|
20
|
+
# # expect(repos).to zen_true(rule: REPOS_IN_REPOS_MODULE) { |r| r.top_level_module == 'Repos' }
|
|
21
|
+
# def zen_true(custom_message = nil, rule: nil, allowlist: nil, baseline: nil, &block); end
|
|
17
22
|
# end
|
|
18
23
|
# end
|
|
19
|
-
RSpec::Matchers.define :zen_true do |custom_message=nil, allowlist: nil, baseline: nil|
|
|
24
|
+
RSpec::Matchers.define :zen_true do |custom_message=nil, rule: nil, allowlist: nil, baseline: nil|
|
|
20
25
|
include Rubyzen::ExpectationHelpers
|
|
21
26
|
|
|
22
27
|
match do |subject_collection|
|
|
23
28
|
options = custom_message.is_a?(Hash) ? custom_message : {}
|
|
24
29
|
resolved_allowlist = allowlist || options[:allowlist] || options['allowlist']
|
|
25
30
|
resolved_baseline = baseline || options[:baseline] || options['baseline']
|
|
26
|
-
|
|
31
|
+
positional_message = custom_message unless custom_message.is_a?(Hash)
|
|
32
|
+
assign_failure_explanation(
|
|
33
|
+
options[:message] || options['message'] || positional_message,
|
|
34
|
+
rule || options[:rule] || options['rule']
|
|
35
|
+
)
|
|
27
36
|
@offenders = []
|
|
28
37
|
|
|
29
38
|
if block_arg != nil
|
data/lib/rubyzen/rule.rb
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
# Describes an architectural lint rule: what it requires, why, and how to fix a violation.
|
|
3
|
+
#
|
|
4
|
+
# Pass a +Rule+ to any Rubyzen matcher (+rule:+) or assertion (+rule:+) and the failure
|
|
5
|
+
# message explains the rule instead of just listing the violations. This gives whoever reads
|
|
6
|
+
# the failure — a developer or an AI agent — the context needed to fix the code rather than
|
|
7
|
+
# to silence the rule.
|
|
8
|
+
#
|
|
9
|
+
# Define the sections in a block (see {Builder}) or pass them as keywords. Only +description+
|
|
10
|
+
# is required; the other sections are omitted from the message when +nil+.
|
|
11
|
+
#
|
|
12
|
+
# @example Defining a rule with the block DSL and attaching it to an RSpec matcher
|
|
13
|
+
# let(:rule) do
|
|
14
|
+
# Rubyzen::Rule.new do
|
|
15
|
+
# description 'Controllers do not contain if statements.'
|
|
16
|
+
# rationale <<~TEXT
|
|
17
|
+
# Controllers only orchestrate; branching is business logic in the wrong layer.
|
|
18
|
+
# TEXT
|
|
19
|
+
# fix_hint 'Move the condition into a Service step and return a Failure.'
|
|
20
|
+
# bad_example <<~RUBY
|
|
21
|
+
# return error(:forbidden) if profile.banned?
|
|
22
|
+
# RUBY
|
|
23
|
+
# good_example <<~RUBY
|
|
24
|
+
# Services::Profiles::Update.new.call(profile:)
|
|
25
|
+
# RUBY
|
|
26
|
+
# end
|
|
27
|
+
# end
|
|
28
|
+
#
|
|
29
|
+
# it 'has no if statements' do
|
|
30
|
+
# expect(controllers.all_methods.if_statements).to zen_empty(rule:)
|
|
31
|
+
# end
|
|
32
|
+
#
|
|
33
|
+
# @example Defining a short rule with keywords and attaching it to a Minitest assertion
|
|
34
|
+
# RULE = Rubyzen::Rule.new(description: 'Controllers do not contain if statements.')
|
|
35
|
+
#
|
|
36
|
+
# assert_zen_empty(controllers.all_methods.if_statements, rule: RULE)
|
|
37
|
+
#
|
|
38
|
+
class Rule
|
|
39
|
+
# @return [String] one-line statement of what the rule requires
|
|
40
|
+
attr_reader :description
|
|
41
|
+
|
|
42
|
+
# @return [String, nil] why the rule exists — the architectural reasoning
|
|
43
|
+
attr_reader :rationale
|
|
44
|
+
|
|
45
|
+
# @return [String, nil] how to bring violating code into compliance
|
|
46
|
+
attr_reader :fix_hint
|
|
47
|
+
|
|
48
|
+
# @return [String, nil] a short snippet that violates the rule
|
|
49
|
+
attr_reader :bad_example
|
|
50
|
+
|
|
51
|
+
# @return [String, nil] a short snippet that satisfies the rule
|
|
52
|
+
attr_reader :good_example
|
|
53
|
+
|
|
54
|
+
# @param description [String] one-line statement of what the rule requires
|
|
55
|
+
# @param rationale [String, nil] why the rule exists
|
|
56
|
+
# @param fix_hint [String, nil] how to fix a violation
|
|
57
|
+
# @param bad_example [String, nil] a snippet that violates the rule
|
|
58
|
+
# @param good_example [String, nil] a snippet that satisfies the rule
|
|
59
|
+
# @yield the block DSL, evaluated by a {Builder}; use it instead of the keywords
|
|
60
|
+
# @yieldparam builder [Builder] passed when the block declares a parameter
|
|
61
|
+
# @raise [ArgumentError] if +description+ is blank, or if both keywords and a block are given
|
|
62
|
+
def initialize(description: nil, rationale: nil, fix_hint: nil, bad_example: nil, good_example: nil, &definition)
|
|
63
|
+
sections = { description:, rationale:, fix_hint:, bad_example:, good_example: }
|
|
64
|
+
if definition
|
|
65
|
+
raise ArgumentError, 'Rubyzen::Rule takes its sections as keywords or in a block, not both' if sections.values.any?
|
|
66
|
+
|
|
67
|
+
sections = Builder.build(&definition)
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
@description = normalize_text(sections[:description])
|
|
71
|
+
raise ArgumentError, 'Rubyzen::Rule requires a description' unless @description
|
|
72
|
+
|
|
73
|
+
@rationale = normalize_text(sections[:rationale])
|
|
74
|
+
@fix_hint = normalize_text(sections[:fix_hint])
|
|
75
|
+
@bad_example = normalize_code(sections[:bad_example])
|
|
76
|
+
@good_example = normalize_code(sections[:good_example])
|
|
77
|
+
freeze
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
# Returns the human-readable failure text: the description followed by every
|
|
81
|
+
# provided section, separated by blank lines.
|
|
82
|
+
#
|
|
83
|
+
# @return [String]
|
|
84
|
+
#
|
|
85
|
+
# @example
|
|
86
|
+
# rule.message
|
|
87
|
+
# #=> "RULE: Controllers do not contain if statements.\n\nWHY: ...\n\nHOW TO FIX: ..."
|
|
88
|
+
def message
|
|
89
|
+
[
|
|
90
|
+
"RULE: #{description}",
|
|
91
|
+
rationale && "WHY: #{rationale}",
|
|
92
|
+
fix_hint && "HOW TO FIX: #{fix_hint}",
|
|
93
|
+
bad_example && "BAD:\n#{bad_example}",
|
|
94
|
+
good_example && "GOOD:\n#{good_example}"
|
|
95
|
+
].compact.join("\n\n")
|
|
96
|
+
end
|
|
97
|
+
alias to_s message
|
|
98
|
+
|
|
99
|
+
private
|
|
100
|
+
|
|
101
|
+
def normalize_text(value)
|
|
102
|
+
text = value.to_s.strip
|
|
103
|
+
text.empty? ? nil : text
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
# Keeps the indentation of code snippets and only drops surrounding blank lines,
|
|
107
|
+
# so heredoc examples render as written.
|
|
108
|
+
def normalize_code(value)
|
|
109
|
+
code = value.to_s.sub(/\A(\s*\n)+/, '').rstrip
|
|
110
|
+
code.empty? ? nil : code
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
# The block DSL of {Rule#initialize}: one method per section. The block is evaluated
|
|
114
|
+
# with the builder as +self+, or receives it as a parameter (+do |rule| ... end+) when the
|
|
115
|
+
# block needs to reach methods of the surrounding scope. Calling a method again replaces
|
|
116
|
+
# the earlier value.
|
|
117
|
+
#
|
|
118
|
+
# @example
|
|
119
|
+
# Rubyzen::Rule.new do
|
|
120
|
+
# description 'Jobs are namespaced in the Jobs module.'
|
|
121
|
+
# fix_hint 'Wrap the class in `module Jobs`.'
|
|
122
|
+
# end
|
|
123
|
+
class Builder
|
|
124
|
+
# Evaluates a rule definition block.
|
|
125
|
+
#
|
|
126
|
+
# @return [Hash{Symbol => String}] the sections that the block defined
|
|
127
|
+
def self.build(&definition)
|
|
128
|
+
builder = new
|
|
129
|
+
definition.arity == 1 ? definition.call(builder) : builder.instance_eval(&definition)
|
|
130
|
+
builder.sections
|
|
131
|
+
end
|
|
132
|
+
|
|
133
|
+
# @return [Hash{Symbol => String}] the sections defined so far
|
|
134
|
+
attr_reader :sections
|
|
135
|
+
|
|
136
|
+
def initialize
|
|
137
|
+
@sections = {}
|
|
138
|
+
end
|
|
139
|
+
|
|
140
|
+
# @param text [String] one-line statement of what the rule requires
|
|
141
|
+
# @return [void]
|
|
142
|
+
def description(text)
|
|
143
|
+
@sections[:description] = text
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
# @param text [String] why the rule exists — the architectural reasoning
|
|
147
|
+
# @return [void]
|
|
148
|
+
def rationale(text)
|
|
149
|
+
@sections[:rationale] = text
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
# @param text [String] how to bring violating code into compliance
|
|
153
|
+
# @return [void]
|
|
154
|
+
def fix_hint(text)
|
|
155
|
+
@sections[:fix_hint] = text
|
|
156
|
+
end
|
|
157
|
+
|
|
158
|
+
# @param code [String] a short snippet that violates the rule
|
|
159
|
+
# @return [void]
|
|
160
|
+
def bad_example(code)
|
|
161
|
+
@sections[:bad_example] = code
|
|
162
|
+
end
|
|
163
|
+
|
|
164
|
+
# @param code [String] a short snippet that satisfies the rule
|
|
165
|
+
# @return [void]
|
|
166
|
+
def good_example(code)
|
|
167
|
+
@sections[:good_example] = code
|
|
168
|
+
end
|
|
169
|
+
end
|
|
170
|
+
end
|
|
171
|
+
end
|
data/lib/rubyzen/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: rubyzen-lint
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.4.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Perry Street Software
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2026-
|
|
11
|
+
date: 2026-11-05 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: rubocop-ast
|
|
@@ -171,6 +171,7 @@ files:
|
|
|
171
171
|
- lib/rubyzen/providers/source_code_provider.rb
|
|
172
172
|
- lib/rubyzen/providers/visibility_provider.rb
|
|
173
173
|
- lib/rubyzen/rspec.rb
|
|
174
|
+
- lib/rubyzen/rule.rb
|
|
174
175
|
- lib/rubyzen/version.rb
|
|
175
176
|
- rubyzen-lint.gemspec
|
|
176
177
|
homepage: https://github.com/perrystreetsoftware/Rubyzen
|