tech-debt(coverage-merge) — propagate enum_spec_base_path through CoverageMergeCommand

[wadakatu]

Background

PR #171 (issue #170) added the optional enum_spec_base_path parameter to OpenApiSpecLoader::configure() for #[BoundToOpenApiEnum] resolution. The PHPUnit extension (OpenApiCoverageExtension::setupExtension()) reads the new parameter and forwards it to the loader. However, the standalone merge CLI does not.

Surfaced during PR #171 review (php-laravel-reviewer):

CoverageMergeCommand does not propagate enum_spec_base_path — src/Coverage/CoverageMergeCommand.php:267 still calls OpenApiSpecLoader::configure($specBasePath, $stripPrefixes). If/when the merge CLI grows enum-drift responsibilities, it will resolve #[BoundToOpenApiEnum] paths against spec_base_path only.

Current state

// src/Coverage/CoverageMergeCommand.php (around line 267)
OpenApiSpecLoader::configure($specBasePath, $stripPrefixes);

bin/openapi-coverage-merge exposes no --enum-spec-base-path flag and never plumbs one through to the loader.

Why this matters (today: latent, tomorrow: bug)

Today the merge command does not invoke EnumDriftAsserter — it only reads paratest sidecar JSONs and computes coverage. So this gap is latent rather than broken on main.

If a future change adds enum-drift checking to the merge CLI (e.g. for the bundled-external dogfood layout from #170 where the merge step happens after parallel test runs), the resolver would silently use spec_base_path only — failing on bindings whose JSON lives outside the bundle root. The failure would manifest as EnumBindingReason::SpecFileNotFound against an unhelpfully derived absolute path, masking the real cause (the merge CLI never received the secondary root).

What to do

When (and only when) the merge CLI grows enum-drift responsibilities:

1. Add --enum-spec-base-path=PATH to bin/openapi-coverage-merge (mirror the existing --spec-base-path shape).
2. Plumb it through CoverageMergeCommand::__construct / run() to the OpenApiSpecLoader::configure(..., enumBasePath: $enumBasePath) call.
3. Mirror OpenApiCoverageExtension's validation: empty / whitespace / orphaned (set without --spec-base-path) → FATAL with the same EnumSpecBasePathOrphaned reason.
4. Add an integration test under tests/Integration/CoverageMergeCliIntegrationTest.php exercising a bundled-external sidecar merge.

Until then, no production code change is required — this issue tracks the awareness so the gap is closed alongside the next merge-CLI enum-drift feature, not retrofit later.

Goal

• bin/openapi-coverage-merge accepts --enum-spec-base-path
• CoverageMergeCommand forwards it to OpenApiSpecLoader::configure()
• Bundled-external layout works end-to-end through the merge CLI, not just the PHPUnit extension
• Misconfiguration (orphaned / empty value) FATALs with the same diagnostic shape as the extension layer

References

• PR feat(schema): resolve #[BoundToOpenApiEnum] from optional enum_spec_base_path #171 (closes feat(schema): allow #[BoundToOpenApiEnum] paths to resolve from a secondary base path (or bundled-external root) #170) — introduces enum_spec_base_path at the extension layer
• src/Coverage/CoverageMergeCommand.php:267 — current configure() call
• src/PHPUnit/OpenApiCoverageExtension.php resolveEnumSpecBasePathParameter() — the shape to mirror