Merge branch 'main' into copilot/fix-dependabot-fileupdater-error

Author: thavaahariharangit

.github/copilot-instructions.md

@@ -0,0 +1,77 @@
+---
+applyTo:
+  - "**/file_fetcher.rb"
+  - "**/file_fetcher/**"
+  - "**/file_parser.rb"
+  - "**/file_parser/**"
+  - "**/file_updater.rb"
+  - "**/file_updater/**"
+  - "**/update_checker.rb"
+  - "**/update_checker/**"
+  - "**/metadata_finder.rb"
+  - "**/metadata_finder/**"
+  - "**/version.rb"
+  - "**/requirement.rb"
+---
+
+# Core Class Structure Pattern
+
+**CRITICAL**: All Dependabot core classes with nested helper classes must follow the exact pattern to avoid "superclass mismatch" errors. This pattern is used consistently across all established ecosystems (bundler, npm_and_yarn, go_modules, etc.).
+
+## Main Class Structure
+
+Applies to FileFetcher, FileParser, FileUpdater, UpdateChecker, etc.
+
+```ruby
+# {ecosystem}/lib/dependabot/{ecosystem}/file_updater.rb (or file_fetcher.rb, file_parser.rb, etc.)
+require "dependabot/file_updaters"
+require "dependabot/file_updaters/base"
+
+module Dependabot
+  module {Ecosystem}
+    class FileUpdater < Dependabot::FileUpdaters::Base
+      # require_relative statements go INSIDE the class
+      require_relative "file_updater/helper_class"
+
+      # Main logic here...
+    end
+  end
+end
+
+Dependabot::FileUpdaters.register("{ecosystem}", Dependabot::{Ecosystem}::FileUpdater)
+```
+
+## Helper Class Structure
+
+```ruby
+# {ecosystem}/lib/dependabot/{ecosystem}/file_updater/helper_class.rb
+require "dependabot/{ecosystem}/file_updater"
+
+module Dependabot
+  module {Ecosystem}
+    class FileUpdater < Dependabot::FileUpdaters::Base
+      class HelperClass
+        # Helper logic nested INSIDE the main class
+      end
+    end
+  end
+end
+```
+
+## Key Rules
+
+1. **Main classes** inherit from appropriate base: `Dependabot::FileUpdaters::Base`, `Dependabot::FileFetchers::Base`, etc.
+2. **Helper classes** are nested inside the main class.
+3. **`require_relative`** statements go INSIDE the main class, not at module level.
+4. **Helper classes require the main file** first: `require "dependabot/{ecosystem}/file_updater"`.
+5. **Never define multiple top-level classes** with the same name in the same namespace.
+6. **Backward compatibility** can use static methods that delegate to instance methods.
+
+## Applies To
+
+- **FileFetcher** and its helpers (e.g., `FileFetcher::GitCommitChecker`)
+- **FileParser** and its helpers (e.g., `FileParser::ManifestParser`)
+- **FileUpdater** and its helpers (e.g., `FileUpdater::LockfileUpdater`)
+- **UpdateChecker** and its helpers (e.g., `UpdateChecker::VersionResolver`)
+- **MetadataFinder** and its helpers
+- **Version** and **Requirement** classes (if they have nested classes)

.github/instructions/class-structure.instructions.md

@@ -0,0 +1,92 @@
+---
+applyTo: "**/*.rb"
+---
+
+# Code Quality Guidelines
+
+## Pre-Commit Checklist
+
+**Do NOT commit or push changes until ALL of the following pass inside a Docker container:**
+
+1. `rubocop` — Passes with no offenses (use `rubocop -A` to auto-fix)
+2. `bundle exec srb tc` — Sorbet type checking passes (for production code)
+3. `rspec spec/path/to/relevant_spec.rb` — Tests covering your changes pass
+
+Run these via `bin/test`:
+
+- `bin/test {ecosystem} rubocop`
+- `bin/test {ecosystem} spec/path/to/spec.rb`
+
+For Sorbet, run from the repo root inside the container:
+
+- `bin/docker-dev-shell {ecosystem}` then `cd /home/dependabot && bundle exec srb tc`
+
+When delegating work to sub-agents, each agent must validate its own changes before committing.
+
+## RuboCop Best Practices
+
+Avoid adding RuboCop exceptions unless absolutely necessary. Resolve offenses using proper coding practices:
+
+- **Method extraction** — Break large methods into smaller, focused methods
+- **Class extraction** — Split large classes into single-responsibility classes
+- **Reduce complexity** — Simplify conditional logic and nested structures
+- **Improve naming** — Use clear, descriptive variable and method names
+- **Refactor long parameter lists** — Use parameter objects or configuration classes
+- **Extract constants** — Move magic numbers and strings to named constants
+
+If a RuboCop exception is truly unavoidable, provide clear justification in a comment explaining why the rule cannot be followed and what alternatives were considered.
+
+## Sorbet Type Checking
+
+- All new files must use `# typed: strict` at minimum
+- Existing files below `strict`: upgrade to `strict` when making changes
+- Add explicit type signatures for method parameters and return values
+- Always validate with `bundle exec srb tc`
+
+### Autocorrect Usage
+
+Use `bundle exec srb tc -a` **cautiously** — it often creates incorrect fixes for complex cases.
+
+Autocorrect is acceptable for simple cases:
+
+- Missing `override.` annotations
+- `T.let` declarations for instance variables
+- Constant type annotations
+
+Always manually resolve complex type mismatches, method signature issues, and structural problems. Review any autocorrected changes carefully.
+
+## Code Comments
+
+Prioritize self-documenting code over comments. Prefer extracting well-named methods over adding explanatory comments.
+
+### DO Comment
+
+- **Business logic context** — Explain *why* something is done when not obvious
+- **Complex algorithms** — Document the approach or concepts
+- **Workarounds** — Explain why a non-obvious solution was necessary
+- **External constraints** — API limitations, ecosystem-specific behaviors
+- **TODOs** — With issue references when possible
+
+### DON'T Comment
+
+- **Implementation decisions** — Don't explain what was *not* implemented
+- **Obvious code** — Don't restate what the code clearly does
+- **Apologies or justifications** — Suggests code quality issues
+- **Outdated information** — Remove comments that no longer apply
+- **Version history** — Use git history instead
+
+### Example
+
+```ruby
+# Good: Explains WHY
+# Retry up to 3 times due to GitHub API rate limiting
+retry_count = 3
+
+# Bad: Explains WHAT (obvious from code)
+# Set retry count to 3
+retry_count = 3
+
+# Good: Documents external constraint
+# GitHub API requires User-Agent header or returns 403
+headers["User-Agent"] = "Dependabot/1.0"
+```

.github/instructions/code-quality.instructions.md

@@ -0,0 +1,102 @@
+---
+applyTo:
+  - "**/*_spec.rb"
+  - "**/spec/**"
+  - "**/spec_helper.rb"
+---
+
+# Testing Guidelines
+
+## Docker-Based Testing
+
+All tests must run inside Docker containers. The development environment, dependencies, and native helpers are containerized and will not work on the host system. Never attempt to run tests directly on your machine.
+
+## Quick Testing with `bin/test`
+
+The `bin/test` script is the fastest way to run tests. It handles container setup automatically.
+
+```bash
+# Run a specific spec file
+bin/test {ecosystem} spec/dependabot/{ecosystem}/file_updater_spec.rb
+
+# Run the full ecosystem test suite
+bin/test {ecosystem}
+
+# Test common/ changes (uses the bundler container internally)
+bin/test common spec/dependabot/file_fetchers/base_spec.rb
+
+# Test updater/ changes (note: use --workdir updater, it maps to dependabot-updater in the container)
+bin/test --workdir updater {ecosystem} rspec spec/path/to/spec.rb
+```
+
+The first run builds the Docker image and can take several minutes. Subsequent runs reuse the cached image and are much faster.
+
+## Interactive Development with `bin/docker-dev-shell`
+
+For iterative development where you need to run multiple commands, use the interactive shell:
+
+```bash
+# Start an interactive container shell
+bin/docker-dev-shell {ecosystem}
+
+# Inside the container:
+cd {ecosystem} && rspec spec
+
+# For updater tests (the folder is renamed inside containers):
+cd dependabot-updater && rspec spec
+```
+
+## GitHub Actions / CI (Non-Interactive)
+
+In CI environments where interactive shells are unavailable, use the non-interactive pattern:
+
+```bash
+# Build the ecosystem image
+script/build {ecosystem}
+
+# Run tests inside the container
+docker run --rm --env "CI=true" ghcr.io/dependabot/dependabot-updater-{ecosystem} bash -c \
+  "cd /home/dependabot/{ecosystem} && rspec spec"
+```
+
+## Testing `updater/` and `common/` Changes
+
+The `updater/` directory is renamed to `dependabot-updater/` inside containers. Always use the container path when running updater tests.
+
+```bash
+# Test updater changes
+bin/test --workdir updater {ecosystem} rspec spec/path/to/spec.rb
+
+# Test common changes (runs inside the bundler container)
+bin/test common spec/path/to/spec.rb
+```
+
+## Test Coverage Requirements
+
+- All changes must be covered by tests to prevent regressions.
+- Add tests for new functionality **before** implementing the feature.
+- When fixing bugs, add a test that reproduces the issue **first**.
+- All existing tests must continue to pass after your changes.
+
+### Rules for Test Design
+
+- **NEVER** test private methods directly — tests should only exercise public interfaces.
+- **NEVER** modify production code visibility to accommodate tests. If a test needs access to a private method, the test design is wrong.
+- **NEVER** add public methods solely for testing — this pollutes the production API.
+- Tests should verify behavior through public APIs and production code paths (e.g., `fetch_files`), not isolated helper methods.
+
+## Fixture-Based Testing
+
+Use real dependency files as fixtures. Helper methods in `spec_helper.rb` generate realistic test data:
+
+```ruby
+let(:dependency_files) { bundler_project_dependency_files("example_project") }
+```
+
+Fixtures live in `{ecosystem}/spec/fixtures/`.
+
+## Mocking External Calls
+
+- Mock HTTP requests to package registries using **VCR** or **WebMock**.
+- Use realistic registry responses to catch edge cases.
+- Never make real network calls in tests.

.github/instructions/testing.instructions.md

@@ -0,0 +1,49 @@
+---
+applyTo: "updater/**"
+---
+
+# Updater & Native Helpers
+
+## Container Path Mapping
+
+The `updater/` directory on the host is mounted as `dependabot-updater/` inside containers. Always use `dependabot-updater` when referencing paths in container commands.
+
+## Running Updater Tests
+
+```bash
+# Quick one-off test run:
+bin/test --workdir updater {ecosystem} rspec spec/path/to/spec.rb
+
+# Interactive development:
+bin/docker-dev-shell {ecosystem}
+# Then inside the container:
+cd dependabot-updater && rspec spec
+```
+
+## Native Helpers
+
+- Located in `{ecosystem}/helpers/`
+- Run exclusively within containers — they will not work on the host
+- Rebuild after changes: `{ecosystem}/helpers/build`
+- Changes are **not** automatically reflected in the container — you must rebuild
+
+## Debugging
+
+All debugging commands must be run inside the dev container. Start one first:
+
+```bash
+bin/docker-dev-shell {ecosystem}
+```
+
+Then use `bin/dry-run.rb` to test against real repositories:
+
+```bash
+# Enable helper debug output
+DEBUG_HELPERS=true bin/dry-run.rb {ecosystem} {repo}
+
+# Debug a specific native helper function
+DEBUG_FUNCTION=function_name bin/dry-run.rb {ecosystem} {repo}
+
+# Profile performance
+bin/dry-run.rb {ecosystem} {repo} --profile
+```

.github/instructions/updater.instructions.md

@@ -534,7 +534,34 @@ def cleanup_workspace
 
       sig { params(group: Dependabot::DependencyGroup).returns(T::Boolean) }
       def pr_exists_for_dependency_group?(group)
-        job.existing_group_pull_requests.any? { |pr| pr["dependency-group-name"] == group.name }
+        !find_existing_group_pr(group).nil?
+      end
+
+      sig { params(group: Dependabot::DependencyGroup).returns(T.nilable(T::Hash[String, T.untyped])) }
+      def find_existing_group_pr(group)
+        job.existing_group_pull_requests.find do |pr|
+          next false unless pr["dependency-group-name"] == group.name
+
+          existing_pr_covers_job_directories?(pr)
+        end
+      end
+
+      sig { params(pull_request: T::Hash[String, T.untyped]).returns(T::Boolean) }
+      def existing_pr_covers_job_directories?(pull_request)
+        dependencies = pull_request["dependencies"]
+
+        # Old PRs without directory info — treat as match (backward compat).
+        # Only enforce directory matching when ALL dependencies include a directory,
+        # consistent with DependencyChange#matches_existing_pr? and PullRequest#using_directory?.
+        return true if dependencies.nil? || !dependencies.all? { |dep| dep["directory"] }
+
+        pr_directories = dependencies.filter_map { |dep| dep["directory"] }
+        job_directories = job.source.directories || [job.source.directory || "/"]
+        normalized_job_dirs = job_directories.map { |d| Pathname.new(d).cleanpath.to_s }.uniq
+        normalized_pr_dirs = pr_directories.map { |d| Pathname.new(d).cleanpath.to_s }.uniq
+
+        # Match only when the PR directories exactly match the job directories
+        normalized_job_dirs.sort == normalized_pr_dirs.sort
       end
 
       sig do

updater/lib/dependabot/updater/group_update_creation.rb

@@ -85,9 +85,9 @@ def run_grouped_dependency_updates
           # Preprocess to discover existing group PRs and add their dependencies to the handled list before processing
           # the rest of the groups. This prevents multiple PRs from being created for the same dependency.
           groups_without_pr = dependency_snapshot.groups.filter_map do |group|
-            if pr_exists_for_dependency_group?(group)
-              existing_pr = job.existing_group_pull_requests.find { |pr| pr["dependency-group-name"] == group.name }
-              pr_number = existing_pr["pr_number"] if existing_pr
+            existing_pr = find_existing_group_pr(group)
+            if existing_pr
+              pr_number = existing_pr["pr_number"]
 
               Dependabot.logger.info(
                 "Detected existing pull request ##{pr_number} for the dependency group '#{group.name}'."