# @skmtc/core overview `@skmtc/core` is the engine package — Apache 2.0, no JSR-published generators included. It carries the three-phase pipeline, the context classes, the DSL primitives, the OAS and GraphQL parsed models, and the helpers that generators and Drivers depend on. For the broader system context (the CLI, stock generators, the worker runtime), see the [docs README](/docs) and [the three phases concept](/docs/concepts/the-three-phases). ## Top-level exports [#top-level-exports] The package's `mod.ts` re-exports from internal modules. There is no deep-import support (e.g., `@skmtc/core/dsl`) — consumers always import from the top-level package: ```ts import { toArtifacts, GenerateContext, Identifier, toOasOperationEntry, OasOperation } from '@skmtc/core' ``` ## Pipeline entry points [#pipeline-entry-points] The functions you call to run the engine. | Export | Purpose | Reference | | --------------------- | ---------------------------------------- | -------------------------------------------------------- | | `toArtifacts` | Run Parse → Generate → Render end-to-end | [toArtifacts](/docs/reference/api/to-artifacts) | | `toOasOperationEntry` | Factory for operation generators | [Projection bases](/docs/reference/api/projection-bases) | | `toModelEntry` | Factory for model generators | [Projection bases](/docs/reference/api/projection-bases) | | `toGqlOperationEntry` | Factory for GraphQL operation generators | [Projection bases](/docs/reference/api/projection-bases) | `toArtifacts` is the engine's true entry point. The `toXxxEntry` factories are the generator-author entry points — what each generator's `mod.ts` exports. ## Context classes [#context-classes] The per-phase orchestrators. Each is created internally by `toArtifacts`; generator code interacts with the Generate context heavily. | Class | Phase | Reference | | ----------------- | -------- | ------------------------------------------------------- | | `ParseContext` | Parse | [ParseContext](/docs/reference/api/parse-context) | | `GenerateContext` | Generate | [GenerateContext](/docs/reference/api/generate-context) | | `RenderContext` | Render | [RenderContext](/docs/reference/api/render-context) | `GenerateContext` is the one generator code touches most — via `this.context.register(...)`, `insertOperation(...)`, `insertModel(...)`, etc. ## DSL classes [#dsl-classes] The building blocks generators use to produce code. | Class | Role | Reference | | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | `SnippetBase` | Root class for Snippets (anonymous helpers) and Projections | [SnippetBase](/docs/reference/api/dsl-snippet-base) | | `Definition` | Wraps a Projection's value into `export const NAME =` | [Definition](/docs/reference/api/dsl-definition) | | `Identifier` | Name + entity-type marker (`'variable'` vs `'type'`); the discriminator maps to `const` vs `type` declaration keywords | [Identifier](/docs/reference/api/dsl-identifier) | | `Import` | Rendered `import { X } from '...'` statement | [Import](/docs/reference/api/dsl-import) | | `ContentSettings` | Per-Projection bundle (identifier, exportPath, enrichments) | [ContentSettings](/docs/reference/api/content-settings) | | `File` | Output file with imports, definitions, and metadata | [File](/docs/reference/api/dsl-file) | | `JsonFile` | Variant of File for JSON output | [JsonFile](/docs/reference/api/dsl-file) | | `CustomValue` | Wraps raw strings as DSL values | [CustomValue](/docs/reference/api/dsl-custom-value) | | `Inserted` | Marker class returned by `insertNormalizedModel` etc. | [Inserted](/docs/reference/api/dsl-inserted) | The DSL classes form a small set of well-defined primitives. The operational principle: **use them, don't bypass them** — raw strings in identifier positions break the import-rendering story under `verbatimModuleSyntax`. See the skmtc-generator skill for the full anti-patterns table. ## Projection bases (factories) [#projection-bases-factories] The three factory functions that produce Projection base classes. Generators extend the result. | Factory | Produces base for | Reference | | ------------------------------ | ----------------------------------------- | -------------------------------------------------------- | | `toOasOperationProjectionBase` | OAS operation generators (REST endpoints) | [Projection bases](/docs/reference/api/projection-bases) | | `toModelProjectionBase` | Model generators (OAS schemas) | [Projection bases](/docs/reference/api/projection-bases) | | `toGqlOperationProjectionBase` | GraphQL operation generators | [Projection bases](/docs/reference/api/projection-bases) | The base classes provide `insertOperation`, `insertModel`, and `insertNormalizedModel` — thin wrappers around the same-named methods on [GenerateContext](/docs/reference/api/generate-context) that auto-fill `destinationPath` from `settings.exportPath`. They also enforce the constructor's `args: { context, operation/schema, settings }` contract. ## OAS object model [#oas-object-model] The parsed OpenAPI document. See [OAS document model](/docs/reference/api/oas-document-model) for the full set. | Class | Reference | | ------------------------------------------------------------ | -------------------------------------------------------------- | | `OasDocument` | [OAS document model](/docs/reference/api/oas-document-model) | | `OasOperation` | [OAS document model](/docs/reference/api/oas-document-model) | | `OasResponse`, `OasRequestBody`, `OasParameter`, `OasHeader` | [OAS document model](/docs/reference/api/oas-document-model) | | `OasMediaType`, `OasExample`, `OasComponents` | [OAS document model](/docs/reference/api/oas-document-model) | | `OasSchema` (the union) and its 8 variants | [OAS schema variants](/docs/reference/api/oas-schema-variants) | | `OasRef` | [OasRef](/docs/reference/api/oas-ref) | | `OasVoid` | [OasRef](/docs/reference/api/oas-ref) (used in same contexts) | The union-with-discriminator pattern (`OasSchema` is a union of 8 sibling classes, **not** a class hierarchy) is load-bearing. See the [OAS schema variants reference](/docs/reference/api/oas-schema-variants) for the "why not a BaseSchema" discussion. ## GraphQL object model [#graphql-object-model] | Class | Purpose | Reference | | ----------------- | ------------------------------------------------- | ----------------------------------------------- | | `GqlDocument` | Parsed GraphQL schema | [GqlDocument](/docs/reference/api/gql-document) | | `GqlRegistry` | Looks up GraphQL types by name | [GqlDocument](/docs/reference/api/gql-document) | | `GqlOperation` | A single GraphQL operation | [GqlDocument](/docs/reference/api/gql-document) | | `GqlType` (union) | Set of GraphQL types (object, scalar, enum, etc.) | [GqlDocument](/docs/reference/api/gql-document) | GraphQL parsing happens **worker-side** (unlike OAS, which is host-side). See [the worker runtime concept](/docs/concepts/the-worker-runtime) for the reason. ## Type system helpers [#type-system-helpers] The TypeScript-level utility types and interfaces. | Type | Purpose | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `IdentifierType` | `{ type: string; typeName?; exported? }` — the non-name identifier parts `toIdentifierType` returns; the per-language declaration vocabulary (`TsEntityType`, `'variable' \| 'type' \| 'class' \| 'interface' \| 'namespace'`) and its keyword mapping live in `@skmtc/lang-typescript` | | `ImportNameArg` | `string \| { name, alias?, type? }` — input to `register({ imports })` | | `GeneratedValue` | Base structural type for what `Definition` wraps | | `Method` | HTTP method literal type | | `OasParameterLocation` | `'path' \| 'query' \| 'header' \| 'cookie'` | | `OasComponentType` | Union of all top-level OAS component classes | | `Stringable` | Anything with a `toString(): string` — every DSL primitive implements it | ### Naming and identifier helpers [#naming-and-identifier-helpers] | Helper | Purpose | | --------------------------- | ------------------------------------------------------------------ | | `toEndpointName(operation)` | Operation → camelCase name (fallback when `operationId` is absent) | | `camelCase(s)` | String → camelCase | | `capitalize(s)` | First-letter uppercase | | `decapitalize(s)` | First-letter lowercase | | `toMethodVerb(method)` | HTTP method → verb name (e.g., `'post'` → `'Create'`) | | `isIdentifierName(s)` | Check if a string is a valid JS identifier | ### Parsing helpers [#parsing-helpers] | Helper | Purpose | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `tryParseAt(ctx, key, valibotSchema, value)` | Lenient parse with fail-open behavior — see [error handling philosophy](/docs/concepts/error-handling-philosophy) | | `removeErroredItems` | One-hop pruning of items whose dependencies failed to parse | ## Stack trail and tracing [#stack-trail-and-tracing] | Class | Purpose | Reference | | ------------ | -------------------------------------------------------- | --------------------------------------------- | | `StackTrail` | Threads "where am I in the doc graph" through all phases | [StackTrail](/docs/reference/api/stack-trail) | `StackTrail` is the single piece of cross-phase context that survives phase teardown. The CLI creates one at the top of `toArtifacts` and passes it down; each phase appends segments as it descends. When an error surfaces, the trail provides "where in the spec did this happen" context for the diagnostic. ## License [#license] The engine (`@skmtc/core`) is **Apache 2.0**, providing: * A patent grant from contributors * Clear contributor terms via the Apache CLA structure * Compatibility with most open-source licenses This contrasts with the stock generators in `@skmtc/gen-*`, which are **MIT** — chosen for fork-friendliness (the clone-to-customize philosophy). See the [license rationale in the README](/docs#license) for the full reasoning. ## Versioning [#versioning] `@skmtc/core` follows semantic versioning. Breaking changes to: * Context class APIs (e.g., `register` signature) * DSL class APIs (e.g., the lang package's `createVariable`) * OAS or GraphQL parsed model shapes are major-version bumps. Additive changes (new helper methods, new exported types) are minor bumps. Stock generators tend to lag the engine by a minor version while they adapt to API additions. ## See also [#see-also] * [The three phases concept](/docs/concepts/the-three-phases) — pipeline overview * [Projections and Snippets concept](/docs/concepts/projections-and-snippets) — DSL mental model * [Cross-generator coordination concept](/docs/concepts/cross-generator-coordination) — how DSL primitives compose * [The worker runtime concept](/docs/concepts/the-worker-runtime) — how the engine is hosted * [Reference: glossary](/docs/reference/glossary) — terminology * skmtc-generator skill — operational distillation for generator authoring