Rector Src Laravel Package

Technical Evaluation

Verdict up front: rector/rector-src is the development monorepo for Rector, not a consumable library. The installable artifact is rector/rector. The single most important TPM decision here is to correct the dependency target before any technical evaluation of the tool itself proceeds.

Architecture fit

• Rector is a dev-time CLI that parses PHP via nikic/php-parser and rewrites the AST according to declarative "rules" grouped into rule sets (PHP version upgrades, framework migrations).
• It is not a runtime dependency and has no place in a Laravel application's production dependency graph. Correct placement is require-dev + a rector.php config + a CI job.
• rector-src is the upstream source tree that gets split/published into the distribution repo. It is structured as a monorepo with its own test harness and tooling — its composer.json is not a contract for downstream consumers.
• Zero dependents on the src package is expected and not a quality signal; it confirms the package is not on any supported consumption path.

Integration feasibility

• High, if we target rector/rector (and optionally the Laravel rule-set package). Low-to-nil if any team attempts to composer require rector/rector-src — this is the primary feasibility risk and it is a specification error, not a technology error.
• The only legitimate uses of rector-src are: (a) reading rule source to understand what a rule does before enabling it, (b) contributing upstream, (c) local development of custom rules via a path repository during a spike — not a durable dependency.
• Laravel-specific coverage comes from the companion rule-set package, not from core; scope the evaluation accordingly.

Technical risk

• Package identity risk (high, immediate): the assessment input names the wrong artifact. Any ticket or ADR citing rector/rector-src as the dependency must be rewritten.
• Version/API churn (medium-high): Rector's config builder API and rule class names have historically shifted across majors; rule sets are renamed and split. Pinning and reading changelogs per upgrade is mandatory.
• Dependency graph collisions (medium): Rector pulls PHPStan and php-parser with tight constraints. In Laravel codebases that already run PHPStan, PHPUnit, or Pint, composer update conflicts are a realistic blocker and can hold back unrelated upgrades.
• Transformation correctness (medium): AST rewriting is deterministic but not infallible; rules can produce code that parses yet is semantically wrong. Diff review is a control, not an afterthought.
• Governance (low, but note it): MIT license is clean. Support is community-only on the main repo; the src repo carries no support commitment.

Key questions

1. Do we actually intend to consume rector/rector (distribution), and is the -src reference a documentation error?
2. Which PHP and Laravel target versions define scope for the first migration?
3. Is the goal one-time framework upgrade, or a standing codebase-modernisation capability?
4. Do we already run PHPStan/php-parser at versions that will conflict? What's the resolution order?
5. Who owns rector.php and the review of generated diffs?
6. Do we need custom rules (implies forking/contributing to rector-src), or are stock sets sufficient?

Integration Approach

Stack fit

• Fits any Composer-managed Laravel/PHP application and any CI that can run a PHP CLI step (GitHub Actions, GitLab CI, Bitbucket Pipelines).
• Natural companion tooling: Pint (formatting after rewrite), PHPStan (static verification after rewrite), PHPUnit (behavioural verification).
• Does not fit: shared hosting or runtime pipelines that cannot afford a dev dependency; projects pinned to PHP versions below the tool's floor.

Migration path

1. Correct the artifact. Require rector/rector as --dev; add the Laravel rule-set package if framework sets are in scope. Never require rector/rector-src in application code.
2. Read-only baseline. Run in --dry-run across the repo to produce a diff volume metric (files touched, rules firing). This is the go/no-go data point.
3. Incremental adoption by rule set. Enable one set at a time, apply, run test suite, merge. Avoid a single mega-diff — it is unreviewable and un-bisectable.
4. Framework sets last. PHP-version and code-quality sets first (low blast radius), then Laravel upgrade sets (high blast radius).
5. Custom rules only if justified. If needed, develop against a local checkout of rector-src via a path repository in a spike branch, then either upstream the rule or extract it into an internal package — do not ship the src checkout as a dependency.

Compatibility

• Pin to an explicit Rector major version in composer.json; treat upgrades as planned work with changelog review.
• Verify PHP floor, PHPStan and php-parser constraints against the current composer.lock before committing to the pilot — this is the most likely source of schedule slip.
• Exclude vendor/, generated code, and Blade-compiled artifacts via config paths/skip up front.

Sequencing

1. Spike: dry-run on a representative module (1–2 days).
2. Decision gate: diff volume and test pass rate acceptable → proceed.
3. Pilot: one full rule set applied and merged behind review (1 sprint).
4. CI gate: add a non-blocking --dry-run check to surface drift; promote to blocking once the codebase is clean.
5. Standing cadence: quarterly rule-set review aligned with framework upgrade windows.

Operational Impact

Maintenance

• The ongoing cost is not the package — it's the config and the version cadence. rector.php is code and needs an owner, review, and changelog discipline.
• Budget roughly one upgrade cycle per Rector major plus a review pass per framework upgrade. Underestimating this is the standard failure of Rector adoptions.
• rector-src itself requires zero maintenance from us because we should not depend on it.

Support

• Community-only via the main rectorphp/rector repository. No SLA, no vendor.
• Internal mitigation: pin versions, keep a rollback branch, and document the rule-set rationale so a new owner can reason about it without re-deriving it.
• 140 stars / 0 dependents on the src package should be read as "development repo," not "immature project" — but it does mean there is no downstream ecosystem to lean on for this specific artifact.

Scaling

• Runtime scales with codebase size and enabled rules; large monorepos need process parallelism and a raised memory limit. Cost is CI compute minutes plus engineer review time — no licensing cost.
• Review load, not execution time, is the true scaling constraint. Cap per-PR rule-set scope to keep diffs reviewable.

Failure modes

• Wrong dependency: someone vendors rector-src; builds break or silently drift from the supported tool.
• Over-broad first run: a single 4,000-file diff merged without per-set review; regressions become unbisectable.
• Semantic breakage: transformations that parse but alter behaviour; caught only by test coverage — coverage gaps are the real exposure.
• Dependency deadlock: Rector's PHPStan/php-parser constraints block an unrelated security upgrade; requires an exit plan (isolate Rector in a separate CI job/image).
• Scope leakage: generated or vendor code rewritten; prevented by explicit path config.
• Rule churn: rule renamed/removed on upgrade, CI silently stops enforcing; prevented by treating the dry-run check as a monitored job, not a fire-and-forget step.

Ramp-up

• Basic operation (install, config, dry-run, apply): hours for a mid-level PHP engineer.
• Productive rule-set curation and diff triage: 1–2 weeks, best learned on a single bounded module.
• Custom rule authoring (the only path that touches rector-src): weeks, requires comfort with PHP ASTs and the rule API; treat as a specialist task, not a team-wide skill.
• TPM-level recommendation: fund a one-sprint pilot with a named owner, gate continuation on dry-run blast-radius data, and correct the dependency reference to rector/rector in all planning artifacts before work begins.