feat(schema): resolve #[BoundToOpenApiEnum] from optional enum_spec_base_path

[wadakatu]

Summary

Adds an opt-in enum_spec_base_path extension parameter (and matching OpenApiSpecLoader::configure(enumBasePath: ...) argument) used only when resolving #[BoundToOpenApiEnum] paths. When the parameter is omitted, behaviour is bit-for-bit identical to v1.1.x — single-root projects need to change nothing.

<extensions>
    <bootstrap class="Studio\OpenApiContractTesting\PHPUnit\OpenApiCoverageExtension">
        <parameter name="spec_base_path" value="openapi/bundled"/>
        <parameter name="enum_spec_base_path" value="openapi"/>     <!-- new -->
        <parameter name="specs" value="front,store,admin"/>
    </bootstrap>
</extensions>

// before — leaks the bundled root choice into the attribute
#[BoundToOpenApiEnum('../_shared/components/schemas/enums/NotificationCodeEnum.json')]

// after
#[BoundToOpenApiEnum('_shared/components/schemas/enums/NotificationCodeEnum.json')]

Why

Per #170: #[BoundToOpenApiEnum] resolution is currently coupled to spec_base_path. Projects that point spec_base_path at openapi/bundled/ (where orval-readable aggregates live) have to write '../_shared/...' in every attribute to reach per-enum source JSONs that deliberately live outside the bundle root. The parent-traversal is awkward, fragile under bundle-layout refactors, and visually leaks the bundle directory choice into every attributed enum.

Workarounds rejected for the reasons spelled out in #170 — duplicating per-enum JSONs under bundled/ re-creates the exact drift this library exists to detect, and re-pointing spec_base_path at openapi/ would break the existing {base}/{spec}.json lookup.

Fixes #170.

Verification

• composer test passes — 1252 tests, 3018 assertions (+10 new across the review fixup commit, on top of the original +10 from the feature commit)
• composer stan passes (PHPStan level 6 clean)
• composer cs-check passes (PHP-CS-Fixer clean)

End-to-end exercise: tests/Integration/EnumDriftIntegrationTest::bundled_external_layout_resolves_via_enum_spec_base_path and three new bootstrap-level cases in OpenApiCoverageExtensionEnumDriftBootstrapTest (auto-discovery clean, auto-discovery drift, orphaned-parameter FATAL) drive the headline dogfood layout end-to-end.

Notes for reviewers

Public API surface added (intentionally additive — SemVer minor):

• OpenApiSpecLoader::configure(..., ?string $enumBasePath = null) — optional 6th argument, defaults preserve all existing call sites. Empty / whitespace-only value rejected with InvalidArgumentException to avoid the unhelpful "is not a directory: " (empty) diagnostic later.
• OpenApiSpecLoader::getEnumBasePath(): ?string — non-throwing on purpose. Absence is the documented default and the asserter relies on the null return to fall back to spec_base_path. (Contrast with getBasePath() which throws because spec_base_path is functionally required for spec lookup.)
• OpenApiCoverageExtension parameter enum_spec_base_path — relative paths resolve against getcwd(), identical to spec_base_path / output_file / sidecar_dir. trim()'d on read so XML editing artefacts (leading newlines, etc.) don't silently coerce to getcwd().
• EnumBindingException::forConfig() — sibling to forScan for global configuration failures (no enumFqcn / specPath because the failure isn't tied to any specific binding).
• New EnumBindingReason cases: EnumBasePathNotFound (parameter set but path doesn't exist) and EnumSpecBasePathOrphaned (parameter set without spec_base_path, or empty/whitespace value).

Design notes:

• EnumDriftAsserter::resolveEnumBasePath() is the new private helper — it consults getEnumBasePath() first and only falls back to getBasePath() when the new parameter is unset.
• Setting enum_spec_base_path to the same value as spec_base_path is functionally equivalent to omitting it (the opt-in branch additionally validates with is_dir() before resolving any binding; the fallback branch defers that check to per-file file_exists() lookups). Pinned by a field-by-field detectAll() comparison test.
• EnumBasePathNotFound / EnumSpecBasePathOrphaned are both routed through forConfig() — the misconfiguration is global, so enumFqcn / specPath are intentionally null instead of being set to an arbitrary "first failing binding".
• Fail-loud-on-misconfiguration is preserved: empty / whitespace / orphaned enum_spec_base_path all FATAL at PHPUnit bootstrap with diagnostics also written to GITHUB_STEP_SUMMARY.
• oneOf enum union resolution is explicitly out of scope (called out in feat(schema): allow #[BoundToOpenApiEnum] paths to resolve from a secondary base path (or bundled-external root) #170 as a known limitation tracked from feat(schema): enum drift detection between OpenAPI spec and bound PHP enums #166).

Review fixups

Commit 8376c8c addresses the multi-agent code review on the initial commit:

• Critical: orphaned and empty enum_spec_base_path no longer silently dropped (review C1, C2)
• Important: forConfig() factory for global config failures (I4); docblock / README accuracy (I1, I2, I3); auto-discovery + bootstrap integration tests (I5); strengthened no-op + trailing-slash unit tests (I6, S3)
• Suggestion: empty enumBasePath rejected at the loader's configure() API surface (S1)

Follow-up

• tech-debt(coverage-merge) — propagate enum_spec_base_path through CoverageMergeCommand #172 — CoverageMergeCommand does not yet plumb enum_spec_base_path through to OpenApiSpecLoader::configure(). Latent today (the merge CLI does not invoke EnumDriftAsserter); worth closing alongside the next merge-CLI enum-drift feature.