rubocop-vicenzo 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b430ab160562cd140cd498e015dbf4e2c03a6bd99189ae24adc00881a3bbab48
-  data.tar.gz: 3757afc640413d2ed6548319003ecf62be4cc84658673d430e5ff8236936f2d6
+  metadata.gz: 2caba14e7971e328ef6fc5c5fb203fe11a26cbd1f78f534f223f01f9d99c240f
+  data.tar.gz: 2eb689487018dfa035aff365831cc219cf71dfce583885639656f314fbcffc82
 SHA512:
-  metadata.gz: 4b2cbdc348b8faa2dd97e722e78e5c8956b67da26df8541314990331a645b156c758540d6602960e8f96340a6294bf0a35a833b4f2d5a1a237349bbb91f58ba6
-  data.tar.gz: 88b77a6119a722404ad6d263f61ed53423e4991ae216bd8ea2295712fa72c5536b902948bea8c61e2f32e832444e356c2a0b16ae2f4a8727993acd063db40130
+  metadata.gz: e1c048efe4a3c8b7f7de35d8fcbe76908efcceb50bf053df761e59d53ea8fa9d74f779f223bb0d6e6ff1274e4ec2c83daf9a561084f970cdd5a48c8b7d4f7dce
+  data.tar.gz: f8c2f91bd54d5845ae68928a5ff783f6b161a47ca0e2e1d0afdc177473761416487d2e0d5c984f9b6d064a98ef3cc64db98baf3454f3989be19bb146172a3620

data/.rubocop.yml

@@ -6,8 +6,20 @@ plugins:
   - rubocop-internal_affairs
 
 AllCops:
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
   NewCops: enable
 
+InternalAffairs/UndefinedConfig: # False positive because conflicts with Rubocop Layout namespace
+  Exclude:
+    - 'lib/rubocop/cop/vicenzo/layout/**/*'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'rakelib/**/*'
+    - 'Rakefile'
+
 Naming/FileName:
   Exclude:
     - lib/rubocop-vicenzo.rb

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-28
+
+- Add RuboCop::Cop::Vicenzo::RSpec::ConditionalInSpec #19;
+- Add RuboCop::Cop::Vicenzo::RSpec::DynamicExampleGeneration #19;
+- Add RuboCop::Cop::Vicenzo::RSpec::IterationInsideExample #19;
+
+## [0.3.0] - 2025-12-17
+
+- Add RuboCop::Cop::Vicenzo::Layout::MultilineMethodCallLineBreaks #12;
+- Add RuboCop::Cop::Vicenzo::Style::MultilineMethodCallParentheses #13;
+- Add `AllowedMethods` configuration to `Vicenzo/Style/MultilineMethodCallParentheses` to allow excluding specific methods (e.g., RSpec DSLs like `to` and `change`) from the rule #15;
+
 ## [0.2.0] - 2025-11-27
 
 - Remove RuboCop::Cop::Vicenzo::RSpec::MixedExampleGroups in favor of InconsistentSiblingStructure #10;

data/README.md

@@ -2,6 +2,8 @@
 
 [![Ruby](https://github.com/bvicenzo/rubocop-vicenzo/actions/workflows/main.yml/badge.svg)](https://github.com/bvicenzo/rubocop-vicenzo/actions/workflows/main.yml)
 
+📖 **[Documentation](https://bvicenzo.github.io/rubocop-vicenzo)**
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -55,6 +57,33 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Documentation
+
+The documentation site is built with [Antora](https://antora.org) and published automatically to GitHub Pages on every new release.
+
+To build it locally, you will need [Node.js](https://nodejs.org) (v20+) installed. Then install Antora:
+
+```bash
+npm install -g @antora/cli @antora/site-generator
+```
+
+Generate the AsciiDoc pages from the cop sources and build the site:
+
+```bash
+bundle exec rake docs:generate
+antora antora-playbook.yml
+```
+
+The site will be available at `build/site/index.html`.
+
+### Generate binstubs
+
+If you want is possible change the command `bundle exec something` by `bin/something` generating binstubs
+
+```bash
+bundle binstubs rake rspec-core rubocop
+```
+
 ### Creating a new cop
 
 ```bash

data/antora-playbook.yml

@@ -0,0 +1,15 @@
+site:
+  title: RuboCop Vicenzo
+  url: https://bvicenzo.github.io/rubocop-vicenzo
+
+content:
+  sources:
+    - url: .
+      branches: HEAD
+      start_path: docs
+
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files: ./docs/supplemental-ui

data/config/default.yml

@@ -1,15 +1,45 @@
+Vicenzo/Layout/MultilineMethodCallLineBreaks:
+  Description: 'Enforces that method calls in a multiline chain must each be on their own line.'
+  Enabled: true
+  Severity: convention
+  IndentationWidth: 2
+  VersionAdded: '0.3.0'
+
 Vicenzo/Rails/EnumInclusionOfValidation:
   Description: 'Check if the enum has the inclusion of validation defined.'
   Enabled: true
   Severity: convention
   VersionAdded: '0.1.0'
 
+Vicenzo/RSpec/ConditionalInSpec:
+  Description: 'Do not use conditional logic in specs. Extract each branch into an explicit context instead.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.4.0'
+
+Vicenzo/RSpec/DynamicExampleGeneration:
+  Description: 'Do not use iteration to dynamically generate example groups or examples.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.4.0'
+
 Vicenzo/RSpec/InconsistentSiblingStructure:
   Description: 'Enforces strict structural consistency (e.g. prevents mixing describe with context or examples with groups).'
   Enabled: true
   Severity: warning
   VersionAdded: '0.2.0'
 
+Vicenzo/RSpec/IterationInsideExample:
+  Description: 'Do not call `expect` inside an iteration within an example.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.4.0'
+
 Vicenzo/RSpec/NestedContextImproperStart:
   Description: 'Check if the nested context does not start as a root one.'
   Enabled: true
@@ -38,3 +68,9 @@ Vicenzo/RSpec/LeakyDefinition:
   Exclude:
     - '**/spec/support/**/*'
     - '**/spec/factories/**/*'
+
+Vicenzo/Style/MultilineMethodCallParentheses:
+  Description: 'Enforces parentheses for method calls with arguments that span multiple lines.'
+  Enabled: true
+  AllowedMethods: []
+  VersionAdded: '0.3.0'

data/docs/antora.yml

@@ -0,0 +1,5 @@
+name: rubocop-vicenzo
+version: ~
+title: RuboCop Vicenzo
+nav:
+  - modules/ROOT/nav.adoc

data/docs/supplemental-ui/partials/header-content.hbs

@@ -0,0 +1,14 @@
+<header class="header">
+  <nav class="navbar">
+    <div class="navbar-brand">
+      <a class="navbar-item" href="{{{or site.url siteRootPath}}}">{{site.title}}</a>
+      {{#if env.SITE_SEARCH_PROVIDER}}
+      <div class="navbar-item search hide-for-print">
+        <div id="search-field" class="field">
+          <input id="search-input" type="text" placeholder="Search the docs"{{#if page.home}} autofocus{{/if}}>
+        </div>
+      </div>
+      {{/if}}
+    </div>
+  </nav>
+</header>

data/lib/rubocop/cop/vicenzo/layout/multiline_method_call_line_breaks.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module Layout
+        # Enforces that method calls in a multiline chain are each on their own line.
+        #
+        # If a method chain spans more than one line, this cop ensures that every
+        # call in the chain is placed on a new line. It prevents "mixed" styles
+        # where some methods are on the same line as the receiver while others are broken.
+        #
+        # @example
+        #   # bad
+        #   object.method_one
+        #     .method_two
+        #
+        #   # bad
+        #   object
+        #     .method_one.method_two
+        #     .method_three
+        #
+        #   # good - single line chain
+        #   object.method_one.method_two
+        #
+        #   # good - multiline chain
+        #   object
+        #     .method_one
+        #     .method_two
+        #
+        #   # good - arguments causing the break (if configured implicitly)
+        #   object.method_one(
+        #     arg1,
+        #     arg2
+        #   ).method_two
+        #
+        # ## Configuration
+        #
+        # This cop allows you to customize the indentation width used during auto-correction.
+        # The default width is 2 spaces relative to the previous line.
+        #
+        # ```yaml
+        # CustomCops/MultilineMethodCallLineBreaks:
+        #   IndentationWidth: 4 # (default is 2)
+        # ```
+        #
+        class MultilineMethodCallLineBreaks < Base
+          extend RuboCop::Cop::AutoCorrector
+
+          MSG = 'Method calls in a multiline chain must each be on their own line.'
+          DEFAULT_INDENTATION_WIDTH = 2
+          LEADING_SPACES_PATTERN = /\A */
+          CHAIN_START_PATTERN = /\A\s*&?\./
+
+          OPERATOR_METHODS = %i[[] []= + - * / % ** << >>].freeze
+
+          def on_send(node)
+            check_node(node)
+          end
+          alias on_csend on_send
+
+          private
+
+          def check_node(node)
+            return if part_of_larger_chain?(node)
+            return if single_line_chain?(node)
+
+            check_chain_structure(node)
+          end
+
+          def check_chain_structure(node)
+            current = node
+
+            while current.call_type?
+              receiver = current.receiver
+              break unless receiver
+
+              check_violation(current, receiver)
+              current = receiver
+            end
+          end
+
+          def check_violation(node, receiver)
+            return unless same_line?(receiver, node)
+            return if valid_same_line_exception?(node)
+
+            add_offense(offense_range(node)) do |corrector|
+              break_line_before_dot(corrector, node, receiver)
+            end
+          end
+
+          def valid_same_line_exception?(node)
+            arguments_cause_multiline?(node) || operator_method?(node)
+          end
+
+          def operator_method?(node)
+            OPERATOR_METHODS.include?(node.method_name)
+          end
+
+          def part_of_larger_chain?(node)
+            parent = node.parent
+            parent&.call_type? && parent.receiver == node
+          end
+
+          def single_line_chain?(node)
+            root = root_node(node)
+            root.loc.last_line == node.loc.last_line
+          end
+
+          def root_node(node)
+            current = node
+            current = current.receiver while current.respond_to?(:receiver) && current.receiver
+            current
+          end
+
+          def same_line?(receiver, node)
+            receiver.loc.last_line == call_start_line(node)
+          end
+
+          def call_start_line(node)
+            node.loc.dot ? node.loc.dot.line : node.loc.selector.line
+          end
+
+          def arguments_cause_multiline?(node)
+            return false if node.arguments.empty?
+            return false if node.receiver.loc.last_line != call_start_line(node)
+
+            return false if node.receiver.call_type? && node.receiver.loc.dot
+
+            node.multiline?
+          end
+
+          def offense_range(node)
+            return node.loc.selector unless node.loc.dot
+            return node.loc.dot unless node.loc.selector
+
+            node.loc.dot.join(node.loc.selector)
+          end
+
+          def break_line_before_dot(corrector, node, receiver)
+            dot = node.loc.dot
+            return unless dot
+
+            last_line_index = receiver.loc.last_line - 1
+            last_line_source = processed_source.lines[last_line_index]
+
+            current_indentation = last_line_source[LEADING_SPACES_PATTERN].length
+
+            previous_line_is_chain = last_line_source.match?(CHAIN_START_PATTERN)
+            extra_indent = previous_line_is_chain ? 0 : indentation_width
+
+            indentation = ' ' * (current_indentation + extra_indent)
+
+            corrector.insert_before(dot, "\n#{indentation}")
+          end
+
+          def indentation_width
+            cop_config.fetch('IndentationWidth', DEFAULT_INDENTATION_WIDTH)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rails/enum_inclusion_of_validation.rb

@@ -7,27 +7,20 @@ module RuboCop
         # Ensures that enums using the new syntax include the
         # `validate: { allow_nil: true }` option.
         #
-        # ## Bad usage
+        # Old-style enums (keyword argument syntax) are ignored.
         #
-        # ```ruby
-        # enum :status, { active: 1, inactive: 0 }, suffix: true
-        # ```
+        # @example
+        #   # bad — missing validate option
+        #   enum :status, { active: 1, inactive: 0 }, suffix: true
         #
-        # ```ruby
-        # enum :status, { active: 1, inactive: 0 }, validate: true, suffix: true
-        # ```
+        #   # bad — validate option present but incorrect
+        #   enum :status, { active: 1, inactive: 0 }, validate: true, suffix: true
         #
-        # ## Good usage
+        #   # good
+        #   enum :status, { active: 1, inactive: 0 }, validate: { allow_nil: true }, suffix: true
         #
-        # ```ruby
-        # enum :status, { active: 1, inactive: 0 }, validate: { allow_nil: true }, suffix: true
-        # ```
-        #
-        # This cop does not enforce validation on enums using the old syntax:
-        #
-        # ```ruby
-        # enum status: { active: 1, inactive: 0 }
-        # ```
+        #   # ignored — old-style enum syntax
+        #   enum status: { active: 1, inactive: 0 }
         class EnumInclusionOfValidation < Base
           extend AutoCorrector
 

data/lib/rubocop/cop/vicenzo/rspec/conditional_in_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Do not use conditional logic in spec files.
+        #
+        # Any `if`, `unless`, or ternary expression in a spec represents a hidden
+        # context. Each branch should be an explicit `context` block so that the
+        # conditions and expectations are always clear and unconditional.
+        #
+        # @example
+        #   # bad — hidden context inside an example
+        #
+        #   it 'grants or denies access' do
+        #     if user.admin?
+        #       expect(result).to eq(:granted)
+        #     else
+        #       expect(result).to eq(:denied)
+        #     end
+        #   end
+        #
+        #   # bad — hidden context inside a let
+        #
+        #   let(:user) { admin? ? create(:admin) : create(:client) }
+        #
+        #   # bad — hidden context inside a before hook
+        #
+        #   before { setup_thing if feature_enabled? }
+        #
+        #   # bad — hidden context at the example group level using unless
+        #
+        #   unless legacy_mode?
+        #     it 'uses the new behaviour' do
+        #       ...
+        #     end
+        #   end
+        #
+        #   # good
+        #
+        #   context 'when user is admin' do
+        #     let(:user) { create(:admin) }
+        #
+        #     it 'grants access' do
+        #       expect(result).to eq(:granted)
+        #     end
+        #   end
+        #
+        #   context 'when user is not admin' do
+        #     let(:user) { create(:client) }
+        #
+        #     it 'denies access' do
+        #       expect(result).to eq(:denied)
+        #     end
+        #   end
+        class ConditionalInSpec < RuboCop::Cop::RSpec::Base
+          MSG = 'Do not use conditional logic in specs. ' \
+                'Extract each branch into an explicit context instead.'
+
+          # Both `if` and `unless` are represented as `if` nodes in the AST,
+          # so this single hook covers all conditional forms: `if`, `unless`,
+          # modifier `if`/`unless`, and ternary `?:`.
+          def on_if(node)
+            offense_location = node.ternary? ? node : node.loc.keyword
+            add_offense(offense_location)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/dynamic_example_generation.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Do not use iteration to dynamically generate example groups or examples.
+        #
+        # Dynamic generation makes tests hard to find, hard to read, and creates
+        # pressure to add conditional logic (e.g. `if variable == :x`) when not
+        # all iterations share the same conditions. Write explicit, static contexts
+        # instead — one context per case.
+        #
+        # @example
+        #   # bad
+        #
+        #   [:admin, :driver].each do |role|
+        #     context "when role is #{role}" do
+        #       it 'does something' do
+        #         ...
+        #       end
+        #     end
+        #   end
+        #
+        #   # good
+        #
+        #   context 'when role is admin' do
+        #     let(:role) { :admin }
+        #
+        #     it 'does something' do
+        #       ...
+        #     end
+        #   end
+        #
+        #   context 'when role is driver' do
+        #     let(:role) { :driver }
+        #
+        #     it 'does something' do
+        #       ...
+        #     end
+        #   end
+        class DynamicExampleGeneration < RuboCop::Cop::RSpec::Base
+          MSG = 'Do not use iteration to dynamically generate example groups or examples. ' \
+                'Write explicit, static contexts instead.'
+
+          ENUMERATION_METHODS = %i[each each_with_index each_with_object map flat_map].freeze
+
+          EXAMPLE_GROUP_DSL = %i[
+            context describe feature experiment
+            it specify example scenario focus
+            let let! subject subject! before after around
+            shared_examples shared_context shared_examples_for
+          ].freeze
+
+          # @!method enumeration_block?(node)
+          def_node_matcher :enumeration_block?, <<~PATTERN
+            (block
+              (send _ {#{ENUMERATION_METHODS.map(&:inspect).join(' ')}} ...)
+              ...)
+          PATTERN
+
+          # @!method example_group_dsl_call?(node)
+          def_node_matcher :example_group_dsl_call?, <<~PATTERN
+            (block (send nil? {#{EXAMPLE_GROUP_DSL.map(&:inspect).join(' ')}} ...) ...)
+          PATTERN
+
+          def on_block(node)
+            return unless enumeration_block?(node)
+            return unless contains_example_group_dsl?(node)
+
+            add_offense(node.send_node)
+          end
+
+          alias on_numblock on_block
+
+          private
+
+          def contains_example_group_dsl?(node)
+            node.body&.each_node(:block) do |child|
+              return true if example_group_dsl_call?(child)
+            end
+
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/iteration_inside_example.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Do not use `expect` inside an iteration within an example.
+        #
+        # Placing `expect` calls inside an iteration block (e.g. `each`) makes
+        # tests implicit and hard to debug: when the assertion fails it is unclear
+        # which element caused the failure, and not all elements may represent the
+        # same condition. Using iteration to build or transform data before calling
+        # `expect` is fine; the problem is calling `expect` inside the iteration.
+        # Write explicit assertions for each relevant case instead.
+        #
+        # @example
+        #   # bad — expect is called inside the iteration
+        #
+        #   it 'returns vehicle costs general values' do
+        #     response_body[:vehicle_costs].first.each do |attribute, value|
+        #       expect(value).to eq(vehicle_cost.send(attribute).to_s)
+        #     end
+        #   end
+        #
+        #   # good — iteration builds data, expect is called once outside
+        #
+        #   it 'returns the expected column names' do
+        #     columns = VehicleCost.column_names.map { |column| column.gsub('_centavos', '') }
+        #     expect(response_body[:vehicle_costs].first.keys).to match_array(columns.map(&:to_sym))
+        #   end
+        #
+        #   # good — each attribute has an explicit example
+        #
+        #   it 'returns the correct name' do
+        #     expect(response_body[:vehicle_costs].first[:name]).to eq(vehicle_cost.name)
+        #   end
+        #
+        #   it 'returns the correct value' do
+        #     expect(response_body[:vehicle_costs].first[:value]).to eq(vehicle_cost.value.to_s)
+        #   end
+        class IterationInsideExample < RuboCop::Cop::RSpec::Base
+          MSG = 'Do not call `expect` inside an iteration. ' \
+                'Write explicit assertions instead.'
+
+          ENUMERATION_METHODS = %i[each each_with_index each_with_object].freeze
+
+          # @!method enumeration_block?(node)
+          def_node_matcher :enumeration_block?, <<~PATTERN
+            (block
+              (send _ {#{ENUMERATION_METHODS.map(&:inspect).join(' ')}} ...)
+              ...)
+          PATTERN
+
+          def on_block(node)
+            return unless example?(node)
+
+            find_iterations_with_assertions(node.body)
+          end
+
+          alias on_numblock on_block
+
+          private
+
+          def find_iterations_with_assertions(body)
+            return unless body
+
+            body.each_node(:block) do |iteration|
+              next unless enumeration_block?(iteration)
+              next unless contains_expectation?(iteration.body)
+
+              add_offense(iteration.send_node)
+            end
+          end
+
+          def contains_expectation?(node)
+            return false unless node
+
+            node.each_node(:send).any? { |send_node| send_node.method?(:expect) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/style/multiline_method_call_parentheses.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module Style
+        # Enforces parentheses for method calls with arguments that span multiple lines.
+        # Single-line calls are ignored (parentheses are optional).
+        #
+        # This cop accepts an `AllowedMethods` configuration to exempt specific methods
+        # from this rule. This is particularly useful for Fluent DSLs (like RSpec's
+        # `to`, `change`, etc.) where parentheses might hurt readability or conflict
+        # with layout rules.
+        #
+        # @example
+        #   # bad
+        #   method_name arg1,
+        #               arg2
+        #
+        #   # good
+        #   method_name(arg1,
+        #               arg2)
+        #
+        #   # good (single line is always allowed)
+        #   method_name arg1, arg2
+        #
+        # @example AllowedMethods: ['to']
+        #   # good (allowed by configuration)
+        #   expect { action }.to change {
+        #     model.attribute
+        #   }
+        #
+        class MultilineMethodCallParentheses < Base
+          extend RuboCop::Cop::AutoCorrector
+          include RuboCop::Cop::RangeHelp
+
+          MSG = 'Use parentheses for method calls with arguments that span multiple lines.'
+
+          def on_send(node)
+            check_node(node)
+          end
+          alias on_csend on_send
+
+          private
+
+          def check_node(node)
+            return unless node.arguments?
+            return unless node.multiline?
+            return if node.parenthesized? || node.operator_method? || node.setter_method? || allowed_method?(node)
+
+            add_offense(node) do |corrector|
+              autocorrect(corrector, node)
+            end
+          end
+
+          def allowed_method?(node)
+            allowed_methods.include?(node.method_name.to_s)
+          end
+
+          def allowed_methods
+            cop_config.fetch('AllowedMethods', [])
+          end
+
+          def autocorrect(corrector, node)
+            if node.loc.selector
+              gap_range = range_between(node.loc.selector.end_pos, node.first_argument.source_range.begin_pos)
+              corrector.replace(gap_range, '(')
+            else
+              corrector.insert_before(node.first_argument, '(')
+            end
+
+            corrector.insert_after(node.last_argument, ')')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo_cops.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
+require_relative 'vicenzo/rspec/conditional_in_spec'
+require_relative 'vicenzo/rspec/dynamic_example_generation'
 require_relative 'vicenzo/rspec/inconsistent_sibling_structure'
+require_relative 'vicenzo/rspec/iteration_inside_example'
 require_relative 'vicenzo/rspec/nested_context_improper_start'
 require_relative 'vicenzo/rspec/nested_let_redefinition'
 require_relative 'vicenzo/rspec/nested_subject_redefinition'
 require_relative 'vicenzo/rspec/leaky_definition'
 require_relative 'vicenzo/rails/enum_inclusion_of_validation'
+require_relative 'vicenzo/layout/multiline_method_call_line_breaks'
+require_relative 'vicenzo/style/multiline_method_call_parentheses'

data/lib/rubocop/vicenzo/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Vicenzo
-    VERSION = '0.2.0'
+    VERSION = '0.4.0'
   end
 end

data/rakelib/docs.rake

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+
+DOCS_PAGES_DIR = 'docs/modules/ROOT/pages'
+DOCS_NAV_FILE  = 'docs/modules/ROOT/nav.adoc'
+
+CAMEL_BOUNDARIES_UPPER_PATTERN  = /(?<leading_caps>[A-Z]+)(?<next_word>[A-Z][a-z])/
+CAMEL_BOUNDARIES_LOWER_PATTERN  = /(?<word_end>[a-z\d])(?<word_start>[A-Z])/
+CLASS_DECLARATION_PATTERN       = /^\s+class\s/
+COMMENT_LINE_PATTERN            = /^\s+#/
+EXAMPLE_TAG_PATTERN             = /^\s+#\s+@example(.*)/
+EXAMPLE_CODE_INDENT_PATTERN     = /^\s+#\s{0,3}/
+ANCHOR_INVALID_CHARS_PATTERN    = /[^a-z0-9-]/
+
+namespace :docs do
+  desc 'Generate AsciiDoc documentation for all Vicenzo cops'
+  task :generate do
+    FileUtils.mkdir_p(DOCS_PAGES_DIR)
+
+    default_config = YAML.load_file('config/default.yml')
+    cop_data = default_config.keys.map { |name| build_cop_data(name, default_config) }
+
+    cops_by_dept = cop_data.group_by { |cop| cop[:department] }
+
+    cops_by_dept.sort.each do |department, cops|
+      content  = render_department_page(department, cops.sort_by { |cop| cop[:name] })
+      filename = "cops_#{department.downcase}.adoc"
+      File.write(File.join(DOCS_PAGES_DIR, filename), content)
+      puts "  Generated: #{filename} (#{cops.size} cop#{'s' if cops.size != 1})"
+    end
+
+    write_index(cop_data)
+    write_nav(cops_by_dept)
+    puts "\nDone. #{cop_data.size} cops documented across #{cops_by_dept.size} departments."
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Data extraction
+# ---------------------------------------------------------------------------
+
+def build_cop_data(cop_name, default_config)
+  config = default_config[cop_name] || {}
+  source = read_cop_source(cop_name)
+  cop_data_hash(cop_name, config, source)
+end
+
+def cop_data_hash(cop_name, config, source)
+  {
+    name: cop_name,
+    department: cop_name.split('/')[1],
+    description: config['Description'] || '',
+    version: config['VersionAdded'] || '-',
+    enabled: config.fetch('Enabled', true),
+    autocorrect: source ? autocorrect?(source) : false,
+    examples: source ? extract_examples(source) : [],
+    config_keys: extra_config_keys(config)
+  }
+end
+
+def read_cop_source(cop_name)
+  path = cop_name_to_path(cop_name)
+  File.exist?(path) ? File.read(path) : nil
+end
+
+def cop_name_to_path(cop_name)
+  parts = cop_name.split('/')
+  dept  = parts[1].downcase
+  klass = underscore(parts[2])
+  "lib/rubocop/cop/vicenzo/#{dept}/#{klass}.rb"
+end
+
+def underscore(str)
+  str
+    .gsub(CAMEL_BOUNDARIES_UPPER_PATTERN, '\k<leading_caps>_\k<next_word>')
+    .gsub(CAMEL_BOUNDARIES_LOWER_PATTERN, '\k<word_end>_\k<word_start>')
+    .downcase
+end
+
+def autocorrect?(source)
+  source.include?('AutoCorrector')
+end
+
+def extract_examples(source)
+  docstring = extract_docstring(source)
+  parse_examples(docstring)
+end
+
+def extract_docstring(source)
+  lines = []
+  source.each_line do |line|
+    break if CLASS_DECLARATION_PATTERN.match?(line)
+
+    lines << line if COMMENT_LINE_PATTERN.match?(line)
+  end
+  lines
+end
+
+def parse_examples(docstring_lines)
+  examples = []
+  current = nil
+  docstring_lines.each do |line|
+    examples, current = update_examples(line, examples, current)
+  end
+  finalize_examples(examples, current)
+end
+
+def update_examples(line, examples, current)
+  if line =~ EXAMPLE_TAG_PATTERN
+    examples << current if current
+    [examples, { title: Regexp.last_match(1).strip, code: [] }]
+  elsif current
+    current[:code] << line.sub(EXAMPLE_CODE_INDENT_PATTERN, '').rstrip
+    [examples, current]
+  else
+    [examples, current]
+  end
+end
+
+def finalize_examples(examples, current)
+  examples << current if current
+  examples.each { |example| example[:code].pop while example[:code].last&.empty? }
+  examples
+end
+
+def extra_config_keys(config)
+  skip = %w[Description Enabled Severity VersionAdded Include Exclude Safe]
+  config.except(*skip)
+end
+
+# ---------------------------------------------------------------------------
+# AsciiDoc rendering
+# ---------------------------------------------------------------------------
+
+def render_department_page(department, cops)
+  lines = ["= Vicenzo/#{department}", ':toc: left', ':toc-title: Cops', ':toclevels: 1', '']
+  cops.each { |cop| lines.concat(render_cop(cop)) }
+  lines.join("\n")
+end
+
+def render_cop(cop)
+  lines = ["== #{cop[:name]}", '', cop[:description], '']
+  lines.concat(render_metadata_table(cop))
+  lines.concat(render_all_examples(cop[:examples]))
+  lines.concat(render_config_keys(cop[:config_keys])) unless cop[:config_keys].empty?
+  lines.push("'''", '')
+end
+
+def render_all_examples(examples)
+  examples.each_with_index.flat_map { |example, index| render_example(example, index) }
+end
+
+def render_metadata_table(cop)
+  enabled     = cop[:enabled] ? 'Enabled' : 'Disabled'
+  autocorrect = cop[:autocorrect] ? 'Yes' : 'No'
+  ['[cols="1,1,1,1"]', '|===', '| Enabled by default | Safe | Supports autocorrection | Version Added',
+   '', "| #{enabled}", '| Yes', "| #{autocorrect}", "| #{cop[:version]}", '|===', '']
+end
+
+def render_example(example, index)
+  title = if example[:title].empty?
+            index.zero? ? 'Example' : "Example #{index + 1}"
+          else
+            example[:title]
+          end
+  ["=== #{title}", '', '[source,ruby]', '----', *example[:code], '----', '']
+end
+
+def render_config_keys(config_keys)
+  lines = ['=== Configurable attributes', '', '[cols="1,1"]', '|===', '| Name | Default value', '']
+  config_keys.each { |key, value| lines.push("| #{key}", "| `#{value.inspect}`", '') }
+  lines.push('|===', '')
+end
+
+# ---------------------------------------------------------------------------
+# Index and navigation
+# ---------------------------------------------------------------------------
+
+def write_index(cop_data)
+  lines = index_header_lines + index_cops_table_lines(cop_data)
+  File.write(File.join(DOCS_PAGES_DIR, 'index.adoc'), lines.join("\n"))
+  puts '  Generated: index.adoc'
+end
+
+def index_header_lines
+  ['= RuboCop Vicenzo', ':toc: left', ''] +
+    ['Custom RuboCop cops for enforcing conventions adopted by Vicenzo projects.', ''] +
+    installation_section_lines +
+    ['== Cops', '', '[cols="2,1,1"]', '|===', '| Cop | Department | Version Added', '']
+end
+
+def installation_section_lines
+  ['== Installation', ''] +
+    gemfile_installation_lines +
+    rubocop_yml_installation_lines
+end
+
+def gemfile_installation_lines
+  ['Add to your `Gemfile`:', '', '[source,ruby]', '----',
+   "gem 'rubocop-vicenzo', require: false", '----', '']
+end
+
+def rubocop_yml_installation_lines
+  ['Then add to your `.rubocop.yml`:', '', '[source,yaml]', '----',
+   'plugins:', '  - rubocop-vicenzo', '----', '']
+end
+
+def index_cops_table_lines(cop_data)
+  lines = cop_data.sort_by { |cop| cop[:name] }.map do |cop|
+    dept     = cop[:department]
+    filename = "cops_#{dept.downcase}.adoc"
+    anchor   = cop[:name].downcase.tr('/', '-').gsub(ANCHOR_INVALID_CHARS_PATTERN, '')
+    "| xref:#{filename}##{anchor}[#{cop[:name]}] | #{dept} | #{cop[:version]}"
+  end
+  lines.push('|===', '')
+end
+
+def write_nav(cops_by_dept)
+  lines = ['* xref:index.adoc[Home]', '* Cops']
+  cops_by_dept
+    .sort
+    .each { |department, _cops| lines << "** xref:cops_#{department.downcase}.adoc[#{department}]" }
+  File.write(DOCS_NAV_FILE, "#{lines.join("\n")}\n")
+  puts '  Generated: nav.adoc'
+end

data/rakelib/release.rake

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'date'
+
+desc 'Prepare release: update config, version file, and changelog'
+task :cut_release, [:version] do |_t, args|
+  version = args[:version]
+
+  # 1. Validation
+  abort 'Error: You must provide a version. Example: rake cut_release[0.3.0]' unless version
+
+  config_file    = 'config/default.yml'
+  version_file   = 'lib/rubocop/vicenzo/version.rb'
+  changelog_file = 'CHANGELOG.md'
+
+  # Check if files exist
+  [config_file, version_file, changelog_file].each do |file|
+    abort "Error: File not found at #{file}" unless File.exist?(file)
+  end
+
+  puts "✂️  Cutting release for version #{version}..."
+
+  # -------------------------------------------------------
+  # 2. Update config/default.yml (<<next>> -> version)
+  # -------------------------------------------------------
+  config_content = File.read(config_file)
+  if config_content.include?("'<<next>>'")
+    updated_config = config_content.gsub("'<<next>>'", "'#{version}'")
+    File.write(config_file, updated_config)
+    puts "   ✅ Updated 'VersionAdded' in #{config_file}"
+  else
+    puts "   ⚠️  No '<<next>>' found in #{config_file} (skipping)"
+  end
+
+  # -------------------------------------------------------
+  # 3. Update lib/rubocop/vicenzo/version.rb
+  # -------------------------------------------------------
+  version_content = File.read(version_file)
+  # Regex looks for: VERSION = '...' or VERSION = "..."
+  if version_content.match?(/VERSION\s*=\s*['"](.+)['"]/)
+    updated_version = version_content.gsub(/VERSION\s*=\s*['"](.+)['"]/, "VERSION = '#{version}'")
+    File.write(version_file, updated_version)
+    puts "   ✅ Updated VERSION constant in #{version_file}"
+  else
+    puts "   ❌ Could not find VERSION constant in #{version_file}"
+  end
+
+  # -------------------------------------------------------
+  # 4. Update CHANGELOG.md
+  # -------------------------------------------------------
+  changelog_content = File.read(changelog_file)
+  unreleased_header = '## [Unreleased]'
+  date = Date.today.to_s # YYYY-MM-DD
+
+  # We replace "## [Unreleased]" with:
+  # ## [Unreleased]
+  #
+  # ## [version] - date
+  #
+  # This pushes the existing unreleased items down under the new version header.
+  new_entry_header = "#{unreleased_header}\n\n## [#{version}] - #{date}"
+
+  if changelog_content.include?(unreleased_header)
+    # We use 'sub' to replace only the first occurrence (the top one)
+    updated_changelog = changelog_content.sub(unreleased_header, new_entry_header)
+    File.write(changelog_file, updated_changelog)
+    puts "   ✅ Updated #{changelog_file} (moved items to [#{version}])"
+  else
+    puts "   ❌ Could not find '#{unreleased_header}' in #{changelog_file}"
+  end
+
+  puts "\n🎉 Release preparation complete! Don't forget to commit."
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-vicenzo
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Bruno Vicenzo
@@ -66,18 +66,28 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- antora-playbook.yml
 - config/default.yml
+- docs/antora.yml
+- docs/supplemental-ui/partials/header-content.hbs
 - lib/rubocop-vicenzo.rb
+- lib/rubocop/cop/vicenzo/layout/multiline_method_call_line_breaks.rb
 - lib/rubocop/cop/vicenzo/rails/enum_inclusion_of_validation.rb
+- lib/rubocop/cop/vicenzo/rspec/conditional_in_spec.rb
+- lib/rubocop/cop/vicenzo/rspec/dynamic_example_generation.rb
 - lib/rubocop/cop/vicenzo/rspec/inconsistent_sibling_structure.rb
+- lib/rubocop/cop/vicenzo/rspec/iteration_inside_example.rb
 - lib/rubocop/cop/vicenzo/rspec/leaky_definition.rb
 - lib/rubocop/cop/vicenzo/rspec/nested_context_improper_start.rb
 - lib/rubocop/cop/vicenzo/rspec/nested_let_redefinition.rb
 - lib/rubocop/cop/vicenzo/rspec/nested_subject_redefinition.rb
+- lib/rubocop/cop/vicenzo/style/multiline_method_call_parentheses.rb
 - lib/rubocop/cop/vicenzo_cops.rb
 - lib/rubocop/vicenzo.rb
 - lib/rubocop/vicenzo/plugin.rb
 - lib/rubocop/vicenzo/version.rb
+- rakelib/docs.rake
+- rakelib/release.rake
 - sig/rubocop/vicenzo.rbs
 homepage: https://github.com/bvicenzo/rubocop-vicenzo
 licenses:
@@ -103,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Cops of Bruno Vicenzo
 test_files: []