feat: Add EventCatalog integration as input type

[jonaslagoni]

Summary

Add inputType: 'eventcatalog' to support generating code directly from an EventCatalog, with automatic handling of AsyncAPI specs, OpenAPI specs, and native EventCatalog events.

Proposed Configuration

// codegen.config.mjs
export default {
  inputType: 'eventcatalog',
  inputPath: './eventcatalog',
  service: 'order-service',  // Select which service to generate for
  language: 'typescript',
  generators: [
    { preset: 'payloads', outputPath: './src/payloads' },
    { preset: 'channels', outputPath: './src/channels', protocols: ['nats'] },
  ],
};

Service Detection Logic

The tool should auto-detect what type of specifications a service has:

Service Metadata	Processing
specifications.asyncapiPath present	Use AsyncAPI processing
specifications.openapiPath present	Use OpenAPI processing
Both present	Generate from BOTH specs, merge outputs
Neither (just sends/receives)	Native mode - load event JSON schemas

Use Cases

1. Service with AsyncAPI Spec

# eventcatalog/services/user-service/index.md
---
id: user-service
specifications:
  asyncapiPath: asyncapi.yaml
---

→ Load asyncapi.yaml, process as AsyncAPI

2. Service with OpenAPI Spec

# eventcatalog/services/petstore-api/index.md
---
id: petstore-api
specifications:
  openapiPath: openapi.json
---

→ Load openapi.json, process as OpenAPI

3. Service with BOTH Specs

# eventcatalog/services/order-service/index.md
---
id: order-service
specifications:
  asyncapiPath: events.yaml      # Event-driven messaging
  openapiPath: api.json          # REST API
---

→ Generate from both, combine outputs (e.g., HTTP client + NATS channels)

4. Native EventCatalog (No Spec Files)

# eventcatalog/services/order-service/index.md
---
id: order-service
sends:
  - id: OrderCreated
  - id: OrderShipped
receives:
  - id: PaymentCompleted
---

→ Load JSON schemas from events/OrderCreated/schema.json, etc.

Implementation Approach

New Input Processor

Create src/codegen/inputs/eventcatalog/:

• parser.ts - Main entry point
• service-loader.ts - Parse service index.md frontmatter
• event-loader.ts - Load native event schemas
• index.ts - Exports

Parser Logic

export async function loadEventCatalog(context: RunGeneratorContext) {
  const { inputPath, service } = context.configuration;
  
  // 1. Load service metadata
  const serviceDir = path.join(inputPath, 'services', service);
  const metadata = parseServiceMetadata(serviceDir);
  
  // 2. Detect spec type(s)
  if (metadata.specifications?.asyncapiPath) {
    const asyncapiDoc = await loadAsyncapi(/* ... */);
    context.asyncapiDocument = asyncapiDoc;
  }
  
  if (metadata.specifications?.openapiPath) {
    const openapiDoc = await loadOpenapi(/* ... */);
    context.openapiDocument = openapiDoc;
  }
  
  // 3. Native mode - load event schemas
  if (!metadata.specifications) {
    const schemas = await loadEventSchemas(metadata.sends, metadata.receives);
    context.jsonSchemaDocument = combineSchemas(schemas);
  }
}

Configuration Types

// In src/codegen/types.ts
export const zodEventCatalogConfiguration = z.object({
  inputType: z.literal('eventcatalog'),
  inputPath: z.string().describe('Path to EventCatalog directory'),
  service: z.string().describe('Service ID to generate code for'),
  // ... rest of common config
});

Dependencies

• Requires: feat: Add remote URL support for input specifications with authentication #359 (Remote URL support) - for services with remote spec URLs
• Optional: @eventcatalog/sdk - could use for more advanced catalog traversal

Acceptance Criteria

• inputType: 'eventcatalog' recognized in configuration
• service option selects which service to generate for
• Auto-detects AsyncAPI specs from asyncapiPath
• Auto-detects OpenAPI specs from openapiPath
• Handles services with BOTH specs (generates from both)
• Native mode loads event schema.json files
• Service metadata parsed from index.md frontmatter
• Clear error if service not found
• Clear error if no specs and no sends/receives
• Examples in examples/eventcatalog-* work
• Documentation added

Examples

Three examples already exist showcasing the proposed configuration:

• examples/eventcatalog-asyncapi/ - Service with AsyncAPI
• examples/eventcatalog-openapi/ - Service with OpenAPI
• examples/eventcatalog-native/ - Service with native events

Related

• Depends on feat: Add remote URL support for input specifications with authentication #359 (Remote URL support)
• EventCatalog
• EventCatalog SDK