rubyzen-lint 0.2.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 +40 -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/arguments_collection.rb +16 -0
- data/lib/rubyzen/collections/assignments_collection.rb +11 -0
- data/lib/rubyzen/collections/blocks_collection.rb +21 -0
- data/lib/rubyzen/collections/classes_collection.rb +8 -0
- data/lib/rubyzen/collections/expressions_collection.rb +27 -0
- data/lib/rubyzen/collections/methods_collection.rb +29 -0
- data/lib/rubyzen/collections/returns_collection.rb +20 -0
- data/lib/rubyzen/declarations/assignment_declaration.rb +57 -0
- data/lib/rubyzen/declarations/block_declaration.rb +2 -0
- data/lib/rubyzen/declarations/call_site_declaration.rb +14 -0
- data/lib/rubyzen/declarations/expression_declaration.rb +99 -0
- data/lib/rubyzen/declarations/method_declaration.rb +2 -0
- data/lib/rubyzen/declarations/return_declaration.rb +51 -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/providers/arguments_provider.rb +15 -0
- data/lib/rubyzen/providers/assignments_provider.rb +15 -0
- data/lib/rubyzen/providers/enclosing_blocks_provider.rb +16 -0
- data/lib/rubyzen/providers/returns_provider.rb +49 -0
- data/lib/rubyzen/rule.rb +171 -0
- data/lib/rubyzen/version.rb +1 -1
- metadata +19 -7
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,45 @@
|
|
|
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
|
+
|
|
19
|
+
## [0.3.0]
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
- **`ExpressionDeclaration`** — a value-expression primitive wrapping any AST node, with
|
|
24
|
+
predicates (`constant?`, `local_variable?`, `method_call?`, `constructor?`, `hash_literal?`,
|
|
25
|
+
`symbol?`, `string?`) and accessors (`constant_name`, `method_name`, `name`).
|
|
26
|
+
- **`#returns`** on `MethodDeclaration` and `BlockDeclaration` — the points at which it yields a
|
|
27
|
+
value (the implicit final expression plus explicit `return`s) as `ReturnDeclaration`s
|
|
28
|
+
(`#explicit?`, `#implicit?`, `#expression`), collected in a `ReturnsCollection` (`#expressions`).
|
|
29
|
+
`#return_expressions` remains as a shortcut for `returns.expressions` — an `ExpressionsCollection`
|
|
30
|
+
(`#hash_literals`, `#constants`). Both are bridged on `MethodsCollection` and `BlocksCollection`.
|
|
31
|
+
- **`CallSiteDeclaration#arguments`** — the call's arguments as an `ArgumentsCollection`
|
|
32
|
+
(a subclass of `ExpressionsCollection`, so it keeps `#hash_literals`/`#constants`).
|
|
33
|
+
- **`CallSiteDeclaration#receiver_expression`** — the receiver modeled structurally (constant /
|
|
34
|
+
constructor / local variable). `#receiver` (String const-name) is unchanged.
|
|
35
|
+
- **`CallSiteDeclaration#enclosing_blocks`** — the chain of enclosing `do..end`/`{ }` blocks
|
|
36
|
+
(innermost first), as a `BlocksCollection`.
|
|
37
|
+
- **`#assignments`** on `MethodDeclaration` and `BlockDeclaration` — local-variable assignments
|
|
38
|
+
(`AssignmentDeclaration`, with `#name` and `#value`) as an `AssignmentsCollection`. Bridged on
|
|
39
|
+
`MethodsCollection` and `BlocksCollection`.
|
|
40
|
+
|
|
41
|
+
All additions are backward-compatible; no existing API changed.
|
|
42
|
+
|
|
3
43
|
## [0.2.0]
|
|
4
44
|
|
|
5
45
|
### 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
|
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Collections
|
|
3
|
+
# Collection of {Rubyzen::Declarations::ExpressionDeclaration} representing the arguments
|
|
4
|
+
# passed at a call site.
|
|
5
|
+
#
|
|
6
|
+
# A specialization of {ExpressionsCollection}: arguments are value-expressions, so this
|
|
7
|
+
# inherits the value-expression filters (`#hash_literals`, `#constants`) and remains a
|
|
8
|
+
# drop-in `ExpressionsCollection`. It exists as a distinct type so argument-specific
|
|
9
|
+
# filters (e.g. positional vs keyword) can be added later without a breaking change.
|
|
10
|
+
#
|
|
11
|
+
# @example
|
|
12
|
+
# call_site.arguments.first.constant_name
|
|
13
|
+
class ArgumentsCollection < ExpressionsCollection
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
end
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Collections
|
|
3
|
+
# Collection of {Rubyzen::Declarations::AssignmentDeclaration} (local-variable assignments).
|
|
4
|
+
#
|
|
5
|
+
# @example
|
|
6
|
+
# method.assignments.with_name('user')
|
|
7
|
+
class AssignmentsCollection < BaseCollection
|
|
8
|
+
include Rubyzen::Providers::CollectionFilterProvider
|
|
9
|
+
end
|
|
10
|
+
end
|
|
11
|
+
end
|
|
@@ -22,6 +22,27 @@ module Rubyzen
|
|
|
22
22
|
all_call_sites = flat_map(&:call_sites)
|
|
23
23
|
CallSiteCollection.new(all_call_sites)
|
|
24
24
|
end
|
|
25
|
+
|
|
26
|
+
# Returns all return points across every block.
|
|
27
|
+
#
|
|
28
|
+
# @return [ReturnsCollection]
|
|
29
|
+
def returns
|
|
30
|
+
ReturnsCollection.new(flat_map(&:returns))
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# Returns all return expressions across every block.
|
|
34
|
+
#
|
|
35
|
+
# @return [ExpressionsCollection]
|
|
36
|
+
def return_expressions
|
|
37
|
+
returns.expressions
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# Returns all local-variable assignments across every block.
|
|
41
|
+
#
|
|
42
|
+
# @return [AssignmentsCollection]
|
|
43
|
+
def assignments
|
|
44
|
+
AssignmentsCollection.new(flat_map(&:assignments))
|
|
45
|
+
end
|
|
25
46
|
end
|
|
26
47
|
end
|
|
27
48
|
end
|
|
@@ -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]
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Collections
|
|
3
|
+
# Collection of {Rubyzen::Declarations::ExpressionDeclaration} — return values,
|
|
4
|
+
# call arguments, and other value-expressions.
|
|
5
|
+
#
|
|
6
|
+
# @example
|
|
7
|
+
# method.return_expressions.hash_literals
|
|
8
|
+
class ExpressionsCollection < BaseCollection
|
|
9
|
+
include Rubyzen::Providers::CollectionFilterProvider
|
|
10
|
+
|
|
11
|
+
# Filters to only braced Hash-literal expressions.
|
|
12
|
+
#
|
|
13
|
+
# @return [ExpressionsCollection]
|
|
14
|
+
def hash_literals
|
|
15
|
+
filter(&:hash_literal?)
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
# Filters to only constant expressions, including constructors of a constant
|
|
19
|
+
# (e.g. both +Repos::Foo+ and +Repos::Foo.new+).
|
|
20
|
+
#
|
|
21
|
+
# @return [ExpressionsCollection]
|
|
22
|
+
def constants
|
|
23
|
+
filter(&:constant_name)
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
end
|
|
27
|
+
end
|
|
@@ -62,6 +62,35 @@ module Rubyzen
|
|
|
62
62
|
end
|
|
63
63
|
)
|
|
64
64
|
end
|
|
65
|
+
|
|
66
|
+
# Returns all return points across every method.
|
|
67
|
+
#
|
|
68
|
+
# @return [ReturnsCollection]
|
|
69
|
+
def returns
|
|
70
|
+
ReturnsCollection.new(
|
|
71
|
+
flat_map do |method|
|
|
72
|
+
method.returns
|
|
73
|
+
end
|
|
74
|
+
)
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
# Returns all return expressions across every method.
|
|
78
|
+
#
|
|
79
|
+
# @return [ExpressionsCollection]
|
|
80
|
+
def return_expressions
|
|
81
|
+
returns.expressions
|
|
82
|
+
end
|
|
83
|
+
|
|
84
|
+
# Returns all local-variable assignments across every method.
|
|
85
|
+
#
|
|
86
|
+
# @return [AssignmentsCollection]
|
|
87
|
+
def assignments
|
|
88
|
+
AssignmentsCollection.new(
|
|
89
|
+
flat_map do |method|
|
|
90
|
+
method.assignments
|
|
91
|
+
end
|
|
92
|
+
)
|
|
93
|
+
end
|
|
65
94
|
end
|
|
66
95
|
end
|
|
67
96
|
end
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Collections
|
|
3
|
+
# Collection of {Rubyzen::Declarations::ReturnDeclaration} — the points at which a
|
|
4
|
+
# method or block yields a value.
|
|
5
|
+
#
|
|
6
|
+
# @example
|
|
7
|
+
# method.returns.expressions.hash_literals
|
|
8
|
+
class ReturnsCollection < BaseCollection
|
|
9
|
+
include Rubyzen::Providers::CollectionFilterProvider
|
|
10
|
+
|
|
11
|
+
# The value expressions of every return. Bare +return+s (which have no value)
|
|
12
|
+
# are omitted.
|
|
13
|
+
#
|
|
14
|
+
# @return [ExpressionsCollection]
|
|
15
|
+
def expressions
|
|
16
|
+
ExpressionsCollection.new(filter_map(&:expression))
|
|
17
|
+
end
|
|
18
|
+
end
|
|
19
|
+
end
|
|
20
|
+
end
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Declarations
|
|
3
|
+
# Represents a local-variable assignment (an +lvasgn+ node), e.g. +x = Repos::Foo.new+.
|
|
4
|
+
#
|
|
5
|
+
# @example
|
|
6
|
+
# assignment = method.assignments.first
|
|
7
|
+
# assignment.name #=> "x"
|
|
8
|
+
# assignment.value.constructor? #=> true
|
|
9
|
+
# assignment.value.constant_name #=> "Repos::Foo"
|
|
10
|
+
#
|
|
11
|
+
# NOTE: Multiple assignment (+a, b = ...+) is only partially modelled. Each target is
|
|
12
|
+
# surfaced as its own AssignmentDeclaration with a correct {#name}, but {#value} is +nil+:
|
|
13
|
+
# in the AST the right-hand side lives on the enclosing +masgn+ node, not on the per-target
|
|
14
|
+
# +lvasgn+, and which value each variable receives generally cannot be known statically
|
|
15
|
+
# (e.g. +a, b = build_pair+). If a rule ever needs to trace destructured assignments, model
|
|
16
|
+
# the shared source explicitly (a +multiple_assignment?+ predicate + +shared_source+) rather
|
|
17
|
+
# than attributing the shared right-hand side to each variable's {#value}.
|
|
18
|
+
#
|
|
19
|
+
class AssignmentDeclaration
|
|
20
|
+
include Rubyzen::Providers::FilePathProvider
|
|
21
|
+
include Rubyzen::Providers::LineNumberProvider
|
|
22
|
+
include Rubyzen::Providers::ClassNameProvider
|
|
23
|
+
include Rubyzen::Providers::SourceCodeProvider
|
|
24
|
+
|
|
25
|
+
# @return [RuboCop::AST::Node]
|
|
26
|
+
attr_reader :node
|
|
27
|
+
|
|
28
|
+
# @return [MethodDeclaration, BlockDeclaration]
|
|
29
|
+
attr_reader :parent
|
|
30
|
+
|
|
31
|
+
# @param node [RuboCop::AST::Node] the +lvasgn+ node
|
|
32
|
+
# @param parent [MethodDeclaration, BlockDeclaration] the enclosing declaration
|
|
33
|
+
def initialize(node, parent)
|
|
34
|
+
@node = node
|
|
35
|
+
@parent = parent
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
# Returns the name of the assigned local variable.
|
|
39
|
+
#
|
|
40
|
+
# @return [String] e.g. +"x"+
|
|
41
|
+
def name
|
|
42
|
+
node.children.first.to_s
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# Returns the assigned value as an expression, or +nil+ when there is no value
|
|
46
|
+
# node (e.g. the per-variable targets of a multiple assignment, +a, b = foo+).
|
|
47
|
+
#
|
|
48
|
+
# @return [ExpressionDeclaration, nil]
|
|
49
|
+
def value
|
|
50
|
+
value_node = node.children[1]
|
|
51
|
+
return nil if value_node.nil?
|
|
52
|
+
|
|
53
|
+
ExpressionDeclaration.new(value_node, self)
|
|
54
|
+
end
|
|
55
|
+
end
|
|
56
|
+
end
|
|
57
|
+
end
|
|
@@ -17,6 +17,8 @@ module Rubyzen
|
|
|
17
17
|
include Rubyzen::Providers::RaisesProvider
|
|
18
18
|
include Rubyzen::Providers::SourceCodeProvider
|
|
19
19
|
include Rubyzen::Providers::CallSiteProvider
|
|
20
|
+
include Rubyzen::Providers::ReturnsProvider
|
|
21
|
+
include Rubyzen::Providers::AssignmentsProvider
|
|
20
22
|
|
|
21
23
|
# @return [RuboCop::AST::Node]
|
|
22
24
|
attr_reader :node
|
|
@@ -13,6 +13,8 @@ module Rubyzen
|
|
|
13
13
|
include Rubyzen::Providers::LineNumberProvider
|
|
14
14
|
include Rubyzen::Providers::ClassNameProvider
|
|
15
15
|
include Rubyzen::Providers::SourceCodeProvider
|
|
16
|
+
include Rubyzen::Providers::ArgumentsProvider
|
|
17
|
+
include Rubyzen::Providers::EnclosingBlocksProvider
|
|
16
18
|
|
|
17
19
|
# @return [RuboCop::AST::Node]
|
|
18
20
|
attr_reader :node
|
|
@@ -41,6 +43,18 @@ module Rubyzen
|
|
|
41
43
|
node.receiver&.type == :const ? node.receiver.const_name : nil
|
|
42
44
|
end
|
|
43
45
|
|
|
46
|
+
# Returns the receiver as an expression, or +nil+ for a receiverless call (e.g. +save+).
|
|
47
|
+
#
|
|
48
|
+
# Unlike {#receiver} (which returns a constant-name String), this models the receiver
|
|
49
|
+
# structurally — constant, constructor, or local variable.
|
|
50
|
+
#
|
|
51
|
+
# @return [Rubyzen::Declarations::ExpressionDeclaration, nil]
|
|
52
|
+
def receiver_expression
|
|
53
|
+
return nil if node.receiver.nil?
|
|
54
|
+
|
|
55
|
+
ExpressionDeclaration.new(node.receiver, self)
|
|
56
|
+
end
|
|
57
|
+
|
|
44
58
|
# Returns the called method name.
|
|
45
59
|
#
|
|
46
60
|
# @return [String]
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Declarations
|
|
3
|
+
# Represents an arbitrary Ruby value-expression node — the value a method returns,
|
|
4
|
+
# the receiver of a call, a positional argument, the value of an assignment, and so on.
|
|
5
|
+
# Wraps any AST node and exposes its "kind" through predicates, so rules can ask
|
|
6
|
+
# structural questions without touching the raw AST.
|
|
7
|
+
#
|
|
8
|
+
# @example
|
|
9
|
+
# expr = call_site.receiver_expression
|
|
10
|
+
# expr.constructor? #=> true (for Repos::Foo.new.bar)
|
|
11
|
+
# expr.constant_name #=> "Repos::Foo"
|
|
12
|
+
#
|
|
13
|
+
class ExpressionDeclaration
|
|
14
|
+
include Rubyzen::Providers::FilePathProvider
|
|
15
|
+
include Rubyzen::Providers::LineNumberProvider
|
|
16
|
+
include Rubyzen::Providers::ClassNameProvider
|
|
17
|
+
include Rubyzen::Providers::SourceCodeProvider
|
|
18
|
+
|
|
19
|
+
# @return [RuboCop::AST::Node]
|
|
20
|
+
attr_reader :node
|
|
21
|
+
|
|
22
|
+
# @return [Object] the declaration that produced this expression
|
|
23
|
+
attr_reader :parent
|
|
24
|
+
|
|
25
|
+
# @param node [RuboCop::AST::Node] the value-expression node
|
|
26
|
+
# @param parent [Object] the declaration that produced this expression
|
|
27
|
+
def initialize(node, parent)
|
|
28
|
+
@node = node
|
|
29
|
+
@parent = parent
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
# Returns a short identifier: the constant, variable, or method name, falling
|
|
33
|
+
# back to the node type.
|
|
34
|
+
#
|
|
35
|
+
# @return [String]
|
|
36
|
+
def name
|
|
37
|
+
constant_name || local_variable_name || (method_call? ? method_name : node.type.to_s)
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# @return [Boolean] true if the expression is a bare constant, e.g. +Repos::Foo+
|
|
41
|
+
def constant?
|
|
42
|
+
node.const_type?
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# @return [Boolean] true if the expression references a local variable
|
|
46
|
+
def local_variable?
|
|
47
|
+
node.lvar_type?
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# @return [Boolean] true if the expression is a method call (a +send+ node)
|
|
51
|
+
def method_call?
|
|
52
|
+
node.send_type?
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
# @return [Boolean] true if the expression is a constructor call, e.g. +Repos::Foo.new+
|
|
56
|
+
def constructor?
|
|
57
|
+
method_call? && node.method_name == :new
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# @return [Boolean] true if the expression is a braced Hash literal with at least one pair
|
|
61
|
+
def hash_literal?
|
|
62
|
+
node.hash_type? && node.braces? && node.pairs.any?
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
# @return [Boolean] true if the expression is a symbol literal
|
|
66
|
+
def symbol?
|
|
67
|
+
node.sym_type?
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
# @return [Boolean] true if the expression is a string literal
|
|
71
|
+
def string?
|
|
72
|
+
node.str_type?
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
# Returns the constant name when the expression is a constant or constructs from one.
|
|
76
|
+
#
|
|
77
|
+
# @return [String, nil] e.g. +"Repos::Foo"+ for both +Repos::Foo+ and +Repos::Foo.new+
|
|
78
|
+
def constant_name
|
|
79
|
+
return node.const_name if constant?
|
|
80
|
+
return node.receiver.const_name if constructor? && node.receiver&.const_type?
|
|
81
|
+
|
|
82
|
+
nil
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
# Returns the called method name when the expression is a method call.
|
|
86
|
+
#
|
|
87
|
+
# @return [String, nil]
|
|
88
|
+
def method_name
|
|
89
|
+
node.method_name.to_s if method_call?
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
private
|
|
93
|
+
|
|
94
|
+
def local_variable_name
|
|
95
|
+
node.children.first.to_s if local_variable?
|
|
96
|
+
end
|
|
97
|
+
end
|
|
98
|
+
end
|
|
99
|
+
end
|
|
@@ -21,6 +21,8 @@ module Rubyzen
|
|
|
21
21
|
include Rubyzen::Providers::VisibilityProvider
|
|
22
22
|
include Rubyzen::Providers::RescuesProvider
|
|
23
23
|
include Rubyzen::Providers::RaisesProvider
|
|
24
|
+
include Rubyzen::Providers::ReturnsProvider
|
|
25
|
+
include Rubyzen::Providers::AssignmentsProvider
|
|
24
26
|
|
|
25
27
|
# @return [RuboCop::AST::Node]
|
|
26
28
|
attr_reader :node
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Declarations
|
|
3
|
+
# Represents a single point at which a method or block yields a value: the
|
|
4
|
+
# implicit final expression of its body, or an explicit +return+ statement.
|
|
5
|
+
#
|
|
6
|
+
# @example
|
|
7
|
+
# ret = method.returns.first
|
|
8
|
+
# ret.explicit? #=> false
|
|
9
|
+
# ret.expression.hash_literal? #=> true
|
|
10
|
+
#
|
|
11
|
+
class ReturnDeclaration
|
|
12
|
+
include Rubyzen::Providers::FilePathProvider
|
|
13
|
+
include Rubyzen::Providers::LineNumberProvider
|
|
14
|
+
include Rubyzen::Providers::ClassNameProvider
|
|
15
|
+
include Rubyzen::Providers::SourceCodeProvider
|
|
16
|
+
|
|
17
|
+
# @return [RuboCop::AST::Node] the +return+ node, or the implicit final-expression node
|
|
18
|
+
attr_reader :node
|
|
19
|
+
|
|
20
|
+
# @return [MethodDeclaration, BlockDeclaration] the declaration that returns this value
|
|
21
|
+
attr_reader :parent
|
|
22
|
+
|
|
23
|
+
# @param node [RuboCop::AST::Node] the +return+ node, or the implicit final-expression node
|
|
24
|
+
# @param parent [MethodDeclaration, BlockDeclaration] the enclosing declaration
|
|
25
|
+
def initialize(node, parent)
|
|
26
|
+
@node = node
|
|
27
|
+
@parent = parent
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# @return [Boolean] true if this is an explicit +return+ statement
|
|
31
|
+
def explicit?
|
|
32
|
+
node.return_type?
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
# @return [Boolean] true if this is the implicit final expression of the body
|
|
36
|
+
def implicit?
|
|
37
|
+
!explicit?
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# The value expression being returned.
|
|
41
|
+
#
|
|
42
|
+
# @return [ExpressionDeclaration, nil] +nil+ for a bare +return+ with no value
|
|
43
|
+
def expression
|
|
44
|
+
value_node = explicit? ? node.children.first : node
|
|
45
|
+
return nil if value_node.nil?
|
|
46
|
+
|
|
47
|
+
ExpressionDeclaration.new(value_node, self)
|
|
48
|
+
end
|
|
49
|
+
end
|
|
50
|
+
end
|
|
51
|
+
end
|
|
@@ -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
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Providers
|
|
3
|
+
# Provides the arguments passed at a call site (or macro), as expressions.
|
|
4
|
+
module ArgumentsProvider
|
|
5
|
+
# @return [Rubyzen::Collections::ArgumentsCollection]
|
|
6
|
+
def arguments
|
|
7
|
+
Collections::ArgumentsCollection.new(
|
|
8
|
+
node.arguments.map do |argument_node|
|
|
9
|
+
Declarations::ExpressionDeclaration.new(argument_node, self)
|
|
10
|
+
end
|
|
11
|
+
)
|
|
12
|
+
end
|
|
13
|
+
end
|
|
14
|
+
end
|
|
15
|
+
end
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Providers
|
|
3
|
+
# Provides local-variable assignments within a method or block.
|
|
4
|
+
module AssignmentsProvider
|
|
5
|
+
# @return [Rubyzen::Collections::AssignmentsCollection]
|
|
6
|
+
def assignments
|
|
7
|
+
Collections::AssignmentsCollection.new(
|
|
8
|
+
node.each_descendant(:lvasgn).map do |assignment_node|
|
|
9
|
+
Declarations::AssignmentDeclaration.new(assignment_node, self)
|
|
10
|
+
end
|
|
11
|
+
)
|
|
12
|
+
end
|
|
13
|
+
end
|
|
14
|
+
end
|
|
15
|
+
end
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Providers
|
|
3
|
+
# Provides the chain of blocks (do..end / { }) that lexically enclose a declaration,
|
|
4
|
+
# innermost first.
|
|
5
|
+
module EnclosingBlocksProvider
|
|
6
|
+
# @return [Rubyzen::Collections::BlocksCollection]
|
|
7
|
+
def enclosing_blocks
|
|
8
|
+
Collections::BlocksCollection.new(
|
|
9
|
+
node.each_ancestor(:block).map do |block_node|
|
|
10
|
+
Declarations::BlockDeclaration.new(block_node, parent)
|
|
11
|
+
end
|
|
12
|
+
)
|
|
13
|
+
end
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
end
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
module Rubyzen
|
|
2
|
+
module Providers
|
|
3
|
+
# Provides the points at which a method or block yields a value: the implicit final
|
|
4
|
+
# expression of its body, plus every explicit +return+. Each is wrapped in a
|
|
5
|
+
# {Rubyzen::Declarations::ReturnDeclaration}, which knows how to extract its own value.
|
|
6
|
+
module ReturnsProvider
|
|
7
|
+
# @return [Rubyzen::Collections::ReturnsCollection]
|
|
8
|
+
def returns
|
|
9
|
+
Collections::ReturnsCollection.new(
|
|
10
|
+
return_nodes.map do |return_node|
|
|
11
|
+
Declarations::ReturnDeclaration.new(return_node, self)
|
|
12
|
+
end
|
|
13
|
+
)
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
# The value-expression(s) this method or block evaluates to, as a flat collection.
|
|
17
|
+
# A shortcut for +returns.expressions+.
|
|
18
|
+
#
|
|
19
|
+
# @return [Rubyzen::Collections::ExpressionsCollection]
|
|
20
|
+
def return_expressions
|
|
21
|
+
returns.expressions
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
private
|
|
25
|
+
|
|
26
|
+
# The return points to wrap: the implicit final expression of the body (unless it is
|
|
27
|
+
# itself an explicit +return+, which is collected separately to avoid double-counting),
|
|
28
|
+
# followed by every explicit +return+.
|
|
29
|
+
def return_nodes
|
|
30
|
+
nodes = []
|
|
31
|
+
final = implicit_final_node
|
|
32
|
+
nodes << final unless final.nil?
|
|
33
|
+
node.each_descendant(:return) { |return_node| nodes << return_node }
|
|
34
|
+
nodes
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
# The node a body implicitly evaluates to: the last statement of a multi-statement
|
|
38
|
+
# body (+begin+) or an explicit +begin..end+ (+kwbegin+), otherwise the body itself.
|
|
39
|
+
# Returns +nil+ when that node is an explicit +return+ (collected separately).
|
|
40
|
+
def implicit_final_node
|
|
41
|
+
body = node.body
|
|
42
|
+
return nil if body.nil?
|
|
43
|
+
|
|
44
|
+
final = body.begin_type? || body.kwbegin_type? ? body.children.last : body
|
|
45
|
+
final unless final.return_type?
|
|
46
|
+
end
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
end
|
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
|
-
autorequire:
|
|
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
|
|
@@ -90,7 +90,7 @@ description: Rubyzen is a modern linter for Ruby that allows you to write archit
|
|
|
90
90
|
lint rules as unit tests. In the era of AI-generated code, it provides your team
|
|
91
91
|
with deterministic guardrails to keep your codebase clean, maintainable, and consistent
|
|
92
92
|
as it grows.
|
|
93
|
-
email:
|
|
93
|
+
email:
|
|
94
94
|
executables: []
|
|
95
95
|
extensions: []
|
|
96
96
|
extra_rdoc_files: []
|
|
@@ -105,6 +105,8 @@ files:
|
|
|
105
105
|
- lib/rubyzen/assertions/assert_zen_true.rb
|
|
106
106
|
- lib/rubyzen/assertions/zen_assertions.rb
|
|
107
107
|
- lib/rubyzen/cache/parse_cache.rb
|
|
108
|
+
- lib/rubyzen/collections/arguments_collection.rb
|
|
109
|
+
- lib/rubyzen/collections/assignments_collection.rb
|
|
108
110
|
- lib/rubyzen/collections/attributes_collection.rb
|
|
109
111
|
- lib/rubyzen/collections/base_collection.rb
|
|
110
112
|
- lib/rubyzen/collections/blocks_collection.rb
|
|
@@ -112,6 +114,7 @@ files:
|
|
|
112
114
|
- lib/rubyzen/collections/classes_collection.rb
|
|
113
115
|
- lib/rubyzen/collections/constants_collection.rb
|
|
114
116
|
- lib/rubyzen/collections/declaration_collection.rb
|
|
117
|
+
- lib/rubyzen/collections/expressions_collection.rb
|
|
115
118
|
- lib/rubyzen/collections/file_collection.rb
|
|
116
119
|
- lib/rubyzen/collections/macros_collection.rb
|
|
117
120
|
- lib/rubyzen/collections/methods_collection.rb
|
|
@@ -120,12 +123,15 @@ files:
|
|
|
120
123
|
- lib/rubyzen/collections/raises_collection.rb
|
|
121
124
|
- lib/rubyzen/collections/requires_collection.rb
|
|
122
125
|
- lib/rubyzen/collections/rescues_collection.rb
|
|
126
|
+
- lib/rubyzen/collections/returns_collection.rb
|
|
123
127
|
- lib/rubyzen/core.rb
|
|
128
|
+
- lib/rubyzen/declarations/assignment_declaration.rb
|
|
124
129
|
- lib/rubyzen/declarations/attribute_declaration.rb
|
|
125
130
|
- lib/rubyzen/declarations/block_declaration.rb
|
|
126
131
|
- lib/rubyzen/declarations/call_site_declaration.rb
|
|
127
132
|
- lib/rubyzen/declarations/class_declaration.rb
|
|
128
133
|
- lib/rubyzen/declarations/constant_declaration.rb
|
|
134
|
+
- lib/rubyzen/declarations/expression_declaration.rb
|
|
129
135
|
- lib/rubyzen/declarations/file_declaration.rb
|
|
130
136
|
- lib/rubyzen/declarations/if_statement_declaration.rb
|
|
131
137
|
- lib/rubyzen/declarations/macro_declaration.rb
|
|
@@ -135,6 +141,7 @@ files:
|
|
|
135
141
|
- lib/rubyzen/declarations/raise_declaration.rb
|
|
136
142
|
- lib/rubyzen/declarations/require_declaration.rb
|
|
137
143
|
- lib/rubyzen/declarations/rescue_declaration.rb
|
|
144
|
+
- lib/rubyzen/declarations/return_declaration.rb
|
|
138
145
|
- lib/rubyzen/expectation_helpers.rb
|
|
139
146
|
- lib/rubyzen/lint.rb
|
|
140
147
|
- lib/rubyzen/matchers/zen_empty_matcher.rb
|
|
@@ -143,12 +150,15 @@ files:
|
|
|
143
150
|
- lib/rubyzen/minitest.rb
|
|
144
151
|
- lib/rubyzen/parsers/a_s_t_parser.rb
|
|
145
152
|
- lib/rubyzen/project.rb
|
|
153
|
+
- lib/rubyzen/providers/arguments_provider.rb
|
|
154
|
+
- lib/rubyzen/providers/assignments_provider.rb
|
|
146
155
|
- lib/rubyzen/providers/attributes_provider.rb
|
|
147
156
|
- lib/rubyzen/providers/blocks_provider.rb
|
|
148
157
|
- lib/rubyzen/providers/call_site_provider.rb
|
|
149
158
|
- lib/rubyzen/providers/class_name_provider.rb
|
|
150
159
|
- lib/rubyzen/providers/collection_filter_provider.rb
|
|
151
160
|
- lib/rubyzen/providers/constants_provider.rb
|
|
161
|
+
- lib/rubyzen/providers/enclosing_blocks_provider.rb
|
|
152
162
|
- lib/rubyzen/providers/file_path_provider.rb
|
|
153
163
|
- lib/rubyzen/providers/if_statements_provider.rb
|
|
154
164
|
- lib/rubyzen/providers/line_number_provider.rb
|
|
@@ -157,9 +167,11 @@ files:
|
|
|
157
167
|
- lib/rubyzen/providers/raises_provider.rb
|
|
158
168
|
- lib/rubyzen/providers/requires_provider.rb
|
|
159
169
|
- lib/rubyzen/providers/rescues_provider.rb
|
|
170
|
+
- lib/rubyzen/providers/returns_provider.rb
|
|
160
171
|
- lib/rubyzen/providers/source_code_provider.rb
|
|
161
172
|
- lib/rubyzen/providers/visibility_provider.rb
|
|
162
173
|
- lib/rubyzen/rspec.rb
|
|
174
|
+
- lib/rubyzen/rule.rb
|
|
163
175
|
- lib/rubyzen/version.rb
|
|
164
176
|
- rubyzen-lint.gemspec
|
|
165
177
|
homepage: https://github.com/perrystreetsoftware/Rubyzen
|
|
@@ -170,7 +182,7 @@ metadata:
|
|
|
170
182
|
bug_tracker_uri: https://github.com/perrystreetsoftware/Rubyzen/issues
|
|
171
183
|
documentation_uri: https://perrystreetsoftware.github.io/Rubyzen
|
|
172
184
|
changelog_uri: https://github.com/perrystreetsoftware/Rubyzen/blob/main/CHANGELOG.md
|
|
173
|
-
post_install_message:
|
|
185
|
+
post_install_message:
|
|
174
186
|
rdoc_options: []
|
|
175
187
|
require_paths:
|
|
176
188
|
- lib
|
|
@@ -185,8 +197,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
185
197
|
- !ruby/object:Gem::Version
|
|
186
198
|
version: '0'
|
|
187
199
|
requirements: []
|
|
188
|
-
rubygems_version: 3.
|
|
189
|
-
signing_key:
|
|
200
|
+
rubygems_version: 3.5.22
|
|
201
|
+
signing_key:
|
|
190
202
|
specification_version: 4
|
|
191
203
|
summary: Architectural linter for Ruby — write lint rules as unit tests
|
|
192
204
|
test_files: []
|