@goast/core 0.6.0 → 0.7.0-beta.1

package/src/src/transform/helpers.ts

@@ -1,251 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,332 +0,0 @@
-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;
-}