rubocop-aaa 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88bb8909e976646d38fa8d819807e978ad8e2db91592ee69fe1e8f848dc13692
+  data.tar.gz: 84ae0416f47272ccdcf38fc48b55c060106b96cff1b5828075da5aaf4886140a
+SHA512:
+  metadata.gz: 5eea4bdadc3cbc5755f3c40d300dc188df672d20032c2781fd832d65c5fe795f020e1834c288acf271492450933d7f5ff9938b2bcbce28ab9e51749a60a979a3
+  data.tar.gz: 6a8e83b998e8e385064ee34311bd280ea9c6ae251a2ed4a9ad081790e564233283052ae4221a4d163340a04894d14001af6d8ef82cfb1d517b166802f9be2b80

data/README.md

@@ -0,0 +1,88 @@
+# rubocop-aaa
+
+RuboCop cop that enforces the **Arrange-Act-Assert** pattern in Ruby test code.
+
+## Install
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem 'rubocop-aaa', require: false
+end
+```
+
+## Usage
+
+Enable the cop in your `.rubocop.yml`:
+
+```yaml
+require:
+  - rubocop-aaa
+
+AAA/Pattern:
+  Enabled: true
+  Include:
+    - 'spec/**/*.rb'
+    - 'test/**/*.rb'
+```
+
+## What it checks
+
+Every test block (`it`, `test`, `specify`, `example` by default) must contain three marker comments in order:
+
+```ruby
+it 'adds' do
+  # arrange
+  a = 1
+  b = 2
+
+  # act
+  sum = a + b
+
+  # assert
+  expect(sum).to eq(3)
+end
+```
+
+## Configuration
+
+```yaml
+AAA/Pattern:
+  TestFunctions:
+    - it
+    - test
+    - specify
+    - example
+  Labels:
+    arrange: [arrange]
+    act:     [act]
+    assert:  [assert]
+  CaseSensitive: false
+  AllowEmptySection: true
+```
+
+### Given / When / Then
+
+```yaml
+AAA/Pattern:
+  Labels:
+    arrange: [given]
+    act:     [when]
+    assert:  [then]
+```
+
+### Japanese
+
+Japanese phrasing varies, so no preset ships — configure with the wording your team uses:
+
+```yaml
+AAA/Pattern:
+  Labels:
+    arrange: [準備, 前準備]
+    act:     [実行]
+    assert:  [検証, 確認]
+```
+
+## License
+
+MIT

data/config/default.yml

@@ -0,0 +1,21 @@
+AAA/Pattern:
+  Description: 'Enforce Arrange-Act-Assert comments in test blocks.'
+  Enabled: true
+  VersionAdded: '0.0.1'
+  Include:
+    - 'spec/**/*.rb'
+    - 'test/**/*.rb'
+  TestFunctions:
+    - it
+    - test
+    - specify
+    - example
+  Labels:
+    arrange:
+      - arrange
+    act:
+      - act
+    assert:
+      - assert
+  CaseSensitive: false
+  AllowEmptySection: true

data/lib/rubocop/cop/aaa/pattern.rb

@@ -0,0 +1,123 @@
+module RuboCop
+  module Cop
+    module AAA
+      class Pattern < Base
+        SECTIONS = %i[arrange act assert].freeze
+
+        MSG_MISSING = 'Missing "%<section>s" comment in test block.'.freeze
+        MSG_ORDER   = 'AAA comments must appear in order: arrange -> act -> assert.'.freeze
+        MSG_EMPTY   = 'Section "%<section>s" has no statements.'.freeze
+
+        DEFAULT_LABELS = {
+          'arrange' => %w[arrange],
+          'act'     => %w[act],
+          'assert'  => %w[assert]
+        }.freeze
+
+        DEFAULT_TEST_FUNCTIONS = %w[it test specify example].freeze
+
+        def on_block(node)
+          return unless test_method?(node.method_name)
+
+          found = collect_sections(node)
+          seen = {}
+          found.each { |section, comment| seen[section] ||= comment }
+
+          SECTIONS.each do |section|
+            unless seen[section]
+              add_offense(node, message: format(MSG_MISSING, section: section))
+              return
+            end
+          end
+
+          ordered = SECTIONS.map { |s| seen[s] }
+          (1...ordered.size).each do |i|
+            if ordered[i].loc.expression.begin_pos < ordered[i - 1].loc.expression.begin_pos
+              add_offense(ordered[i], message: MSG_ORDER)
+              return
+            end
+          end
+
+          return if allow_empty_section?
+
+          check_empty_sections(node, seen)
+        end
+        alias on_numblock on_block
+
+        private
+
+        def collect_sections(node)
+          block_range = node.loc.expression
+          processed_source.comments.each_with_object([]) do |comment, acc|
+            pos = comment.loc.expression.begin_pos
+            next unless pos > block_range.begin_pos && pos < block_range.end_pos
+
+            section = match_section(comment_body(comment))
+            acc << [section, comment] if section
+          end
+        end
+
+        def check_empty_sections(node, seen)
+          block_end = node.loc.end.begin_pos
+          boundaries = [
+            [:arrange, seen[:arrange].loc.expression.end_pos, seen[:act].loc.expression.begin_pos],
+            [:act,     seen[:act].loc.expression.end_pos,     seen[:assert].loc.expression.begin_pos],
+            [:assert,  seen[:assert].loc.expression.end_pos,  block_end]
+          ]
+
+          boundaries.each do |section, start_pos, end_pos|
+            next if has_code_between?(start_pos, end_pos)
+
+            add_offense(seen[section], message: format(MSG_EMPTY, section: section))
+          end
+        end
+
+        def has_code_between?(start_pos, end_pos)
+          return false if start_pos >= end_pos
+
+          between = processed_source.raw_source[start_pos...end_pos].to_s
+          between.each_line.any? do |line|
+            stripped = line.strip
+            !stripped.empty? && !stripped.start_with?('#')
+          end
+        end
+
+        def match_section(text)
+          normalized = case_sensitive? ? text : text.downcase
+          SECTIONS.each do |section|
+            candidates = labels[section.to_s] || []
+            candidates.each do |label|
+              target = case_sensitive? ? label : label.downcase
+              return section if normalized == target
+            end
+          end
+          nil
+        end
+
+        def comment_body(comment)
+          comment.text.sub(/\A#\s*/, '').strip
+        end
+
+        def test_method?(name)
+          test_functions.include?(name.to_s)
+        end
+
+        def test_functions
+          cop_config.fetch('TestFunctions', DEFAULT_TEST_FUNCTIONS)
+        end
+
+        def labels
+          cop_config.fetch('Labels', DEFAULT_LABELS)
+        end
+
+        def case_sensitive?
+          cop_config.fetch('CaseSensitive', false)
+        end
+
+        def allow_empty_section?
+          cop_config.fetch('AllowEmptySection', true)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop-aaa.rb

@@ -0,0 +1,2 @@
+require 'rubocop'
+require_relative 'rubocop/cop/aaa/pattern'

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-aaa
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- babu-ch
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: A custom RuboCop cop that checks test blocks contain arrange/act/assert
+  comments in order.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- config/default.yml
+- lib/rubocop-aaa.rb
+- lib/rubocop/cop/aaa/pattern.rb
+homepage: https://babu-ch.github.io/aaa-lint/guide/rubocop
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://babu-ch.github.io/aaa-lint/guide/rubocop
+  source_code_uri: https://github.com/babu-ch/aaa-lint/tree/main/packages/rubocop-aaa
+  bug_tracker_uri: https://github.com/babu-ch/aaa-lint/issues
+  documentation_uri: https://babu-ch.github.io/aaa-lint/guide/rubocop
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: RuboCop cop enforcing the Arrange-Act-Assert pattern in test code.
+test_files: []