feat: add eventcatalog input type

[jonaslagoni]

Summary

Adds inputType: 'eventcatalog' so codegen can read an EventCatalog directory directly. The loader picks one service via a new required service field, follows its frontmatter, and routes generation through the existing AsyncAPI or OpenAPI pipeline (or synthesizes an AsyncAPI 3.0 document for native services with no spec file). No per-generator branching is needed — every existing preset works for EventCatalog inputs.

Closes #360.

Type of Change

• New feature (adds functionality)

Changes Made

New Files

• src/codegen/inputs/eventcatalog/{index,parser,serviceLoader,eventLoader,types}.ts — full loader stack
• docs/inputs/eventcatalog.md — input page covering 3 modes, native synthesis rules, both-specs disambiguation, remote URLs, examples, limitations
• test/codegen/inputs/eventcatalog/{serviceLoader,eventLoader,parser}.spec.ts + 5 fixture catalogs (asyncapi, openapi, native, both-specs, invalid)
• test/runtime/typescript/codegen-eventcatalog.mjs + test/inputs/eventcatalog.spec.ts + runtime fixture catalog

Modified Files

• src/codegen/types.ts — zodEventCatalogCodegenConfiguration added; discriminated union extended to 4 arms
• src/codegen/configurations.ts — eventcatalog dispatch arm; mutates configuration.inputType to the effective spec type after loading so downstream generators see a familiar 'asyncapi'/'openapi' discriminator
• src/codegen/renderer.ts — narrowed inputType cast for models/custom (the eventcatalog literal is gone by the time the renderer runs)
• src/codegen/errors.ts — widened validTypes and expectedType union
• src/codegen/inputs/index.ts — re-export the new loader
• src/browser/generate.ts — explicit error path: filesystem-bound, not supported in browser bundle
• src/commands/init.ts — eventcatalog and jsonschema choices added; new --service flag; conditional prompt
• src/telemetry/events.ts — input_type union widened
• examples/eventcatalog-{asyncapi,openapi,native}/codegen.config.mjs — removed "PROPOSED" disclaimers
• test/codegen/configurations.spec.ts — 5 new Zod validation tests
• test/runtime/typescript/package.json — generate:eventcatalog + test:eventcatalog scripts
• docs/{README,configurations,getting-started/README,telemetry,usage}.md — input list, cross-links, telemetry enum, CLI flag listing
• schemas/configuration-schema-0*.json — auto-regenerated with the new union arm

Key Implementation Details

Translation, not a fourth first-class input

The loader populates asyncapiDocument or openapiDocument on RunGeneratorContext and mutates context.configuration.inputType to the effective tag. Every existing generator-side switch (~30 files) keeps working unchanged — only the type/config/dispatch layer touches the new literal.

Native-mode synthesis

Services with no specifications block but with sends/receives events get a synthesized AsyncAPI 3.0 document: one channel per event id, payload from the event's schema.json, action: 'send' for sends, action: 'receive' for receives. This makes presets like channels and client work out-of-the-box without authoring a real AsyncAPI file.

Both-specs services (disambiguation, not multiplexing)

If a service declares both asyncapiPath and openapiPath, the user must set specType: 'asyncapi' | 'openapi'. Generating from both specs in one run is out of scope for v1 (would require running the renderer twice or per-generator dual-document support). Workaround documented: two configs, one with each specType.

Frontmatter parsing

Used the existing yaml@^2.8.0 dep + a manual --- split — no new dependency added.

Testing

Unit Tests

✅ 638 passed, 1 skipped, 74 snapshots, 51 suites

• 25 new EventCatalog-specific unit tests (9 serviceLoader + 5 eventLoader + 6 parser + 5 configurations)
• Coverage on src/codegen/inputs/eventcatalog/: 87–96% statements

Blackbox Tests

✅ 12/12 syntactic compilation tests pass

Runtime Generation

✅ All five runtime:typescript:generate configs succeed:

• regular, request-reply, openapi, payload-types, eventcatalog (new)

Manual Example Verification

✅ All three examples/eventcatalog-* configs run end-to-end and produce code:

• eventcatalog-asyncapi → 11 files
• eventcatalog-openapi → 33 files
• eventcatalog-native → 7 files (channels, client/NatsClient, OrderCreated/OrderShipped/OrderShippedCarrierEnum payloads)

Build / Lint / Format

✅ npm run build — clean
✅ npm run lint:fix — clean (max-warnings 0 + tsconfig.test.json typecheck)
✅ npm run format — clean

Runtime NATS spec

The runtime spec at test/runtime/typescript/test/inputs/eventcatalog.spec.ts was authored and type-checks against the generated NATS code. Executing it requires npm run runtime:services:start (Docker NATS), which CI handles.

Documentation

• New input page: docs/inputs/eventcatalog.md
• docs/README.md — listed in Inputs index
• docs/getting-started/README.md — extended Input Types blurb
• docs/configurations.md — new "Input Types" section with cross-link
• docs/usage.md — regenerated by oclif: --input-type=asyncapi|openapi|jsonschema|eventcatalog, new --service flag
• docs/telemetry.md — input_type enum comment updated

Breaking Changes

None. All existing input types continue to work identically. The discriminated union is widened, not narrowed. No existing config field types changed.

Out of Scope (deferred follow-ups)

These are documented in the new docs page:

1. Dual-spec generation in a single run (use two configs)
2. @eventcatalog/sdk integration (we parse files directly)
3. Cross-service event references
4. Browser-mode EventCatalog support
5. domains/ and flows/ traversal
6. Telemetry originalInputType capture — types already widened, but the runtime telemetry currently records the translated value after dispatch-site mutation. Easy follow-up.

Checklist

• Code follows project conventions
• All tests pass (unit + blackbox + new EventCatalog suites)
• Documentation updated
• No TypeScript errors (both tsconfig.json and tsconfig.test.json)
• Lint passes
• Build succeeds
• Examples work end-to-end
• Follows existing input patterns (mirrors AsyncAPI/OpenAPI/JSON Schema layout)
• No new runtime dependencies

Example

```javascript
// codegen.config.mjs
export default {
inputType: 'eventcatalog',
inputPath: './eventcatalog',
service: 'order-service',
language: 'typescript',
generators: [
{ preset: 'payloads', outputPath: './src/payloads' },
{ preset: 'channels', outputPath: './src/channels', protocols: ['nats'] },
{ preset: 'client', outputPath: './src/client', protocols: ['nats'] }
]
};
```

For an order-service declaring sends: [OrderCreated, OrderShipped] with no spec file, this produces a synthesized AsyncAPI document and generates NATS publish/subscribe channels + a NatsClient exactly as if the user had authored an AsyncAPI 3.0 document by hand.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
the-codegen-project	Ready	Preview, Comment	Apr 26, 2026 8:17pm
the-codegen-project-mcp	Canceled		Apr 26, 2026 8:17pm

[netlify]

✅ Deploy Preview for the-codegen-project canceled.

Name	Link
🔨 Latest commit	76c4e96
🔍 Latest deploy log	https://app.netlify.com/projects/the-codegen-project/deploys/69ee7139f3d6bc00081a7847