Emit per-operation security metadata behind a feature flag (SOAR-0015)

[vdsingh]

Implements SOAR-0015 (proposal included in this PR) and addresses #37.

Depends on apple/swift-openapi-runtime#203, which adds the SecurityRequirement value types this generated code references. That PR should land (and be tagged in a release) first.

Motivation

The generator discards the OpenAPI security / securitySchemes sections entirely, so a ClientMiddleware — which only receives an operationID — cannot tell which operations require authentication, or which scheme. Adopters must either apply credentials unconditionally or hand-maintain a list that drifts from the document (#37, and the per-operation targeting gap in #551).

Modifications

Adds a securityMetadata feature flag. When enabled, TypesFileTranslator emits, per operation, the security requirements it currently drops:

public enum Operations {
    public enum getGreeting {
        public static let id: String = "getGreeting"
        public static let securityRequirements: [OpenAPIRuntime.SecurityRequirement] = [
            .init(schemes: [.init(name: "OAuth2", kind: .oauth2, scopes: ["read"])])
        ]
    }
}
public enum OperationSecurity {
    public static let requirementsByOperationID: [String: [OpenAPIRuntime.SecurityRequirement]] = ...
}

Semantics mirror OpenAPI: outer array = OR of alternatives, each requirement's schemes = AND-group, [] = explicitly public; an operation without security inherits the document-level requirements. AND-groups are sorted by scheme name for deterministic output. Unsupported cases (mutualTLS, non-bearer/basic HTTP) raise a diagnostic. With the flag off, generated output is byte-identical.

Also includes the SOAR-0015 proposal, the Proposals.md entry, and the corresponding checkboxes in the supported-features article.

Result

Adopters can enable securityMetadata and drive a conditional-authentication middleware from OperationSecurity.requirementsByOperationID — applying credentials only where required and failing fast when a required one is missing.

Test Plan

Adds reference tests in SnippetBasedReferenceTests for inherited document-level security, operation-level AND/OR groups (apiKey + http-bearer + oauth2), explicit security: [], the OperationSecurity namespace, and that nothing is emitted when the flag is off. Full suite passes (330 tests). Also dogfooded end-to-end against a real 130-operation document, generating and compiling the metadata (114 authenticated / 16 public) into an app.

cc @czechboy0 @simonjbeaumont - flagging per the proposal process.