Add audience filtering support

[zebapy]

Summary

This PR adds support for filtering OpenAPI specifications by audience using the x-openapi-interfaces-audience extension, similar to Fern's x-fern-audiences feature.

Features

CLI Arguments

• --audience <name>: Filter by one or more audiences (can be specified multiple times)
• --audience-mode <include|exclude>: Control filtering mode (defaults to "include")

Supported Levels

• Operations/Endpoints: Tag entire HTTP operations with audiences
• Schema Properties: Tag individual fields within interface members with audiences

Filtering Behavior

• Items without an audience tag are treated as public/default and always included
• Include mode: Only items with matching audiences (plus public items) are included
• Exclude mode: Items with matching audiences are excluded (public items remain)

Usage Examples

# Include only beta features (plus public features)
openapi-interfaces api.yml -o api_beta.yml --audience beta

# Exclude internal features
openapi-interfaces api.yml -o api_public.yml --audience internal --audience-mode exclude

# Include multiple audiences
openapi-interfaces api.yml -o api.yml --audience beta --audience internal

Example YAML

paths:
  /beta-endpoint:
    get:
      x-openapi-interfaces-audience: ["beta"]
      responses:
        200:
          description: Beta endpoint

components:
  interfaces:
    Widget:
      members:
        publicField:
          schema:
            type: string
        betaField:
          schema:
            type: string
            x-openapi-interfaces-audience: ["beta"]

Implementation Details

• Extended Scope struct with audience filtering configuration
• Added AudienceFilterMode enum for include/exclude control
• Filter operations during OpenApi transpilation
• Filter interface members during Interface transpilation
• Filter schema properties during PrimitiveSchema transpilation
• Maintain consistency of required fields when filtering properties

Testing

• ✅ All existing tests pass
• ✅ Added comprehensive example file (examples/audience_example.yml)
• ✅ Tested endpoint filtering (include/exclude modes)
• ✅ Tested property filtering (include/exclude modes)
• ✅ Tested multiple audiences
• ✅ Tested public (untagged) items

Documentation

• Updated README with audience filtering section
• Added usage examples
• Created example file demonstrating the feature

🤖 Generated with Claude Code