@goast/core 0.6.0-beta.1 → 0.6.0

package/src/src/transform/helpers.ts

@@ -0,0 +1,251 @@
+import { parse as parsePath } from 'node:path';
+import { isOpenApiObjectProperty } from '../internal-utils.js';
+import type { OpenApiHttpMethod, OpenApiObject } from '../parse/openapi-types.js';
+import type { Deref, DerefSource } from '../parse/types.js';
+import { isNullish } from '../utils/common.utils.js';
+import { getDeepProperty } from '../utils/object.utils.js';
+import { getLineInfo } from '../utils/yaml-info.js';
+import type { ApiSchema, ApiSchemaAccessibility, ApiSchemaKind, ApiSchemaProperty } from './api-types.js';
+import type { OpenApiTransformerContext } from './types.js';
+
+/** Normalizes a `type` keyword to an array, so a scalar type and a 3.1 type array can be treated alike. */
+export function asTypeArray(type: string | string[] | undefined | null): string[] {
+  if (isNullish(type)) return [];
+  return Array.isArray(type) ? type : [type];
+}
+
+// OpenAPI 3.1 allows `type: [~]`, which YAML parses to `null` rather than to the string `'null'`.
+function isNullType(type: string | null): boolean {
+  return type === 'null' || type === null;
+}
+
+/** The declared types with every `null` member removed. */
+export function withoutNullType(types: (string | null)[]): string[] {
+  return types.filter((t): t is string => !isNullType(t));
+}
+
+/** Whether the `type` keyword declares `null`, either as a scalar type or as a member of a 3.1 type array. */
+export function hasNullType(type: string | string[] | undefined | null): boolean {
+  return asTypeArray(type).some(isNullType);
+}
+
+export function determineSchemaKind<
+  T extends {
+    oneOf?: unknown;
+    allOf?: unknown;
+    anyOf?: unknown;
+    type?: string | string[];
+    properties?: Record<string, unknown>;
+    additionalProperties?: unknown;
+  },
+>(ctx: OpenApiTransformerContext, schema: T): ApiSchemaKind {
+  // An OpenAPI 3.1 type array that reduces to at most one non-null type is normalised away by
+  // `transformSchema`, which replaces `type` with the narrowed scalar (or `'null'`) and then asks this
+  // function again. Such an array therefore has to reach the `multi-type` branch below *before* the
+  // `allOf`/`anyOf` branch can claim it as `combined`, because a type array is 3.1's only way of expressing
+  // nullability and it would otherwise never be looked at. The second pass gives the `allOf`/`anyOf` branch
+  // its chance, this time with a scalar type it can judge correctly.
+  //
+  // A type array with two or more non-null members is *not* normalised away: nothing re-asks, so it must keep
+  // falling through to the `allOf`/`anyOf` branch exactly as it always has. Its nullability is picked up by
+  // `transformSchema` from the type as declared instead.
+  const narrowsToSingleType = Array.isArray(schema.type) && withoutNullType(schema.type).length <= 1;
+
+  if (schema.oneOf) {
+    return 'oneOf';
+  } else if (!narrowsToSingleType && schema.type !== 'object' && (schema.allOf || schema.anyOf)) {
+    const hasProperties = (schema.properties && Object.keys(schema.properties).length > 0) ||
+      schema.additionalProperties;
+    return hasProperties ? 'object' : 'combined';
+  } else if (Array.isArray(schema.type)) {
+    return 'multi-type';
+  } else if (
+    schema.type === 'object' ||
+    schema.type === 'string' ||
+    schema.type === 'boolean' ||
+    schema.type === 'null' ||
+    schema.type === 'number' ||
+    schema.type === 'integer' ||
+    schema.type === 'array'
+  ) {
+    return schema.type;
+  }
+
+  const treadAsObject = ctx.config.unknownTypeBehavior === 'always-object' ||
+    (ctx.config.unknownTypeBehavior === 'object-if-properties' &&
+      schema.properties &&
+      Object.keys(schema.properties).length > 0);
+
+  return treadAsObject ? 'object' : 'unknown';
+}
+
+export function determineSchemaName(
+  schema: {
+    title?: string;
+    $src: DerefSource<unknown>;
+  },
+  id: string,
+): { name: string; isGenerated: boolean } {
+  if (schema.title) return { name: schema.title, isGenerated: false };
+
+  if (schema.$src.path === '/') return { name: parsePath(schema.$src.file).name, isGenerated: true };
+
+  const schemaNameMatch = schema.$src.path.match(/(?<=\/components\/schemas\/|\/definitions\/)[^/]+$/i);
+  if (schemaNameMatch) {
+    return { name: schemaNameMatch[0], isGenerated: false };
+  }
+
+  const paramNameMatch = schema.$src.path.match(/\/components\/parameters\/([^/]+)\/schema$/i);
+  if (paramNameMatch) {
+    return { name: paramNameMatch[1], isGenerated: true };
+  }
+
+  const responseMatch = schema.$src.path.match(/\/paths\/(?<path>.+)\/(?<method>.+)\/responses\/(?<status>\d+)\//);
+  if (responseMatch && responseMatch.groups) {
+    const { path, method, status } = responseMatch.groups;
+    const operation = schema.$src.document.paths?.[path]?.[method as OpenApiHttpMethod] ?? {};
+    return {
+      name: `${determineEndpointName({ method, path: `/${path}`, operation })}_${status}_Response`,
+      isGenerated: true,
+    };
+  }
+
+  const responseCompMatch = schema.$src.path.match(/\/components\/responses\/([^/]+)\/content\/.+\/schema/);
+  if (responseCompMatch) {
+    return {
+      name: responseCompMatch[1].toLowerCase().endsWith('response')
+        ? responseCompMatch[1]
+        : responseCompMatch[1] + 'Response',
+      isGenerated: true,
+    };
+  }
+
+  const requestBodyMatch = schema.$src.path.match(/\/paths\/(?<path>.+)\/(?<method>.+)\/requestBody\//);
+  if (requestBodyMatch && requestBodyMatch.groups) {
+    const { path, method } = requestBodyMatch.groups;
+    const operation = schema.$src.document.paths?.[path]?.[method as OpenApiHttpMethod] ?? {};
+    return { name: `${determineEndpointName({ method, path: `/${path}`, operation })}_Request`, isGenerated: true };
+  }
+
+  const parentSchemaMatch = schema.$src.path.match(/(.*)\/properties\/([^/]*)(\/additionalProperties)?$/);
+  if (parentSchemaMatch) {
+    const parentSchema = getDeepProperty(schema.$src.document, parentSchemaMatch[1].split('/').filter(Boolean));
+    const parentSchemaName = determineSchemaName(
+      {
+        title: typeof parentSchema === 'object' && parentSchema !== null && 'title' in parentSchema
+          ? String(parentSchema.title)
+          : undefined,
+        $src: {
+          file: schema.$src.file,
+          pos: getLineInfo(schema.$src.document, parentSchemaMatch[1].split('/').filter(Boolean)),
+          path: parentSchemaMatch[1],
+          document: schema.$src.document,
+          originalComponent: parentSchema,
+        },
+      },
+      id,
+    );
+    // Continue the chain as long as the parent has a name of its own. Generated parent names are fine to build
+    // on — that is what makes a third-level inline object `Parent_middle_inner` instead of an opaque ordinal.
+    // Only the `id` fallback below is unusable, because it carries no information about the schema at all.
+    if (parentSchemaName.name !== id) {
+      return { name: `${parentSchemaName.name}_${parentSchemaMatch[2]}`, isGenerated: true };
+    }
+  }
+
+  return { name: id, isGenerated: true };
+}
+
+export function determineSchemaAccessibility(schema: {
+  readOnly?: boolean;
+  writeOnly?: boolean;
+}): ApiSchemaAccessibility {
+  if (schema.readOnly === true) {
+    return schema.writeOnly === true ? 'none' : 'readOnly';
+  } else {
+    return schema.writeOnly === true ? 'writeOnly' : 'all';
+  }
+}
+
+export function updateSchemaAccessibility(
+  accessibility: ApiSchemaAccessibility,
+  schema: {
+    readOnly?: boolean;
+    writeOnly?: boolean;
+  },
+): ApiSchemaAccessibility {
+  if (accessibility === 'none') return 'none';
+  if (accessibility === 'readOnly') return schema.writeOnly === true ? 'none' : 'readOnly';
+  if (accessibility === 'writeOnly') return schema.readOnly === true ? 'none' : 'writeOnly';
+  return determineSchemaAccessibility(schema);
+}
+
+type CustomFields<T extends Record<string, unknown>> = {
+  [K in keyof T as K extends `x-${string}` ? K : never]: T[K];
+};
+
+export function getCustomFields<T extends Record<string, unknown>>(schema: T): CustomFields<T> {
+  const result = {} as CustomFields<T>;
+  for (const key in schema) {
+    if (key.startsWith('x-')) {
+      const name = key.substring(2);
+      (result as Record<string, unknown>)[name] = schema[key];
+    }
+  }
+  return result;
+}
+
+export function determineEndpointName(endpointInfo: {
+  method: string;
+  path: string;
+  operation: { operationId?: string };
+}): string {
+  if (endpointInfo.operation.operationId) return endpointInfo.operation.operationId;
+  return endpointInfo.method + endpointInfo.path.replace(/\{([^}]+)\}/g, ':$1').replace(/\//g, '_');
+}
+
+export function transformAdditionalProperties<TAdditionalProperties>(
+  context: OpenApiTransformerContext,
+  schema: {
+    additionalProperties?: TAdditionalProperties;
+  },
+  transformSchema: (
+    context: OpenApiTransformerContext,
+    schema: Exclude<TAdditionalProperties, undefined | boolean>,
+  ) => ApiSchema,
+): boolean | ApiSchema | undefined {
+  if (isNullish(schema.additionalProperties)) return undefined;
+  if (typeof schema.additionalProperties === 'boolean') return schema.additionalProperties;
+  return transformSchema(context, schema.additionalProperties as Exclude<TAdditionalProperties, undefined | boolean>);
+}
+
+export function transformSchemaProperties<TProperties>(
+  context: OpenApiTransformerContext,
+  schema: { properties?: Record<string, TProperties>; required?: string[] },
+  transformSchema: (context: OpenApiTransformerContext, schema: TProperties) => ApiSchema,
+): Map<string, ApiSchemaProperty> {
+  const result = new Map<string, ApiSchemaProperty>();
+  if (!schema.properties) return result;
+  for (const name of Object.keys(schema.properties)) {
+    if (!isOpenApiObjectProperty(name)) continue;
+    result.set(name, {
+      name,
+      schema: transformSchema(context, schema.properties[name]),
+    });
+  }
+  return result;
+}
+
+export class IdGenerator {
+  private readonly _idMap = new Map<string, number>();
+
+  public generateId(name: string): string {
+    const id = this._idMap.get(name) ?? 1;
+    this._idMap.set(name, id + 1);
+    return `${name}-${id}`;
+  }
+}
+
+export function getOpenApiObjectIdentifier(obj: Deref<OpenApiObject<string>>) {
+  return obj.$src.file + '#' + obj.$src.path;
+}

package/src/src/transform/transform-document.ts

@@ -0,0 +1,35 @@
+import type { OpenApiDocument, OpenApiTag } from '../parse/openapi-types.js';
+import type { Deref } from '../parse/types.js';
+import type { ApiService } from './api-types.js';
+import { getOpenApiObjectIdentifier } from './helpers.js';
+import type { OpenApiTransformerContext } from './types.js';
+
+export function transformDocument(context: OpenApiTransformerContext, document: Deref<OpenApiDocument>) {
+  for (const tag of document.tags ?? []) {
+    transformTag(context, tag);
+  }
+}
+
+function transformTag(context: OpenApiTransformerContext, tag: Deref<OpenApiTag>, isReference = false) {
+  const openApiObjectId = getOpenApiObjectIdentifier(tag);
+  const existing = context.transformed.services.get(openApiObjectId);
+  if (existing) return existing;
+
+  const ref = tag.$ref ? transformTag(context, tag.$ref, true) : undefined;
+  const id = context.idGenerator.generateId('service');
+  const service: ApiService = {
+    $src: {
+      ...tag.$src,
+      component: tag,
+    },
+    $ref: ref,
+    id,
+    name: tag.name ?? id,
+    description: tag.description,
+    endpoints: [],
+  };
+
+  context.transformed.services.set(openApiObjectId, service);
+  if (!isReference) context.services.set(service.name, service);
+  return service;
+}

package/src/src/transform/transform-endpoint.ts

@@ -0,0 +1,332 @@
+import type { OpenApiCollectorEndpointInfo } from '../collect/types.js';
+import { isOpenApiObjectProperty } from '../internal-utils.js';
+import type {
+  OpenApiHeader,
+  OpenApiMediaType,
+  OpenApiParameter,
+  OpenApiPathItem,
+  OpenApiRequestBody,
+  OpenApiResponse,
+  OpenApiSchema,
+} from '../parse/openapi-types.js';
+import type { Deref } from '../parse/types.js';
+import type {
+  ApiContent,
+  ApiEndpoint,
+  ApiHeader,
+  ApiParameter,
+  ApiParameterTarget,
+  ApiPath,
+  ApiRequestBody,
+  ApiResponse,
+} from './api-types.js';
+import { determineEndpointName, getCustomFields, getOpenApiObjectIdentifier } from './helpers.js';
+import { transformSchema } from './transform-schema.js';
+import type { OpenApiTransformerContext } from './types.js';
+
+export function transformEndpoint(context: OpenApiTransformerContext, endpointInfo: OpenApiCollectorEndpointInfo) {
+  const apiPath = transformApiPath(context, endpointInfo.path, endpointInfo.pathItem);
+  const endpoint: ApiEndpoint = {
+    $src: {
+      ...endpointInfo.operation.$src,
+      component: endpointInfo.operation,
+    },
+    $ref: undefined,
+    id: context.idGenerator.generateId('endpoint'),
+    name: determineEndpointName(endpointInfo),
+    path: endpointInfo.path,
+    pathInfo: apiPath,
+    method: endpointInfo.method,
+    summary: endpointInfo.operation.summary,
+    description: endpointInfo.operation.description,
+    parameters: combineParameters(
+      apiPath.parameters,
+      endpointInfo.operation.parameters?.map((p) => transformParameter(context, p)) ?? [],
+    ),
+    deprecated: endpointInfo.operation.deprecated ?? false,
+    requestBody: endpointInfo.operation.requestBody
+      ? transformRequestBody(context, endpointInfo.operation.requestBody)
+      : undefined,
+    responses: transformResponses(context, endpointInfo.operation.responses),
+    tags: endpointInfo.operation.tags ?? [],
+    custom: getCustomFields(endpointInfo.operation),
+  };
+
+  const tags = endpoint.tags.length === 0 ? [''] : endpoint.tags;
+  for (const tag of tags) {
+    let service = context.services.get(tag);
+    if (!service) {
+      const id = context.idGenerator.generateId('service');
+      service = {
+        $ref: undefined,
+        id,
+        name: tag || id,
+        description: undefined,
+        endpoints: [],
+      };
+      context.services.set(tag, service);
+    }
+
+    service.endpoints.push(endpoint);
+  }
+
+  apiPath[endpointInfo.method] = endpoint;
+  context.endpoints.set(`${endpointInfo.method}:${endpointInfo.path}`, endpoint);
+  return endpoint;
+}
+
+function transformApiPath(
+  context: OpenApiTransformerContext,
+  path: string,
+  pathItem: Deref<OpenApiPathItem>,
+  isReference = false,
+): ApiPath {
+  const existingPath = context.paths.get(path);
+  if (existingPath) return existingPath;
+
+  const openApiObjectId = getOpenApiObjectIdentifier(pathItem);
+  const existing = context.transformed.paths.get(openApiObjectId);
+  if (existing) return existing;
+
+  const ref = pathItem.$ref ? transformApiPath(context, path, pathItem.$ref, true) : undefined;
+  const apiPath: ApiPath = {
+    $src: {
+      ...pathItem.$src,
+      component: pathItem,
+    },
+    $ref: ref,
+    id: context.idGenerator.generateId('path'),
+    summary: pathItem.summary,
+    description: pathItem.description,
+    path: path,
+    parameters: pathItem.parameters?.map((p) => transformParameter(context, p)) ?? [],
+
+    // HTTP methods are added later (see transformEndpoint)
+    get: undefined,
+    put: undefined,
+    post: undefined,
+    delete: undefined,
+    options: undefined,
+    head: undefined,
+    patch: undefined,
+    trace: undefined,
+  };
+
+  context.transformed.paths.set(openApiObjectId, apiPath);
+  if (!isReference) context.paths.set(path, apiPath);
+  return apiPath;
+}
+
+function transformParameter(context: OpenApiTransformerContext, parameter: Deref<OpenApiParameter>): ApiParameter {
+  const openApiObjectId = getOpenApiObjectIdentifier(parameter);
+  const existing = context.transformed.parameters.get(openApiObjectId);
+  if (existing) return existing;
+
+  const ref = parameter.$ref ? transformParameter(context, parameter.$ref) : undefined;
+  const id = context.idGenerator.generateId('parameter');
+  const p: ApiParameter = {
+    $src: {
+      ...parameter.$src,
+      component: parameter,
+    },
+    $ref: ref,
+    id: id,
+    name: parameter.name ?? id,
+    target: parameter.in as ApiParameterTarget,
+    description: parameter.description,
+    required: parameter.required ?? false,
+    deprecated: parameter.deprecated ?? false,
+    allowEmptyValue: parameter.allowEmptyValue,
+    style: parameter.style,
+    explode: parameter.explode,
+    allowReserved: parameter.allowReserved,
+    schema: parameter.schema ? transformSchema(context, parameter.schema) : undefined,
+  };
+
+  context.transformed.parameters.set(openApiObjectId, p);
+  return p;
+}
+
+function transformRequestBody(
+  context: OpenApiTransformerContext,
+  requestBody: Deref<OpenApiRequestBody>,
+): ApiRequestBody {
+  const openApiObjectId = getOpenApiObjectIdentifier(requestBody);
+  const existing = context.transformed.requestBodies.get(openApiObjectId);
+  if (existing) return existing;
+
+  const ref = requestBody.$ref ? transformRequestBody(context, requestBody.$ref) : undefined;
+  const rb: ApiRequestBody = {
+    $src: {
+      ...requestBody.$src,
+      component: requestBody,
+    },
+    $ref: ref,
+    id: context.idGenerator.generateId('requestBody'),
+    description: requestBody.description,
+    required: requestBody.required ?? false,
+    content: transformContent(context, requestBody.content),
+  };
+
+  context.transformed.requestBodies.set(openApiObjectId, rb);
+  return rb;
+}
+
+function transformResponses(
+  context: OpenApiTransformerContext,
+  responses?: Record<string, Deref<OpenApiResponse>>,
+): ApiResponse[] {
+  if (!responses) return [];
+  const result: ApiResponse[] = [];
+  for (const status of Object.keys(responses)) {
+    if (!isOpenApiObjectProperty(status)) continue;
+    result.push(transformResponse(context, responses[status], status));
+  }
+  return result;
+}
+
+function transformResponse(
+  context: OpenApiTransformerContext,
+  response: Deref<OpenApiResponse>,
+  status: string,
+): ApiResponse {
+  const openApiObjectId = getOpenApiObjectIdentifier(response);
+  const existing = context.transformed.responses.get(openApiObjectId);
+  if (existing) return existing;
+
+  const ref = response.$ref ? transformResponse(context, response.$ref, status) : undefined;
+  const r: ApiResponse = {
+    $src: {
+      ...response.$src,
+      component: response,
+    },
+    $ref: ref,
+    id: context.idGenerator.generateId('response'),
+    statusKey: status,
+    statusCode: Number(status) || undefined,
+    description: response.description,
+    headers: transformHeaders(context, response.headers),
+    contentOptions: transformContent(context, response.content),
+  };
+
+  context.transformed.responses.set(openApiObjectId, r);
+  return r;
+}
+
+function transformContent(
+  context: OpenApiTransformerContext,
+  content?: Record<string, Deref<OpenApiMediaType>>,
+): ApiContent[] {
+  if (!content) return [];
+  const result: ApiContent[] = [];
+  for (const media of Object.keys(content)) {
+    if (!isOpenApiObjectProperty(media)) continue;
+    result.push(transformMediaType(context, content[media], media));
+  }
+  return result;
+}
+
+function transformMediaType(
+  context: OpenApiTransformerContext,
+  mediaType: Deref<OpenApiMediaType>,
+  media: string,
+): ApiContent {
+  const openApiObjectId = getOpenApiObjectIdentifier(mediaType);
+  const existing = context.transformed.content.get(openApiObjectId);
+  if (existing) return existing;
+
+  const ref = mediaType.$ref ? transformMediaType(context, mediaType.$ref, media) : undefined;
+  const mt: ApiContent = {
+    $src: {
+      ...mediaType.$src,
+      component: mediaType,
+    },
+    $ref: ref,
+    id: context.idGenerator.generateId('content'),
+    type: media,
+    schema: mediaType.schema ? transformSchema(context, mediaType.schema) : undefined,
+  };
+
+  context.transformed.content.set(openApiObjectId, mt);
+  return mt;
+}
+
+function combineParameters(pathParams: ApiParameter[], operationParams: ApiParameter[]): ApiParameter[] {
+  const result = [...pathParams];
+  for (const opParam of operationParams) {
+    const existingParam = result.findIndex((p) => p.name === opParam.name);
+    if (existingParam >= 0) {
+      result[existingParam] = opParam;
+    } else {
+      result.push(opParam);
+    }
+  }
+  return result;
+}
+
+function isSchema(obj: Record<string, unknown>): obj is Deref<OpenApiSchema> {
+  return obj && typeof obj === 'object' && obj['type'] !== undefined;
+}
+
+function transformHeaders(
+  context: OpenApiTransformerContext,
+  headers?: Record<string, Deref<OpenApiHeader> | Deref<OpenApiSchema>>,
+): ApiHeader[] {
+  if (!headers) return [];
+  const result: ApiHeader[] = [];
+  for (const name of Object.keys(headers)) {
+    if (!isOpenApiObjectProperty(name)) continue;
+    result.push(transformHeader(context, headers[name], name));
+  }
+  return result;
+}
+
+function transformHeader(
+  context: OpenApiTransformerContext,
+  header: Deref<OpenApiHeader> | Deref<OpenApiSchema>,
+  name: string,
+): ApiHeader {
+  const openApiObjectId = getOpenApiObjectIdentifier(header);
+  const existing = context.transformed.headers.get(openApiObjectId);
+  if (existing) return existing;
+
+  let h: ApiHeader;
+  const ref = header.$ref ? transformHeader(context, header.$ref, name) : undefined;
+  const id = context.idGenerator.generateId('header');
+  if (isSchema(header)) {
+    h = {
+      // deno-lint-ignore no-explicit-any
+      $src: Object.assign({}, header.$src, { component: header }) as any,
+      $ref: ref as ApiHeader['$ref'],
+      id,
+      name,
+      description: header.description,
+      required: false,
+      deprecated: false,
+      allowEmptyValue: undefined,
+      style: undefined,
+      explode: undefined,
+      allowReserved: undefined,
+      schema: transformSchema(context, header),
+    };
+  } else {
+    h = {
+      // deno-lint-ignore no-explicit-any
+      $src: Object.assign({}, header.$src, { component: header }) as any,
+      $ref: ref as ApiHeader['$ref'],
+      id,
+      name,
+      description: header.description,
+      required: header.required ?? false,
+      deprecated: header.deprecated ?? false,
+      allowEmptyValue: header.allowEmptyValue,
+      style: header.style,
+      explode: header.explode,
+      allowReserved: header.allowReserved,
+      schema: header.schema ? transformSchema(context, header.schema) : undefined,
+    };
+  }
+
+  context.transformed.headers.set(openApiObjectId, h);
+  return h;
+}