rubocop-view_component 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d84d4738ad3da42500e46d9f0b2bb90160eb5501e6dc515fea63bf582917f1f1
-  data.tar.gz: 9376295000ba2f7c30e8f74e8c707371333e2681454ad402e4d33472f05576a7
+  metadata.gz: 89e1184369a777c4428be4b9428e6ed7b8c9f21f1e17f4434afba8eabefa8651
+  data.tar.gz: 47a1c93267420a04a18d3bb9a160b4c3d956f3d1ac7d7ea119f144e779908ea7
 SHA512:
-  metadata.gz: a4058fb7e22e45a737703dccb110560b2360f66010feccc9afde757ac8551351872cfb9a4cc0022d511c453eb96bfddcb6adde9ecf16426aba8bad34aa4ffc09
-  data.tar.gz: 27297ff15bb964213a7017cbb37920b5c8950570a405c654a18bcedb8d742a6c6f46a873fa7239653e5ed70b09360fccd36d4fbd670bb5c78385a55266608409
+  metadata.gz: 0512f6877bba3a6d9091e51bd18a4e68912738614782bcf9dd435c86507f6add98cae4e9b3c98142ba9e6e204c603cbfb4b31812fee45d6497b005e58436d943
+  data.tar.gz: 866a844c2ee8e220aca9b9b553e29c73eba3c275a3fdb55344bf39b18ec4c4bbbe0f7d1a07fe9902ae0b0694e81f91b190ca44831816d121ec1bf36cb72c4536

data/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,177 @@
+# Implementation Plan: Fix PreferPrivateMethods False Positives
+
+## Problem
+
+The `ViewComponent/PreferPrivateMethods` cop currently generates false positives by flagging methods that are called from ERB templates. In ViewComponent, methods called from templates must remain public, otherwise they cause runtime errors.
+
+## Solution Overview
+
+Use the `herb` gem to parse ERB templates and extract method calls. Only flag public methods that are NOT called from the component's template(s).
+
+## Implementation Steps
+
+### 1. Add herb Dependency
+
+**File:** `rubocop-view_component.gemspec`
+
+- Add `spec.add_dependency "herb", "~> 0.1"` (check latest stable version)
+
+### 2. Create Template Finder Helper
+
+**File:** `lib/rubocop/cop/view_component/template_analyzer.rb` (new)
+
+Create a module `TemplateAnalyzer` with:
+
+```ruby
+module TemplateAnalyzer
+  # Find template file(s) for a component
+  # Returns array of template file paths (can be empty)
+  def template_paths_for(component_file_path)
+    # Check for sibling template: same_name.html.erb
+    # Check for sidecar template: same_name/same_name.html.erb
+    # Handle variants: same_name.variant.html.erb
+  end
+
+  # Extract method calls from ERB template
+  def extract_method_calls(template_path)
+    # Use Herb.extract_ruby to get Ruby code
+    # Parse Ruby code with RuboCop's parser
+    # Traverse AST to find method calls (send nodes with nil receiver)
+    # Return Set of method names (symbols)
+  end
+end
+```
+
+**Implementation details:**
+
+- Use `File.exist?` to check for template files
+- Handle both naming conventions (sibling and sidecar)
+- Parse extracted Ruby code using `RuboCop::AST::ProcessedSource`
+- Traverse AST to find `send` nodes with `nil` receiver (local method calls)
+- Handle edge cases:
+  - Missing template (component uses `call` method)
+  - Multiple templates (variants)
+  - Parse errors in template
+
+### 3. Update PreferPrivateMethods Cop
+
+**File:** `lib/rubocop/cop/view_component/prefer_private_methods.rb`
+
+Modify the cop to:
+
+1. Include `TemplateAnalyzer` module
+2. In `check_public_methods`, find template paths using the component file path
+3. Extract method calls from all templates
+4. Skip offense if method is called from any template
+
+```ruby
+def check_public_methods(class_node)
+  current_visibility = :public
+  template_method_calls = methods_called_in_templates(class_node)
+
+  class_node.body&.each_child_node do |child|
+    # ... existing visibility tracking ...
+
+    next unless child.def_type?
+    next unless current_visibility == :public
+    next if ALLOWED_PUBLIC_METHODS.include?(child.method_name)
+    next if template_method_calls.include?(child.method_name)  # NEW
+
+    add_offense(child)
+  end
+end
+
+private
+
+def methods_called_in_templates(class_node)
+  component_path = processed_source.file_path
+  template_paths = template_paths_for(component_path)
+
+  template_paths.flat_map { |path| extract_method_calls(path) }.to_set
+rescue => e
+  # Log error and return empty set (graceful degradation)
+  Set.new
+end
+```
+
+### 4. Update Tests
+
+**File:** `spec/rubocop/cop/view_component/prefer_private_methods_spec.rb`
+
+Add new test contexts:
+
+1. **Methods called from template should NOT be flagged**
+   - Create fixture component + template
+   - Method is public and called in template
+   - Expect no offense
+
+2. **Methods NOT called from template should be flagged**
+   - Create fixture component + template
+   - Method is public but not used in template
+   - Expect offense
+
+3. **Component without template**
+   - Component has no template file
+   - Should fall back to current behavior (flag all non-interface methods)
+
+4. **Component with multiple templates (variants)**
+   - Component has multiple template files
+   - Method called in any template should not be flagged
+
+5. **Template with parse errors**
+   - Invalid ERB syntax
+   - Should gracefully degrade (don't flag any methods)
+
+**Fixture structure:**
+
+```
+spec/fixtures/components/
+  example_component.rb
+  example_component.html.erb
+  variant_component.rb
+  variant_component.html.erb
+  variant_component.phone.html.erb
+```
+
+### 5. Handle Edge Cases
+
+- **No template file**: Fall back to current behavior
+- **Invalid ERB**: Catch parse errors, log warning, skip template analysis
+- **Sidecar directories**: Check both naming conventions
+- **Variants**: Find all variant templates (*.html.erb, *.phone.html.erb, etc.)
+- **Conditional method calls**: `<%= foo if condition %>` - still counts as using `foo`
+- **Method chains**: `<%= user.name %>` - only `user` is a method call, not `name`
+- **Block parameters**: `<% items.each do |item| %>` - `item` is not a method
+
+### 6. Documentation Updates
+
+**File:** `README.md`
+
+Update the PreferPrivateMethods cop description to mention:
+- Now checks ERB templates for method usage
+- Only flags methods not called from templates
+- Requires templates to be in conventional locations
+
+## Testing Strategy
+
+1. Unit tests for `TemplateAnalyzer` methods
+2. Integration tests for the full cop with fixtures
+3. Manual testing on real ViewComponent codebases
+
+## Potential Issues
+
+1. **Performance**: Parsing templates for every component could be slow
+   - Mitigation: Cache template analysis results
+
+2. **Complex Ruby in ERB**: Nested blocks, conditionals, etc.
+   - Mitigation: Robust AST traversal
+
+3. **Dynamic method calls**: `send(:method_name)`, `public_send`, etc.
+   - Limitation: Won't detect these (acceptable trade-off)
+
+## Success Criteria
+
+- False positive rate drops from ~1,363 to near zero on the reported codebase
+- No new false negatives (methods that should be private but aren't flagged)
+- Tests pass
+- Performance acceptable (< 100ms per component)

data/README.md

@@ -1,5 +1,7 @@
 # RuboCop::ViewComponent
 
+> **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).
 
 ## Installation
@@ -23,7 +25,7 @@ This gem provides several cops to enforce ViewComponent best practices:
 
 - **ViewComponent/ComponentSuffix** - Enforce `-Component` suffix for ViewComponent classes
 - **ViewComponent/NoGlobalState** - Prevent direct access to `params`, `request`, `session`, etc.
-- **ViewComponent/PreferPrivateMethods** - Suggest making helper methods private
+- **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/TestRenderedOutput** - Encourage testing rendered output over private methods
@@ -38,12 +40,42 @@ Run RuboCop as usual:
 bundle exec rubocop
 ```
 
+## Configuration
+
+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`:
+
+```yaml
+# .rubocop.yml
+AllCops:
+  ViewComponentParentClasses:
+    - Primer::Component
+    - MyApp::BaseComponent
+```
+
+This applies to all ViewComponent cops.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 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
+
+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.
+
+To verify locally:
+
+```bash
+bundle exec ruby script/verify_against_primer.rb
+```
+
+If you intentionally change cop behavior, regenerate the snapshot:
+
+```bash
+bundle exec ruby script/verify_against_primer.rb --regenerate
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/andyw8/rubocop-view_component.

data/config/default.yml

@@ -1,15 +1,18 @@
+AllCops:
+  ViewComponentParentClasses: []
+
 ViewComponent/ComponentSuffix:
   Description: 'Enforce -Component suffix for ViewComponent classes.'
   Enabled: true
   VersionAdded: '0.1'
-  Severity: warning
+  Severity: convention
   StyleGuide: 'https://viewcomponent.org/best_practices.html'
 
 ViewComponent/NoGlobalState:
   Description: 'Avoid accessing global state (params, request, session, cookies, flash) directly.'
   Enabled: true
   VersionAdded: '0.1'
-  Severity: warning
+  Severity: convention
   StyleGuide: 'https://viewcomponent.org/best_practices.html'
 
 ViewComponent/PreferPrivateMethods:
@@ -24,10 +27,14 @@ ViewComponent/PreferPrivateMethods:
     - before_render
     - before_render_check
     - render?
+    - render_in
+    - around_render
+  AllowedPublicMethodPatterns:
+    - "^with_"
 
 ViewComponent/PreferSlots:
   Description: 'Prefer slots over HTML string parameters.'
   Enabled: true
   VersionAdded: '0.1'
-  Severity: warning
+  Severity: convention
   StyleGuide: 'https://viewcomponent.org/best_practices.html'

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

@@ -15,12 +15,16 @@ module RuboCop
           view_component_parent?(parent_class)
         end
 
-        # Check if node represents ViewComponent::Base or ApplicationComponent
+        # Check if node represents ViewComponent::Base, ApplicationComponent,
+        # or a configured additional parent class
         def view_component_parent?(node)
           return false unless node.const_type?
 
           source = node.source
-          source == "ViewComponent::Base" || source == "ApplicationComponent"
+          return true if source == "ViewComponent::Base" || source == "ApplicationComponent"
+
+          additional = config.for_all_cops["ViewComponentParentClasses"] || []
+          additional.include?(source)
         end
 
         # Find the enclosing class node

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "template_analyzer"
+
 module RuboCop
   module Cop
     module ViewComponent
@@ -24,18 +26,11 @@ module RuboCop
       #
       class PreferPrivateMethods < RuboCop::Cop::Base
         include ViewComponent::Base
+        include TemplateAnalyzer
 
         MSG = "Consider making this method private. " \
               "Only ViewComponent interface methods should be public."
 
-        ALLOWED_PUBLIC_METHODS = %i[
-          initialize
-          call
-          before_render
-          before_render_check
-          render?
-        ].freeze
-
         def on_class(node)
           return unless view_component_class?(node)
 
@@ -46,8 +41,14 @@ module RuboCop
 
         def check_public_methods(class_node)
           current_visibility = :public
+          template_method_calls = methods_called_in_templates
+
+          body = class_node.body
+          return unless body
+
+          children = body.begin_type? ? body.children : [body]
 
-          class_node.body&.each_child_node do |child|
+          children.each do |child|
             if visibility_modifier?(child)
               current_visibility = child.method_name
               next
@@ -55,12 +56,40 @@ module RuboCop
 
             next unless child.def_type?
             next unless current_visibility == :public
-            next if ALLOWED_PUBLIC_METHODS.include?(child.method_name)
+            next if allowed_public_method?(child.method_name)
+            next if template_method_calls.include?(child.method_name)
 
             add_offense(child)
           end
         end
 
+        def allowed_public_method?(method_name)
+          allowed_public_methods.include?(method_name.to_s) ||
+            allowed_public_method_patterns.any? { |pattern| method_name.to_s.match?(pattern) }
+        end
+
+        def allowed_public_methods
+          cop_config.fetch("AllowedPublicMethods", [])
+        end
+
+        def allowed_public_method_patterns
+          cop_config.fetch("AllowedPublicMethodPatterns", []).map { |pattern| Regexp.new(pattern) }
+        end
+
+        def methods_called_in_templates
+          component_path = processed_source.file_path
+          return Set.new unless component_path
+
+          template_paths = template_paths_for(component_path)
+          template_paths.each_with_object(Set.new) do |path, methods|
+            methods.merge(extract_method_calls(path))
+          end
+        rescue => e
+          # Graceful degradation on errors
+          warn "Warning: Failed to analyze templates: #{e.message}" if ENV["RUBOCOP_DEBUG"]
+          Set.new
+        end
+
         def visibility_modifier?(node)
           return false unless node.send_type?
           return false unless node.receiver.nil?

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "herb"
+
+module RuboCop
+  module Cop
+    module ViewComponent
+      # Helper module for analyzing ViewComponent ERB templates
+      module TemplateAnalyzer
+        # Find template file paths for a component
+        # @param component_path [String] Path to the component Ruby file
+        # @return [Array<String>] Array of template file paths
+        def template_paths_for(component_path)
+          return [] unless component_path
+
+          base_path = component_path.sub(/\.rb$/, "")
+          component_dir = File.dirname(component_path)
+          component_name = File.basename(component_path, ".rb")
+
+          paths = []
+
+          # Check for sibling template: same_name.html.erb
+          sibling_template = "#{base_path}.html.erb"
+          paths << sibling_template if File.exist?(sibling_template)
+
+          # Check for sidecar template: same_name/same_name.html.erb
+          sidecar_template = File.join(component_dir, component_name, "#{component_name}.html.erb")
+          paths << sidecar_template if File.exist?(sidecar_template)
+
+          # Check for variants: same_name.*.html.erb
+          variant_pattern = "#{base_path}.*.html.erb"
+          paths.concat(Dir.glob(variant_pattern))
+
+          # Check for sidecar variants: same_name/same_name.*.html.erb
+          sidecar_variant_pattern = File.join(component_dir, component_name, "#{component_name}.*.html.erb")
+          paths.concat(Dir.glob(sidecar_variant_pattern))
+
+          paths.uniq
+        end
+
+        # Extract method calls from an ERB template
+        # @param template_path [String] Path to the ERB template file
+        # @return [Set<Symbol>] Set of method names called in the template
+        def extract_method_calls(template_path)
+          return Set.new unless File.exist?(template_path)
+
+          source = File.read(template_path)
+          ruby_code = Herb.extract_ruby(source)
+
+          # Parse the extracted Ruby code
+          parse_ruby_for_method_calls(ruby_code)
+        rescue => e
+          # Graceful degradation on parse errors
+          warn "Warning: Failed to parse template #{template_path}: #{e.message}" if ENV["RUBOCOP_DEBUG"]
+          Set.new
+        end
+
+        private
+
+        # Parse Ruby code and extract method calls (send nodes with nil receiver)
+        def parse_ruby_for_method_calls(ruby_code)
+          # Use RuboCop's ProcessedSource to parse Ruby code
+          processed = RuboCop::ProcessedSource.new(
+            ruby_code,
+            RuboCop::TargetRuby.supported_versions.max,
+            "(template)"
+          )
+
+          return Set.new unless processed.valid_syntax?
+
+          method_calls = Set.new
+          traverse_for_method_calls(processed.ast, method_calls) if processed.ast
+          method_calls
+        end
+
+        # Recursively traverse AST to find method calls
+        def traverse_for_method_calls(node, method_calls)
+          return unless node.respond_to?(:type)
+
+          # Look for send nodes with nil receiver (local method calls)
+          if node.type == :send && node.receiver.nil?
+            method_name = node.method_name
+            method_calls.add(method_name)
+          end
+
+          # Recursively traverse children
+          node.each_child_node do |child|
+            traverse_for_method_calls(child, method_calls)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/view_component/version.rb

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

data/script/verify_against_primer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "tmpdir"
+require "fileutils"
+require "open3"
+require "bundler"
+
+GEM_DIR = File.expand_path("..", __dir__)
+RESULTS_FILE = File.join(GEM_DIR, "spec", "expected_primer_failures.json")
+TARBALL_URL = "https://github.com/primer/view_components/archive/refs/heads/main.tar.gz"
+
+def main
+  mode = ARGV.include?("--regenerate") ? :regenerate : :verify
+
+  Dir.mktmpdir do |dir|
+    download_source(dir)
+
+    Dir.chdir(dir) do
+      configure_rubocop
+      add_gem_to_gemfile
+
+      Bundler.with_unbundled_env do
+        output = run_rubocop
+        offenses = extract_offenses(output)
+
+        case mode
+        when :regenerate then regenerate(offenses)
+        when :verify then verify(offenses)
+        end
+      end
+    end
+  end
+end
+
+def system!(*args)
+  system(*args, exception: true)
+end
+
+def download_source(dir)
+  puts "Downloading primer/view_components..."
+  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
+  puts "Configuring ViewComponentParentClasses in .rubocop.yml..."
+  config = YAML.load_file(".rubocop.yml") || {}
+  config["AllCops"] ||= {}
+  parents = config["AllCops"]["ViewComponentParentClasses"] || []
+  unless parents.include?("Primer::Component")
+    parents << "Primer::Component"
+    config["AllCops"]["ViewComponentParentClasses"] = parents
+    File.write(".rubocop.yml", YAML.dump(config))
+  end
+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)
+  json = "#{JSON.pretty_generate(offenses)}\n"
+  File.write(RESULTS_FILE, json)
+  puts "#{offenses.length} offense(s) written to #{RESULTS_FILE}"
+end
+
+def verify(offenses)
+  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