multilapis 0.1.1

package/src/multilapis.ts

@@ -0,0 +1,403 @@
+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 type {
+  LapisDocument,
+  LapisError,
+  LapisField,
+  LapisOperation,
+  LapisType,
+  LapisWebhook,
+  OpenApiDocument,
+} from "./models.js";
+import { convert } from "./converter.js";
+import { normalizeDescription, toSnakeCase, isRecord } from "./utils.js";
+
+const UNTAGGED = "_untagged";
+
+export interface MultiLapisWriteOptions {
+  outputDir?: string;
+}
+
+export interface MultiLapisBuildOptions {
+  truncateDescriptions?: boolean;
+}
+
+export interface GeneratedFile {
+  path: string;
+  content: string;
+}
+
+interface TagInfo {
+  name: string;
+  slug: string;
+  description?: string;
+  ops: FileEntry<LapisOperation>[];
+  webhooks: FileEntry<LapisWebhook>[];
+}
+
+interface FileEntry<T> {
+  item: T;
+  kind: "operation" | "webhook";
+  filename: string;
+  summary?: string;
+  deprecatedEndpoint?: boolean;
+}
+
+export async function writeMultiLapis(
+  doc: OpenApiDocument,
+  inputPath: string,
+  options: MultiLapisWriteOptions = {},
+): Promise<string> {
+  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: OpenApiDocument,
+  options: MultiLapisBuildOptions = {},
+): GeneratedFile[] {
+  const lapis = convert(doc, {
+    truncateDescriptions: options.truncateDescriptions ?? false,
+  });
+  const tagDescriptions = extractTagDescriptions(doc);
+  const tags = groupByTags(lapis, tagDescriptions);
+  const files: GeneratedFile[] = [
+    {
+      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: string): string {
+  return join(dirname(input), basename(input, extname(input)));
+}
+
+function groupByTags(lapis: LapisDocument, tagDescriptions: Map<string, string>): TagInfo[] {
+  const tags = new Map<string, TagInfo>();
+  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: Map<string, TagInfo>,
+  name: string,
+  descriptions: Map<string, string>,
+): TagInfo {
+  const slug = tagSlug(name);
+  const existing = tags.get(slug);
+  if (existing) return existing;
+
+  const tag: TagInfo = {
+    name,
+    slug,
+    description: descriptions.get(name),
+    ops: [],
+    webhooks: [],
+  };
+  tags.set(slug, tag);
+  return tag;
+}
+
+function itemTags(item: { tags?: string[] }): string[] {
+  return item.tags && item.tags.length > 0 ? item.tags : [UNTAGGED];
+}
+
+function itemSummary(item: { description?: string; comments?: string[] }): string | undefined {
+  const candidates = [item.description, ...(item.comments ?? [])]
+    .map((value) => normalizeDescription(value)?.replace(/\n/g, " "))
+    .filter((value): value is string => Boolean(value));
+  if (candidates.length === 0) return undefined;
+  return candidates.sort((a, b) => a.length - b.length)[0];
+}
+
+function allDeprecatedEndpointPaths(ops: LapisOperation[]): Set<string> {
+  const byPath = new Map<string, LapisOperation[]>();
+  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<string>();
+  for (const [path, pathOps] of byPath) {
+    if (pathOps.length > 0 && pathOps.every(isDeprecatedOperation)) deprecatedPaths.add(path);
+  }
+  return deprecatedPaths;
+}
+
+function isDeprecatedOperation(op: LapisOperation): boolean {
+  return op.modifiers.some(
+    (modifier) => modifier === "+deprecated" || modifier.startsWith("+deprecated "),
+  );
+}
+
+function withDuplicateComments<T extends LapisOperation | LapisWebhook>(
+  entry: FileEntry<T>,
+  currentTag: TagInfo,
+  tags: TagInfo[],
+): T {
+  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<T extends LapisOperation | LapisWebhook>(
+  entry: FileEntry<T>,
+  currentTag: TagInfo,
+  tags: TagInfo[],
+): string[] {
+  const siblings: string[] = [];
+  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: LapisDocument, op: LapisOperation): LapisDocument {
+  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: LapisDocument, webhook: LapisWebhook): LapisDocument {
+  return {
+    ...lapis,
+    types: collectTypes(lapis.types, fieldsTypeRoots(webhook.outputs)),
+    ops: [],
+    webhooks: [webhook],
+    errors: [],
+    errorBaseType: undefined,
+    flows: [],
+    limits: undefined,
+  };
+}
+
+function operationErrors(lapis: LapisDocument, op: LapisOperation): LapisError[] {
+  return lapis.errors
+    .filter((error) => error.ops.length === 0 || error.ops.includes(op.name))
+    .map((error) => ({ ...error, ops: [] }));
+}
+
+function operationTypeRoots(
+  op: LapisOperation,
+  errors: LapisError[],
+  errorBaseType?: string,
+): Set<string> {
+  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: LapisField[]): Set<string> {
+  const roots = new Set<string>();
+  addFieldRoots(roots, fields);
+  return roots;
+}
+
+function addFieldRoots(roots: Set<string>, fields: LapisField[]): void {
+  for (const field of fields) addTypeExprRoots(roots, field.typeExpr);
+}
+
+function addTypeExprRoots(roots: Set<string>, typeExpr: string): void {
+  for (const token of typeExpr.split(/[\s[\]{}:,?|]+/)) {
+    const name = token.trim();
+    if (name) roots.add(name);
+  }
+}
+
+function collectTypes(types: LapisType[], roots: Set<string>): LapisType[] {
+  const byName = new Map(types.map((type) => [type.name, type]));
+  const needed = new Set<string>();
+  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: LapisDocument, tags: TagInfo[]): string {
+  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: TagInfo): string {
+  return `${tag.slug}/index.md`;
+}
+
+function emitTagIndex(tag: TagInfo): string {
+  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: FileEntry<LapisOperation | LapisWebhook>): string {
+  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: OpenApiDocument): Map<string, string> {
+  const descriptions = new Map<string, string>();
+  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: string,
+  entries: FileEntry<LapisOperation | LapisWebhook>[],
+): string {
+  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: string): string {
+  return name === UNTAGGED ? UNTAGGED : slugify(name);
+}
+
+function slugify(value: string): string {
+  return toSnakeCase(value).replace(/_/g, "-") || UNTAGGED;
+}

package/src/openapi-loader.ts

@@ -0,0 +1,117 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { load as loadYaml } from "js-yaml";
+import { isRecord } from "./utils.js";
+import type { OpenApiDocument } from "./models.js";
+import {
+  applyOpenApiOverlaySources,
+  applyOpenApiOverlays,
+  type OpenApiOverlaySource,
+  OpenApiOverlayError,
+} from "./openapi-overlay.js";
+
+export class OpenApiLoadError extends Error {}
+
+export interface LoadOpenApiFromStringOptions {
+  skipValidation?: boolean;
+  overlays?: OpenApiOverlaySource[];
+  sourceName: string;
+}
+
+export async function loadOpenApi(
+  path: string,
+  options: { skipValidation?: boolean; overlayPaths?: string[] } = {},
+): Promise<OpenApiDocument> {
+  let text: string;
+  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: unknown;
+  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: OpenApiDocument;
+  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: string,
+  options: LoadOpenApiFromStringOptions,
+): OpenApiDocument {
+  let data: unknown;
+  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: OpenApiDocument;
+  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: OpenApiDocument): string {
+  return String(doc.openapi ?? "");
+}
+
+function parseOpenApiText(text: string, sourceName: string): unknown {
+  return parse(extname(sourceName).toLowerCase(), text);
+}
+
+function parse(suffix: string, text: string): unknown {
+  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: Record<string, unknown>): void {
+  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.`,
+    );
+  }
+}