multilapis 0.1.1

package/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6.0.9
+        with:
+          version: 11.10.0
+          cache: true
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run typecheck
+      - run: pnpm test
+
+  publish-npm:
+    name: Publish to npm
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6.0.9
+        with:
+          version: 11.10.0
+          cache: true
+      - uses: actions/setup-node@v6.4.0
+        with:
+          node-version: "26"
+          registry-url: "https://registry.npmjs.org"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: npm stage publish --provenance --access public

package/.prettierignore

@@ -0,0 +1,2 @@
+dist
+node_modules

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "printWidth": 100,
+  "trailingComma": "all"
+}

package/README.md

@@ -0,0 +1,139 @@
+# multilapis
+
+TypeScript tools for converting OpenAPI 3.0/3.1 documents to LAPIS.
+
+LAPIS is a compact API description format designed for LLM context. It keeps the API details a
+model needs, but removes much of the YAML and JSON Schema overhead that makes OpenAPI expensive to
+send to an LLM. See [What Is LAPIS?](./docs/lapis.md) for the format overview.
+
+## Install
+
+```sh
+pnpm install
+pnpm build
+```
+
+The package exposes:
+
+- a `multilapis` CLI
+- TypeScript APIs from `dist/index.js`
+
+## CLI
+
+Convert one OpenAPI file to one `.lapis` file.
+
+```sh
+multilapis openapi.yaml -o api.lapis
+```
+
+If `-o` is omitted, output is written beside the input using the same base name.
+
+```sh
+multilapis openapi.yaml
+# writes openapi.lapis
+```
+
+The older `-i, --input` form is also supported.
+
+```sh
+multilapis -i openapi.yaml -o api.lapis
+```
+
+Write a MultiLAPIS directory instead of one file.
+
+```sh
+multilapis openapi.yaml --multilapis -o api/
+```
+
+Skip OpenAPI schema validation.
+
+```sh
+multilapis openapi.yaml --no-validate
+```
+
+Preserve full descriptions instead of shortening them for compact output.
+
+```sh
+multilapis openapi.yaml --no-truncate-descriptions
+```
+
+## OpenAPI Overlays
+
+OpenAPI overlays patch an OpenAPI document before conversion. Use them to add LAPIS-friendly
+summaries, tags, rate-limit metadata, flows, or other converter extensions without editing the
+source OpenAPI file.
+
+Pass explicit overlay files:
+
+```sh
+multilapis openapi.yaml --overlay openapi.overlay.yaml -o api.lapis
+```
+
+Pass multiple overlays. They are applied in order.
+
+```sh
+multilapis openapi.yaml --overlay base.overlay.yaml docs.overlay.yaml -o api.lapis
+```
+
+Use the default sibling overlay path by passing `--overlay` with no file:
+
+```sh
+multilapis openapi.yaml --overlay -o api.lapis
+# reads openapi.overlay.yaml
+```
+
+Apply overlays without converting to LAPIS. The output flag is required for this command.
+
+```sh
+multilapis overlay openapi.yaml -o patched-openapi.yaml
+# reads openapi.overlay.yaml
+
+multilapis overlay openapi.yaml --overlay base.overlay.yaml docs.overlay.yaml -o patched-openapi.yaml
+```
+
+See [OpenAPI Overlays](./docs/openapi-overlays.md) for the overlay format and examples.
+
+## TypeScript API
+
+```ts
+import { loadOpenApi, loadOpenApiFromString, convertToString, buildMultiLapis } from "multilapis";
+
+const doc = await loadOpenApi("openapi.yaml", {
+  overlayPaths: ["openapi.overlay.yaml"],
+});
+
+const lapis = convertToString(doc);
+
+const embeddedDoc = loadOpenApiFromString(openApiText, {
+  sourceName: "openapi.yaml",
+  overlays: [{ sourceName: "openapi.overlay.yaml", text: overlayText }],
+});
+
+const files = buildMultiLapis(embeddedDoc);
+```
+
+Useful exports include:
+
+- `loadOpenApi(path, options)`
+- `loadOpenApiFromString(text, options)`
+- `convert(doc, options)`
+- `convertToString(doc, options)`
+- `buildMultiLapis(doc, options)`
+- `writeMultiLapis(doc, inputPath, options)`
+- `applyOpenApiOverlay(doc, overlay)`
+- `applyOpenApiOverlayFromString(doc, text, options)`
+- `applyOpenApiOverlays(doc, overlayPaths)`
+
+## Docs
+
+- [What Is LAPIS?](./docs/lapis.md)
+- [OpenAPI Overlays](./docs/openapi-overlays.md)
+- [MultiLAPIS](./docs/multilapis.md)
+
+## Development
+
+```sh
+pnpm test
+pnpm typecheck
+pnpm format:check
+```

package/dist/bin/multilapis.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { defaultMultiLapisOutputPath } from "../multilapis.js";
+export declare function main(argv?: string[]): Promise<number>;
+export declare function defaultOutputPath(input: string): string;
+export declare function defaultOverlayPath(input: string): string;
+export declare function resolveOverlayPaths(input: string, overlay: string[] | boolean | undefined): string[] | undefined;
+export { defaultMultiLapisOutputPath };

package/dist/bin/multilapis.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+import { dump as dumpYaml } from "js-yaml";
+import { convertToString } from "../converter.js";
+import { defaultMultiLapisOutputPath, writeMultiLapis } from "../multilapis.js";
+import { loadOpenApi, OpenApiLoadError } from "../openapi-loader.js";
+export async function main(argv = process.argv.slice(2)) {
+    const { Command, CommanderError } = await import("commander");
+    const program = new Command()
+        .name("multilapis")
+        .description("Convert OpenAPI 3.0/3.1 specifications to LAPIS or MultiLAPIS output.")
+        .version("0.1.0")
+        .enablePositionalOptions()
+        .argument("[input]", "Path to the OpenAPI file (.json, .yaml, .yml)")
+        .option("-i, --input <path>", "Path to the OpenAPI file (.json, .yaml, .yml)")
+        .option("-o, --output <path>", "Path to the output .lapis file or MultiLAPIS directory")
+        .option("--overlay [path...]", "Path(s) to OpenAPI overlay files applied before conversion")
+        .option("--multilapis", "Write a MultiLAPIS directory instead of one .lapis file")
+        .option("--no-validate", "Skip OpenAPI schema validation")
+        .option("--no-truncate-descriptions", "Preserve full descriptions in LAPIS output")
+        .exitOverride();
+    program
+        .command("overlay")
+        .description("Apply OpenAPI overlays and write the patched OpenAPI document.")
+        .argument("[input]", "Path to the OpenAPI file (.json, .yaml, .yml)")
+        .option("-i, --input <path>", "Path to the OpenAPI file (.json, .yaml, .yml)")
+        .option("--overlay [path...]", "Path(s) to OpenAPI overlay files to apply")
+        .requiredOption("-o, --output <path>", "Path to the patched OpenAPI output file")
+        .option("--no-validate", "Skip OpenAPI schema validation")
+        .action(async (inputArg, options) => {
+        if (inputArg && options.input) {
+            program.error("pass input only once: use either <input> or -i, --input <path>");
+            return;
+        }
+        const input = inputArg ?? options.input;
+        if (!input) {
+            program.error("missing required input path (pass <input> or -i, --input <path>)");
+            return;
+        }
+        exitCode = await applyOverlayFile({ ...options, input, output: options.output });
+    });
+    let exitCode = 0;
+    program.action(async (inputArg, options) => {
+        if (inputArg && options.input) {
+            program.error("pass input only once: use either <input> or -i, --input <path>");
+            return;
+        }
+        const input = inputArg ?? options.input;
+        if (!input) {
+            program.error("missing required input path (pass <input> or -i, --input <path>)");
+            return;
+        }
+        exitCode = await convertFile({ ...options, input });
+    });
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return exitCode;
+    }
+    catch (error) {
+        if (error instanceof CommanderError)
+            return error.exitCode;
+        throw error;
+    }
+}
+async function convertFile(options) {
+    try {
+        const doc = await loadOpenApi(options.input, {
+            skipValidation: options.noValidate,
+            overlayPaths: resolveOverlayPaths(options.input, options.overlay),
+        });
+        if (options.multilapis) {
+            await writeMultiLapis(doc, options.input, { outputDir: options.output });
+            return 0;
+        }
+        const output = options.output ?? defaultOutputPath(options.input);
+        const text = convertToString(doc, {
+            truncateDescriptions: options.truncateDescriptions,
+        });
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, text, "utf8");
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof OpenApiLoadError)
+            console.error(`Error: ${error.message}`);
+        else
+            console.error(`Conversion error: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+async function applyOverlayFile(options) {
+    try {
+        const doc = await loadOpenApi(options.input, {
+            skipValidation: options.noValidate,
+            overlayPaths: resolveOverlayPaths(options.input, options.overlay ?? true),
+        });
+        await mkdir(dirname(options.output), { recursive: true });
+        await writeFile(options.output, serializeOpenApi(doc, options.output), "utf8");
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof OpenApiLoadError)
+            console.error(`Error: ${error.message}`);
+        else
+            console.error(`Overlay error: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+function serializeOpenApi(doc, output) {
+    const suffix = extname(output).toLowerCase();
+    if (suffix === ".json")
+        return `${JSON.stringify(doc, null, 2)}\n`;
+    return dumpYaml(doc, { lineWidth: -1 });
+}
+export function defaultOutputPath(input) {
+    return join(dirname(input), `${basename(input, extname(input))}.lapis`);
+}
+export function defaultOverlayPath(input) {
+    return join(dirname(input), `${basename(input, extname(input))}.overlay.yaml`);
+}
+export function resolveOverlayPaths(input, overlay) {
+    if (overlay === undefined || overlay === false)
+        return undefined;
+    if (overlay === true || overlay.length === 0)
+        return [defaultOverlayPath(input)];
+    return overlay;
+}
+export { defaultMultiLapisOutputPath };
+if (import.meta.url === `file://${process.argv[1]}`) {
+    process.exitCode = await main();
+}

package/dist/converter.d.ts

@@ -0,0 +1,3 @@
+import type { LapisConvertOptions, LapisDocument, OpenApiDocument } from "./models.js";
+export declare function convert(doc: OpenApiDocument, options?: LapisConvertOptions): LapisDocument;
+export declare function convertToString(doc: OpenApiDocument, options?: LapisConvertOptions): string;

package/dist/converter.js

@@ -0,0 +1,55 @@
+import { resolveRefs } from "./ref-resolver.js";
+import { flattenSchemas } from "./schema-flattener.js";
+import { convertErrors, convertFlows, convertLimits, convertMeta, convertOps, convertTypes, convertWebhooks, } from "./sections.js";
+import { deepClone, isRecord } from "./utils.js";
+import { emit } from "./emitter.js";
+const SCHEMA_REF_RE = /^#\/components\/schemas\/(.+)$/;
+export function convert(doc, options = {}) {
+    const tagged = annotateRefs(deepClone(doc));
+    tagSchemaNames(tagged);
+    const resolved = resolveRefs(tagged);
+    const flattened = flattenSchemas(resolved);
+    const meta = convertMeta(flattened, options);
+    const { types, schemaNameMap } = convertTypes(flattened);
+    const { errors, errorBaseType } = convertErrors(flattened, schemaNameMap);
+    return {
+        meta,
+        types,
+        ops: convertOps(flattened, schemaNameMap, options),
+        webhooks: convertWebhooks(flattened, schemaNameMap, options),
+        errors,
+        errorBaseType,
+        limits: convertLimits(flattened),
+        flows: convertFlows(flattened),
+    };
+}
+export function convertToString(doc, options = {}) {
+    return emit(convert(doc, options));
+}
+function tagSchemaNames(doc) {
+    const components = isRecord(doc.components) ? doc.components : {};
+    const schemas = isRecord(components.schemas) ? components.schemas : {};
+    for (const [name, schema] of Object.entries(schemas))
+        if (isRecord(schema))
+            schema["x-schema-name"] = name;
+}
+function annotateRefs(doc) {
+    walkAnnotate(doc);
+    return doc;
+}
+function walkAnnotate(node) {
+    if (isRecord(node)) {
+        const ref = node.$ref;
+        if (typeof ref === "string") {
+            const match = SCHEMA_REF_RE.exec(ref);
+            if (match)
+                node["x-schema-name"] = match[1];
+        }
+        for (const value of Object.values(node))
+            walkAnnotate(value);
+    }
+    else if (Array.isArray(node)) {
+        for (const item of node)
+            walkAnnotate(item);
+    }
+}

package/dist/emitter.d.ts

@@ -0,0 +1,2 @@
+import type { LapisDocument } from "./models.js";
+export declare function emit(doc: LapisDocument): string;

package/dist/emitter.js

@@ -0,0 +1,203 @@
+export function emit(doc) {
+    const parts = ["# LAPIS v0.1.0", "", emitMeta(doc)];
+    if (doc.types.length)
+        parts.push("", emitTypes(doc.types));
+    if (doc.ops.length)
+        parts.push("", emitOps(doc));
+    if (doc.webhooks.length)
+        parts.push("", emitWebhooks(doc));
+    if (doc.errors.length)
+        parts.push("", emitErrors(doc));
+    if (doc.limits)
+        parts.push("", emitLimits(doc.limits));
+    if (doc.flows.length)
+        parts.push("", emitFlows(doc));
+    parts.push("");
+    return parts.join("\n");
+}
+function emitMeta(doc) {
+    const lines = ["[meta]", `api: ${doc.meta.api}`, `base: ${doc.meta.base}`];
+    if (doc.meta.version)
+        lines.push(`version: ${doc.meta.version}`);
+    if (doc.meta.desc)
+        lines.push(`desc: ${doc.meta.desc}`);
+    if (doc.meta.auth)
+        lines.push(`auth: ${doc.meta.auth}`);
+    if (doc.meta.format && doc.meta.format !== "json")
+        lines.push(`format: ${doc.meta.format}`);
+    return lines.join("\n");
+}
+function emitTypes(types) {
+    const lines = ["[types]"];
+    for (let i = 0; i < types.length; i += 1) {
+        const type = types[i];
+        if (i > 0)
+            lines.push("");
+        if (type.kind === "enum") {
+            lines.push(`${type.name}: ${type.values.join(" | ")}`);
+        }
+        else {
+            lines.push(`${type.name}:`);
+            for (const field of type.fields)
+                lines.push(`  ${emitFieldDef(field)}`);
+        }
+    }
+    return lines.join("\n");
+}
+function emitFieldDef(field) {
+    let line = `${field.name}${field.optional ? "?" : ""}: ${field.typeExpr}`;
+    if (field.default !== undefined)
+        line += ` = ${field.default}`;
+    if (field.since)
+        line += ` @since:${field.since}`;
+    if (field.deprecated) {
+        line += " @deprecated";
+        if (field.deprecatedNote)
+            line += ` "${field.deprecatedNote}"`;
+    }
+    return line;
+}
+function emitOps(doc) {
+    const lines = ["[ops]"];
+    for (let i = 0; i < doc.ops.length; i += 1) {
+        const op = doc.ops[i];
+        if (i > 0)
+            lines.push("");
+        let header = `${op.name} ${op.method} ${op.path}`;
+        if (op.modifiers.length)
+            header += ` ${op.modifiers.join(" ")}`;
+        if (op.since)
+            header += ` @since:${op.since}`;
+        lines.push(header);
+        for (const comment of op.preComments ?? [])
+            emitMultiline(lines, comment, "  # ");
+        if (op.description)
+            emitMultiline(lines, op.description, "  ");
+        for (const comment of op.comments ?? [])
+            emitMultiline(lines, comment, "  # ");
+        for (const input of op.inputs)
+            lines.push(`  > ${emitInputField(input)}`);
+        if (op.outputRef)
+            lines.push(`  < ${op.outputRef}`);
+        for (const output of op.outputs)
+            lines.push(`  < ${output.name}: ${output.typeExpr}`);
+    }
+    return lines.join("\n");
+}
+function emitInputField(field) {
+    let line = `${field.name}${field.optional ? "?" : ""}: ${field.typeExpr}`;
+    if (field.default !== undefined)
+        line += ` = ${field.default}`;
+    if (field.location)
+        line += ` @${field.location}`;
+    if (field.description)
+        line += ` # ${field.description}`;
+    return line;
+}
+function emitWebhooks(doc) {
+    const lines = ["[webhooks]"];
+    for (let i = 0; i < doc.webhooks.length; i += 1) {
+        const wh = doc.webhooks[i];
+        if (i > 0)
+            lines.push("");
+        lines.push(`${wh.name} -> ${wh.method} ${wh.path}`);
+        for (const comment of wh.preComments ?? [])
+            emitMultiline(lines, comment, "  # ");
+        if (wh.description)
+            emitMultiline(lines, wh.description, "  ");
+        for (const comment of wh.comments ?? [])
+            emitMultiline(lines, comment, "  # ");
+        for (const trigger of wh.triggers)
+            lines.push(`  ! ${trigger}`);
+        for (const out of wh.outputs) {
+            let line = `  < ${out.name}${out.optional ? "?" : ""}: ${out.typeExpr}`;
+            if (out.headerName)
+                line += ` @header:${out.headerName}`;
+            lines.push(line);
+        }
+    }
+    return lines.join("\n");
+}
+function emitMultiline(lines, text, prefix) {
+    for (const line of text.split("\n"))
+        lines.push(`${prefix}${line}`);
+}
+function emitErrors(doc) {
+    const lines = ["[errors]"];
+    if (doc.errorBaseType)
+        lines.push(`# Base structure for all errors: ${doc.errorBaseType}`, "");
+    for (let i = 0; i < doc.errors.length; i += 1) {
+        const err = doc.errors[i];
+        if (i > 0)
+            lines.push("");
+        let header = `${err.code} ${err.name}`;
+        if (err.ops.length)
+            header += ` @ops:${err.ops.join(",")}`;
+        lines.push(header);
+        if (err.description)
+            lines.push(`  ${err.description}`);
+        for (const field of err.fields)
+            lines.push(`  ~ ${field.name}${field.optional ? "?" : ""}: ${field.typeExpr}`);
+    }
+    return lines.join("\n");
+}
+function emitLimits(limits) {
+    const lines = ["[limits]"];
+    if (limits.headers)
+        lines.push(`headers: ${limits.headers}`);
+    if (limits.onExceed)
+        lines.push(`on_exceed: ${limits.onExceed}`);
+    if (limits.maxBody)
+        lines.push(`max_body: ${limits.maxBody}`);
+    if (limits.maxUpload)
+        lines.push(`max_upload: ${limits.maxUpload}`);
+    if (limits.maxResponse)
+        lines.push(`max_response: ${limits.maxResponse}`);
+    if (limits.maxBatch !== undefined)
+        lines.push(`max_batch: ${limits.maxBatch}`);
+    for (const rate of limits.rates)
+        lines.push(emitRate(rate));
+    for (const quota of limits.quotas)
+        lines.push(emitQuota(quota));
+    for (const plan of limits.plans) {
+        lines.push("", `plan: ${plan.name}`);
+        emitPlanBody(plan, lines);
+    }
+    return lines.join("\n");
+}
+function emitRate(rate, indent = "") {
+    return `${indent}rate: ${rate.count}/${rate.window}${rate.scope ? ` ${rate.scope}` : ""}`;
+}
+function emitQuota(quota, indent = "") {
+    let line = quota.unlimited
+        ? `${indent}quota: unlimited`
+        : `${indent}quota: ${quota.count}/${quota.period}`;
+    if (quota.scope)
+        line += ` ${quota.scope}`;
+    if (quota.description)
+        line += ` "${quota.description}"`;
+    return line;
+}
+function emitPlanBody(plan, lines) {
+    for (const rate of plan.rates)
+        lines.push(emitRate(rate, "  "));
+    for (const quota of plan.quotas)
+        lines.push(emitQuota(quota, "  "));
+    if (plan.maxBatch !== undefined)
+        lines.push(`  max_batch: ${plan.maxBatch}`);
+}
+function emitFlows(doc) {
+    const lines = ["[flows]"];
+    for (let i = 0; i < doc.flows.length; i += 1) {
+        const flow = doc.flows[i];
+        if (i > 0)
+            lines.push("");
+        lines.push(`${flow.name} "${flow.description}"`, `  ${flow.chain}`);
+        for (const cond of flow.conditions)
+            lines.push(`  ? ${cond.op}: ${cond.description}`);
+        if (flow.narrative)
+            for (const line of flow.narrative.split("\n"))
+                lines.push(`  ${line.trim()}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./models.js";
+export * from "./converter.js";
+export * from "./emitter.js";
+export * from "./openapi-loader.js";
+export * from "./openapi-overlay.js";
+export * from "./multilapis.js";
+export * from "./ref-resolver.js";
+export * from "./schema-flattener.js";
+export * from "./type-mapper.js";
+export * from "./sections.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./models.js";
+export * from "./converter.js";
+export * from "./emitter.js";
+export * from "./openapi-loader.js";
+export * from "./openapi-overlay.js";
+export * from "./multilapis.js";
+export * from "./ref-resolver.js";
+export * from "./schema-flattener.js";
+export * from "./type-mapper.js";
+export * from "./sections.js";