@thymian/plugin-sampler 0.3.0-canary.20261007-e6cb8dc → 0.3.0-canary.20261007-cdbe1d3

package/dist/generation/types/schema-type.d.ts

@@ -0,0 +1,20 @@
+import { type Declaration } from './declaration-set.js';
+export type GeneratedType = {
+    /** The declarations this type is made of: its own, plus every named
+     * component it references. */
+    declarations: Declaration[];
+    /** The name of the root declaration, usable wherever a type is expected. */
+    type: string;
+};
+/** Whether a media type is one whose body has a JSON shape worth typing. */
+export declare function isJsonMediaType(mediaType: string): boolean;
+/**
+ * The TypeScript type for one schema, with its `examples` reflected into
+ * property types.
+ *
+ * A non-JSON media type is `unknown`: the sampler can generate a body for it,
+ * but a schema is not what describes it, so pretending to type it would be
+ * worse than admitting we do not.
+ */
+export declare function generateSchemaType(schema: unknown, mediaType: string, typeName: string): Promise<GeneratedType>;
+//# sourceMappingURL=schema-type.d.ts.map

package/dist/generation/types/schema-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-type.d.ts","sourceRoot":"","sources":["../../../src/generation/types/schema-type.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,sBAAsB,CAAC;AAG3E,MAAM,MAAM,aAAa,GAAG;IAC1B;kCAC8B;IAC9B,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAmMF,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CA+BxB"}

package/dist/generation/types/schema-type.js

@@ -0,0 +1,203 @@
+import { isRecord } from '@thymian/core';
+import { compile } from 'json-schema-to-typescript';
+import { closedObjectsToBoolean } from '../closed-schema.js';
+import { splitDeclarations } from './declaration-set.js';
+import { reflectExamples } from './example-reflection.js';
+const UNKNOWN = { declarations: [], type: 'unknown' };
+/**
+ * `$defs` is the 2020-12 spelling of the keyword `definitions` names in
+ * draft-07, and `json-schema-to-typescript` only resolves the older one. So
+ * both the key **and** every `$ref` pointing into it are rewritten — renaming
+ * the key alone leaves the pointers aimed at a token that no longer exists,
+ * which fails the whole generation with `Missing $ref pointer`.
+ */
+function defsToDefinitions(input) {
+    if (Array.isArray(input)) {
+        return input.map(defsToDefinitions);
+    }
+    if (!isRecord(input)) {
+        return input;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (key === '$ref' && typeof value === 'string') {
+            out[key] = value.replace(/\/\$defs\//g, '/definitions/');
+            continue;
+        }
+        out[key === '$defs' ? 'definitions' : key] = defsToDefinitions(value);
+    }
+    // A top-level `$ref` beside `definitions` is what a description produces when
+    // a body is exactly one named schema, and the emitter cannot compile that
+    // shape: wrapping the reference in an `allOf` says the same thing in a shape
+    // it can.
+    if ('$ref' in out && 'definitions' in out) {
+        const ref = out['$ref'];
+        delete out['$ref'];
+        out['allOf'] = [{ $ref: ref }];
+    }
+    return out;
+}
+/**
+ * The keywords a schema names ITSELF with, in the library's own precedence
+ * order. All three outrank the name `compile()` is handed, so all three have to
+ * be gone before the schema is compiled.
+ *
+ * The library resolves a declaration name as
+ * `options.customName?.(…) || schema.title || schema.$id || keyNameFromDefinition`
+ * (`json-schema-to-typescript@15/dist/src/parser.js`), and its normalizer only
+ * synthesises the `$id` we rely on `if (!schema.$id && !schema.title …)`. So a
+ * schema-level `title` — which any hand-written OpenAPI document is likely to
+ * carry — makes the library declare `export interface Astronaut` while the
+ * surface still references the name we asked for, and the committed file no
+ * longer compiles. `id` is not covered by removing `$id`: the normalizer runs a
+ * `Transform id to $id` rule AFTER this pass, so the draft-04 spelling walks
+ * back in through the very keyword `$id` was removed to protect.
+ *
+ * None of the three carries type information. `description` is the keyword the
+ * library turns into a JSDoc comment and is deliberately KEPT.
+ *
+ * Enumerating keywords is not a proof, which is why {@link assertDeclares}
+ * turns a keyword this list forgets into a loud failure rather than a surface
+ * that silently does not compile.
+ */
+const NAME_KEYWORDS = ['title', '$id', 'id'];
+/**
+ * The emitter's own extensions, which let a schema write TypeScript directly.
+ *
+ * `tsType` is printed VERBATIM in place of whatever the node would have
+ * compiled to, and `tsEnumNames` mints a `const enum` declaration of its own.
+ * An API description is input — it can be fetched over the network, and it is
+ * not reviewed the way source is — so leaving these through means a description
+ * decides the contents of a file the project commits and compiles against.
+ * `tsType: 'any'` alone silently switches off type checking for that property
+ * everywhere a hook touches it, and a `tsEnumNames` declaration is named after
+ * the property rather than by {@link NameRegistry}, so it can shadow anything.
+ *
+ * The sampler uses `tsType` itself, for example reflection. That is why this
+ * strip runs BEFORE `reflectExamples`: what a description asked for is gone,
+ * and what the generator adds afterwards is its own.
+ */
+const TYPE_DIRECTIVES = ['tsType', 'tsEnumNames'];
+/**
+ * Where a schema nests another schema, by the shape of the position.
+ *
+ * The walk below has to be keyword-aware rather than a blind key filter: `id`
+ * is a name keyword in a SCHEMA position and an ordinary property NAME inside
+ * `properties`, so filtering every key called `id` deletes the `id` property
+ * from every body that has one. That is not hypothetical — it is what the first
+ * version of this strip did, and the type surface it produced was clean
+ * TypeScript describing the wrong object.
+ */
+const NESTED_SCHEMA = {
+    /** Positions holding exactly one schema. */
+    single: [
+        'additionalItems',
+        'additionalProperties',
+        'contains',
+        'else',
+        'if',
+        'items',
+        'not',
+        'propertyNames',
+        'then',
+        'unevaluatedItems',
+        'unevaluatedProperties',
+    ],
+    /** Positions holding an array of schemas. */
+    list: ['allOf', 'anyOf', 'oneOf', 'prefixItems'],
+    /** Positions holding a name-to-schema map, where the KEY is not a keyword. */
+    map: [
+        '$defs',
+        'definitions',
+        'dependentSchemas',
+        'patternProperties',
+        'properties',
+    ],
+};
+/**
+ * Strips the given keywords at every schema position — the root, a nested
+ * property, an array's element, a composition branch and a named component
+ * alike, because the emitter reads them the same way at each of them.
+ */
+function stripKeywords(schema, keywords) {
+    if (!isRecord(schema)) {
+        return schema;
+    }
+    const node = { ...schema };
+    for (const keyword of keywords) {
+        delete node[keyword];
+    }
+    for (const keyword of NESTED_SCHEMA.single) {
+        if (keyword in node) {
+            node[keyword] = stripKeywords(node[keyword], keywords);
+        }
+    }
+    for (const keyword of NESTED_SCHEMA.list) {
+        const branches = node[keyword];
+        if (Array.isArray(branches)) {
+            node[keyword] = branches.map((branch) => stripKeywords(branch, keywords));
+        }
+    }
+    for (const keyword of NESTED_SCHEMA.map) {
+        const members = node[keyword];
+        if (isRecord(members)) {
+            node[keyword] = Object.fromEntries(Object.entries(members).map(([name, member]) => [
+                name,
+                stripKeywords(member, keywords),
+            ]));
+        }
+    }
+    return node;
+}
+/**
+ * Fails if the library did not declare under the name it was handed.
+ *
+ * The surface references `typeName`, so a declaration under any other name is a
+ * dangling reference in a committed file — a `tsc` error for the user, in
+ * generated code they are told not to edit. Catching it here costs one regex
+ * and names the schema that caused it.
+ */
+function assertDeclares(declaration, typeName) {
+    const declared = new RegExp(`^export (?:interface|type) ${typeName}\\b`, 'm').test(declaration);
+    if (!declared) {
+        throw new Error(`The type generator asked for a declaration named ${typeName} and did ` +
+            `not get one. A schema keyword is overriding the name; see ` +
+            `NAME_KEYWORDS in schema-type.ts.`);
+    }
+}
+/** Whether a media type is one whose body has a JSON shape worth typing. */
+export function isJsonMediaType(mediaType) {
+    const essence = mediaType.split(';', 1)[0]?.trim().toLowerCase() ?? '';
+    return essence === 'application/json' || /\+json$/.test(essence);
+}
+/**
+ * The TypeScript type for one schema, with its `examples` reflected into
+ * property types.
+ *
+ * A non-JSON media type is `unknown`: the sampler can generate a body for it,
+ * but a schema is not what describes it, so pretending to type it would be
+ * worse than admitting we do not.
+ */
+export async function generateSchemaType(schema, mediaType, typeName) {
+    if (!isJsonMediaType(mediaType)) {
+        return UNKNOWN;
+    }
+    if (schema === undefined) {
+        return UNKNOWN;
+    }
+    // The strip comes first so that the only `tsType` the emitter sees is the one
+    // example reflection adds next.
+    const stripped = stripKeywords(structuredClone(schema), [
+        ...NAME_KEYWORDS,
+        ...TYPE_DIRECTIVES,
+    ]);
+    const declaration = await compile(defsToDefinitions(closedObjectsToBoolean(reflectExamples(stripped))), typeName, {
+        bannerComment: '',
+        additionalProperties: true,
+        style: { semi: false },
+        $refOptions: { mutateInputSchema: true },
+    });
+    assertDeclares(declaration, typeName);
+    return { declarations: splitDeclarations(declaration), type: typeName };
+}
+//# sourceMappingURL=schema-type.js.map

package/dist/generation/types/schema-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-type.js","sourceRoot":"","sources":["../../../src/generation/types/schema-type.ts"],"names":[],"mappings":"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"}

package/dist/generation/types/self-check-surface.d.ts

@@ -0,0 +1,32 @@
+import { type TypeSurface } from './generate-type-surface.js';
+/**
+ * Compile the emitted declaration files **alone**, with `skipLibCheck: false`,
+ * and report what `tsc` says about them.
+ *
+ * Every path that consumes the surface afterwards — the scaffolded tsconfig,
+ * `typecheckHooks`, the hook-authoring compile probe — sets `skipLibCheck:
+ * true`, because a user's own `@types` tree is not the sampler's business to
+ * police. That is exactly the flag that stops TypeScript from reporting an
+ * error *inside* a `.d.ts`, so the file the sampler commits — and whose diff
+ * is the drift signal every other gate trusts — is the one file none of those
+ * paths actually check. This is the check that does.
+ *
+ * Both files are given as program roots, not just one: `hooksApi` imports
+ * `requestTypes`, so a root of `requestTypes` alone never pulls `hooksApi`
+ * into the program, and a defect confined to the (mostly static) hooks
+ * surface would go unreported.
+ */
+export declare function surfaceDiagnostics(surface: TypeSurface): Promise<string[]>;
+/**
+ * The self-check gate: refuse to hand back a surface that does not compile.
+ *
+ * Called wherever a fresh surface is produced — `init`, `sync`, and
+ * `validate`'s scratch surface — so no emitter defect, present or future, can
+ * hide behind a user's own compiler settings (`skipLibCheck` among them) and
+ * surface later as a confusing error in their hooks. The message and the
+ * `GeneratedSurfaceError` name deliberately attribute the fault to the
+ * generator: whatever a diagnostic here says, it is never something a user's
+ * API description or hooks could have caused.
+ */
+export declare function selfCheckSurface(surface: TypeSurface): Promise<void>;
+//# sourceMappingURL=self-check-surface.d.ts.map

package/dist/generation/types/self-check-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-check-surface.d.ts","sourceRoot":"","sources":["../../../src/generation/types/self-check-surface.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CA2DnB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB1E"}

package/dist/generation/types/self-check-surface.js

@@ -0,0 +1,92 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ThymianBaseError } from '@thymian/core';
+import ts from 'typescript';
+import { tsPathRelativeTo } from '../../ts-path.js';
+import { sharedCompilerHost } from '../../validation/shared-compiler-host.js';
+import { HOOKS_API_FILE, REQUEST_TYPES_FILE, } from './generate-type-surface.js';
+/**
+ * Compile the emitted declaration files **alone**, with `skipLibCheck: false`,
+ * and report what `tsc` says about them.
+ *
+ * Every path that consumes the surface afterwards — the scaffolded tsconfig,
+ * `typecheckHooks`, the hook-authoring compile probe — sets `skipLibCheck:
+ * true`, because a user's own `@types` tree is not the sampler's business to
+ * police. That is exactly the flag that stops TypeScript from reporting an
+ * error *inside* a `.d.ts`, so the file the sampler commits — and whose diff
+ * is the drift signal every other gate trusts — is the one file none of those
+ * paths actually check. This is the check that does.
+ *
+ * Both files are given as program roots, not just one: `hooksApi` imports
+ * `requestTypes`, so a root of `requestTypes` alone never pulls `hooksApi`
+ * into the program, and a defect confined to the (mostly static) hooks
+ * surface would go unreported.
+ */
+export async function surfaceDiagnostics(surface) {
+    const root = await mkdtemp(join(tmpdir(), 'thymian-surface-check-'));
+    try {
+        const generated = join(root, 'generated');
+        const requestTypes = join(generated, REQUEST_TYPES_FILE);
+        const hooksApi = join(generated, HOOKS_API_FILE);
+        await mkdir(generated, { recursive: true });
+        await writeFile(requestTypes, surface.requestTypes, 'utf-8');
+        await writeFile(hooksApi, surface.hooksApi, 'utf-8');
+        const options = {
+            strict: true,
+            noEmit: true,
+            module: ts.ModuleKind.NodeNext,
+            moduleResolution: ts.ModuleResolutionKind.NodeNext,
+            target: ts.ScriptTarget.ES2023,
+            // The whole point of this probe: do not skip the files under test.
+            skipLibCheck: false,
+            baseUrl: root,
+            paths: { '@thymian/hooks': [`./generated/${HOOKS_API_FILE}`] },
+            lib: ['lib.es2023.d.ts'],
+            types: [],
+        };
+        const program = ts.createProgram([hooksApi, requestTypes], options, sharedCompilerHost(options));
+        return ts.getPreEmitDiagnostics(program).flatMap((diagnostic) => {
+            const file = diagnostic.file;
+            // `generated` is a `node:path` value; TypeScript's own `fileName`s are
+            // forward-slashed. `tsPathRelativeTo` normalizes both, which keeps this
+            // correct on Windows.
+            const relativeFile = file
+                ? tsPathRelativeTo(file.fileName, generated)
+                : undefined;
+            if (!file || relativeFile === undefined) {
+                return [];
+            }
+            const { line } = file.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+            const where = `${relativeFile}:${line + 1}`;
+            const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ');
+            return [`${where} TS${diagnostic.code}: ${message}`];
+        });
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+/**
+ * The self-check gate: refuse to hand back a surface that does not compile.
+ *
+ * Called wherever a fresh surface is produced — `init`, `sync`, and
+ * `validate`'s scratch surface — so no emitter defect, present or future, can
+ * hide behind a user's own compiler settings (`skipLibCheck` among them) and
+ * surface later as a confusing error in their hooks. The message and the
+ * `GeneratedSurfaceError` name deliberately attribute the fault to the
+ * generator: whatever a diagnostic here says, it is never something a user's
+ * API description or hooks could have caused.
+ */
+export async function selfCheckSurface(surface) {
+    const diagnostics = await surfaceDiagnostics(surface);
+    if (diagnostics.length === 0) {
+        return;
+    }
+    throw new ThymianBaseError(`The sampler generated a type surface that does not compile (${diagnostics.length} ${diagnostics.length === 1 ? 'diagnostic' : 'diagnostics'}). This is a defect in the sampler's own generator — not your API description or your hooks — please report it.`, {
+        name: 'GeneratedSurfaceError',
+        ref: 'https://thymian.dev/references/errors/generated-surface-error/',
+        suggestions: diagnostics,
+    });
+}
+//# sourceMappingURL=self-check-surface.js.map

package/dist/generation/types/self-check-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-check-surface.js","sourceRoot":"","sources":["../../../src/generation/types/self-check-surface.ts"],"names":[],"mappings":"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"}

package/dist/generation/types/type-names.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Deterministic TypeScript identifiers for the declarations the type surface
+ * emits.
+ *
+ * Every name is a pure function of the transaction's selector plus the schema's
+ * role within that transaction. Naming by catalog position instead
+ * (`Transaction4Type2`) is stable under a document reorder but not under an
+ * *insertion*: a new endpoint that sorts first renumbers every declaration
+ * after it. The surface is committed and the diff against it **is** the
+ * staleness signal, so a positional name turns adding one endpoint into a
+ * whole-file diff — 282 changed lines on the demo description, for one added
+ * operation.
+ *
+ * SANITISATION IS NOT COSMETIC AND THE COLLISION SUFFIX IS NOT DEFENSIVE. A
+ * selector legitimately carries characters no identifier can: a method is an
+ * RFC 9110 section 5.6.2 token, paths carry `/`, `{`, `}` and percent-encoding,
+ * and media types carry `/`, `+`, `;` and `=`. Two distinct selectors therefore
+ * collapse onto one stem — methods `A-B` and `A.B` on the same path both
+ * sanitise to `AB` — so the suffix is reached by real input.
+ *
+ * THE NAME WE REFERENCE AND THE NAME THE LIBRARY DECLARES ARE ONE STRING.
+ * `json-schema-to-typescript` does not declare under the name it is handed: it
+ * declares under `toSafeString(name)`, which re-cases a lowercase letter that
+ * follows a digit (`V1beta` becomes `V1Beta`), collapses `_x` into `X` and
+ * upper-cases the first letter. A positional name is already a fixed point of
+ * that transform; a selector-derived one is not, and a name that changes on the
+ * way in is a dangling reference on the way out. {@link safeIdentifier} is the
+ * single boundary, and {@link NameRegistry} uniquifies AFTER it — so two
+ * candidates that sanitise onto one identifier get a suffix rather than one
+ * declaration emitted twice under two names.
+ */
+/**
+ * The fixed declarations `generate-type-surface.ts` emits around the
+ * generated ones. Shared by {@link NameRegistry} (so a generated declaration
+ * never shadows one of these) and by `DeclarationSet` (so a description
+ * component named after one of these — `Status`, say — is reserved out from
+ * under it rather than silently merged into it, which is what let a
+ * description declaring a `Status` component reach the committed surface as
+ * two conflicting `export type Status` and `export interface Status`
+ * declarations, `skipLibCheck` hiding the fault until a user's own hook
+ * compile — or, once the self-check gate is on, at generation time with an
+ * unattributed `TS2300`).
+ */
+export declare const FIXED_ROOT_NAMES: readonly ["Endpoints", "Method", "Path", "RequestMediaType", "ResponseMediaType", "Responses", "Selector", "Status", "StatusClass", "TransactionResponse", "WireMediaType"];
+/** Which schema of a transaction a declaration was generated for. */
+export type SchemaRole = {
+    readonly kind: 'request-body';
+} | {
+    readonly kind: 'response-body';
+} | {
+    readonly kind: 'query-parameter';
+    readonly parameter: string;
+} | {
+    readonly kind: 'path-parameter';
+    readonly parameter: string;
+} | {
+    readonly kind: 'request-header';
+    readonly parameter: string;
+} | {
+    readonly kind: 'cookie';
+    readonly parameter: string;
+} | {
+    readonly kind: 'response-header';
+    readonly parameter: string;
+};
+/**
+ * Splits on every run of non-alphanumeric characters and upper-cases each
+ * remaining segment's first character, so `GET`, `astronauts`, `{id}` and
+ * `application/vnd.Example+JSON` become `Get`, `Astronauts`, `Id` and
+ * `ApplicationVndExampleJson`.
+ *
+ * The tail is lower-cased deliberately: a declaration NAME is not required to
+ * be byte-exact — only the emitted selector keys and union members are — and
+ * folding it keeps `JSON` and `json` from producing two visually
+ * indistinguishable identifiers.
+ */
+export declare function pascalSegments(value: string): string;
+/** The role's contribution to a declaration name. */
+export declare function roleSuffix(role: SchemaRole): string;
+/**
+ * The identifier a selector plus a role WANTS. Several sites may want the same
+ * one; {@link NameRegistry} is what turns wants into names.
+ *
+ * A method is an RFC 9110 token, so it may be all digits (`123 /x` is a legal
+ * selector), and a parameter name may start with one (`2fa`). Neither an
+ * identifier nor the library's own transform tolerates a leading digit, so the
+ * candidate leaves through {@link safeIdentifier} rather than through a local
+ * guard.
+ */
+export declare function candidateName(selector: string, role: SchemaRole): string;
+/**
+ * An identifier `json-schema-to-typescript`'s `toSafeString` leaves alone, for
+ * any input string.
+ *
+ * The contract is deliberately weaker than "reproduce `toSafeString`": the
+ * library never sees the original, only this function's output, so all that has
+ * to hold is that the output is a FIXED POINT of the library's transform. That
+ * is four conditions, and each is enforced by one branch below:
+ *
+ * - every character is in `[A-Za-z0-9_$]`, so nothing is replaced by whitespace;
+ * - the first character is never a digit, hence the `_` prefix;
+ * - no lowercase letter follows a digit, a `$` or an `_`;
+ * - the first character is never lowercase, so `upperFirst` is a no-op.
+ *
+ * A run of unusable characters is a word boundary rather than a deletion, so
+ * `foo bar` and `foo-bar` both become `FooBar` — the same convention
+ * {@link pascalSegments} uses, which is why applying both is harmless.
+ */
+export declare function safeIdentifier(value: string): string;
+/**
+ * Hands out unique identifiers, remembering what each site was given.
+ *
+ * The suffix order is a function of the description rather than of traversal
+ * order, because the catalog is sorted by selector and each transaction's
+ * schemas are visited in a fixed role order. Adding a transaction that collides
+ * with an existing stem can renumber the colliding group, and only that group;
+ * adding a non-colliding one — the overwhelmingly common case — renames
+ * nothing.
+ */
+export declare class NameRegistry {
+    private readonly used;
+    private readonly byKey;
+    /**
+     * @param reserved names nothing may be assigned, such as the fixed
+     * declarations the surface emits around the generated ones.
+     */
+    constructor(reserved?: Iterable<string>);
+    /**
+     * The name for `selector` in `role`, minted the first time it is asked for
+     * and returned unchanged thereafter — so two references to one site cannot
+     * drift apart.
+     */
+    nameFor(selector: string, role: SchemaRole): string;
+}
+//# sourceMappingURL=type-names.d.ts.map

package/dist/generation/types/type-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-names.d.ts","sourceRoot":"","sources":["../../../src/generation/types/type-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,6KAYnB,CAAC;AAEX,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASpD;AAcD,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAiBnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAMxE;AAYD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiCpD;AAED;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IAEnD;;;OAGG;gBACS,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAM;IAI3C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM;CAsBpD"}