[OAS] Detect colliding shared schema ids during OpenAPI generation

[tobio]

Closes part of #271809.
Companion to #271812 (Path A).

Summary

Adds a runtime guardrail in @kbn/router-to-openapispec that fails
OAS generation loudly when two distinct schema shapes are registered
under the same shared-schema id during a single generation pass. This
is the silent-overwrite class of bug that caused the Fleet regressions
in #271809.

The OAS converter keeps a Map<id, schema> of named components so it
can emit $ref-based reuse. Today that map is last-write-wins: if two
routes register the same id with different shapes (most often through
Base.extends({...}) inheriting meta.id from its base), one shape
silently overwrites the other in the bundled spec, dropping fields. With
this PR the converter throws an OasSchemaCollisionError instead, with
a key-set diff and a concrete fix suggestion pointing back to #271809:

OAS shared schema collision for id "package_policy_status_response":
the same id was registered with two different shapes.
  properties only in the first registration: (none)
  properties only in the second registration: `output_id`, `policy_id`,
    `policy_ids`, `package`
This usually means a `Base.extends({...})` call inherited `meta.id`
from its base, or two unrelated schemas accidentally chose the same id
string. Pass `{ meta: { id: 'distinct_id' } }` as the second argument
to `extends()` to give the derived schema its own component name.
See https://github.com/elastic/kibana/issues/271809.

Re-using the same shared schema across multiple routes (the common,
intended case) stays a no-op — equality is deep, but ignores the
transient META_FIELD_X_OAS_OPTIONAL annotation that MaybeType
attaches mid-parse and removeInternalOptionalMarker strips on the
way out.

Changes

• oas_converter/kbn_config_schema/post_process_mutations/schema_collision.ts
  (new) — OasSchemaCollisionError, describeSchemaCollision,
  and a schemasMatch deep-equality helper that ignores the
  internal optional marker.
• oas_converter/kbn_config_schema/post_process_mutations/context.ts
  — Context.addSharedSchema now compares any existing entry against
  the incoming shape via schemasMatch and dispatches on a new
  OnCollision = 'throw' | 'warn' | 'ignore' option (default
  'throw').
• oas_converter/index.ts — OasConverter accepts an
  OasConverterOptions { onCollision } second-arg, threads it through
  to the underlying Context, and applies the same check as a backstop
  in #addComponents (covers convertPathParameters /
  convertQuery, which currently create their own Context).
• kbn_config_schema/lib.ts + type.ts — propagate onCollision
  through the converter API.
• index.ts — re-export OasSchemaCollisionError so callers can
  catch it.
• Tests:
  • context.test.ts — 7 cases (idempotent re-registration, throw
    on shape mismatch, error-message contents, 'warn' mode,
    'ignore' mode, and a @kbn/config-schema-driven repro of
    the issue [Fleet] Named OpenAPI components from #270560 silently drop fields (output_id, policy_id, policy_ids, supports_agentless, id, package) #271809 pattern).
  • generate_oas.test.ts — 2 end-to-end cases that wire two
    routes through generateOpenApiDocument: one collides, one
    doesn't.

Sequencing

This PR should land after #271812.
Without Path A merged first, the existing Fleet collisions (the very
ones #271809 reports) would now trip the strict throw and break the
OAS snapshot CI step. Once Path A is in, this PR locks the door behind
it: any future regression of the same shape gets caught at build time
rather than silently corrupting the bundle.

Test plan

• node scripts/jest src/platform/packages/shared/kbn-router-to-openapispec — 252/252 pass (18 suites; +9 new tests covering the guardrail).
• node scripts/type_check --project src/platform/packages/shared/kbn-router-to-openapispec/tsconfig.json — clean.
• node scripts/eslint on the diff — clean.
• OAS snapshot CI step is green once Path A ([Fleet] Restore dropped OpenAPI fields by giving extends() schemas distinct meta.id #271812) is merged into this branch's base.

Risks

Low. The throw is a build-time check on the OAS bundle pipeline; it
does not affect any runtime route handler. The new 'warn' and
'ignore' modes are escape hatches for transitional or test usage —
nothing in production sets them. The biggest exposure is the
sequencing dependency on Path A: if this lands first, the next OAS
snapshot run will fail on the existing Fleet collisions until Path A
also merges.

Release Notes

None — internal tooling change. Failures here surface during OAS
generation, not at runtime.

Made with Cursor

[kibanamachine]

💔 Build Failed

• Buildkite Build
• Commit: 3009d03
• Build duration: 25 mins

Failed CI Steps

• Check OAS Snapshot

Metrics [docs]

Unknown metric groups

ESLint disabled line counts

id	before	after	diff
@kbn/router-to-openapispec	2	4	+2

Total ESLint disabled count

id	before	after	diff
@kbn/router-to-openapispec	2	4	+2

History

[infra-vault-gh-plugin-prod]

Pinging @elastic/kibana-core (Team:Core)