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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 500e791179afc539a3b93a9300c55661567131776188a7ae484e5a2cffa3e12d
4
- data.tar.gz: 1793077a6d2cfaa933c8a607cab96a3f84afe97e58f1a1926eaf6d60d2febed6
3
+ metadata.gz: 40b1ca0286479fe9a2beb115960c65c9540ae2d9c4b4b3553e7ead435e2bbb88
4
+ data.tar.gz: 8d8e612170759162ea21501d31cdb9138327ffad70cd8fef493aaa11272950dc
5
5
  SHA512:
6
- metadata.gz: fc076838beaafc1461c8c650e7a50e92ad0f4d32adc1c7f2ee15e9b47aeb9ac33a4742b2a98d47c23c2a73085f58b9cbbaa16d6a0d03526866472462bcb8f71f
7
- data.tar.gz: b26b14d82f55b207b61601dd629154765488bf6154256738e11b1e96dfe14669109406513a12d4814c128e2cfbfc97b697c88ae68910d9d6c6c03a96c0d62164
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 custom failure message.
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
- def assert_zen_empty(collection, message: nil, allowlist: nil, baseline: nil)
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
- @custom_message = message
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
- def assert_zen_false(collection, message: nil, allowlist: nil, baseline: nil, &block)
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
- @custom_message = message
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
- def assert_zen_true(collection, message: nil, allowlist: nil, baseline: nil, &block)
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
- @custom_message = message
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 @custom_message
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
- # def zen_empty(custom_message = nil, allowlist: nil, baseline: nil); end
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
- @custom_message = options[:message] || options['message'] || (custom_message unless custom_message.is_a?(Hash))
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
- # def zen_false(custom_message = nil, allowlist: nil, baseline: nil, &block); end
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
- @custom_message = options[:message] || options['message'] || (custom_message unless custom_message.is_a?(Hash))
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
- # def zen_true(custom_message = nil, allowlist: nil, baseline: nil, &block); end
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
- @custom_message = options[:message] || options['message'] || (custom_message unless custom_message.is_a?(Hash))
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
@@ -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
@@ -1,4 +1,4 @@
1
1
  module Rubyzen
2
2
  # @return [String] the current gem version
3
- VERSION = '0.3.0'
3
+ VERSION = '0.4.0'
4
4
  end
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.3.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-06-24 00:00:00.000000000 Z
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