@skmtc/core overview

Index of exports from @skmtc/core for engine consumers. This is the navigation page — each section links to the detailed reference for the class or function.

@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 and the three phases concept.

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:

import {
  toArtifacts,
  GenerateContext,
  Identifier,
  toOasOperationEntry,
  OasOperation
} from '@skmtc/core'

Pipeline entry points

The functions you call to run the engine.

Export	Purpose	Reference
`toArtifacts`	Run Parse → Generate → Render end-to-end	toArtifacts
`toOasOperationEntry`	Factory for operation generators	Projection bases
`toModelEntry`	Factory for model generators	Projection bases
`toGqlOperationEntry`	Factory for GraphQL operation generators	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

The per-phase orchestrators. Each is created internally by toArtifacts; generator code interacts with the Generate context heavily.

Class	Phase	Reference
`ParseContext`	Parse	ParseContext
`GenerateContext`	Generate	GenerateContext
`RenderContext`	Render	RenderContext

GenerateContext is the one generator code touches most — via this.context.register(...), insertOperation(...), insertModel(...), etc.

DSL classes

The building blocks generators use to produce code.

Class	Role	Reference
`SnippetBase`	Root class for Snippets (anonymous helpers) and Projections	SnippetBase
`Definition`	Wraps a Projection's value into `export const NAME =`	Definition
`Identifier`	Name + entity-type marker (`'variable'` vs `'type'`); the discriminator maps to `const` vs `type` declaration keywords	Identifier
`Import`	Rendered `import { X } from '...'` statement	Import
`ContentSettings`	Per-Projection bundle (identifier, exportPath, enrichments)	ContentSettings
`File`	Output file with imports, definitions, and metadata	File
`JsonFile`	Variant of File for JSON output	JsonFile
`CustomValue`	Wraps raw strings as DSL values	CustomValue
`Inserted`	Marker class returned by `insertNormalizedModel` etc.	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)

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
`toModelProjectionBase`	Model generators (OAS schemas)	Projection bases
`toGqlOperationProjectionBase`	GraphQL operation generators	Projection bases

The base classes provide insertOperation, insertModel, and insertNormalizedModel — thin wrappers around the same-named methods on GenerateContext that auto-fill destinationPath from settings.exportPath. They also enforce the constructor's args: { context, operation/schema, settings } contract.

OAS object model

The parsed OpenAPI document. See OAS document model for the full set.

Class	Reference
`OasDocument`	OAS document model
`OasOperation`	OAS document model
`OasResponse`, `OasRequestBody`, `OasParameter`, `OasHeader`	OAS document model
`OasMediaType`, `OasExample`, `OasComponents`	OAS document model
`OasSchema` (the union) and its 8 variants	OAS schema variants
`OasRef<T>`	OasRef
`OasVoid`	OasRef (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 for the "why not a BaseSchema" discussion.

GraphQL object model

Class	Purpose	Reference
`GqlDocument`	Parsed GraphQL schema	GqlDocument
`GqlRegistry`	Looks up GraphQL types by name	GqlDocument
`GqlOperation`	A single GraphQL operation	GqlDocument
`GqlType` (union)	Set of GraphQL types (object, scalar, enum, etc.)	GqlDocument

GraphQL parsing happens worker-side (unlike OAS, which is host-side). See the worker runtime concept for the reason.

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

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

Helper	Purpose
`tryParseAt(ctx, key, valibotSchema, value)`	Lenient parse with fail-open behavior — see error handling philosophy
`removeErroredItems`	One-hop pruning of items whose dependencies failed to parse

Stack trail and tracing

Class	Purpose	Reference
`StackTrail`	Threads "where am I in the doc graph" through all phases	StackTrail

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

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 for the full reasoning.

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.