rubocop-view_component 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be0a1c1c9a7489ed311953b5f67c7108dbca8b1f43debef36026ec011781a549
-  data.tar.gz: 0b62b04534ab81725ab96d28c0b1931671d92944277ac7b5217f4d36d9d91f9b
+  metadata.gz: ab88d6999ec2a99b6f9e459d22a14b9d727b62edd967088fa22aef709681dbdb
+  data.tar.gz: b06b97cebdb888ba95176af4d9d664c9f75bf75865eacb148bc327bba761f77f
 SHA512:
-  metadata.gz: 7fc23bef50c35486b422362f9e738e5347b41eaeb8171f2dfca21884dbd87542f2db1e22618c1b239a1bfd2d878b448cb208539678c37b6e622086c1ee4d2871
-  data.tar.gz: f67e8fc0ec682da84318f7078bc5eaffd4a7e9907e9d4e281a224e240e57a13b4f4ec010ef31cce3f20528b4f6fc4ce5acf538385736a837095ef21a90fcf641
+  metadata.gz: 8b6aa5e13ce63d13205335bb2d900a29d57e80ce1b9d1906c92e3548d85941875b18235a36775849e35752fed347c260e842289fb8e805ad0ee7670c252c89b1
+  data.tar.gz: b65833f97c6211d366b5c0cdeba807e501f6ef10a8a878f63e0379de23be3c2a4842542e50e43171254886204990ae5224a4d3e3abbe90f72be1e05f9cfb0f08

data/.rubocop.yml

@@ -12,10 +12,14 @@ AllCops:
   TargetRubyVersion: 3.2
   NewCops: enable
   SuggestExtensions: false
+  # Required by this gem's own cops, which resolve ancestry through the
+  # project index (see docs/rubydex.md).
+  UseProjectIndex: true
   Exclude:
     - 'verification/**/*'
     - 'script/verify'
     - 'spec/fixtures/**/*'
+    - 'gemfiles/**/*'
 
 Metrics/BlockLength:
   Exclude:

data/{CLAUDE.md → AGENTS.md}

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to coding agents when working with code in this repository.
 
 ## Project Overview
 
@@ -40,8 +40,10 @@ All cops inherit from `RuboCop::Cop::Base` and are located in `lib/rubocop/cop/v
 ### 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
+- Includes `RuboCop::Cop::ProjectIndexHelp` for [rubydex integration](docs/rubydex.md)
+- Provides `view_component_class?(node)` - Detects ViewComponent classes via ancestry resolution
+- Provides `view_component_parent?(node)` - Checks if inheriting from ViewComponent::Base
+- Provides `view_component_parent_class?(node)` - Checks if a class is an abstract parent (has descendants)
 - Provides `inside_view_component?(node)` - Checks if code is within a ViewComponent
 
 **`TemplateAnalyzer`** (`lib/rubocop/cop/view_component/template_analyzer.rb`)
@@ -50,16 +52,6 @@ All cops inherit from `RuboCop::Cop::Base` and are located in `lib/rubocop/cop/v
 - 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 `ViewComponent` config supports `ViewComponentParentClasses` to configure additional base classes beyond `ViewComponent::Base` and `ApplicationComponent`:
-
-```yaml
-ViewComponent:
-  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.yml`.

data/Appraisals

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+appraise "rubocop-minimum" do
+  gem "rubocop", "= 1.89.0"
+end

data/README.md

@@ -13,9 +13,19 @@ gem 'rubocop-view_component', require: false
 Add to your `.rubocop.yml`:
 
 ```yaml
-require:
+plugins:
   - rubocop-view_component
 ```
+**Note:** From v0.7.0 onwards, this gem makes use of [rubydex](https://github.com/Shopify/rubydex) to discover which classes inherit from `ViewComponent::Base`. `UseProjectIndex` is required. Without it, cops that depend on ancestry detection will raise an error.
+
+```yaml
+AllCops:
+  UseProjectIndex: true
+```
+
+If you use a ViewComponent library such as [primer](https://github.com/primer/view_components) then you'll also need to set `ProjectIndexIncludesGems: true` so the cops can resolve ancestry chains that pass through gem classes.
+
+For more background on how RuboCop uses rubydex for cross-file analysis, see [RuboCop 1.89: Project-Wide Analysis with Rubydex](https://metaredux.com/posts/2026/08/05/rubocop-1-89.html).
 
 ## Cops
 
@@ -25,47 +35,40 @@ 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** - Avoid inheriting one ViewComponent from another (prefer composition)
-- **ViewComponent/TestRenderedOutput** - Encourage testing rendered output over private methods
-- **ViewComponent/MissingPreview** - Ensure every ViewComponent has a corresponding preview file (requires `PreviewPaths` configuration). Classes listed in `ViewComponentParentClasses` are automatically exempt, as abstract base classes are not rendered standalone.
+- **ViewComponent/PreferComposition** - Avoid inheriting one ViewComponent from another (prefer composition). Abstract bases without their own template, such as `ApplicationComponent`, are allowed
+- **ViewComponent/TestRenderedOutput** - Encourage testing rendered output over private methods. Supports Minitest and RSpec styles, including components built via `described_class.new` or a `let`/`subject` helper
+- **ViewComponent/MissingPreview** - Ensure every ViewComponent has a corresponding preview file (defaults to `test/components/previews` and `spec/components/previews` if `PreviewPaths` is not configured). Abstract base classes with descendants are automatically exempt.
 
 ## Optional Configuration
 
-### Base Class
+### Components Directory
 
-By default, the cops detect classes that inherit from `ViewComponent::Base` or `ApplicationComponent`. To add extra parent classes, use `inherit_mode: merge` so the defaults are preserved:
+Several cops (`ComponentSuffix`, `PreferComposition`, `TestRenderedOutput`) default to running only on files under `app/components/`. If your project uses a different path, override `Include` in your `.rubocop.yml`:
 
 ```yaml
 # .rubocop.yml
-ViewComponent:
-  inherit_mode:
-    merge:
-      - ViewComponentParentClasses
-  ViewComponentParentClasses:
-    - MyApp::BaseComponent
+ViewComponent/ComponentSuffix:
+  Include:
+    - 'app/components/**/*.rb'
+    - 'engines/*/app/components/**/*.rb'
 ```
 
-To replace the defaults entirely (e.g. if your project has renamed `ApplicationComponent`), omit `inherit_mode`:
+### Additional Source Paths
+
+`AllCops/ProjectIndexIncludesGems` only indexes a gem's `lib`, so a class that inherits through a
+Rails engine's `app/components` stays unresolved. If your components inherit from an engine gem,
+point the cops at its sources:
 
 ```yaml
 # .rubocop.yml
 ViewComponent:
-  ViewComponentParentClasses:
-    - ViewComponent::Base
-    - MyApp::BaseComponent
+  AdditionalSourcePaths:
+    - ../my_engine/app/components
 ```
 
-### Components Directory
-
-Several cops (`ComponentSuffix`, `PreferComposition`, `MissingPreview`, `TestRenderedOutput`) default to running only on files under `app/components/`. If your project uses a different path, override `Include` in your `.rubocop.yml`:
-
-```yaml
-# .rubocop.yml
-ViewComponent/ComponentSuffix:
-  Include:
-    - 'app/components/**/*.rb'
-    - 'engines/*/app/components/**/*.rb'
-```
+Paths are relative to the config file that sets them. The cops index those directories themselves
+and fall back to them when RuboCop's index can't resolve a constant. Unlike `ComponentNamespaces`,
+this only adds declarations to the index — it does not treat a whole namespace as components.
 
 ### No Super
 
@@ -157,6 +160,26 @@ To force download the latest Polaris source:
 script/verify polaris --update
 ```
 
+### Flowbite Components
+
+To verify against [substancelab/flowbite-components](https://github.com/substancelab/flowbite-components) locally:
+
+```bash
+script/verify flowbite
+```
+
+If you intentionally change cop behavior, regenerate the snapshot:
+
+```bash
+script/verify flowbite --regenerate
+```
+
+To force download the latest Flowbite source:
+
+```bash
+script/verify flowbite --update
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/andyw8/rubocop-view_component.

data/config/default.yml

@@ -1,8 +1,11 @@
 ViewComponent:
-  ViewComponentParentClasses:
-    - ViewComponent::Base
-    - ApplicationComponent
   ComponentNamespaces: []
+  # Source directories the cops index themselves, in addition to RuboCop's
+  # project index. Use this when ancestry passes through a gem RuboCop does not
+  # index (notably a Rails engine's app/components, which
+  # AllCops/ProjectIndexIncludesGems misses because it only covers a gem's lib).
+  # Paths are relative to the config file that sets them.
+  AdditionalSourcePaths: []
 
 ViewComponent/ComponentSuffix:
   Description: 'Enforce -Component suffix for ViewComponent classes.'
@@ -18,8 +21,6 @@ ViewComponent/MissingPreview:
   Enabled: true
   VersionAdded: '0.5.0'
   Severity: convention
-  Include:
-    - 'app/components/**/*_component.rb'
   PreviewPaths:
     - test/components/previews
     - spec/components/previews

data/docs/rubydex.md

@@ -0,0 +1,136 @@
+# rubydex integration
+
+This gem uses [rubydex](https://github.com/Shopify/rubydex), Shopify's high-performance
+static analysis toolkit for Ruby, to answer questions that cannot be answered from a
+single file's AST.
+
+Most ViewComponent cops only care about *ancestry*: is this class (or the class it
+inherits from) ultimately a `ViewComponent::Base` descendant? A class may inherit from
+`ApplicationComponent`, which inherits from a gem's base class, which finally inherits
+from `ViewComponent::Base` — none of which is visible in the file being inspected.
+Resolving that chain requires a project-wide index, and that is what rubydex provides.
+
+## How RuboCop exposes the index
+
+RuboCop 1.89+ integrates rubydex behind an opt-in flag. This gem requires that
+version (see `rubocop-view_component.gemspec`).
+
+1. When `AllCops/UseProjectIndex` is `true`, RuboCop builds a resolved
+   `Rubydex::Graph` for the whole project (`RuboCop::ProjectIndexLoader`).
+2. The graph is exposed to cops through `RuboCop::Cop::Base#project_index`.
+3. Cops that mix in `RuboCop::Cop::ProjectIndexHelp` also get an
+   `external_dependency_checksum` override, which invalidates RuboCop's result cache
+   whenever an indexed file changes on disk.
+
+If the `rubydex` gem is not installed, or the running Ruby is older than 3.2, RuboCop
+warns and degrades to file-local analysis (`project_index` is `nil`).
+
+## How this gem uses it
+
+`ViewComponent::Base` (`lib/rubocop/cop/view_component/base.rb`) includes
+`ProjectIndexHelp` and queries the index through `resolve_constant_in_index`:
+
+- `view_component_class?` — resolves a class's superclass expression and checks it.
+- `view_component_parent?` — resolves a constant and calls
+  `declaration.has_ancestor?("ViewComponent::Base")`.
+- `view_component_parent_class?` — checks `has_ancestor?` plus `declaration.descendants`
+  to detect abstract base classes that have their own subclasses in the project.
+- `resolved_index_declaration` — returns the raw declaration for a constant, or nil
+  when it isn't defined in the index. This lets a cop distinguish "resolved but not a
+  ViewComponent" from "not resolvable", and inspect the declaration (for example, to
+  locate the class's source file).
+- `inside_view_component?` — finds the enclosing class and delegates to
+  `view_component_class?`.
+
+`PreferComposition` uses `resolved_index_declaration` together with the parent's
+template to tell a concrete component apart from an abstract base: it flags a parent
+only when its name follows the component convention *and* the index resolves it to a
+ViewComponent that has its own template. Bases without a template (such as
+`ApplicationComponent`) and constants that resolve to something other than a
+ViewComponent are allowed.
+
+All of these call `require_project_index!` first, which raises with an actionable
+message if the index is unavailable:
+
+```
+ViewComponent cops require `AllCops/UseProjectIndex: true` in your .rubocop.yml
+for ancestry-based class detection.
+```
+
+The one exception is `ComponentNamespaces`: if a class's fully-qualified name matches a
+configured namespace prefix, `view_component_class?` can return `true` without touching
+the index, so projects that use explicit namespaces can avoid the requirement in that
+specific case.
+
+## Configuration
+
+Enable the index in your `.rubocop.yml`:
+
+```yaml
+AllCops:
+  UseProjectIndex: true
+```
+
+If your components inherit from a library (e.g. Primer) whose base class lives in a gem,
+also enable gem indexing so the ancestry chain can be followed through the gem's source:
+
+```yaml
+AllCops:
+  ProjectIndexIncludesGems: true
+```
+
+### Rails engines
+
+Gem indexing only covers a gem's `lib`. A Rails engine's components live under `app/components`,
+so a chain that passes through one — such as a project's components inheriting
+`MyEngine::ApplicationComponent` — stays unresolved even with the flag on. List the engine's
+sources in `ViewComponent/AdditionalSourcePaths` and the cops index them in a small supplementary
+graph of their own, used as a fallback when RuboCop's index can't resolve a constant:
+
+```yaml
+ViewComponent:
+  AdditionalSourcePaths:
+    - ../my_engine/app/components
+```
+
+Paths are relative to the config file that sets them, and the supplementary files take part in the
+result cache's checksum, so changing one invalidates a cached run. `ComponentNamespaces` is not a
+substitute here: it treats *every* class under the namespace as a component, which is wrong for a
+namespace that also holds helpers, tests, or other application code.
+
+## Performance notes
+
+- The index always covers the whole project (rooted at the directory of the config that
+  enabled it), not just the files in the current run, so cross-file offenses are
+  consistent between full runs, editor runs, and CI shards.
+- `external_dependency_checksum` ties the result cache to the indexed files' mtimes and
+  sizes, so a warm cache is reused until a relevant file changes.
+- On Windows, parallel inspection is skipped when the index is enabled.
+
+## Testing
+
+Specs do not build a full RuboCop run. `spec/support/project_index_helpers.rb` builds a
+`Rubydex::Graph` directly from a set of in-memory sources:
+
+```ruby
+graph = Rubydex::Graph.new
+graph.index_source("file:///user_component.rb", source, "ruby")
+graph.resolve
+```
+
+`ProjectIndexHelpers::LazyIndex` wraps the graph and lazily indexes the source under
+inspection on first miss, mirroring how the real runner indexes every project file
+(including the one being inspected). `spec_helper.rb` assigns this to each cop's
+`project_index` before examples run.
+
+The real-world verification suites (`verification/*_rubocop_config.yml`) set
+`UseProjectIndex: true` so the cops are exercised through the actual RuboCop runner.
+
+## Further reading
+
+- rubydex repository: <https://github.com/Shopify/rubydex>
+- Ruby API documentation: <https://shopify.github.io/rubydex/>
+- "One engine, many tools — Introducing Rubydex":
+  <https://railsatscale.com/2026-05-12-one-engine-many-tools/>
+- RuboCop 1.89 project-wide analysis announcement:
+  <https://metaredux.com/posts/2026/08/05/rubocop-1-89.html>

data/gemfiles/rubocop_minimum.gemfile

@@ -0,0 +1,13 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "irb"
+gem "rake", "~> 13.4"
+gem "rspec"
+gem "rubocop", "= 1.89.0"
+gem "rubocop-rake"
+gem "rubocop-rspec"
+
+gemspec path: "../"

data/gemfiles/rubocop_minimum.gemfile.lock

@@ -0,0 +1,162 @@
+PATH
+  remote: ..
+  specs:
+    rubocop-view_component (0.6.0)
+      activesupport
+      herb
+      lint_roller (~> 1.1)
+      parser
+      rubocop (>= 1.89.0)
+      rubydex
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (8.1.3.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    appraisal (2.5.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    erb (6.0.7)
+    herb (0.10.3)
+    herb (0.10.3-aarch64-linux-gnu)
+    herb (0.10.3-aarch64-linux-musl)
+    herb (0.10.3-arm-linux-gnu)
+    herb (0.10.3-arm-linux-musl)
+    herb (0.10.3-arm64-darwin)
+    herb (0.10.3-x86-linux-gnu)
+    herb (0.10.3-x86-linux-musl)
+    herb (0.10.3-x86_64-darwin)
+    herb (0.10.3-x86_64-linux-gnu)
+    herb (0.10.3-x86_64-linux-musl)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    io-console (0.9.1)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    parallel (1.28.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rbs (4.1.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.7.0)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.89.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.7.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    ruby-progressbar (1.13.0)
+    rubydex (0.3.0)
+    rubydex (0.3.0-aarch64-linux)
+    rubydex (0.3.0-arm64-darwin)
+    rubydex (0.3.0-x86_64-darwin)
+    rubydex (0.3.0-x86_64-linux)
+    securerandom (0.4.1)
+    thor (1.5.0)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  appraisal
+  irb
+  rake (~> 13.4)
+  rspec
+  rubocop (= 1.89.0)
+  rubocop-rake
+  rubocop-rspec
+  rubocop-view_component!
+
+BUNDLED WITH
+   2.7.2

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

@@ -1,35 +1,63 @@
 # frozen_string_literal: true
 
+require "rubydex"
+require_relative "supplementary_index"
+
 module RuboCop
   module Cop
     module ViewComponent
-      # Shared helper methods for ViewComponent cops
+      # Shared helper methods for ViewComponent cops.
+      # Requires rubydex with UseProjectIndex: true for ancestry resolution.
       module Base
-        # Check if a class node inherits from ViewComponent::Base or ApplicationComponent
+        include ProjectIndexHelp
+        include SupplementaryIndex
+
+        VC_BASE = "ViewComponent::Base"
+
+        # Check if a class node inherits from ViewComponent::Base
         def view_component_class?(node)
           return false unless node&.class_type?
 
           class_source = fully_qualified_name(node)
           return true if component_namespaces.any? { |ns| class_source.start_with?(ns) }
 
+          require_project_index!
+
           parent_class = node.parent_class
           return false unless parent_class
 
           view_component_parent?(parent_class)
         end
 
-        # Check if node represents a configured parent class
+        # Check if a constant node resolves to a class with ViewComponent::Base as ancestor
         def view_component_parent?(node)
-          return false unless node.const_type?
+          declaration = view_component_declaration(node)
+          return false unless declaration
 
-          (cop_config["ViewComponentParentClasses"] || []).include?(node.source)
+          declaration.name == VC_BASE || declaration.has_ancestor?(VC_BASE)
         end
 
-        # Check if a class node is itself one of the registered parent classes.
+        # Check if a class node is itself an abstract parent class
+        # (has ViewComponent::Base as ancestor and has descendants in the project)
         def view_component_parent_class?(node)
           return false unless node&.class_type?
 
-          (cop_config["ViewComponentParentClasses"] || []).include?(fully_qualified_name(node))
+          declaration = view_component_declaration(node.identifier)
+          return false unless declaration
+
+          declaration.has_ancestor?(VC_BASE) &&
+            declaration.descendants.any? { |d| d.name != declaration.name }
+        end
+
+        # Resolve a constant node to its declaration in the project index, or
+        # nil when the node is not a constant or isn't defined anywhere in the
+        # index. The declaration may or may not be a ViewComponent; callers can
+        # inspect it (for example, to locate the class's source file).
+        def resolved_index_declaration(node)
+          return nil unless node&.const_type?
+
+          require_project_index!
+          resolve_constant_in_index(node)
         end
 
         def fully_qualified_name(node)
@@ -51,11 +79,32 @@ module RuboCop
 
         # Check if node is within a ViewComponent class
         def inside_view_component?(node)
+          require_project_index!
+
           klass = enclosing_class(node)
           return false unless klass
 
           view_component_class?(klass)
         end
+
+        def require_project_index!
+          return if project_index
+
+          raise <<~MSG
+            ViewComponent cops require `AllCops/UseProjectIndex: true` in your .rubocop.yml
+            for ancestry-based class detection.
+          MSG
+        end
+
+        private
+
+        # Resolve a constant node to a namespace declaration in the project
+        # index, or nil when the node is not a constant or does not resolve to a
+        # class or module.
+        def view_component_declaration(node)
+          declaration = resolved_index_declaration(node)
+          declaration if declaration.respond_to?(:has_ancestor?)
+        end
       end
     end
   end