feat: add OpenAPI Overlays support

[Copilot]

Summary

Adds support for OpenAPI Overlays v1.0.0 — a mechanism to apply targeted patches to an OpenAPI document without modifying the original file.

New CLI flag (repeatable, applied in order):

counterfact openapi.yaml ./out --overlay base.yaml --overlay env-override.yaml

Overlay file format (my-overlay.yaml):

overlay: 1.0.0
info:
  title: My Overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: Injected by overlay
  - target: $.paths['/internal']
    remove: true

Per-spec overlays in counterfact.yaml:

spec:
  - source: openapi.yaml
    group: ""
    overlays:
      - base-overlay.yaml
      - env-overlay.yaml

Overlays are applied in both the code-generation pipeline (Specification.fromFile) and the runtime server pipeline (OpenApiDocument.load). deepMerge is guarded against prototype pollution.

Original Prompt

Add support for OpenAPI overlays

Manual acceptance tests

• counterfact openapi.yaml ./out --overlay overlay.yaml applies the overlay's update action (e.g. changes info.title) before generating route stubs
• An overlay remove action suppresses route stub generation for the removed path
• Overlays specified under overlays: in a counterfact.yaml spec entry are applied on startup
• Repeating --overlay multiple times applies each file in the order given
• A missing overlay file exits with a clear error message rather than a silent crash
• Routes unaffected by an overlay continue to serve responses unchanged

Tasks

• Added src/util/apply-overlay.ts: loadOverlay, applyOverlayActions (JSONPath via jsonpath-plus), applyOverlays; deepMerge with __proto__/constructor/prototype guard
• Extended Specification.fromFile()/load() and OpenApiDocument constructor to accept overlays?: readonly string[]
• Propagated overlays through Config, SpecConfig, ApiRunner, CodeGenerator, and loadOpenApiDocument
• Added repeatable --overlay <path> Commander option to run.ts; per-spec overlays in multi-spec config entries; single-spec CLI flag falls back to config.overlays
• Added 20 unit tests in test/util/apply-overlay.test.ts, including fixture-based integration tests
• Added three example overlay fixtures under test/fixtures/openapi/overlays/:
  • update-info.yaml — patches the API title, description, and contact block
  • remove-deprecated.yaml — removes the deprecated /legacy/items endpoint
  • add-extensions.yaml — adds x-internal: true to targeted operations
• Added two black box tests in test-black-box/test_counterfact.py:
  • test_overlay_removes_path_from_generated_routes — runs --generate --overlay with a remove action and asserts the removed path produces no route file
  • test_overlay_update_changes_served_response — starts a live server with --serve --generate --overlay and verifies the overlay-modified example value is returned at runtime
• Updated docs/reference.md with full Overlays section and CLI flag entry
• Added minor changeset

[pmcelhaney]

Add some example overlays to fixtures.

[pmcelhaney]

Add a black box test

[Copilot]

Add some example overlays to fixtures.

Done in 5532344. Added three overlay fixtures under test/fixtures/openapi/overlays/:

• update-info.yaml – patches the API title, description, and adds a contact block
• remove-deprecated.yaml – removes the deprecated /legacy/items path
• add-extensions.yaml – adds x-internal: true to the /count and /ping operations

Each fixture is exercised by a new test in test/util/apply-overlay.test.ts that loads it against example.yaml via Specification.fromFile().

[Copilot]

Add a black box test

Done in 0ca5b36. Added two black box tests to test-black-box/test_counterfact.py:

• test_overlay_removes_path_from_generated_routes — runs counterfact --generate --overlay remove-beta.yaml against a spec with /alpha and /beta; asserts routes/alpha.ts is generated and routes/beta.ts is absent (removed by the overlay).
• test_overlay_update_changes_served_response — starts a live server with --serve --generate --overlay change-greeting.yaml; the overlay updates the /greeting example from hello to hello-from-overlay, and the test asserts GET /greeting returns hello-from-overlay.