rubocop-view_component 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89e1184369a777c4428be4b9428e6ed7b8c9f21f1e17f4434afba8eabefa8651
-  data.tar.gz: 47a1c93267420a04a18d3bb9a160b4c3d956f3d1ac7d7ea119f144e779908ea7
+  metadata.gz: 60cf1f19ad3af3d8c80a7da526c8fcc77658723067e67bb42b6ce4bd97709302
+  data.tar.gz: ac9a362b04a16a58549e0733c72fbf874ae7ca954ce0509eac5fe763f00283c5
 SHA512:
-  metadata.gz: 0512f6877bba3a6d9091e51bd18a4e68912738614782bcf9dd435c86507f6add98cae4e9b3c98142ba9e6e204c603cbfb4b31812fee45d6497b005e58436d943
-  data.tar.gz: 866a844c2ee8e220aca9b9b553e29c73eba3c275a3fdb55344bf39b18ec4c4bbbe0f7d1a07fe9902ae0b0694e81f91b190ca44831816d121ec1bf36cb72c4536
+  metadata.gz: 7282cc87157b8b189a735b776cf93d48f9084b93a60a637e8a349806cef1706d1aa3581a308a2ccac21cdff7fe7613dd6fd0098c5d542493f2a98c87b8280bea
+  data.tar.gz: bc67d21c75e60619c11e75db291f602f8a9967a7b1c31041341207a4ccba72e9aafe3029fd1efdb9db2a60c36b68e4b961e7fe40c50bd50d8023958ea0472944

data/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a RuboCop extension that enforces ViewComponent best practices. It provides custom cops that detect anti-patterns and style issues specific to ViewComponent development.
+
+## Common Commands
+
+### Testing
+- `rake spec` - Run all RSpec tests
+- `bundle exec rspec spec/rubocop/cop/view_component/FILENAME_spec.rb` - Run a specific spec file
+- `rake standard` - Run Standard (RuboCop) linting
+- `rake` - Run both tests and linting (default task)
+
+### Verification
+The project includes a verification system that tests cops against real-world component libraries:
+
+- `script/verify primer` - Verify against Primer ViewComponents
+- `script/verify govuk` - Verify against x-govuk components
+- `script/verify polaris` - Verify against Polaris ViewComponents
+- `script/verify LIBRARY --regenerate` - Update expected results after intentional changes
+- `script/verify LIBRARY --update` - Force re-download latest library source
+
+### Development
+- `bundle exec rake new_cop[ViewComponent/CopName]` - Generate a new cop with template files
+
+## Code Architecture
+
+### Cop Structure
+
+All cops inherit from `RuboCop::Cop::Base` and are located in `lib/rubocop/cop/view_component/`. Each cop:
+
+1. Includes `ViewComponent::Base` module for shared helper methods
+2. Defines detection logic in `on_class`, `on_def`, or other AST node callbacks
+3. Has configuration in `config/default.yml`
+4. Has corresponding specs in `spec/rubocop/cop/view_component/`
+
+### Shared Modules
+
+**`ViewComponent::Base`** (`lib/rubocop/cop/view_component/base.rb`)
+- Provides `view_component_class?(node)` - Detects ViewComponent classes
+- Provides `view_component_parent?(node)` - Checks if inheriting from ViewComponent::Base, ApplicationComponent, or configured parent classes
+- Provides `inside_view_component?(node)` - Checks if code is within a ViewComponent
+
+**`TemplateAnalyzer`** (`lib/rubocop/cop/view_component/template_analyzer.rb`)
+- Used by PreferPrivateMethods cop to analyze ERB templates
+- Extracts method calls from templates to avoid flagging template-used methods as private candidates
+- Handles both sibling templates (`component.html.erb`) and sidecar templates (`component/component.html.erb`)
+- Uses the `herb` gem to parse ERB and extract Ruby code
+
+### Configuration
+
+The `AllCops` config supports `ViewComponentParentClasses` to configure additional base classes beyond `ViewComponent::Base` and `ApplicationComponent`:
+
+```yaml
+AllCops:
+  ViewComponentParentClasses:
+    - MyApp::BaseComponent
+```
+
+### Verification System
+
+The `script/verify` script downloads real component libraries, runs all ViewComponent cops, and compares results to checked-in snapshots. This catches regressions when cop behavior changes. Libraries are configured in `verification/libraries.yml`, downloaded to `verification/LIBRARY/`, and expected results stored in `spec/expected_LIBRARY_failures.json`.
+
+## Implementation Notes
+
+- When adding a new cop, use `rake new_cop[ViewComponent/CopName]` to generate the boilerplate
+- Template analysis is performance-sensitive - `PreferPrivateMethods` uses `herb` gem for efficient ERB parsing
+- Cops must handle graceful degradation when templates can't be parsed
+- All cops should include `ViewComponent::Base` module to get detection helpers

data/README.md

@@ -1,8 +1,6 @@
-# RuboCop::ViewComponent
+# rubocop-view_component
 
-> **Note:** This gem was vibe-coded and is not yet ready for real-world use. It's currently experimental and may have bugs or incomplete features. Contributions are welcome!
-
-A RuboCop extension that enforces [ViewComponent best practices](https://viewcomponent.org/best_practices.html).
+A RuboCop extension that encourages [ViewComponent best practices](https://viewcomponent.org/best_practices.html).
 
 ## Installation
 
@@ -27,32 +25,32 @@ This gem provides several cops to enforce ViewComponent best practices:
 - **ViewComponent/NoGlobalState** - Prevent direct access to `params`, `request`, `session`, etc.
 - **ViewComponent/PreferPrivateMethods** - Suggest making helper methods private (analyzes ERB templates to avoid flagging methods used in views)
 - **ViewComponent/PreferSlots** - Detect HTML parameters that should be slots
-- **ViewComponent/PreferComposition** - Discourage deep inheritance chains
+- **ViewComponent/PreferComposition** - Avoid inheriting one ViewComponent from another (prefer composition)
 - **ViewComponent/TestRenderedOutput** - Encourage testing rendered output over private methods
 
-See [PLAN.md](PLAN.md) for detailed cop descriptions and implementation status.
-
-## Usage
-
-Run RuboCop as usual:
-
-```bash
-bundle exec rubocop
-```
+## Optional Configuration
 
-## Configuration
+### Base Class
 
-By default, all cops detect classes that inherit from `ViewComponent::Base` or `ApplicationComponent`. If your project uses a different base class (e.g. `Primer::Component`), you can configure additional parent classes under `AllCops`:
+By default, the cops detect classes that inherit from `ViewComponent::Base` or `ApplicationComponent`. If your project uses a different base class (e.g. `Primer::Component`), you can configure additional parent classes under `AllCops`, for example:
 
 ```yaml
 # .rubocop.yml
 AllCops:
   ViewComponentParentClasses:
-    - Primer::Component
     - MyApp::BaseComponent
 ```
 
-This applies to all ViewComponent cops.
+### No Super
+
+View Component convention is to not calling `super` in component initializers, but that may cause `Lint/MissingSuper` failures from RuboCop. We suggest disabling that rule for your view components directory, for example:
+
+```yaml
+# .rubocop.yml
+Lint/MissingSuper:
+  Exclude:
+    - 'app/components/**/*'
+```
 
 ## Development
 
@@ -60,20 +58,70 @@ 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).
 
-## Primer Verification
+## Real-World Verification
+
+The cops are tested against real-world component libraries as baselines to catch regressions.
 
-The cops are tested against [primer/view_components](https://github.com/primer/view_components) as a real-world baseline, and to catch regressions. The script [`verify_against_primer.rb`](script/verify_against_primer.rb) copies the Primer repo, runs all ViewComponent cops against it, and compares the results to a checked-in snapshot ([`expected_primer_failures.json`](spec/expected_primer_failures.json)). This runs automatically in CI.
+The [`script/verify`](script/verify) script downloads component libraries (cached in `verification/`), runs all ViewComponent cops against them, and compares the results to checked-in snapshots. This runs automatically in CI.
 
-To verify locally:
+### Primer ViewComponents
+
+To verify against [primer/view_components](https://github.com/primer/view_components) locally:
 
 ```bash
-bundle exec ruby script/verify_against_primer.rb
+script/verify primer
 ```
 
 If you intentionally change cop behavior, regenerate the snapshot:
 
 ```bash
-bundle exec ruby script/verify_against_primer.rb --regenerate
+script/verify primer --regenerate
+```
+
+To force download the latest Primer source:
+
+```bash
+script/verify primer --update
+```
+
+### x-govuk Components
+
+To verify against [x-govuk/govuk-components](https://github.com/x-govuk/govuk-components) locally:
+
+```bash
+script/verify govuk
+```
+
+If you intentionally change cop behavior, regenerate the snapshot:
+
+```bash
+script/verify govuk --regenerate
+```
+
+To force download the latest x-govuk source:
+
+```bash
+script/verify govuk --update
+```
+
+### Polaris ViewComponents
+
+To verify against [baoagency/polaris_view_components](https://github.com/baoagency/polaris_view_components) locally:
+
+```bash
+script/verify polaris
+```
+
+If you intentionally change cop behavior, regenerate the snapshot:
+
+```bash
+script/verify polaris --regenerate
+```
+
+To force download the latest Polaris source:
+
+```bash
+script/verify polaris --update
 ```
 
 ## Contributing

data/config/default.yml

@@ -32,9 +32,26 @@ ViewComponent/PreferPrivateMethods:
   AllowedPublicMethodPatterns:
     - "^with_"
 
+ViewComponent/PreferComposition:
+  Description: 'Prefer composition over inheritance for ViewComponents.'
+  Enabled: true
+  VersionAdded: '0.3'
+  Severity: convention
+  StyleGuide: 'https://viewcomponent.org/best_practices.html'
+
 ViewComponent/PreferSlots:
   Description: 'Prefer slots over HTML string parameters.'
   Enabled: true
   VersionAdded: '0.1'
   Severity: convention
   StyleGuide: 'https://viewcomponent.org/best_practices.html'
+
+ViewComponent/TestRenderedOutput:
+  Description: 'Test rendered output instead of component instance methods.'
+  Enabled: true
+  VersionAdded: '0.3'
+  Severity: convention
+  StyleGuide: 'https://viewcomponent.org/guide/testing.html'
+  Include:
+    - 'spec/components/**/*_spec.rb'
+    - 'test/components/**/*_test.rb'

data/lib/rubocop/cop/view_component/prefer_composition.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ViewComponent
+      # Detects ViewComponent classes that inherit from another component
+      # instead of using composition. Inheriting one component from another
+      # causes confusion when each has its own template.
+      #
+      # @example
+      #   # bad
+      #   class UserCardComponent < BaseCardComponent
+      #   end
+      #
+      #   # good
+      #   class UserCardComponent < ViewComponent::Base
+      #     # Render BaseCardComponent within template via composition
+      #   end
+      #
+      class PreferComposition < RuboCop::Cop::Base
+        include ViewComponent::Base
+
+        MSG = "Avoid inheriting from another ViewComponent."
+
+        def on_class(node)
+          parent_class = node.parent_class
+          return unless parent_class
+          return if view_component_parent?(parent_class)
+          return unless component_like_parent?(parent_class)
+
+          add_offense(parent_class)
+        end
+
+        private
+
+        def component_like_parent?(node)
+          return false unless node.const_type?
+
+          node.source.end_with?("Component")
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/view_component/prefer_private_methods.rb

@@ -28,7 +28,7 @@ module RuboCop
         include ViewComponent::Base
         include TemplateAnalyzer
 
-        MSG = "Consider making this method private. " \
+        MSG = "Consider making `%<method_name>s` private. " \
               "Only ViewComponent interface methods should be public."
 
         def on_class(node)
@@ -59,7 +59,7 @@ module RuboCop
             next if allowed_public_method?(child.method_name)
             next if template_method_calls.include?(child.method_name)
 
-            add_offense(child)
+            add_offense(child, message: format(MSG, method_name: child.method_name))
           end
         end
 

data/lib/rubocop/cop/view_component/prefer_slots.rb

@@ -29,20 +29,7 @@ module RuboCop
         MSG = "Consider using `%<slot_method>s` instead of passing HTML " \
               "as a parameter. This maintains Rails' automatic HTML escaping."
 
-        HTML_PARAM_PATTERNS = [
-          /_html$/,
-          /_content$/,
-          /^html_/,
-          /^content$/
-        ].freeze
-
-        # Exclude common non-HTML parameters
-        EXCLUDED_PARAMS = %i[
-          html_class
-          html_classes
-          html_id
-          html_tag
-        ].freeze
+        HTML_PARAM_PATTERN = /_html$/
 
         def_node_search :html_safe_call?, "(send _ :html_safe)"
 
@@ -69,9 +56,6 @@ module RuboCop
 
             param_name = arg.children[0]
 
-            # Skip excluded parameters
-            next if EXCLUDED_PARAMS.include?(param_name)
-
             # Check parameter name patterns
             if html_param_name?(param_name)
               suggested_slot = suggest_slot_name(param_name)
@@ -88,15 +72,11 @@ module RuboCop
         end
 
         def html_param_name?(name)
-          HTML_PARAM_PATTERNS.any? { |pattern| pattern.match?(name.to_s) }
+          HTML_PARAM_PATTERN.match?(name.to_s)
         end
 
         def suggest_slot_name(param_name)
-          clean_name = param_name.to_s
-            .sub(/_html$/, "")
-            .sub(/_content$/, "")
-            .sub(/^html_/, "")
-
+          clean_name = param_name.to_s.sub(/_html$/, "")
           "renders_one :#{clean_name}"
         end
       end

data/lib/rubocop/cop/view_component/test_rendered_output.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ViewComponent
+      # Ensures that ViewComponent tests use `render_inline` to test rendered output
+      # rather than testing component methods directly.
+      #
+      # This cop is only enabled for test files by default (see config).
+      #
+      # @example
+      #   # bad
+      #   def test_formatted_title
+      #     component = TitleComponent.new("hello")
+      #     assert_equal "HELLO", component.formatted_title
+      #   end
+      #
+      #   # good
+      #   def test_formatted_title
+      #     render_inline TitleComponent.new("hello")
+      #     assert_text "HELLO"
+      #   end
+      #
+      class TestRenderedOutput < RuboCop::Cop::Base
+        MSG = "Test instantiates a component but doesn't use `render_inline` or `render_preview`. " \
+              "Test the rendered output instead of component methods directly."
+
+        # Check Minitest-style test methods
+        def on_def(node)
+          method_name = node.method_name.to_s
+          return unless method_name.start_with?("test_")
+          return unless instantiates_component?(node)
+          return if contains_render_method?(node)
+
+          add_offense(node)
+        end
+
+        # Check RSpec-style it blocks
+        def on_block(node)
+          return unless rspec_it_block?(node)
+          return unless instantiates_component?(node)
+          return if contains_render_method?(node)
+
+          add_offense(node)
+        end
+
+        private
+
+        def instantiates_component?(node)
+          node.each_descendant(:send).any? do |send_node|
+            next unless send_node.method_name == :new
+
+            send_node.receiver&.const_type?
+          end
+        end
+
+        def contains_render_method?(node)
+          node.each_descendant(:send).any? do |send_node|
+            %i[render_inline render_preview].include?(send_node.method_name)
+          end
+        end
+
+        def rspec_it_block?(node)
+          send_node = node.send_node
+          return false unless send_node
+
+          %i[it specify example].include?(send_node.method_name)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/view_component_cops.rb

@@ -4,4 +4,6 @@ require_relative "view_component/base"
 require_relative "view_component/component_suffix"
 require_relative "view_component/no_global_state"
 require_relative "view_component/prefer_private_methods"
+require_relative "view_component/prefer_composition"
 require_relative "view_component/prefer_slots"
+require_relative "view_component/test_rendered_output"

data/lib/rubocop/view_component/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module ViewComponent
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/script/verify

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "tmpdir"
+require "fileutils"
+require "open3"
+require "bundler"
+
+GEM_DIR = File.expand_path("..", __dir__)
+LIBRARIES_CONFIG = File.join(GEM_DIR, "verification", "libraries.yml")
+
+def load_libraries
+  config = YAML.load_file(LIBRARIES_CONFIG)
+
+  # Build full paths for each library
+  config.transform_values do |library|
+    library_key = config.key(library)
+    {
+      tarball_url: library["tarball_url"],
+      verification_dir: File.join(GEM_DIR, "verification", library_key),
+      config_file: File.join(GEM_DIR, "verification", "#{library_key}_rubocop_config.yml"),
+      results_file: File.join(GEM_DIR, "spec", "expected_#{library_key}_failures.json"),
+      display_name: library["display_name"]
+    }
+  end
+end
+
+def main
+  libraries = load_libraries
+  library = parse_library_arg(libraries)
+
+  config = libraries[library]
+  mode = ARGV.include?("--regenerate") ? :regenerate : :verify
+  force_update = ARGV.include?("--update")
+
+  if force_update && Dir.exist?(config[:verification_dir])
+    puts "Removing existing #{config[:display_name]} source for update..."
+    FileUtils.rm_rf(config[:verification_dir])
+  end
+
+  if Dir.exist?(config[:verification_dir]) && !Dir.empty?(config[:verification_dir])
+    puts "Using existing #{config[:display_name]} source at #{config[:verification_dir]}"
+  else
+    FileUtils.mkdir_p(config[:verification_dir])
+    download_source(config[:verification_dir], config[:tarball_url], config[:display_name])
+  end
+
+  Dir.chdir(config[:verification_dir]) do
+    configure_rubocop(config[:config_file], config[:display_name])
+    add_gem_to_gemfile
+
+    Bundler.with_unbundled_env do
+      output = run_rubocop
+      offenses = extract_offenses(output)
+
+      case mode
+      when :regenerate then regenerate(offenses, config[:results_file])
+      when :verify then verify(offenses, config[:results_file])
+      end
+    end
+  end
+end
+
+def parse_library_arg(libraries)
+  # Find the library argument (not --flags)
+  library_arg = ARGV.find { |arg| !arg.start_with?("--") }
+
+  if library_arg.nil?
+    abort "Usage: #{$PROGRAM_NAME} <library> [--regenerate] [--update]\n" \
+          "  library: #{libraries.keys.join(", ")}"
+  end
+
+  unless libraries.key?(library_arg)
+    abort "ERROR: Unknown library '#{library_arg}'. Valid options: #{libraries.keys.join(", ")}"
+  end
+
+  library_arg
+end
+
+def system!(*args)
+  system(*args, exception: true)
+end
+
+def download_source(dir, tarball_url, display_name)
+  puts "Downloading #{display_name}..."
+  system!("curl", "-sL", tarball_url, "-o", "#{dir}/source.tar.gz")
+  system!("tar", "xz", "-C", dir, "--strip-components=1", "-f", "#{dir}/source.tar.gz")
+end
+
+def configure_rubocop(config_file, display_name)
+  puts "Configuring .rubocop.yml with #{display_name} overrides..."
+  config = File.exist?(".rubocop.yml") ? YAML.load_file(".rubocop.yml") : {}
+  library_config = YAML.load_file(config_file)
+
+  # Merge the library config into the existing config
+  library_config.each do |key, value|
+    config[key] = if config[key].is_a?(Hash) && value.is_a?(Hash)
+      config[key].merge(value)
+    else
+      value
+    end
+  end
+
+  File.write(".rubocop.yml", YAML.dump(config))
+end
+
+def add_gem_to_gemfile
+  puts "Adding rubocop-view_component gem to Gemfile..."
+  File.open("Gemfile", "a") { |f| f.puts "gem 'rubocop-view_component', path: '#{GEM_DIR}'" }
+end
+
+def run_rubocop
+  puts "Running bundle install..."
+  system!("bundle", "install")
+
+  puts "Running RuboCop (ViewComponent cops only)..."
+  output, status = Open3.capture2(
+    "bundle", "exec", "rubocop",
+    "--require", "rubocop-view_component",
+    "--only", "ViewComponent",
+    "--format", "json"
+  )
+
+  puts "RuboCop exit status: #{status.exitstatus}"
+
+  if output.strip.empty?
+    abort "ERROR: RuboCop produced no output (exit status: #{status.exitstatus})"
+  end
+
+  output
+end
+
+def extract_offenses(rubocop_output)
+  data = JSON.parse(rubocop_output)
+  data["files"].flat_map do |file|
+    file["offenses"].map do |offense|
+      {
+        "path" => file["path"],
+        "line" => offense["location"]["start_line"],
+        "cop" => offense["cop_name"],
+        "message" => offense["message"]
+      }
+    end
+  end
+end
+
+def regenerate(offenses, results_file)
+  json = "#{JSON.pretty_generate(offenses)}\n"
+  File.write(results_file, json)
+  puts "#{offenses.length} offense(s) written to #{results_file}"
+end
+
+def verify(offenses, results_file)
+  unless File.exist?(results_file)
+    abort "ERROR: #{results_file} not found. Run '#{$PROGRAM_NAME} --regenerate' first."
+  end
+
+  current_json = JSON.pretty_generate(offenses)
+  expected_json = File.read(results_file)
+
+  if current_json.strip == expected_json.strip
+    puts "Verification passed: output matches #{results_file}"
+  else
+    puts "Verification failed: output differs from #{results_file}"
+    expected = JSON.parse(expected_json)
+    added = offenses - expected
+    removed = expected - offenses
+
+    added.each { |o| puts "  + #{o["cop"]}: #{o["path"]}:#{o["line"]}" }
+    removed.each { |o| puts "  - #{o["cop"]}: #{o["path"]}:#{o["line"]}" }
+
+    exit 1
+  end
+end
+
+main