@redocly/client-generator 0.3.8 → 0.4.0

package/lib/authoring/pagination.js

@@ -0,0 +1,45 @@
+// Language-neutral pagination-rule resolution: which rule applies to an operation
+// (per-op config > the `x-redoclyPagination` extension > a fitting convention) and
+// its normalized shape. Declaration-based — the TS toolkit's static fit VERIFICATION
+// (schema-level advance-param/pointer checks) remains generation-side; this helper is
+// what every language generator shares.
+/**
+ * Pagination for one operation. The convention rule applies only where it structurally
+ * fits — the advance parameter exists on the operation, or for `link` (which has no
+ * parameter) the success response documents a `Link` header; `exclude` kills every source.
+ * Returns undefined when the operation does not paginate.
+ */
+export function paginationRuleFor(op, config) {
+    const configuration = config ?? {};
+    const id = op.specName ?? op.name;
+    if (Array.isArray(configuration.exclude) && configuration.exclude.includes(id)) {
+        return undefined;
+    }
+    const operations = (configuration.operations ?? {});
+    let rule = operations[id] ?? op.paginationExtension;
+    if (rule === undefined && typeof configuration.style === 'string') {
+        const { exclude: _exclude, operations: _operations, ...convention } = configuration;
+        const advance = convention.style === 'cursor' ? convention.cursorParam : convention.offsetParam;
+        // A convention needs a structural fit signal: the advance parameter for cursor/offset/
+        // page, and a documented `Link` response header for `link` (which has no parameter) —
+        // the same gate the TypeScript emitter applies. Without it, a link convention would
+        // attach page iterators to every operation in the description.
+        const fits = convention.style === 'link'
+            ? op.successResponseHeaders?.some((header) => header.name === 'link') === true
+            : typeof advance === 'string' && op.queryParams.some((param) => param.name === advance);
+        if (fits)
+            rule = convention;
+    }
+    if (rule === undefined || typeof rule.style !== 'string')
+        return undefined;
+    const param = rule.style === 'cursor' ? rule.cursorParam : rule.offsetParam;
+    return {
+        style: rule.style,
+        ...(typeof param === 'string' ? { param } : {}),
+        ...(typeof rule.nextCursor === 'string' ? { nextCursor: rule.nextCursor } : {}),
+        ...(typeof rule.hasMore === 'string' ? { hasMore: rule.hasMore } : {}),
+        ...(typeof rule.limitParam === 'string' ? { limitParam: rule.limitParam } : {}),
+        ...(typeof rule.items === 'string' ? { items: rule.items } : {}),
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/lib/authoring/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/authoring/pagination.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,mFAAmF;AACnF,qFAAqF;AACrF,sFAAsF;AACtF,wCAAwC;AAexC;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,EAAkB,EAClB,MAA2C;IAE3C,MAAM,aAAa,GAAG,MAAM,IAAI,EAAE,CAAC;IACnC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAC/E,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,aAAa,CAAC,UAAU,IAAI,EAAE,CAA4C,CAAC;IAC/F,IAAI,IAAI,GACN,UAAU,CAAC,EAAE,CAAC,IAAK,EAAE,CAAC,mBAA2D,CAAC;IACpF,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,aAAa,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAClE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,UAAU,EAAE,GAAG,aAAa,CAAC;QACpF,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC;QAChG,uFAAuF;QACvF,sFAAsF;QACtF,oFAAoF;QACpF,+DAA+D;QAC/D,MAAM,IAAI,GACR,UAAU,CAAC,KAAK,KAAK,MAAM;YACzB,CAAC,CAAC,EAAE,CAAC,sBAAsB,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,IAAI;YAC9E,CAAC,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAC5F,IAAI,IAAI;YAAE,IAAI,GAAG,UAAqC,CAAC;IACzD,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC;IAC5E,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC"}

package/lib/authoring/printer.d.ts

@@ -0,0 +1,16 @@
+export declare class Printer {
+    private readonly indentUnit;
+    private readonly lines;
+    private depth;
+    constructor(indentUnit?: string);
+    /** Append one line at the current depth; no argument appends an empty line. */
+    line(text?: string): this;
+    blank(): this;
+    /** Run `body` with the depth increased by one. */
+    indent(body: () => void): this;
+    /** `open` at the current depth, `body` indented, `close` back at the current depth.
+     * Omit `close` for languages whose blocks end by dedent alone (Python, YAML). */
+    block(open: string, body: () => void, close?: string): this;
+    toString(): string;
+}
+//# sourceMappingURL=printer.d.ts.map

package/lib/authoring/printer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"printer.d.ts","sourceRoot":"","sources":["../../src/authoring/printer.ts"],"names":[],"mappings":"AAGA,qBAAa,OAAO;IAIN,OAAO,CAAC,QAAQ,CAAC,UAAU;IAHvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,KAAK,CAAK;gBAEW,UAAU,GAAE,MAAa;IAEtD,+EAA+E;IAC/E,IAAI,CAAC,IAAI,SAAK,GAAG,IAAI;IAKrB,KAAK,IAAI,IAAI;IAIb,kDAAkD;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI;IAO9B;qFACiF;IACjF,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAM3D,QAAQ,IAAI,MAAM;CAGnB"}

package/lib/authoring/printer.js

@@ -0,0 +1,36 @@
+// A small indentation-aware text builder for emitting code in ANY language —
+// deliberately not an AST. Part of the language-neutral authoring toolkit.
+export class Printer {
+    indentUnit;
+    lines = [];
+    depth = 0;
+    constructor(indentUnit = '  ') {
+        this.indentUnit = indentUnit;
+    }
+    /** Append one line at the current depth; no argument appends an empty line. */
+    line(text = '') {
+        this.lines.push(text === '' ? '' : this.indentUnit.repeat(this.depth) + text);
+        return this;
+    }
+    blank() {
+        return this.line();
+    }
+    /** Run `body` with the depth increased by one. */
+    indent(body) {
+        this.depth++;
+        body();
+        this.depth--;
+        return this;
+    }
+    /** `open` at the current depth, `body` indented, `close` back at the current depth.
+     * Omit `close` for languages whose blocks end by dedent alone (Python, YAML). */
+    block(open, body, close) {
+        this.line(open);
+        this.indent(body);
+        return close === undefined ? this : this.line(close);
+    }
+    toString() {
+        return this.lines.join('\n') + '\n';
+    }
+}
+//# sourceMappingURL=printer.js.map

package/lib/authoring/printer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"printer.js","sourceRoot":"","sources":["../../src/authoring/printer.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAE3E,MAAM,OAAO,OAAO;IAIW;IAHZ,KAAK,GAAa,EAAE,CAAC;IAC9B,KAAK,GAAG,CAAC,CAAC;IAElB,YAA6B,aAAqB,IAAI;QAAzB,eAAU,GAAV,UAAU,CAAe;IAAG,CAAC;IAE1D,+EAA+E;IAC/E,IAAI,CAAC,IAAI,GAAG,EAAE;QACZ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED,kDAAkD;IAClD,MAAM,CAAC,IAAgB;QACrB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,EAAE,CAAC;QACP,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED;qFACiF;IACjF,KAAK,CAAC,IAAY,EAAE,IAAgB,EAAE,KAAc;QAClD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACtC,CAAC;CACF"}

package/lib/authoring/reference-page.d.ts

@@ -0,0 +1,31 @@
+import type { ApiModel, OperationModel } from '../intermediate-representation/model.js';
+/** What a generator knows about its language that the IR cannot tell the renderer. */
+export type ReferenceLanguage = {
+    /** Generator name; also the infix of the page file (`<stem>.python.md`). */
+    name: string;
+    /** Display name for the default heading. */
+    label: string;
+    /** Fence language for the call samples. */
+    fence: string;
+    /** What the SDK needs at run time, as one sentence. */
+    requires: string;
+};
+export type ReferencePageOptions = {
+    /** Page heading. */
+    title: string;
+    /** Emit YAML front matter carrying the title, for docs sites that expect it. */
+    frontmatter: boolean;
+    language: ReferenceLanguage;
+    /** The call snippet for one operation — the generator's own `sample` hook. */
+    sample: (operation: OperationModel) => {
+        lang: string;
+        source: string;
+    } | undefined;
+    /** The `pagination` config, passed through to `paginationRuleFor`. */
+    pagination?: Record<string, unknown>;
+    /** Operation names the RUN resolved as paginated — preferred over re-resolving. */
+    paginated?: ReadonlySet<string>;
+};
+/** The whole page: heading, requirements, security schemes, then every operation by tag. */
+export declare function renderReferencePage(model: ApiModel, options: ReferencePageOptions): string;
+//# sourceMappingURL=reference-page.d.ts.map

package/lib/authoring/reference-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-page.d.ts","sourceRoot":"","sources":["../../src/authoring/reference-page.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EAGf,MAAM,yCAAyC,CAAC;AAIjD,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,CAAC,SAAS,EAAE,cAAc,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACpF,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,mFAAmF;IACnF,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAoHF,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,CA4D1F"}

package/lib/authoring/reference-page.js

@@ -0,0 +1,160 @@
+// The reference-page renderer: the Markdown reference for ONE generated SDK, built from
+// the IR that SDK is built from, plus that generator's own `sample` hook for the call
+// snippets. It writes no call syntax of its own — a second spelling of the SDK would
+// drift from it the first time either side changed. Part of the authoring toolkit, so a
+// generator ejected as source (python, go, php) reaches it the same way we do.
+import { paginationRuleFor } from './pagination.js';
+import { Printer } from './printer.js';
+/** Table-cell-safe text: one line, with pipes and backslashes escaped. */
+function cell(text) {
+    return (text ?? '').replace(/\s+/g, ' ').trim().replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}
+/** A wire-level type name for a schema — the vocabulary of the description, not of a language. */
+function typeLabel(schema) {
+    switch (schema.kind) {
+        case 'ref':
+            return schema.name;
+        case 'omit':
+            return schema.base;
+        case 'scalar':
+            return schema.scalar;
+        case 'array':
+            return `array of ${typeLabel(schema.items)}`;
+        case 'record':
+            return `map of ${typeLabel(schema.value)}`;
+        case 'enum': {
+            const values = schema.values.map(String);
+            const shown = values.slice(0, 6).join(', ');
+            return values.length > 6 ? `enum: ${shown}, and ${values.length - 6} more` : `enum: ${shown}`;
+        }
+        case 'literal':
+            return String(schema.value);
+        case 'union':
+            return schema.members.map(typeLabel).join(' or ');
+        case 'intersection':
+            return schema.members.map(typeLabel).join(' and ');
+        case 'object':
+            return 'object';
+        case 'null':
+            return 'null';
+        case 'unknown':
+            return 'any';
+    }
+}
+/** Binary success content with no JSON alternative — the same test the clients apply. */
+function isBinary(op) {
+    if (op.successResponses.some((response) => response.contentType.toLowerCase().includes('json'))) {
+        return false;
+    }
+    return op.successResponses.some((response) => response.contentType.startsWith('image/') ||
+        response.contentType === 'application/octet-stream');
+}
+function writeParameterTable(printer, params) {
+    printer.line('| Parameter | In | Type | Required | Description |');
+    printer.line('| --------- | -- | ---- | -------- | ----------- |');
+    for (const param of params) {
+        printer.line(`| \`${param.name}\` | ${param.in} | ${cell(typeLabel(param.schema))} | ${param.required ? 'yes' : 'no'} | ${cell(param.description)} |`);
+    }
+    printer.blank();
+}
+function writeOperation(printer, op, options) {
+    printer.line(`### \`${op.specName ?? op.name}\``);
+    printer.blank();
+    if (op.summary !== undefined) {
+        printer.line(cell(op.summary));
+        printer.blank();
+    }
+    printer.line(`\`${op.method.toUpperCase()} ${op.path}\``);
+    printer.blank();
+    const sample = options.sample(op);
+    if (sample !== undefined) {
+        printer.line('```' + options.language.fence);
+        for (const line of sample.source.replace(/\n+$/, '').split('\n'))
+            printer.line(line);
+        printer.line('```');
+        printer.blank();
+    }
+    const params = [...op.pathParams, ...op.queryParams, ...op.headerParams];
+    if (params.length > 0)
+        writeParameterTable(printer, params);
+    if (op.requestBody !== undefined) {
+        printer.line(`Body: \`${op.requestBody.contentType}\`${op.requestBody.required ? ', required' : ', optional'}, of type ${typeLabel(op.requestBody.schema)}.`);
+    }
+    const success = op.successResponses[0];
+    printer.line(success === undefined
+        ? 'Returns no content.'
+        : `Returns \`${success.contentType}\`, of type ${typeLabel(success.schema)}.`);
+    // The same three declaration-level facts every SDK reads: `paginationRuleFor` is the
+    // helper the language generators resolve pagination with, and the success content type
+    // is what decides a streaming or a binary response.
+    const paginates = options.paginated !== undefined
+        ? options.paginated.has(op.name)
+        : paginationRuleFor(op, options.pagination) !== undefined;
+    if (paginates) {
+        printer.line('This operation is paginated, so the SDK gives it page and item iterators.');
+    }
+    if (op.successResponses.some((response) => response.contentType === 'text/event-stream')) {
+        printer.line('This operation streams server-sent events, so the SDK iterates the events.');
+    }
+    if (isBinary(op)) {
+        printer.line('This operation returns binary content.');
+    }
+    printer.blank();
+}
+/** The whole page: heading, requirements, security schemes, then every operation by tag. */
+export function renderReferencePage(model, options) {
+    const printer = new Printer();
+    if (options.frontmatter) {
+        printer.line('---');
+        printer.line(`title: ${options.title}`);
+        printer.line('---');
+        printer.blank();
+    }
+    printer.line(`# ${options.title}`);
+    printer.blank();
+    printer.line(`Generated reference for the ${options.language.label} SDK, produced from the API description by \`redocly generate-client\`.`);
+    printer.line('Re-run generation to update it — this file is not hand-edited.');
+    printer.blank();
+    printer.line(options.language.requires);
+    printer.blank();
+    printer.line('## Authentication');
+    printer.blank();
+    if (model.securitySchemes.length === 0) {
+        printer.line('The description declares no security schemes.');
+    }
+    else {
+        printer.line('The description declares these schemes, which you pass to the client:');
+        printer.blank();
+        printer.line('| Scheme | Kind | Sent as |');
+        printer.line('| ------ | ---- | ------- |');
+        for (const scheme of model.securitySchemes) {
+            const sentAs = scheme.kind === 'bearer'
+                ? '`Authorization: Bearer <token>`'
+                : scheme.kind === 'basic'
+                    ? '`Authorization: Basic <base64>`'
+                    : scheme.kind === 'apiKeyHeader'
+                        ? `the \`${scheme.headerName}\` header`
+                        : scheme.kind === 'apiKeyQuery'
+                            ? `the \`${scheme.paramName}\` query parameter`
+                            : `the \`${scheme.cookieName}\` cookie`;
+            printer.line(`| \`${scheme.key}\` | ${scheme.kind} | ${sentAs} |`);
+        }
+    }
+    printer.blank();
+    // One section per tag, in the order the description declares them, then the untagged
+    // operations — the same grouping the CLI and the split output modes use.
+    const operations = model.services.flatMap((service) => service.operations);
+    const groups = [...new Set(operations.map((op) => op.tags[0]))];
+    for (const group of groups) {
+        printer.line(group === undefined ? '## Operations' : `## ${group}`);
+        printer.blank();
+        for (const op of operations.filter((candidate) => candidate.tags[0] === group)) {
+            writeOperation(printer, op, options);
+        }
+    }
+    return (printer
+        .toString()
+        .replace(/\n{3,}/g, '\n\n')
+        .trimEnd() + '\n');
+}
+//# sourceMappingURL=reference-page.js.map

package/lib/authoring/reference-page.js.map

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

package/lib/authoring/schema.d.ts

@@ -0,0 +1,51 @@
+import type { ApiModel, NamedSchemaModel, PropertyModel, SchemaModel } from '../intermediate-representation/model.js';
+/** Follow a `ref` chain through the model's named schemas; undefined on a miss or cycle. */
+export declare function deref(schema: SchemaModel, model: ApiModel): SchemaModel | undefined;
+/**
+ * The flattened view of an object or `allOf` composition — what every language
+ * without intersection types renders. Later members win on property-name
+ * conflicts (allOf refinement); returns undefined when a member is not an
+ * object (nothing coherent to flatten).
+ */
+export declare function flattenAllOf(schema: SchemaModel, model: ApiModel): {
+    properties: PropertyModel[];
+    description?: string;
+} | undefined;
+/** The neutral discriminator dispatch table; each language renders its own idiom from it. */
+export declare function discriminatorCases(schema: SchemaModel, model: ApiModel): {
+    property: string;
+    cases: Array<{
+        value: string;
+        schemaName: string;
+        schema: SchemaModel;
+    }>;
+} | undefined;
+export declare function isNullable(schema: SchemaModel): boolean;
+/** The schema without its `null` union members (a single survivor is unwrapped). */
+export declare function unwrapNullable(schema: SchemaModel): SchemaModel;
+/** Enum values plus language-safe SCREAMING_SNAKE member-name suggestions. */
+export declare function enumValues(schema: SchemaModel): {
+    values: Array<string | number | boolean>;
+    scalar: string;
+    memberNames: string[];
+} | undefined;
+/** Description text as trimmed lines ready for any comment syntax; blank edges dropped. */
+export declare function docText(description?: string): string[];
+/**
+ * Resolve an RFC 6901 JSON pointer (`~1` → `/`, `~0` → `~`) over a schema, walking the
+ * VALUE shape it describes: object property steps by name, record values for any token,
+ * array items for numeric tokens, with `ref` steps resolved through the model's named
+ * schemas (cycle-guarded) and intersections (`allOf`) resolved across their members.
+ * Unions bail (genuinely ambiguous). Returns `undefined` on any miss.
+ */
+export declare function schemaAtPointer(schema: SchemaModel, pointer: string, model: ApiModel): SchemaModel | undefined;
+/**
+ * The wire-coerce hint for a response HEADER schema: `'integer'` / `'number'` /
+ * `'boolean'` for scalar-ish leaves, `'string'` for everything else (headers are
+ * strings on the wire; complex schemas have no sensible coercion). Resolves `ref`s
+ * through the model, peels nullable unions and constraint-only `allOf` members.
+ */
+export declare function headerCoerceType(schema: SchemaModel, model: {
+    schemas: readonly NamedSchemaModel[];
+}, seen?: Set<string>): 'string' | 'number' | 'integer' | 'boolean';
+//# sourceMappingURL=schema.d.ts.map

package/lib/authoring/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/authoring/schema.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,WAAW,EACZ,MAAM,yCAAyC,CAAC;AAGjD,4FAA4F;AAC5F,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAYnF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,QAAQ,GACd;IAAE,UAAU,EAAE,aAAa,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAcnE;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,QAAQ,GAEb;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,CAAC,CAAA;CAAE,GAC9F,SAAS,CAUZ;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEvD;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAI/D;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,GAClB;IAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,CAcjG;AAED,2FAA2F;AAC3F,wBAAgB,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAMtD;AAuBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,QAAQ,GACd,WAAW,GAAG,SAAS,CAYzB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE;IAAE,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAAE,EAC/C,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAC5B,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAoC7C"}

package/lib/authoring/schema.js

@@ -0,0 +1,190 @@
+// Language-neutral schema helpers: the cross-language variance points (allOf,
+// discriminators, nullability, enums) exposed as pure functions over the IR, so
+// a generator in ANY output language never re-implements schema semantics.
+import { casing, uniqueIdentifiers } from './naming.js';
+/** Follow a `ref` chain through the model's named schemas; undefined on a miss or cycle. */
+export function deref(schema, model) {
+    const seen = new Set();
+    let current = schema;
+    while (current.kind === 'ref') {
+        const { name } = current;
+        if (seen.has(name))
+            return undefined;
+        seen.add(name);
+        const named = model.schemas.find((s) => s.name === name);
+        if (named === undefined)
+            return undefined;
+        current = named.schema;
+    }
+    return current;
+}
+/**
+ * The flattened view of an object or `allOf` composition — what every language
+ * without intersection types renders. Later members win on property-name
+ * conflicts (allOf refinement); returns undefined when a member is not an
+ * object (nothing coherent to flatten).
+ */
+export function flattenAllOf(schema, model) {
+    const resolved = deref(schema, model);
+    if (resolved === undefined)
+        return undefined;
+    if (resolved.kind === 'object') {
+        return { properties: resolved.properties, description: resolved.description };
+    }
+    if (resolved.kind !== 'intersection')
+        return undefined;
+    const merged = new Map();
+    for (const member of resolved.members) {
+        const flat = flattenAllOf(member, model);
+        if (flat === undefined)
+            return undefined;
+        for (const property of flat.properties)
+            merged.set(property.name, property);
+    }
+    return { properties: [...merged.values()], description: resolved.description };
+}
+/** The neutral discriminator dispatch table; each language renders its own idiom from it. */
+export function discriminatorCases(schema, model) {
+    const resolved = deref(schema, model);
+    if (resolved?.kind !== 'union' || resolved.discriminator === undefined)
+        return undefined;
+    const cases = [];
+    for (const { value, schemaName } of resolved.discriminator.mapping) {
+        const target = deref({ kind: 'ref', name: schemaName }, model);
+        if (target === undefined)
+            return undefined;
+        cases.push({ value, schemaName, schema: target });
+    }
+    return { property: resolved.discriminator.propertyName, cases };
+}
+export function isNullable(schema) {
+    return schema.kind === 'union' && schema.members.some((member) => member.kind === 'null');
+}
+/** The schema without its `null` union members (a single survivor is unwrapped). */
+export function unwrapNullable(schema) {
+    if (schema.kind !== 'union' || !isNullable(schema))
+        return schema;
+    const rest = schema.members.filter((member) => member.kind !== 'null');
+    return rest.length === 1 ? rest[0] : { ...schema, members: rest };
+}
+/** Enum values plus language-safe SCREAMING_SNAKE member-name suggestions. */
+export function enumValues(schema) {
+    if (schema.kind !== 'enum')
+        return undefined;
+    // `casing` owns the value-to-word rules (`-1` → `MINUS_1`), and `uniqueIdentifiers` owns
+    // the rest of "language-safe": two values may fold to one name (`a-b` and `a b`), and an
+    // empty string folds to nothing at all — both must still yield distinct usable members.
+    const memberNames = uniqueIdentifiers(schema.values.map((value) => typeof value === 'string'
+        ? casing.screaming(value)
+        : `VALUE_${casing.screaming(String(value))}`), { style: 'screaming' });
+    return { values: schema.values, scalar: schema.scalar, memberNames };
+}
+/** Description text as trimmed lines ready for any comment syntax; blank edges dropped. */
+export function docText(description) {
+    if (!description)
+        return [];
+    const lines = description.split(/\r\n|\n|\r/).map((line) => line.trim());
+    while (lines.length > 0 && lines[0] === '')
+        lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/** One pointer step over a (dereferenced) schema; an intersection takes the LAST member that resolves, since later `allOf` members refine earlier ones. */
+function stepIntoSchema(schema, key, model) {
+    if (schema.kind === 'object')
+        return schema.properties.find((p) => p.name === key)?.schema;
+    if (schema.kind === 'record')
+        return schema.value;
+    if (schema.kind === 'array' && /^(0|[1-9]\d*)$/.test(key))
+        return schema.items;
+    if (schema.kind === 'intersection') {
+        let match;
+        for (const member of schema.members) {
+            const target = deref(member, model);
+            if (target === undefined)
+                continue;
+            match = stepIntoSchema(target, key, model) ?? match;
+        }
+        return match;
+    }
+    return undefined;
+}
+/**
+ * Resolve an RFC 6901 JSON pointer (`~1` → `/`, `~0` → `~`) over a schema, walking the
+ * VALUE shape it describes: object property steps by name, record values for any token,
+ * array items for numeric tokens, with `ref` steps resolved through the model's named
+ * schemas (cycle-guarded) and intersections (`allOf`) resolved across their members.
+ * Unions bail (genuinely ambiguous). Returns `undefined` on any miss.
+ */
+export function schemaAtPointer(schema, pointer, model) {
+    let current = deref(schema, model);
+    if (current === undefined || (pointer !== '' && !pointer.startsWith('/')))
+        return undefined;
+    if (pointer === '')
+        return current;
+    for (const token of pointer.slice(1).split('/')) {
+        const key = token.replaceAll('~1', '/').replaceAll('~0', '~');
+        const next = stepIntoSchema(current, key, model);
+        if (next === undefined)
+            return undefined;
+        current = deref(next, model);
+        if (current === undefined)
+            return undefined;
+    }
+    return current;
+}
+/**
+ * The wire-coerce hint for a response HEADER schema: `'integer'` / `'number'` /
+ * `'boolean'` for scalar-ish leaves, `'string'` for everything else (headers are
+ * strings on the wire; complex schemas have no sensible coercion). Resolves `ref`s
+ * through the model, peels nullable unions and constraint-only `allOf` members.
+ */
+export function headerCoerceType(schema, model, seen = new Set()) {
+    if (schema.kind === 'ref') {
+        if (seen.has(schema.name))
+            return 'string';
+        seen.add(schema.name);
+        const named = model.schemas.find((entry) => entry.name === schema.name);
+        if (named === undefined)
+            return 'string';
+        return headerCoerceType(named.schema, model, seen);
+    }
+    if (schema.kind === 'intersection') {
+        const members = schema.members.filter((member) => member.kind !== 'unknown');
+        if (members.length === 1)
+            return headerCoerceType(members[0], model, seen);
+        const types = [
+            ...new Set(members.map((member) => headerCoerceType(member, model, new Set(seen)))),
+        ];
+        if (types.length === 1)
+            return types[0];
+        // An integer member refined by a number bound (or vice versa) stays numeric.
+        if (types.every((type) => type === 'integer' || type === 'number'))
+            return 'number';
+        return 'string';
+    }
+    if (schema.kind === 'union') {
+        const members = schema.members.filter((member) => member.kind !== 'null');
+        if (members.length === 1)
+            return headerCoerceType(members[0], model, seen);
+        return 'string';
+    }
+    if (schema.kind === 'scalar' || schema.kind === 'enum') {
+        if (schema.scalar === 'integer')
+            return 'integer';
+        if (schema.scalar === 'number')
+            return 'number';
+        if (schema.scalar === 'boolean')
+            return 'boolean';
+    }
+    if (schema.kind === 'literal') {
+        if (typeof schema.value === 'number') {
+            return Number.isInteger(schema.value) ? 'integer' : 'number';
+        }
+        if (typeof schema.value === 'boolean')
+            return 'boolean';
+    }
+    return 'string';
+}
+//# sourceMappingURL=schema.js.map

package/lib/authoring/schema.js.map

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