skmtc-operation

Operation generators: decompose the operation, reference the models

An operation generator turns each operation — subject (path, method) — into one definition in one file. Unlike models, there is no single output shape: a TanStack hook, a Kotlin SDK method, a form component, and a doc page look nothing alike. What they share is the decomposition: every one of them is assembled from the same subject-derived pieces plus references to model generators' artifacts. Author the composition; never re-derive the pieces.

1. The method

Clone the nearest stock generator by output family (there is no fill-in skeleton for this shape yet):

The clone gives you the anatomy (same package convention as models: entry / base / projection / value snippets). This skill carries the rules the clone can't show you.

2. The subject API — read, never re-parse

Every piece of the operation comes from the engine's OasOperation, by name. Re-spelling any of them (parsing the path yourself, guessing a response shape) breaks the moment the schema evolves.

• Name: derive from method + path via core's toEndpointName(operation) (post→Create, put→Update...), then apply your policy (use prefix, Fn suffix). Never operationId — author-controlled, absent in many specs, unstable across emitters.
• Filter: isSupported({ operation }) in the entry config — claim only what you can render (e.g. mutations require operation.toRequestBody(({ schema }) => schema) to exist). An unfiltered entry constructs subjects it can't handle and fails them one by one.
• Inputs: operation.toParams(['path']) / ['query'] / ['header'] for individual parameters; operation.toParametersObject() for all of them as ONE object schema — the form you hand to a model generator (§3).
• Request body: operation.toRequestBody(({ schema }) => schema).
• Response: operation.toSuccessResponse()?.resolve().toSchema() ?? OasVoid.empty() — selection and void-fallback in one idiom.
• Request line: operation.path and operation.method are stored facts; the target-syntax path template (/users/${id} vs "/users/{id}") is RENDER-time work done by your lang layer's path-template helper inside a toString() body.
• Grouping: operation.tags.

3. The operation law: schemas in your output are peer references

An operation's params object, request body, and response are schemas — and rendering a schema is a MODEL generator's job. The single worst operation-generator failure is rendering one inline: it compiles, then duplicates the model, drifts from the canonical definition, and its imports never settle.

Inline (unnamed) schemas go through the projection's insertNormalizedModel, with a fallback name derived from your own settings identifier so variants stay distinct automatically:

const args = this.insertNormalizedModel(PeerProjection, {
  schema: operation.toParametersObject(),
  fallbackName: `${capitalize(settings.identifier.name)}Args`
})

const response = this.insertNormalizedModel(PeerProjection, {
  schema: operation.toSuccessResponse()?.resolve().toSchema() ?? OasVoid.empty(),
  fallbackName: `${decapitalize(settings.identifier.name)}Response`
})
this.responseName = response.identifier.name   // the NAME is yours; the definition is theirs

Named $ref schemas go through insertModel(Peer, refName) (name via .toName()). Either way: the peer renders the schema ONCE at its own path, your file's import is stitched by the engine, and only the identifier lands in your tree. Import peer projections through their package alias (@skmtc/gen-zod), never by relative path.

What the insert gives you — the name, the placement (normalized models co-locate at YOUR export path via the base wrapper), the declaration form — is the convention. If it does not match what you want, do not fight it by driving the peer's machinery yourself: fabricating a refName to key the peer's identity statics, calling its toExportPath/toIdentifierName directly, or reading fields off its returned value beyond the definition and its name are all the same mistake — a reimplementation of the engine that passes every automated check and breaks on the next peer or engine change. Those are the TWO DOORS of skmtc-generator §4; when neither door fits, do not settle for a degraded render — research how other code generators handle the same edge case (the lang skill's notes, retired in-house generators in git history, OpenAPI Generator's inline-model hoisting). The usual answer is a synthesized named declaration, reached through the peer's exported API or your own lang package's defineAndRegister. If the known solution needs machinery the engine lacks, name the gap in your summary and raise it — never silently ship the degraded form.

4. Dispatch and composition

Models route on schema type; operations route on operation kind — method, response shape, body presence — at the top of the projection:

this.client = match(operation)
  .with({ method: 'get' }, () => isListResponse(operation)
    ? new PaginatedQuery({ context, operation, settings })
    : new Query({ context, operation, settings }))
  .otherwise(() => new Mutation({ context, operation, settings }))

Each kind is its own snippet class taking (context, operation, settings) (OasOperationProjectionConstructorArgs), storing snippets and peer names in its constructor, and composing target syntax ONLY in toString(). Runtime-library imports (useQuery, a client class) register in the constructor. The litmus from skmtc-generator applies with one addition: if you are about to write a schema's target-syntax by hand — a field list, a validator call, a type body — stop; that is a peer insert.

5. Variants

transform({ context, operation, variant }) — pass variant through: context.insertOperation({ projection, operation, variant }). Dropping it constructs every variant as 'main' and dies on the second with Registered definition mismatch. Names fold the variant via withVariant in the base; anything you derive from settings.identifier.name (incl. §3 fallback names) inherits it for free — one reason never to hand-compose those names.

6. Enrichments

Same three-scope umbrella as models; the subject key for operations is [path][method] (plus variant where variants exist). Opt-out stays toEnrichmentSchema = () => emptyEnrichmentSchema.

7. Verify

Generation is sub-second — run after every change. Operation-specific reading order: (1) your artifact's import header — every consumed model must appear as an import of the peer's file (missing = a string swallowed a schema); (2) the peer's files — each consumed schema defined exactly ONCE, named as expected (an Args/Response explosion or a ...2 suffix means fallback names collided or weren't identifier-derived); (3) unsupported operations absent, not errored.

8. Operation pitfalls

9. Boundaries

Engine rules (the one law, memoization, the two insert return shapes, enrichment umbrellas) live in skmtc-generator — read it first. Everything concrete about the emitted language — the to<Lang>OasOperationProjectionBase factory, parameter-list and path-template helpers, import forms — lives in the lang skill (skmtc-lang-typescript). The model side of the seam (how the peer you insert into actually renders schemas) is skmtc-model. Accumulator generators — many subjects appending into one shared definition via the findDefinition ?? defineAndRegister idiom — are a different shape, deliberately not covered here.