(feat): map OAS 3.1 annotated enumerations onto StringSchema

[ChiragAgg5k]

Summary

• Map OpenAPI 3.1 annotated enumerations (oneOf/anyOf of const + title) onto the existing StringSchema fields (enum, enumName, enumKeys, open) so sdk-generator does not need to walk unions.
• This is a breaking 0.2 change. Enum type name is the composite schema title. Value names are each branch’s title. Vendor extensions stay opaque and are not used for enum metadata.
• Closed annotated composites stay CompositeSchema. Call stringEnum() for the synthesized StringSchema. openStringEnumBranch() is the open subset (anyOf with an unconstrained type: string).

Changes

• CompositeSchema detects closed and open annotated string enums (nested oneOf inside anyOf, or flattened consts plus unconstrained string), synthesizes StringSchema, and throws InvalidSpecification with a JSON Pointer for object/const mixes, numeric consts, and multi-value enum mixed with const.
• Reader fills StringSchema enum values from enum/const only. Type and value names come from titles on annotated enumerations.
• Tests cover closed oneOf/anyOf, missing titles, nested and flattened open enums, rejection cases, and the legacy multi-value open anyOf shape.
• README and CONTEXT document annotated enumerations. Vendor extensions remain uninterpreted.

Test plan

• composer test passes locally — 65 tests, 471 assertions
• CI green on this PR
• After merge, tag 0.2.0
• Migrate appwrite/specs (and the spec emitter) to annotated enumerations before bumping sdk-generator to 0.2
• In sdk-generator, switch getEnumSchema to stringEnum() and update fixtures to the official shape

[greptile-apps]

Greptile Summary

The PR maps OpenAPI 3.1 annotated string enumerations onto synthesized StringSchema metadata while preserving the underlying composite tree.

• Adds closed and open annotated-enumeration detection to CompositeSchema.
• Derives enum names and keys from schema and branch titles rather than vendor extensions.
• Updates parsing, documentation, and tests for the new enumeration representation.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up-review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/Model/CompositeSchema.php	Adds synthesis and exposure of closed and open annotated string enums through stringEnum() and openStringEnumBranch().
src/Parser/Schema/Reader.php	Passes source locations into composite schemas and stops interpreting enum vendor extensions.
tests/Schema/ReaderTest.php	Expands coverage for annotated enum detection, metadata synthesis, open enum shapes, and documented rejection cases.
README.md	Documents the new annotated-enumeration representation and consumer API.

_{Reviews (3): Last reviewed commit: "(docs): describe enum names using schema..." | Re-trigger Greptile}

[ChiragAgg5k]

@greptile review