Skip to content

CLAUDE.md

Latest commit

 

History

History
79 lines (58 loc) · 7.34 KB

CLAUDE.md

File metadata and controls

79 lines (58 loc) · 7.34 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

@the-codegen-project/cli — an oclif-based CLI (binary name codegen) that reads API specification documents (AsyncAPI v2/v3, OpenAPI 2.0/3.0/3.1 + Swagger, JSON Schema Draft 4/6/7) and generates TypeScript code: payload/message models, parameter models, header models, general types, protocol channel helpers (NATS, Kafka, MQTT, AMQP, EventSource, HTTP client, HTTP server, WebSocket), and full clients. It is a standalone repo that happens to live inside the platform-and-services monorepo — it uses npm (not the monorepo's pnpm) and requires Node.js 22+.

Commands

This project uses npm. Run all commands from this directory (cli/), not the monorepo root.

npm run build            # rimraf dist && tsc && oclif manifest
npm run dev              # tsc --watch
npm run lint             # eslint (max-warnings 0) + typecheck:test — must pass clean
npm run lint:fix         # autofix + typecheck:test
npm run format           # prettier --write on src/**/*.ts
npm test                 # jest with coverage (excludes test/blackbox)
npm run typecheck        # tsc --noEmit

# Run a single test file / pattern
npm test -- --testPathPattern=test/codegen/generators/payloads
npm test -- --testNamePattern="payloads.*asyncapi"
npm test -- -u          # update snapshots (alias: npm run test:update)

MANDATORY before considering any task complete: run npm run prepare:pr (build → generate:assets → lint:fix → test:update → regenerate runtime). It is the project's quality gate — do not mark work done until it passes. See .cursor/rules/task-completion.mdc.

generate:assets regenerates the README table of contents, the command docs under docs/, and the JSON schemas in schemas/ from the Zod schemas (scripts/generateSchemaFiles.js). When you change a generator's Zod schema, these must be regenerated.

Three-tier testing

Correctness is validated at three levels — understand which tier a change needs:

  1. Unit (test/codegen/) — logic and syntax of generator functions. Fast, snapshot-heavy. npm test.
  2. Blackbox (test/blackbox/) — runs real config × input combinations and type-checks the generated output. Excluded from the default npm test; run via npm run test:blackbox.
  3. Runtime (test/runtime/typescript/) — proves generated code works semantically against live message brokers in Docker. This project is also the design surface: per the "Expected Output First" philosophy, you manually write the desired output here and its tests before building the generator that produces it.
npm run runtime:services:start   # docker compose up NATS + Kafka + MQTT + AMQP
npm run runtime:typescript       # full runtime suite (links CLI, generates, tests)
npm run runtime:services:stop

Architecture

CLI and library live in the same package under src/.

  • src/commands/ — oclif commands (generate, init, telemetry), all extending base.ts. bin/run.mjs is the entry point; oclif discovers commands from dist/commands.
  • src/codegen/ — the generation engine:
    • inputs/ — parse + normalize documents into standardized Processed*SchemaData interfaces. One subdir per input type: asyncapi/, openapi/, jsonschema/. Core generators are input-agnostic and only see processed data, never raw documents.
    • generators/ — language generators. generators/typescript/ is the bulk; generators/generic/custom.ts runs user-defined generators. Protocol channel code lives under generators/typescript/channels/protocols/<protocol>/.
    • types.ts — central type definitions and the Zod discriminated unions (zodAsyncAPITypeScriptGenerators, zodOpenAPITypeScriptGenerators, etc.) keyed on the preset field. New generators must be registered here.
    • configurations.ts — loads the user config (JSON/YAML/ESM/CJS/TS via cosmiconfig) and validates it with Zod.
    • renderer.ts — orchestrates generators in dependency order via a graphology render graph.
  • src/browser/ — a separate browser bundle (built with esbuild via esbuild.browser.mjs, npm run build:browser) that runs generation in-memory in a web page. It shims Node-only deps (fs, parsers) under browser/shims/. Used by the playground/website.
  • mcp-server/ — an independent Next.js sub-app (its own package.json, npm install separately) exposing an MCP server.
  • website/ — docs/playground site.

The generation flow

  1. Load & validate the user's codegen config (Zod).
  2. Parse the input document (inputs/<type>/parser.ts).
  3. For each configured generator, run its input processor to produce Processed*SchemaData.
  4. The renderer runs generators in dependency order; TypeScript generators wrap @asyncapi/modelina's TypeScriptFileGenerator and write files with generateToFiles().

Conventions specific to this repo

The .cursor/rules/*.mdc files are the detailed, authoritative spec — read the relevant one before non-trivial work (generators.mdc, inputs.mdc, protocols.mdc, modelina-presets.mdc, code-style.mdc, testing.mdc). Highlights:

  • Object parameters are mandatory for any function (and any generated function) with 2+ parameters — destructured object, explicit type, defaults in the destructure. Positional params only for single-arg / simple math / constructor-like helpers. This applies to callbacks in generated code too: callback: (params: {error?: Error, data?: T}) => void. See code-style.mdc.
  • Every generator follows the fixed shape: a zodTypeScript<Name>Generator schema (with id, preset, outputPath, language + .default() on every optional field), a z.input<> external type and z.infer<> internal type, a generateTypescript<Name>Core function, and a generateTypescript<Name> entry that switches on inputType. See generators.mdc.
  • Zod is the single source of truth for config; JSON schemas in schemas/ are generated from it — never hand-edit generated schema files.
  • Use Logger from src/LoggingInterface.ts, never console.log. Avoid any without justification, hardcoded paths, and sync file ops in generators.
  • MQTT channel code requires protocol v5 (user properties) and must topic-filter incoming messages — see protocols.mdc.
  • Conventional commits (feat:, fix:, docs:, …); releases are automated via semantic-release (.releaserc).
  • No feature without docs + an example: update docs/, add to examples/, regenerate schemas/. Anything under docs/ is written for the reader, not as a record of the work — no "non-goals", no design rationale, no capability rows phrased in negative space (Frameworks other than Express ❌). Use the write-docs skill; docs/protocols/http_client.md is the model page.
  • Protocol lists are duplicated across surfaces the generator doesn't own — the codegen init wizard, the website playground and homepage, and the MCP server tool schemas each keep a hand-maintained copy. test/protocol-surfaces.spec.ts fails with the exact file and literal to add; the add-protocol skill has the full checklist. Never hand-edit the generated copies (website/src/schemas/configuration-schema.json, website/static/codegen.browser.mjs, mcp-server/lib/resources/bundled-docs.ts) — the release pipeline regenerates those.