[architecture] Extract dependency-health with read-only analysis and explicit upgrade boundaries #381

Proposal / validation gate: this issue records an extraction design for maintainer validation. Repository/package names are candidates. Approve the boundary and migration plan before implementation; this task does not authorize creating repositories, implementing the extraction, releases or consumer rollout.

Problem and proposal

Propose php-fast-forward/dependency-health / fast-forward/dependency-health around DependenciesCommand and Config/ComposerDependencyAnalyserConfig.php. Current behavior composes ShipMonk dependency analyser and Rector Swiss Knife constraints/outdated operations; it should not require formatting/testing/docs to inspect a dependency graph.

Scope

Own declared-versus-used dependency checks, intentional shadow-dependency policy, outdated/breakpoint reporting and explicitly selected dependency-upgrade operations, plus workflow/CLI/skill when useful. Not a generic Rector owner: source refactoring belongs to code-standards. Composer metadata bootstrap belongs to repository-metadata. Static source analysis remains #14, not duplicated here.

Concrete tasks / acceptance

• Characterize current raise/open constraints commands and --upgrade side effects. Publish explicit read-only check/plan versus apply/update contracts; do not inherit implicit writes as harmless analysis.
• Preserve [dependencies] Handle intentional shadow dependencies without hiding accidental ones #233 intentional-shadow exceptions without hiding accidental dependencies; fixtures cover direct/dev/transitive/shadow/unused and invalid manifests.
• Distinguish outdated threshold policy (CI uses -1) from tool failure and security advisory results; do not infer safety from outdated counts or suppress unrelated failures.
• Separate application constraints/lock resolution from external tool runtime; failures report exact affected manifest without dumping credentials.
• Define JSON/artifact/result identity and integration with DevTools aggregate exit status, test workflows and optional PR feedback.
• Test no-write checks, reviewed upgrade diffs and rollback, local/isolated runtime and unsupported manifests. Do not update consumer dependencies merely by adopting the package.

Alternatives

Keep within DevTools temporarily until output contract is stable; do not put all source static analysis, mutation testing and formatting in this package. A separate package is justified by Composer graph/policy ownership, not the fact a command invokes Rector Swiss Knife.

Delivery and migration gates

• One domain owner for library/CLI, relevant reusable workflow/Action, portable skill, tests and versioned docs; adapters call the same implementation. Do not create a surface solely for symmetry.
• No production dependency back to DevTools; no generic Actions repository as mandatory runtime. CPX/external execution does not isolate PHPUnit/config classes loaded in the same PHP process.
• Preserve project overrides, exit codes, JSON contracts, working directory/cache/color options, and PHP consumer compatibility. Distinguish tool runtime from application minimum.
• Validate Composer archives, runtime resources and skill provenance outside the source checkout; no host-cache absolute paths in consumer files.
• Release availability, exact workflow/runtime/skill compatibility, then pilot consumer PRs and rollback are separate gates. Never point consumers at a not-yet-published version. No release/merge/deploy/repository creation is performed by this planning issue.
• Root architecture tracking: [architecture] Plan domain-owned tooling extraction and DevTools orchestration #240; release-safe refs Define release-safe refs for consumer workflow wrappers and checked-out actions #238; open distribution redesign PR feat!: distribute DevTools through CPX and portable skills #376 must be revalidated before implementation. Evidence baseline: DevTools main 35d27ee (2026-10-21), not an assertion that PR feat!: distribute DevTools through CPX and portable skills #376 is merged.

Architectural / Isolation Criteria

• MUST: Core logic MUST live in dedicated services; commands/controllers only orchestrate.
• MUST: Separate input resolution, domain transformations and rendering; keep CLI/framework I/O out of reusable behavior.
• MUST: Support reuse/extensibility without major refactoring and deterministic, testable exits/output.
• MUST: Separate gathering/transformation from writes/publishing; repeated execution MUST be idempotent or explicitly bounded.
• MUST: Update README, command/config docs, skill references and synchronized consumer examples with the actual new ownership.

Repository-split decision gate

Before implementation, compare independent consumers, current code size, dependency/release cadence and maintenance cost with keeping this responsibility as a bounded module under the nearest domain or DevTools. A separate repository is a candidate, not mandatory. If reuse/lifecycle does not justify it, document the smaller grouping and avoid artificial fragmentation. Validate the recommendation with the maintainer.