multilapis 0.1.1

package/dist/models.d.ts

@@ -0,0 +1,132 @@
+export type OpenApiDocument = Record<string, unknown>;
+export type Schema = Record<string, unknown>;
+/**
+ * Options that control how an OpenAPI document is converted to LAPIS.
+ */
+export interface LapisConvertOptions {
+    /**
+     * Whether descriptions are shortened to fit compact LAPIS output.
+     *
+     * Defaults to `true`. Set to `false` to preserve full OpenAPI descriptions.
+     */
+    truncateDescriptions?: boolean;
+    /**
+     * Maximum description length when `truncateDescriptions` is enabled.
+     *
+     * Defaults to 80 characters.
+     */
+    maxDescriptionLength?: number;
+}
+export interface LapisMeta {
+    api: string;
+    base: string;
+    version?: string;
+    desc?: string;
+    auth?: string;
+    format?: string;
+}
+export interface LapisField {
+    name: string;
+    typeExpr: string;
+    description?: string;
+    optional?: boolean;
+    default?: string;
+    since?: string;
+    deprecated?: boolean;
+    deprecatedNote?: string;
+    location?: string;
+    headerName?: string;
+}
+export interface LapisEnumType {
+    kind: "enum";
+    name: string;
+    values: string[];
+}
+export interface LapisObjectType {
+    kind: "object";
+    name: string;
+    fields: LapisField[];
+}
+export type LapisType = LapisEnumType | LapisObjectType;
+export interface LapisOperation {
+    name: string;
+    method: string;
+    path: string;
+    tags?: string[];
+    preComments?: string[];
+    description?: string;
+    comments?: string[];
+    inputs: LapisField[];
+    outputs: LapisField[];
+    outputRef?: string;
+    modifiers: string[];
+    since?: string;
+}
+export interface LapisWebhook {
+    name: string;
+    method: string;
+    path: string;
+    tags?: string[];
+    preComments?: string[];
+    description?: string;
+    comments?: string[];
+    triggers: string[];
+    outputs: LapisField[];
+}
+export interface LapisError {
+    code: number;
+    name: string;
+    description?: string;
+    ops: string[];
+    fields: LapisField[];
+}
+export interface LapisRateLimit {
+    count: number;
+    window: string;
+    scope?: string;
+}
+export interface LapisQuota {
+    count?: number;
+    period?: string;
+    unlimited?: boolean;
+    scope?: string;
+    description?: string;
+}
+export interface LapisPlan {
+    name: string;
+    rates: LapisRateLimit[];
+    quotas: LapisQuota[];
+    maxBatch?: number;
+}
+export interface LapisLimits {
+    headers?: string;
+    onExceed?: string;
+    maxBody?: string;
+    maxUpload?: string;
+    maxResponse?: string;
+    maxBatch?: number;
+    plans: LapisPlan[];
+    rates: LapisRateLimit[];
+    quotas: LapisQuota[];
+}
+export interface LapisFlowCondition {
+    op: string;
+    description: string;
+}
+export interface LapisFlow {
+    name: string;
+    description: string;
+    chain: string;
+    conditions: LapisFlowCondition[];
+    narrative?: string;
+}
+export interface LapisDocument {
+    meta: LapisMeta;
+    types: LapisType[];
+    ops: LapisOperation[];
+    webhooks: LapisWebhook[];
+    errors: LapisError[];
+    errorBaseType?: string;
+    limits?: LapisLimits;
+    flows: LapisFlow[];
+}

package/dist/models.js

@@ -0,0 +1 @@
+export {};

package/dist/multilapis.d.ts

@@ -0,0 +1,14 @@
+import type { OpenApiDocument } from "./models.js";
+export interface MultiLapisWriteOptions {
+    outputDir?: string;
+}
+export interface MultiLapisBuildOptions {
+    truncateDescriptions?: boolean;
+}
+export interface GeneratedFile {
+    path: string;
+    content: string;
+}
+export declare function writeMultiLapis(doc: OpenApiDocument, inputPath: string, options?: MultiLapisWriteOptions): Promise<string>;
+export declare function buildMultiLapis(doc: OpenApiDocument, options?: MultiLapisBuildOptions): GeneratedFile[];
+export declare function defaultMultiLapisOutputPath(input: string): string;

package/dist/multilapis.js

@@ -0,0 +1,311 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import posixPath from "node:path/posix";
+import { emit } from "./emitter.js";
+import { convert } from "./converter.js";
+import { normalizeDescription, toSnakeCase, isRecord } from "./utils.js";
+const UNTAGGED = "_untagged";
+export async function writeMultiLapis(doc, inputPath, options = {}) {
+    const outputDir = options.outputDir ?? defaultMultiLapisOutputPath(inputPath);
+    const files = buildMultiLapis(doc);
+    await mkdir(outputDir, { recursive: true });
+    for (const file of files) {
+        const outputPath = join(outputDir, file.path);
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, file.content, "utf8");
+    }
+    return outputDir;
+}
+export function buildMultiLapis(doc, options = {}) {
+    const lapis = convert(doc, {
+        truncateDescriptions: options.truncateDescriptions ?? false,
+    });
+    const tagDescriptions = extractTagDescriptions(doc);
+    const tags = groupByTags(lapis, tagDescriptions);
+    const files = [
+        {
+            path: "index.md",
+            content: emitTopLevelIndex(lapis, tags),
+        },
+    ];
+    for (const tag of tags) {
+        files.push({
+            path: posixPath.join(tag.slug, "index.md"),
+            content: emitTagIndex(tag),
+        });
+        for (const entry of tag.ops) {
+            const op = withDuplicateComments(entry, tag, tags);
+            files.push({
+                path: posixPath.join(tag.slug, entry.filename),
+                content: emit(singleOperationDocument(lapis, op)),
+            });
+        }
+        for (const entry of tag.webhooks) {
+            const webhook = withDuplicateComments(entry, tag, tags);
+            files.push({
+                path: posixPath.join(tag.slug, entry.filename),
+                content: emit(singleWebhookDocument(lapis, webhook)),
+            });
+        }
+    }
+    return files;
+}
+export function defaultMultiLapisOutputPath(input) {
+    return join(dirname(input), basename(input, extname(input)));
+}
+function groupByTags(lapis, tagDescriptions) {
+    const tags = new Map();
+    const deprecatedEndpointPaths = allDeprecatedEndpointPaths(lapis.ops);
+    for (const op of lapis.ops) {
+        const opTags = itemTags(op);
+        const baseSlug = slugify(op.name);
+        const filename = `${baseSlug}.op.lapis`;
+        for (const tagName of opTags) {
+            const tag = getTag(tags, tagName, tagDescriptions);
+            tag.ops.push({
+                item: op,
+                kind: "operation",
+                filename: uniqueFilename(filename, [...tag.ops, ...tag.webhooks]),
+                summary: itemSummary(op),
+                deprecatedEndpoint: deprecatedEndpointPaths.has(op.path),
+            });
+        }
+    }
+    for (const webhook of lapis.webhooks) {
+        const webhookTags = itemTags(webhook);
+        const baseSlug = slugify(webhook.name);
+        const filename = `${baseSlug}.webhook.lapis`;
+        for (const tagName of webhookTags) {
+            const tag = getTag(tags, tagName, tagDescriptions);
+            tag.webhooks.push({
+                item: webhook,
+                kind: "webhook",
+                filename: uniqueFilename(filename, [...tag.ops, ...tag.webhooks]),
+                summary: itemSummary(webhook),
+            });
+        }
+    }
+    return [...tags.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function getTag(tags, name, descriptions) {
+    const slug = tagSlug(name);
+    const existing = tags.get(slug);
+    if (existing)
+        return existing;
+    const tag = {
+        name,
+        slug,
+        description: descriptions.get(name),
+        ops: [],
+        webhooks: [],
+    };
+    tags.set(slug, tag);
+    return tag;
+}
+function itemTags(item) {
+    return item.tags && item.tags.length > 0 ? item.tags : [UNTAGGED];
+}
+function itemSummary(item) {
+    const candidates = [item.description, ...(item.comments ?? [])]
+        .map((value) => normalizeDescription(value)?.replace(/\n/g, " "))
+        .filter((value) => Boolean(value));
+    if (candidates.length === 0)
+        return undefined;
+    return candidates.sort((a, b) => a.length - b.length)[0];
+}
+function allDeprecatedEndpointPaths(ops) {
+    const byPath = new Map();
+    for (const op of ops) {
+        const pathOps = byPath.get(op.path);
+        if (pathOps)
+            pathOps.push(op);
+        else
+            byPath.set(op.path, [op]);
+    }
+    const deprecatedPaths = new Set();
+    for (const [path, pathOps] of byPath) {
+        if (pathOps.length > 0 && pathOps.every(isDeprecatedOperation))
+            deprecatedPaths.add(path);
+    }
+    return deprecatedPaths;
+}
+function isDeprecatedOperation(op) {
+    return op.modifiers.some((modifier) => modifier === "+deprecated" || modifier.startsWith("+deprecated "));
+}
+function withDuplicateComments(entry, currentTag, tags) {
+    const siblingPaths = findSiblingPaths(entry, currentTag, tags);
+    if (siblingPaths.length === 0)
+        return entry.item;
+    const label = entry.kind === "webhook" ? "webhook" : "operation";
+    const preComments = siblingPaths.map((path) => `Same ${label} as ${path}`);
+    return { ...entry.item, preComments: [...preComments, ...(entry.item.preComments ?? [])] };
+}
+function findSiblingPaths(entry, currentTag, tags) {
+    const siblings = [];
+    for (const tag of tags) {
+        if (tag.slug === currentTag.slug)
+            continue;
+        const entries = entry.kind === "operation" ? tag.ops : tag.webhooks;
+        const sibling = entries.find((candidate) => candidate.item === entry.item);
+        if (sibling)
+            siblings.push(posixPath.relative(currentTag.slug, posixPath.join(tag.slug, sibling.filename)));
+    }
+    return siblings;
+}
+function singleOperationDocument(lapis, op) {
+    const errors = operationErrors(lapis, op);
+    return {
+        ...lapis,
+        types: collectTypes(lapis.types, operationTypeRoots(op, errors, lapis.errorBaseType)),
+        ops: [op],
+        webhooks: [],
+        errors,
+        errorBaseType: errors.length > 0 ? lapis.errorBaseType : undefined,
+        flows: [],
+        limits: undefined,
+    };
+}
+function singleWebhookDocument(lapis, webhook) {
+    return {
+        ...lapis,
+        types: collectTypes(lapis.types, fieldsTypeRoots(webhook.outputs)),
+        ops: [],
+        webhooks: [webhook],
+        errors: [],
+        errorBaseType: undefined,
+        flows: [],
+        limits: undefined,
+    };
+}
+function operationErrors(lapis, op) {
+    return lapis.errors
+        .filter((error) => error.ops.length === 0 || error.ops.includes(op.name))
+        .map((error) => ({ ...error, ops: [] }));
+}
+function operationTypeRoots(op, errors, errorBaseType) {
+    const roots = fieldsTypeRoots([...op.inputs, ...op.outputs]);
+    if (op.outputRef)
+        addTypeExprRoots(roots, op.outputRef);
+    for (const error of errors)
+        addFieldRoots(roots, error.fields);
+    if (errors.length > 0 && errorBaseType)
+        roots.add(errorBaseType);
+    return roots;
+}
+function fieldsTypeRoots(fields) {
+    const roots = new Set();
+    addFieldRoots(roots, fields);
+    return roots;
+}
+function addFieldRoots(roots, fields) {
+    for (const field of fields)
+        addTypeExprRoots(roots, field.typeExpr);
+}
+function addTypeExprRoots(roots, typeExpr) {
+    for (const token of typeExpr.split(/[\s[\]{}:,?|]+/)) {
+        const name = token.trim();
+        if (name)
+            roots.add(name);
+    }
+}
+function collectTypes(types, roots) {
+    const byName = new Map(types.map((type) => [type.name, type]));
+    const needed = new Set();
+    const queue = [...roots].filter((name) => byName.has(name));
+    for (let index = 0; index < queue.length; index += 1) {
+        const name = queue[index];
+        if (needed.has(name))
+            continue;
+        needed.add(name);
+        const type = byName.get(name);
+        if (!type || type.kind !== "object")
+            continue;
+        for (const field of type.fields) {
+            for (const token of field.typeExpr.split(/[\s[\]{}:,?|]+/)) {
+                if (byName.has(token) && !needed.has(token))
+                    queue.push(token);
+            }
+        }
+    }
+    return types.filter((type) => needed.has(type.name));
+}
+function emitTopLevelIndex(lapis, tags) {
+    const lines = [`# ${lapis.meta.api}`, ""];
+    if (lapis.meta.desc)
+        lines.push(lapis.meta.desc, "");
+    if (lapis.meta.version)
+        lines.push(`- Version: ${lapis.meta.version}`);
+    lines.push(`- Base URL: ${lapis.meta.base}`);
+    if (lapis.meta.auth)
+        lines.push(`- Auth: ${lapis.meta.auth}`);
+    lines.push("", "## Tags", "");
+    for (const tag of tags) {
+        const count = tag.ops.length + tag.webhooks.length;
+        const href = tagIndexHref(tag);
+        lines.push(tag.description
+            ? `- [${tag.name}](${href}) - ${tag.description}`
+            : `- [${tag.name}](${href}) - ${count} entries`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function tagIndexHref(tag) {
+    return `${tag.slug}/index.md`;
+}
+function emitTagIndex(tag) {
+    const lines = [`# ${tag.name}`, ""];
+    if (tag.description)
+        lines.push(tag.description, "");
+    if (tag.ops.length) {
+        lines.push("## Operations", "");
+        for (const entry of tag.ops)
+            lines.push(indexLine(entry));
+        lines.push("");
+    }
+    if (tag.webhooks.length) {
+        lines.push("## Webhooks", "");
+        for (const entry of tag.webhooks)
+            lines.push(indexLine(entry));
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function indexLine(entry) {
+    const deprecated = entry.deprecatedEndpoint ? ", deprecated" : "";
+    return entry.summary
+        ? `- [${entry.item.name}](${entry.filename}) - ${entry.summary}${deprecated}`
+        : `- [${entry.item.name}](${entry.filename})${deprecated}`;
+}
+function extractTagDescriptions(doc) {
+    const descriptions = new Map();
+    if (!Array.isArray(doc.tags))
+        return descriptions;
+    for (const tag of doc.tags) {
+        if (!isRecord(tag) || typeof tag.name !== "string")
+            continue;
+        const description = normalizeDescription(tag.description);
+        if (description)
+            descriptions.set(tag.name, description);
+    }
+    return descriptions;
+}
+function uniqueFilename(filename, entries) {
+    const used = new Set(entries.map((entry) => entry.filename));
+    if (!used.has(filename))
+        return filename;
+    const extension = filename.endsWith(".webhook.lapis") ? ".webhook.lapis" : ".op.lapis";
+    const base = filename.slice(0, -extension.length);
+    let index = 2;
+    let next = `${base}-${index}${extension}`;
+    while (used.has(next)) {
+        index += 1;
+        next = `${base}-${index}${extension}`;
+    }
+    return next;
+}
+function tagSlug(name) {
+    return name === UNTAGGED ? UNTAGGED : slugify(name);
+}
+function slugify(value) {
+    return toSnakeCase(value).replace(/_/g, "-") || UNTAGGED;
+}

package/dist/openapi-loader.d.ts

@@ -0,0 +1,15 @@
+import type { OpenApiDocument } from "./models.js";
+import { type OpenApiOverlaySource } from "./openapi-overlay.js";
+export declare class OpenApiLoadError extends Error {
+}
+export interface LoadOpenApiFromStringOptions {
+    skipValidation?: boolean;
+    overlays?: OpenApiOverlaySource[];
+    sourceName: string;
+}
+export declare function loadOpenApi(path: string, options?: {
+    skipValidation?: boolean;
+    overlayPaths?: string[];
+}): Promise<OpenApiDocument>;
+export declare function loadOpenApiFromString(text: string, options: LoadOpenApiFromStringOptions): OpenApiDocument;
+export declare function detectOpenApiVersion(doc: OpenApiDocument): string;

package/dist/openapi-loader.js

@@ -0,0 +1,91 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { load as loadYaml } from "js-yaml";
+import { isRecord } from "./utils.js";
+import { applyOpenApiOverlaySources, applyOpenApiOverlays, OpenApiOverlayError, } from "./openapi-overlay.js";
+export class OpenApiLoadError extends Error {
+}
+export async function loadOpenApi(path, options = {}) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new OpenApiLoadError(`File not found: ${path}`, { cause: error });
+    }
+    if (!options.overlayPaths || options.overlayPaths.length === 0) {
+        return loadOpenApiFromString(text, {
+            skipValidation: options.skipValidation,
+            sourceName: path,
+        });
+    }
+    let data;
+    try {
+        data = parseOpenApiText(text, path);
+    }
+    catch (error) {
+        if (error instanceof OpenApiLoadError)
+            throw error;
+        throw new OpenApiLoadError(`Failed to parse ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!isRecord(data))
+        throw new OpenApiLoadError(`Expected a mapping at the root of ${path}`);
+    let doc;
+    try {
+        doc = await applyOpenApiOverlays(data, options.overlayPaths);
+    }
+    catch (error) {
+        if (error instanceof OpenApiOverlayError) {
+            throw new OpenApiLoadError(`OpenAPI overlay failed: ${error.message}`, { cause: error });
+        }
+        throw error;
+    }
+    checkOpenApiVersion(doc);
+    void options.skipValidation;
+    return doc;
+}
+export function loadOpenApiFromString(text, options) {
+    let data;
+    try {
+        data = parseOpenApiText(text, options.sourceName);
+    }
+    catch (error) {
+        if (error instanceof OpenApiLoadError)
+            throw error;
+        throw new OpenApiLoadError(`Failed to parse ${options.sourceName}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!isRecord(data))
+        throw new OpenApiLoadError(`Expected a mapping at the root of ${options.sourceName}`);
+    let doc;
+    try {
+        doc = applyOpenApiOverlaySources(data, options.overlays);
+    }
+    catch (error) {
+        if (error instanceof OpenApiOverlayError) {
+            throw new OpenApiLoadError(`OpenAPI overlay failed: ${error.message}`, { cause: error });
+        }
+        throw error;
+    }
+    checkOpenApiVersion(doc);
+    void options.skipValidation;
+    return doc;
+}
+export function detectOpenApiVersion(doc) {
+    return String(doc.openapi ?? "");
+}
+function parseOpenApiText(text, sourceName) {
+    return parse(extname(sourceName).toLowerCase(), text);
+}
+function parse(suffix, text) {
+    if (suffix === ".json")
+        return JSON.parse(text);
+    if (suffix === ".yaml" || suffix === ".yml")
+        return loadYaml(text);
+    throw new OpenApiLoadError(`Unsupported file extension: ${suffix} (expected .json, .yaml, .yml)`);
+}
+function checkOpenApiVersion(data) {
+    const version = String(data.openapi ?? "");
+    if (!(version.startsWith("3.0") || version.startsWith("3.1"))) {
+        throw new OpenApiLoadError(`Unsupported OpenAPI version: ${JSON.stringify(version)}. Only 3.0.x and 3.1.x are supported.`);
+    }
+}

package/dist/openapi-overlay.d.ts

@@ -0,0 +1,14 @@
+import type { OpenApiDocument } from "./models.js";
+export declare class OpenApiOverlayError extends Error {
+}
+export interface OpenApiOverlaySource {
+    sourceName: string;
+    text: string;
+}
+export declare function applyOpenApiOverlays(doc: OpenApiDocument, overlayPaths?: string[]): Promise<OpenApiDocument>;
+export declare function applyOpenApiOverlaySources(doc: OpenApiDocument, overlays?: OpenApiOverlaySource[]): OpenApiDocument;
+export declare function applyOpenApiOverlayFromString(doc: OpenApiDocument, text: string, options: {
+    sourceName: string;
+}): OpenApiDocument;
+export declare function applyOpenApiOverlay(doc: OpenApiDocument, overlay: Record<string, unknown>): OpenApiDocument;
+export declare function parseOpenApiOverlay(source: OpenApiOverlaySource): Record<string, unknown>;