multilapis 0.1.1

package/dist/sections.js

@@ -0,0 +1,624 @@
+import { countRefs, refToSchemaName } from "./ref-resolver.js";
+import { formatDefaultValue, isNullable, mapType } from "./type-mapper.js";
+import { formatDescriptionBlock, formatDescription, generateOperationId, isRecord, normalizeDescription, toSnakeCase, } from "./utils.js";
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
+export function convertMeta(doc, options = {}) {
+    const info = isRecord(doc.info) ? doc.info : {};
+    return {
+        api: typeof info.title === "string" ? info.title : "Untitled API",
+        base: extractBaseUrl(doc.servers),
+        version: typeof info.version === "string" ? info.version : undefined,
+        desc: formatDescription(info.description, options),
+        auth: extractAuth(doc),
+    };
+}
+function extractBaseUrl(servers) {
+    if (Array.isArray(servers) && isRecord(servers[0]) && typeof servers[0].url === "string") {
+        return servers[0].url.replace(/\/+$/g, "");
+    }
+    return "https://api.example.com";
+}
+function extractAuth(doc) {
+    const components = isRecord(doc.components) ? doc.components : {};
+    const schemes = isRecord(components.securitySchemes) ? components.securitySchemes : {};
+    for (const scheme of Object.values(schemes)) {
+        if (!isRecord(scheme))
+            continue;
+        if (scheme.type === "http") {
+            const httpScheme = typeof scheme.scheme === "string" ? scheme.scheme.toLowerCase() : "";
+            if (httpScheme === "bearer")
+                return "bearer header:Authorization";
+            if (httpScheme === "basic")
+                return "basic";
+        }
+        else if (scheme.type === "apiKey") {
+            const location = typeof scheme.in === "string" ? scheme.in : "header";
+            const name = typeof scheme.name === "string" ? scheme.name : "X-API-Key";
+            return `apikey ${location}:${name}`;
+        }
+        else if (scheme.type === "oauth2") {
+            const flows = isRecord(scheme.flows) ? scheme.flows : {};
+            for (const flow of Object.values(flows)) {
+                if (isRecord(flow) && typeof flow.tokenUrl === "string")
+                    return `oauth2 ${flow.tokenUrl}`;
+            }
+            return "oauth2";
+        }
+        else if (scheme.type === "openIdConnect") {
+            return "bearer header:Authorization";
+        }
+    }
+    return undefined;
+}
+export function convertTypes(doc) {
+    const schemas = getSchemas(doc);
+    const refCounts = countRefs(doc);
+    const multiRefNames = new Set();
+    for (const [ref, count] of refCounts) {
+        const name = refToSchemaName(ref);
+        if (name && count > 1)
+            multiRefNames.add(name);
+    }
+    const types = [];
+    const schemaNameMap = new Map();
+    for (const [name, schema] of Object.entries(schemas)) {
+        if (!isRecord(schema))
+            continue;
+        if ("enum" in schema) {
+            types.push({
+                kind: "enum",
+                name,
+                values: Array.isArray(schema.enum) ? schema.enum.map(String) : [],
+            });
+            schemaNameMap.set(name, name);
+        }
+        else if (isObjectSchema(schema)) {
+            types.push({ kind: "object", name, fields: convertObjectFields(schema, schemas) });
+            schemaNameMap.set(name, name);
+        }
+        else if (!multiRefNames.has(name)) {
+            continue;
+        }
+    }
+    return { types, schemaNameMap };
+}
+function getSchemas(doc) {
+    const components = isRecord(doc.components) ? doc.components : {};
+    return isRecord(components.schemas) ? components.schemas : {};
+}
+function isObjectSchema(schema) {
+    return schema.type === "object" || "properties" in schema;
+}
+function convertObjectFields(schema, allSchemas) {
+    const props = isRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    return Object.entries(props)
+        .filter(([, sub]) => isRecord(sub))
+        .map(([name, sub]) => convertField(name, sub, required.has(name), allSchemas));
+}
+function convertField(name, schema, isRequired, allSchemas) {
+    const deprecated = schema.deprecated === true || Boolean(schema["x-deprecated"]);
+    const xDeprecated = schema["x-deprecated"];
+    return {
+        name,
+        typeExpr: resolveFieldType(schema, allSchemas),
+        optional: !isRequired,
+        default: formatDefaultValue(schema.default),
+        since: schema["x-since"] === undefined ? undefined : String(schema["x-since"]),
+        deprecated,
+        deprecatedNote: typeof xDeprecated === "string" ? xDeprecated : undefined,
+    };
+}
+function resolveFieldType(schema, allSchemas) {
+    const refName = matchKnownSchema(schema, allSchemas);
+    if (refName)
+        return refName;
+    if (schema.type === "array" && isRecord(schema.items)) {
+        const inner = matchKnownSchema(schema.items, allSchemas);
+        if (inner)
+            return `[${inner}]`;
+    }
+    return mapType(schema);
+}
+function matchKnownSchema(schema, allSchemas) {
+    const stored = schema["x-schema-name"];
+    if (typeof stored === "string" && stored in allSchemas)
+        return stored;
+    if (schema.type === "object" && isRecord(schema.properties)) {
+        const props = new Set(Object.keys(schema.properties));
+        if (props.size === 0)
+            return undefined;
+        for (const [name, candidate] of Object.entries(allSchemas)) {
+            if (!isRecord(candidate) || !isRecord(candidate.properties))
+                continue;
+            const candidateProps = Object.keys(candidate.properties);
+            if (candidateProps.length === props.size && candidateProps.every((key) => props.has(key)))
+                return name;
+        }
+    }
+    return undefined;
+}
+export function convertOps(doc, schemaNameMap, options = {}) {
+    const paths = isRecord(doc.paths) ? doc.paths : {};
+    const operations = [];
+    for (const [path, pathItem] of Object.entries(paths)) {
+        if (!isRecord(pathItem))
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = pathItem[method];
+            if (isRecord(op))
+                operations.push(convertOperation(method, path, op, schemaNameMap, options));
+        }
+    }
+    return operations;
+}
+function convertOperation(method, path, op, schemaNameMap, options) {
+    const pathParams = new Set([...path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]));
+    const { outputs, outputRef } = extractOutputs(op, schemaNameMap);
+    const description = splitSummaryAndDescription(op.summary, op.description, options);
+    return {
+        name: typeof op.operationId === "string" ? op.operationId : generateOperationId(method, path),
+        method: method.toUpperCase(),
+        path,
+        tags: extractTags(op),
+        description: description.description,
+        comments: description.comments,
+        inputs: extractInputs(op, method, pathParams, schemaNameMap, options),
+        outputs,
+        outputRef,
+        modifiers: extractModifiers(op),
+        since: op["x-since"] === undefined ? undefined : String(op["x-since"]),
+    };
+}
+function extractModifiers(op) {
+    const mods = [];
+    if (op.deprecated) {
+        mods.push(typeof op["x-deprecated-message"] === "string" && op["x-deprecated-message"]
+            ? `+deprecated "${op["x-deprecated-message"]}"`
+            : "+deprecated");
+    }
+    if (op["x-paginated"])
+        mods.push("+paginated");
+    if (op["x-idempotent"])
+        mods.push("+idempotent");
+    if (op["x-stream"])
+        mods.push("+stream");
+    return mods;
+}
+function extractInputs(op, method, pathParams, schemaNameMap, options) {
+    const fields = [];
+    if (Array.isArray(op.parameters)) {
+        for (const param of op.parameters) {
+            if (!isRecord(param))
+                continue;
+            const field = convertParameter(param, method, pathParams, schemaNameMap, options);
+            if (field)
+                fields.push(field);
+        }
+    }
+    if (isRecord(op.requestBody))
+        fields.push(...extractRequestBody(op.requestBody, schemaNameMap));
+    return fields;
+}
+function convertParameter(param, method, pathParams, schemaNameMap, options) {
+    if (typeof param.name !== "string")
+        return undefined;
+    const description = formatDescription(param.description, options);
+    const isPathParam = pathParams.has(param.name) || param.in === "path";
+    if (isPathParam && !description)
+        return undefined;
+    const schema = isRecord(param.schema) ? param.schema : {};
+    return {
+        name: param.name,
+        typeExpr: resolveType(schema, schemaNameMap),
+        description,
+        optional: param.required !== true,
+        default: formatDefaultValue(schema.default),
+        location: isPathParam
+            ? "path"
+            : param.in === "header"
+                ? "header"
+                : param.in === "query" && ["post", "put", "patch"].includes(method.toLowerCase())
+                    ? "query"
+                    : undefined,
+    };
+}
+function extractRequestBody(body, schemaNameMap) {
+    const schema = getJsonSchema(body);
+    if (!schema)
+        return [];
+    const typeName = getSchemaName(schema, schemaNameMap);
+    if (typeName)
+        return [{ name: "", typeExpr: typeName, optional: false }];
+    const props = isRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    return Object.entries(props)
+        .filter(([, prop]) => isRecord(prop))
+        .map(([name, prop]) => ({
+        name,
+        typeExpr: resolveType(prop, schemaNameMap),
+        optional: !required.has(name),
+        default: formatDefaultValue(prop.default),
+    }));
+}
+function extractOutputs(op, schemaNameMap) {
+    const responses = isRecord(op.responses) ? op.responses : {};
+    for (const code of ["200", "201", "202", "203", "204"]) {
+        const resp = responses[code];
+        if (!isRecord(resp))
+            continue;
+        const schema = getJsonSchema(resp);
+        if (!schema)
+            continue;
+        const typeName = getSchemaName(schema, schemaNameMap);
+        if (typeName)
+            return { outputs: [], outputRef: typeName };
+        if (schema.type === "array" && isRecord(schema.items)) {
+            const itemName = getSchemaName(schema.items, schemaNameMap);
+            if (itemName)
+                return { outputs: [], outputRef: `[${itemName}]` };
+        }
+        const props = isRecord(schema.properties) ? schema.properties : undefined;
+        if (!props) {
+            const typeExpr = resolveType(schema, schemaNameMap);
+            if (typeExpr && typeExpr !== "any")
+                return { outputs: [], outputRef: typeExpr };
+            continue;
+        }
+        return {
+            outputs: Object.entries(props)
+                .filter(([, prop]) => isRecord(prop))
+                .map(([name, prop]) => ({ name, typeExpr: resolveType(prop, schemaNameMap) })),
+        };
+    }
+    return { outputs: [] };
+}
+function getJsonSchema(container) {
+    const content = isRecord(container.content) ? container.content : {};
+    const json = isRecord(content["application/json"]) ? content["application/json"] : {};
+    return isRecord(json.schema) ? json.schema : undefined;
+}
+function resolveType(schema, schemaNameMap) {
+    const name = getSchemaName(schema, schemaNameMap);
+    if (name)
+        return name;
+    if (schema.type === "array" && isRecord(schema.items)) {
+        const inner = getSchemaName(schema.items, schemaNameMap);
+        if (inner)
+            return `[${inner}]`;
+    }
+    return mapType(schema);
+}
+function getSchemaName(schema, schemaNameMap) {
+    const stored = schema["x-schema-name"];
+    return typeof stored === "string" ? schemaNameMap.get(stored) : undefined;
+}
+export function convertWebhooks(doc, schemaNameMap, options = {}) {
+    const webhooks = isRecord(doc.webhooks)
+        ? doc.webhooks
+        : isRecord(doc["x-webhooks"])
+            ? doc["x-webhooks"]
+            : {};
+    return Object.entries(webhooks).flatMap(([name, item]) => isRecord(item) ? (convertWebhook(name, item, schemaNameMap, options) ?? []) : []);
+}
+function convertWebhook(name, item, schemaNameMap, options) {
+    for (const method of ["post", "put", "patch", "get", "delete"]) {
+        const op = item[method];
+        if (!isRecord(op))
+            continue;
+        return {
+            name: typeof op.operationId === "string" ? op.operationId : toSnakeCase(name),
+            method: method.toUpperCase(),
+            path: `/webhooks/${name.replace(/_/g, "-")}`,
+            tags: extractTags(op),
+            ...splitSummaryAndDescription(op.summary, op.description, options),
+            triggers: Array.isArray(op["x-triggers"])
+                ? op["x-triggers"].filter((v) => typeof v === "string")
+                : [],
+            outputs: extractWebhookOutputs(op, schemaNameMap),
+        };
+    }
+    return undefined;
+}
+function extractTags(op) {
+    if (!Array.isArray(op.tags))
+        return undefined;
+    const tags = op.tags.filter((tag) => typeof tag === "string" && tag.trim() !== "");
+    return tags.length > 0 ? tags : undefined;
+}
+function splitSummaryAndDescription(summary, description, options) {
+    const summaryText = normalizeDescription(summary);
+    const descriptionText = normalizeDescription(description);
+    if (summaryText && descriptionText) {
+        if (summaryText === descriptionText) {
+            return { description: formatDescription(summaryText, options) };
+        }
+        const [main, comment] = summaryText.length <= descriptionText.length
+            ? [summaryText, descriptionText]
+            : [descriptionText, summaryText];
+        return {
+            description: formatDescription(main, options),
+            comments: formatDescriptionComments(comment, options),
+        };
+    }
+    if (summaryText)
+        return { description: formatDescription(summaryText, options) };
+    if (descriptionText)
+        return { comments: formatDescriptionComments(descriptionText, options) };
+    return {};
+}
+function formatDescriptionComments(text, options) {
+    const description = formatDescriptionBlock(text, options);
+    return description ? [description] : undefined;
+}
+function extractWebhookOutputs(op, schemaNameMap) {
+    const schema = isRecord(op.requestBody) ? getJsonSchema(op.requestBody) : undefined;
+    if (!schema || !isRecord(schema.properties))
+        return [];
+    const headers = {};
+    if (isRecord(op["x-webhook-headers"])) {
+        for (const [headerName, mapping] of Object.entries(op["x-webhook-headers"]))
+            if (typeof mapping === "string")
+                headers[mapping] = headerName;
+    }
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    return Object.entries(schema.properties)
+        .filter(([, fieldSchema]) => isRecord(fieldSchema))
+        .map(([fieldName, fieldSchema]) => ({
+        name: fieldName,
+        typeExpr: resolveWebhookType(fieldSchema, schemaNameMap),
+        optional: !required.has(fieldName),
+        headerName: headers[fieldName],
+    }));
+}
+function resolveWebhookType(schema, schemaNameMap) {
+    return getSchemaName(schema, schemaNameMap) ?? mapType(schema);
+}
+export function convertErrors(doc, schemaNameMap) {
+    const paths = isRecord(doc.paths) ? doc.paths : {};
+    const collected = new Map();
+    let totalOps = 0;
+    for (const pathItem of Object.values(paths)) {
+        if (!isRecord(pathItem))
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = pathItem[method];
+            if (!isRecord(op))
+                continue;
+            totalOps += 1;
+            const responses = isRecord(op.responses) ? op.responses : {};
+            for (const [codeStr, resp] of Object.entries(responses)) {
+                if (!isRecord(resp))
+                    continue;
+                const code = Number.parseInt(codeStr, 10);
+                if (!Number.isInteger(code) || code < 400)
+                    continue;
+                const schema = getJsonSchema(resp);
+                const key = errorKey(code, schema);
+                if (!collected.has(key))
+                    collected.set(key, {
+                        code,
+                        schema,
+                        description: typeof resp.description === "string" ? resp.description : undefined,
+                        ops: new Set(),
+                    });
+                if (typeof op.operationId === "string")
+                    collected.get(key)?.ops.add(op.operationId);
+            }
+        }
+    }
+    const errorBaseType = detectCommonErrorType([...collected.values()], schemaNameMap);
+    return {
+        errors: buildErrors([...collected.values()], totalOps, Boolean(errorBaseType)),
+        errorBaseType,
+    };
+}
+function errorKey(code, schema) {
+    if (!schema)
+        return `${code}:none`;
+    return `${code}:${JSON.stringify(Object.keys(isRecord(schema.properties) ? schema.properties : {}).sort())}`;
+}
+function detectCommonErrorType(entries, schemaNameMap) {
+    const schemas = entries
+        .map((e) => e.schema)
+        .filter((s) => Boolean(s && isRecord(s.properties)));
+    if (schemas.length < 2)
+        return undefined;
+    const first = Object.keys(schemas[0].properties)
+        .sort()
+        .join("\0");
+    if (schemas.every((schema) => Object.keys(schema.properties)
+        .sort()
+        .join("\0") === first)) {
+        return [...schemaNameMap.keys()].find((name) => name.toLowerCase().includes("error"));
+    }
+    return undefined;
+}
+function buildErrors(entries, totalOps, hasBaseType) {
+    return entries
+        .sort((a, b) => a.code - b.code)
+        .map((entry) => ({
+        code: entry.code,
+        name: generateErrorName(entry),
+        description: entry.description,
+        ops: entry.ops.size > 0 && entry.ops.size < totalOps ? [...entry.ops].sort() : [],
+        fields: hasBaseType || !entry.schema || !isRecord(entry.schema.properties)
+            ? []
+            : Object.entries(entry.schema.properties)
+                .filter(([, fieldSchema]) => isRecord(fieldSchema))
+                .map(([name, fieldSchema]) => {
+                const schema = fieldSchema;
+                return { name, typeExpr: `${mapType(schema)}${isNullable(schema) ? "?" : ""}` };
+            }),
+    }));
+}
+function generateErrorName(entry) {
+    const defaults = new Map([
+        [400, "validation_error"],
+        [401, "unauthorized"],
+        [403, "forbidden"],
+        [404, "not_found"],
+        [409, "conflict"],
+        [422, "unprocessable_entity"],
+        [429, "rate_limited"],
+        [500, "internal_error"],
+        [502, "bad_gateway"],
+        [503, "service_unavailable"],
+        [504, "gateway_timeout"],
+    ]);
+    return (defaults.get(entry.code) ??
+        (entry.description ? toSnakeCase(entry.description.slice(0, 40)) : `error_${entry.code}`));
+}
+export function convertLimits(doc) {
+    const info = isRecord(doc.info) ? doc.info : {};
+    const extensions = { ...pickExtensions(doc), ...pickExtensions(info) };
+    const rateLimits = extensions["x-rateLimit"] ?? extensions["x-rate-limit"];
+    const quotas = extensions["x-quota"] ?? extensions["x-quotas"];
+    const plansData = extensions["x-plans"] ?? extensions["x-pricing-plans"];
+    if (!rateLimits && !quotas && !plansData)
+        return undefined;
+    const limits = { plans: [], rates: [], quotas: [] };
+    if (isRecord(rateLimits))
+        parseRateLimits(rateLimits, limits);
+    else if (Array.isArray(rateLimits))
+        for (const rl of rateLimits)
+            if (isRecord(rl)) {
+                const parsed = parseSingleRate(rl);
+                if (parsed)
+                    limits.rates.push(parsed);
+            }
+    if (Array.isArray(quotas))
+        for (const q of quotas)
+            if (isRecord(q)) {
+                const parsed = parseSingleQuota(q);
+                if (parsed)
+                    limits.quotas.push(parsed);
+            }
+    if (isRecord(plansData))
+        for (const [name, planInfo] of Object.entries(plansData))
+            if (isRecord(planInfo))
+                limits.plans.push(parsePlan(name, planInfo));
+    const headers = extensions["x-rateLimit-headers"];
+    if (Array.isArray(headers))
+        limits.headers = headers.map(String).join(", ");
+    else if (typeof headers === "string")
+        limits.headers = headers;
+    return limits;
+}
+function pickExtensions(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([key]) => key.startsWith("x-")));
+}
+function parseRateLimits(data, limits) {
+    if ("count" in data && "window" in data) {
+        const parsed = parseSingleRate(data);
+        if (parsed)
+            limits.rates.push(parsed);
+    }
+    if (typeof data.headers === "string")
+        limits.headers = data.headers;
+    if (typeof data.on_exceed === "string")
+        limits.onExceed = data.on_exceed;
+    if (typeof data.max_body === "string")
+        limits.maxBody = data.max_body;
+    if (typeof data.max_upload === "string")
+        limits.maxUpload = data.max_upload;
+}
+function parseSingleRate(data) {
+    const count = data.count ?? data.limit;
+    const window = data.window ?? data.per ?? data.period;
+    if (count === undefined || window === undefined)
+        return undefined;
+    return {
+        count: Number(count),
+        window: String(window),
+        scope: typeof data.scope === "string" ? data.scope : undefined,
+    };
+}
+function parseSingleQuota(data) {
+    const count = data.count ?? data.limit;
+    const period = data.period ?? data.per;
+    const unlimited = Boolean(data.unlimited);
+    if (count === undefined && !unlimited)
+        return undefined;
+    return {
+        count: count === undefined ? undefined : Number(count),
+        period: period === undefined ? undefined : String(period),
+        unlimited,
+        scope: typeof data.scope === "string" ? data.scope : undefined,
+        description: typeof data.description === "string" ? data.description : undefined,
+    };
+}
+function parsePlan(name, data) {
+    const plan = { name, rates: [], quotas: [] };
+    const rates = data.rates ?? data.rateLimit;
+    if (Array.isArray(rates))
+        for (const rl of rates)
+            if (isRecord(rl)) {
+                const parsed = parseSingleRate(rl);
+                if (parsed)
+                    plan.rates.push(parsed);
+            }
+    const quotas = data.quotas ?? data.quota;
+    if (Array.isArray(quotas))
+        for (const q of quotas)
+            if (isRecord(q)) {
+                const parsed = parseSingleQuota(q);
+                if (parsed)
+                    plan.quotas.push(parsed);
+            }
+    if (data.max_batch !== undefined)
+        plan.maxBatch = Number(data.max_batch);
+    return plan;
+}
+export function convertFlows(doc) {
+    if (Array.isArray(doc["x-flows"]))
+        return fromFlowExtension(doc["x-flows"]);
+    if (isRecord(doc["x-flows"]))
+        return Object.entries(doc["x-flows"]).flatMap(([name, entry]) => isRecord(entry) ? [flowFromEntry(name, entry)] : []);
+    return fromLinks(doc);
+}
+function fromFlowExtension(flows) {
+    return flows
+        .filter(isRecord)
+        .map((entry) => flowFromEntry(typeof entry.name === "string" ? entry.name : "unnamed_flow", entry));
+}
+function flowFromEntry(name, entry) {
+    return {
+        name,
+        description: typeof entry.description === "string" ? entry.description : "",
+        chain: typeof entry.chain === "string" ? entry.chain : "",
+        conditions: [],
+        narrative: typeof entry.narrative === "string" ? entry.narrative : undefined,
+    };
+}
+function fromLinks(doc) {
+    const paths = isRecord(doc.paths) ? doc.paths : {};
+    const chains = new Map();
+    for (const pathItem of Object.values(paths)) {
+        if (!isRecord(pathItem))
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = pathItem[method];
+            if (!isRecord(op) || typeof op.operationId !== "string")
+                continue;
+            const responses = isRecord(op.responses) ? op.responses : {};
+            for (const resp of Object.values(responses)) {
+                if (!isRecord(resp) || !isRecord(resp.links))
+                    continue;
+                for (const link of Object.values(resp.links)) {
+                    if (isRecord(link) && typeof link.operationId === "string") {
+                        const targets = chains.get(op.operationId) ?? [];
+                        targets.push(link.operationId);
+                        chains.set(op.operationId, targets);
+                    }
+                }
+            }
+        }
+    }
+    return [...chains.entries()].map(([source, targets]) => ({
+        name: `${source}_flow`,
+        description: `Flow from ${source}`,
+        chain: [source, ...targets].join(" -> "),
+        conditions: [],
+    }));
+}

package/dist/type-mapper.d.ts

@@ -0,0 +1,6 @@
+import type { Schema } from "./models.js";
+export declare function mapType(schema: unknown): string;
+export declare function mapTypeWithNullable(schema: Schema): string;
+export declare function getType(schema: Schema): string;
+export declare function isNullable(schema: Schema): boolean;
+export declare function formatDefaultValue(value: unknown): string | undefined;