feat: add composer-based set binding every rule to an exact drupal/core version

.claude/skills/README.md

@@ -24,6 +24,8 @@ Converts a single drupal-digests rule into a complete drupal-rector implementati
 
 - **QG-A — Type Guard Audit**: ensures every `MethodCall`/`PropertyFetch` node is guarded by `isObjectType()` to avoid false positives on untyped code.
 - **QG-B — Version-Gating Tests**: for BC-wrapped rectors (`AbstractDrupalCoreRector`), adds a `testBelowVersion()` test and a `fixture-below-version/` fixture proving the transformation is suppressed on older Drupal versions.
+- **QG-C — By-Reference Capture**: BC wrappers around by-reference calls use a long closure that captures by reference.
+- **QG-D — Version Bound and Registration**: the rule is registered in its per-minor config **and** in `config/composer-based.php`, with a `drupal/core` bound (`>=introduced <removal-major+1.0.0`) on the class (plain rules) or in the set (configurable rules). See [`prompts/version-bounds.md`](prompts/version-bounds.md).
 
 ```
 /rector-implement repos/drupal-digests/rector/rules/replace-deprecated-sessionmanager-delete-with-3577376.php
@@ -33,14 +35,17 @@ Converts a single drupal-digests rule into a complete drupal-rector implementati
 
 ### `/rector-qa <RectorClassName>`
 
-Four-pass quality review of an existing rector. Use before merging or when auditing existing implementations.
+Seven-pass quality review of an existing rector. Use before merging or when auditing existing implementations.
 
 | Pass | What it checks |
 |------|---------------|
 | 1 — Type Guard | `isObjectType()` guard present for all MethodCall/PropertyFetch nodes |
 | 2 — Fixture Coverage | `basic.php.inc`, `no_change_unrelated.php.inc`, `fixture-below-version/` present as required |
 | 3 — BC Decision | Base class (`AbstractRector` vs `AbstractDrupalCoreRector`) matches the deprecation's version and node type |
 | 4 — @see URL | Docblock URL points to the correct Drupal.org issue or change record |
+| 5 — Registration / bound | Registered in the per-minor config and `config/composer-based.php`; `drupal/core` bound correct and in the right place |
+| 6 — Common Bugs | Idempotency, e.g. attribute dedup by short name |
+| 7 — By-Reference | BC-wrapped by-reference calls capture by reference |
 
 Produces a `PASS / WARN / FAIL` verdict per pass and an overall merge-readiness summary.
 
@@ -89,17 +94,21 @@ A typical cycle for adding a new rector:
   → picks the next pending rule
 
 /rector-implement repos/drupal-digests/rector/rules/<digest-file>.php
-  → writes rector class, fixture, test, config; runs phpstan + phpunit
+  → writes rector class, fixture, test; registers it in the per-minor config and
+    config/composer-based.php with a version bound; runs phpstan + phpunit
 
 /rector-live-test <ClassName>
   → validates against real contrib modules
 
 /rector-qa <ClassName>
-  → final four-pass quality check before opening a PR
+  → final seven-pass quality check before opening a PR
 ```
 
+Registration and version bounds are specified once, in
+[`prompts/version-bounds.md`](prompts/version-bounds.md); the skills and recipes link to it.
+
 ## Requirements
 
-- PHP 8.1+
+- PHP 8.2+
 - [DDEV](https://ddev.com) (for `setup-rector-test.sh` and running tests inside the container)
 - Clone `repos/drupal-digests` and `repos/drupal-core` via `bash .claude/scripts/setup-repos.sh`

.claude/skills/prompts/digest-to-rector-prompt.md

@@ -32,6 +32,12 @@ container. Cleanup is handled automatically by `AbstractDrupalRectorTestCase::te
 not add a `try`/`finally` block. Standard conversion tests do not need this — the stub default
 (`11.99.x-dev`) is sufficient for normal fixture testing.
 
+**Second version mechanism — installed `drupal/core`.** Separate from `\Drupal::VERSION`, the
+test harness pins the *installed* core per test namespace (`Tests\Drupal11\…` → `11.99.99`), and
+class-bound rules are filtered against it. Every new rule also needs a version bound and a second
+registration in `config/composer-based.php`. Read `.claude/skills/prompts/version-bounds.md`
+before Step 6 — it is short and Steps 6, 9b and 12 depend on it.
+
 ---
 
 ## Step 1 — Confirm input
@@ -81,7 +87,10 @@ The issue markdown is at:
 Read it completely. Extract:
 - **Introduced version** — from the `## Impact` section, e.g.:
   `deprecated in drupal:11.4.0` → `'11.4.0'`
-- **Removal version** — e.g., `removed in drupal:13.0.0` → `'13.0.0'`
+- **Removal version** — e.g., `removed in drupal:13.0.0` → `'13.0.0'`. Together with the
+  introduced version this gives the rule's bound: `>=11.4.0 <14.0.0` (upper = the major *after*
+  removal, see `version-bounds.md` §2). Confirm both against `repos/drupal-core`'s
+  `@deprecated` / `trigger_error` text — change records are often wrong about removal.
 - **New API FQCN** — the fully-qualified class name of the replacement API, from `## Upgrade` or `## Technical details`
 - **Description** — one-sentence summary of what this rule does
 - **Change record number** — scan for any `drupal.org/node/` link in the "Upgrade path",
@@ -228,6 +237,10 @@ preferred path — it avoids creating new classes for patterns that drupal-recto
 
 1. Add the configuration entry to `config/drupal-11/drupal-11.4-deprecations.php` (or the
    appropriate versioned file), inside the matching `$rectorConfig->ruleWithConfiguration()` block.
+   Then add it to `config/composer-based.php` as its **own**
+   `ruleWithConfigurationComposerVersionBound(..., 'drupal/core', '>=X.Y.0 <N.0.0')` call under the
+   matching `// Drupal X.Y` heading — one call per deprecation, not appended to an existing block
+   (`version-bounds.md` §1 and §3).
 
 2. Add a fixture file to the existing generic rector's test directory:
    `tests/src/Rector/Deprecation/[GenericRectorName]/fixture/[descriptive-name].php.inc`
@@ -242,6 +255,10 @@ preferred path — it avoids creating new classes for patterns that drupal-recto
 
 5. Skip to Step 11 (fix-style) then Step 12 (phpstan) then Step 13 (test).
 
+`RenameClassRector` entries for renames whose target only exists from that minor on are
+**breaking**: they go in the per-minor `-breaking.php` file and under the `(breaking)` heading in
+`composer-based.php`, not in the deprecations file.
+
 **Configuration entry syntax by generic rector:**
 
 ```php
@@ -301,6 +318,11 @@ tests/src/Drupal11/Rector/Deprecation/[ClassName]/config/configured_rule.php
 tests/src/Drupal11/Rector/Deprecation/[ClassName]/fixture/basic.php.inc
 ```
 
+`Drupal11` is the major the deprecation was **introduced** in. A deprecation introduced in 12.x
+goes under `Drupal12` (source *and* tests) — the test namespace selects the installed-core pin
+(`version-bounds.md` §4), so a mismatch silently filters a class-bound rule out of its own test.
+The rest of this prompt writes `Drupal11`; substitute the real major throughout.
+
 ---
 
 ## Step 6 — Generate the rule class
@@ -321,6 +343,9 @@ namespace DrupalRector\Drupal11\Rector\Deprecation;
 use PhpParser\Node;
 // [copy only the use statements actually needed by the refactor logic — omit Rector\Config\RectorConfig]
 use Rector\Rector\AbstractRector;
+use Rector\VersionBonding\Contract\ComposerPackageConstraintInterface;
+use Rector\VersionBonding\ValueObject\ComposerPackageConstraint;
+use Symplify\RuleDocGenerator\Contract\DocumentedRuleInterface;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
@@ -330,8 +355,15 @@ use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
  * @see https://www.drupal.org/node/[issue-number]
  * @see https://www.drupal.org/node/[change-record-number]
  */
-class [ClassName] extends AbstractRector
+final class [ClassName] extends AbstractRector implements ComposerPackageConstraintInterface, DocumentedRuleInterface
 {
+    // The bound from Step 2: >=introduced <(major after removal).0.0 — see version-bounds.md §2.
+    // A plain rule must declare it here: it is registered with rule(), which cannot carry one.
+    public function provideComposerPackageConstraint(): ComposerPackageConstraint
+    {
+        return new ComposerPackageConstraint('drupal/core', '>=[introduced version] <[major after removal].0.0');
+    }
+
     // [copy private constants and properties from the digests rule unchanged]
 
     public function getRuleDefinition(): RuleDefinition
@@ -400,7 +432,7 @@ use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
  * @see https://www.drupal.org/node/[issue-number]
  * @see https://www.drupal.org/node/[change-record-number]
  */
-class [ClassName] extends AbstractDrupalCoreRector
+final class [ClassName] extends AbstractDrupalCoreRector
 {
     /** @var DrupalIntroducedVersionConfiguration[] */
     protected array $configuration;
@@ -451,7 +483,10 @@ CODE_AFTER,
 ```
 
 **Adaptation notes:**
-- Remove `final` keyword — drupal-rector classes are not final.
+- Keep the `final` keyword — most drupal-rector rule classes are `final` (63 of 93 in
+  `src/Drupal11`). Drop it only if another rule is meant to extend the class.
+- Template B gets **no** class constraint: it is configurable, so its bound goes in
+  `composer-based.php` (Step 9b). Only plain `rule()`-registered classes carry one.
 - Remove `use Rector\Config\RectorConfig` from the rule class (it belongs only in config files).
 - Keep all private constants, arrays, and helper methods unchanged.
 - For multi-node-type rules (two or more different node types in `getNodeTypes()`):
@@ -649,6 +684,29 @@ $this->commentService->addDrupalRectorComment($node, 'Please verify this change
 
 ---
 
+## Step 9b — Register the rule (two files)
+
+Full rules and examples: `.claude/skills/prompts/version-bounds.md`.
+
+1. **Per-minor config** — `config/drupal-11/drupal-11.[Y]-deprecations.php` for the introduced
+   minor (`-breaking.php` if the replacement only exists from that minor on). Add the `use`
+   statement and a comment block (`@see` URLs, "deprecated in … removed in …", replacement):
+   - Template A: `$rectorConfig->rule([ClassName]::class);`
+   - Template B: `$rectorConfig->ruleWithConfiguration([ClassName]::class, [new DrupalIntroducedVersionConfiguration('[introduced version]')]);`
+
+2. **`config/composer-based.php`** — the same rule under the matching `// Drupal 11.[Y]` (or
+   `(breaking)`) heading, in the same position as in the per-minor file, with the same comment
+   block:
+   - Template A: `$rectorConfig->rule([ClassName]::class);` — the bound is on the class.
+   - Template B:
+     ```php
+     $rectorConfig->ruleWithConfigurationComposerVersionBound([ClassName]::class, [
+         new DrupalIntroducedVersionConfiguration('[introduced version]'),
+     ], 'drupal/core', '>=[introduced version] <[major after removal].0.0');
+     ```
+
+---
+
 ## Step 10 — Write all files
 
 Using the write tool, create all four files at the paths derived in Step 5:
@@ -657,6 +715,8 @@ Using the write tool, create all four files at the paths derived in Step 5:
 3. `tests/src/Drupal11/Rector/Deprecation/[ClassName]/config/configured_rule.php`
 4. `tests/src/Drupal11/Rector/Deprecation/[ClassName]/fixture/basic.php.inc`
 
+…and apply the two config edits from Step 9b.
+
 ---
 
 ## Step 11 — Fix code style
@@ -682,6 +742,16 @@ Fix any reported issues before proceeding. Common issues:
 - Incorrect type hints (e.g., `Node` vs a specific subtype)
 - `refactorWithConfiguration()` must declare its return type as mixed or `Node|Node[]|null`
 
+The registration guards report under these identifiers. Fix the registration — **never add them
+to the baseline**:
+
+| Identifier | Meaning | Fix |
+|---|---|---|
+| `drupalRector.composerBasedSetCoverage` | Rule is in a per-minor config but not in `composer-based.php` | Step 9b.2 |
+| `drupalRector.unboundRule` | A `rule()` in `composer-based.php` whose class has no `ComposerPackageConstraintInterface` | Add the constraint to the class (Template A) |
+| `drupalRector.boundRulePackage` | Bound names a package other than `drupal/core` | Use `'drupal/core'` |
+| `drupalRector.boundRuleVersion` / `drupalRector.boundRuleVersionOrder` | Constraint is not `>=X.Y.Z` or `>=X.Y.Z <N.0.0`, or `N` is not above the lower major | Fix the string (`version-bounds.md` §2) |
+
 ---
 
 ## Step 13 — Run the test
@@ -690,7 +760,7 @@ Fix any reported issues before proceeding. Common issues:
 vendor/bin/phpunit tests/src/Drupal11/Rector/Deprecation/[ClassName]/
 ```
 
-**If tests pass:** The conversion is complete. Commit all four files together.
+**If tests pass:** The conversion is complete — continue to Step 14 (no commit).
 
 **If tests fail:** Diagnose the failure:
 
@@ -699,6 +769,9 @@ vendor/bin/phpunit tests/src/Drupal11/Rector/Deprecation/[ClassName]/
 - **"Class not found"** — Check the namespace declaration and file path match.
 - **"Method not found"** — Verify the base class was chosen correctly (Step 4).
 - **"Fixture has no before/after separator"** — The `-----` line is missing or has extra spaces.
+- **Every fixture fails as "no change" on a plain rule** — the class bound is filtering the rule
+  out: the test namespace pins an installed core outside the bound (`version-bounds.md` §4), or
+  the bound itself is wrong.
 - **phpstan errors** — Fix type declarations in the rule class and re-run.
 
 After fixing failures, update the conversion prompt (this file) with any decision rule that
@@ -723,6 +796,9 @@ Before marking a conversion complete, verify:
 - [ ] (Custom class only) `use Rector\Config\RectorConfig` is NOT in the rule class
 - [ ] (Custom class only) Base class matches the BC decision from Step 4
 - [ ] (Custom class only) `getNodeTypes()` lists all node types from the original rule
+- [ ] (Template A only) Class implements `ComposerPackageConstraintInterface` + `DocumentedRuleInterface` with the Step 2 bound
+- [ ] Registered in the per-minor config **and** in `config/composer-based.php` (Step 9b); configurable rules carry the bound there
+- [ ] Bound is `>=introduced <(major after removal).0.0`, both numbers checked against `repos/drupal-core`
 - [ ] Fixture `-----` separator is on its own line
 - [ ] `vendor/bin/phpunit` passes for the relevant test directory
 - [ ] `ddev composer fix-style` has been run

.claude/skills/prompts/recipes/RECIPES.md

@@ -61,14 +61,19 @@ Read the digest. Answer these questions in order:
 Config-only recipes do **not** create a new PHP class. They:
 
 1. Add one entry to an existing config file (e.g. `config/drupal-11/drupal-11.4-deprecations.php`)
-2. Add one fixture file to the existing generic rector's test directory
-3. Add the entry to that rector's test config
-4. Run the existing test suite for that rector
+2. Add the same entry to `config/composer-based.php` as its own
+   `ruleWithConfigurationComposerVersionBound()` call with the version bound
+3. Add one fixture file to the existing generic rector's test directory
+4. Add the entry to that rector's test config
+5. Run the existing test suite for that rector
 
 The config file to edit depends on `introducedVersion` — same lookup table as the
 custom-class recipes. If the file does not yet import the generic rector class, add the
 `use` statement.
 
+**Every recipe registers twice and states a version bound.** The rules, the bound formula and
+the PHPStan guards that enforce them are in [`../version-bounds.md`](../version-bounds.md).
+
 ---
 
 ## What belongs in a recipe vs. the main prompt

.claude/skills/prompts/recipes/config-only-template.md

@@ -9,24 +9,47 @@ the exact config syntax and fixture shape for one generic rector.
 
 ### Step 1 — Identify the config file
 
-| introducedVersion | File |
-|---|---|
-| 11.4.x | `config/drupal-11/drupal-11.4-deprecations.php` |
-| 11.3.x | `config/drupal-11/drupal-11.3-deprecations.php` |
-| 11.2.x | `config/drupal-11/drupal-11.2-deprecations.php` |
-| 11.1.x | `config/drupal-11/drupal-11.1-deprecations.php` |
-| 11.0.x | `config/drupal-11/drupal-11.0-deprecations.php` |
+The file is named after the minor the deprecation was **introduced** in:
+`config/drupal-<major>/drupal-<major>.<minor>-deprecations.php`, e.g. 11.4.x →
+`config/drupal-11/drupal-11.4-deprecations.php`. If that minor has no file yet, create it
+(copy an existing one) and add its constant to `src/Set/Drupal<major>SetList.php` and the
+`drupal-<major>-all-deprecations.php` aggregate.
 
-### Step 2 — Add the config entry
+A `RenameClassRector` entry whose target class only exists from that minor on is **breaking**:
+it goes in `drupal-<major>.<minor>-breaking.php` instead.
+
+Also work out the bound now (`../version-bounds.md` §2): `>={{introducedVersion}} <{{majorAfterRemoval}}.0.0`,
+e.g. deprecated in 11.4.0, removed in 13.0.0 → `>=11.4.0 <14.0.0`.
+
+### Step 2 — Add the config entry (two files)
 
 See the specific recipe for the exact entry syntax.
-Add the `use` statement for the configuration value object if it is not yet imported.
+
+1. **Per-minor file** from Step 1: add the entry inside the matching
+   `$rectorConfig->ruleWithConfiguration()` block. Add the `use` statement for the
+   configuration value object if it is not yet imported.
+2. **`config/composer-based.php`**: add the same entry as its **own** call under the matching
+   `// Drupal X.Y` (or `// Drupal X.Y (breaking)`) heading, copying the comment block above it:
+   ```php
+   // https://www.drupal.org/node/{{issueNumber}}
+   // {{deprecatedSymbol}} deprecated in drupal:{{introducedVersion}}, removed in drupal:{{removedVersion}}.
+   $rectorConfig->ruleWithConfigurationComposerVersionBound({{GenericRectorName}}::class, [
+       {{configEntry}}
+   ], 'drupal/core', '>={{introducedVersion}} <{{majorAfterRemoval}}.0.0');
+   ```
+   One call per deprecation — do not append to another entry's call, its bound may differ.
 
 ### Step 3 — Add a fixture to the generic rector's test directory
 
 Path: `tests/src/Rector/Deprecation/{{GenericRectorName}}/fixture/{{descriptive-name}}.php.inc`
 
-Format (no BC wrapper — generic rectors do not produce one):
+Format below is for the unwrapped generics (`FunctionCallRemovalRector`,
+`MethodToMethodWithCheckRector`, `ClassConstantToClassConstantRector`, `RenameClassRector`).
+The generics that take an `introducedVersion` (`FunctionToStaticRector`, `FunctionToServiceRector`,
+`FunctionToFirstArgMethodRector`, `DrupalServiceRenameRector`, `ConstantToClassConstantRector`)
+are BC-wrapped for versions >= 10.1.0: their "after" is the
+`\Drupal\Component\Utility\DeprecationHelper::backwardsCompatibleCall(\Drupal::VERSION, '…', fn() => <new>, fn() => <old>)`
+form — copy the exact shape from a sibling fixture or from the first failing test diff.
 ```
 <?php
 
@@ -52,10 +75,14 @@ ddev composer fix-style
 ddev composer phpstan
 vendor/bin/phpunit tests/src/Rector/Deprecation/{{GenericRectorName}}/
 git add config/drupal-11/drupal-11.{{X}}-deprecations.php \
+        config/composer-based.php \
         tests/src/Rector/Deprecation/{{GenericRectorName}}/
-git commit -m "feat(Drupal11): Add {{GenericRectorName}} config for issue #{{issueNumber}}"
+git commit -m "feat: add {{GenericRectorName}} config for #{{issueNumber}}"
 ```
 
+A `drupalRector.composerBasedSetCoverage` PHPStan error means Step 2.2 was skipped. Add a
+`CHANGELOG.md` entry under `[Unreleased] / ### Added` (a separate `docs:` commit is fine).
+
 ---
 
 ## Config entry syntax by generic rector
@@ -165,13 +192,14 @@ Fixture "after": `{{NewClass}}::{{NEW_CONST}}`
 
 ### ConstantToClassConstantRector
 
-Values: `{{GLOBAL_CONST}}`, `{{TargetClass}}`, `{{CONST_NAME}}`
+Values: `{{GLOBAL_CONST}}`, `{{TargetClass}}`, `{{CONST_NAME}}`, `{{introducedVersion}}`
 
 ```php
-new ConstantToClassConfiguration('{{GLOBAL_CONST}}', '{{TargetClass}}', '{{CONST_NAME}}'),
+new ConstantToClassConfiguration('{{GLOBAL_CONST}}', '{{TargetClass}}', '{{CONST_NAME}}', '{{introducedVersion}}'),
 ```
 
-No BC wrapping.
+`introducedVersion` is required. BC-wrapped (introduced >= 10.1.0) — the fixture "after" shows the
+`DeprecationHelper::backwardsCompatibleCall()` form.
 Fixture "after": `\{{TargetClass}}::{{CONST_NAME}}`
 
 ---