@goast/core 0.4.0-beta3 → 0.4.0

package/src/src/parse/parser.ts

@@ -0,0 +1,220 @@
+import * as dntShim from "../../_dnt.shims.js";
+import path from 'node:path';
+import { cwd } from 'node:process';
+
+
+import fs from 'fs-extra';
+import * as YAML from 'yaml';
+
+import { collectOpenApi } from '../collect/collector.js';
+import type { ApiData } from '../transform/api-types.js';
+import { transformOpenApi } from '../transform/transformer.js';
+import { isNullish } from '../utils/common.utils.js';
+import { createDerefProxy } from './deref-proxy.js';
+import type { OpenApiDocument, OpenApiObject, OpenApiReference, OpenApiSchema } from './openapi-types.js';
+import { defaultOpenApiParserOptions, type Deref, type OpenApiParserOptions } from './types.js';
+
+type LoadedDocument = {
+  file: string;
+  document: OpenApiDocument;
+  dereferencedDocument: Deref<OpenApiDocument>;
+  dereferencedComponents: Map<string, Deref<OpenApiObject<string>>>;
+};
+
+export class OpenApiParser {
+  private readonly _loadedDocuments = new Map<string, LoadedDocument>();
+  private readonly _config: OpenApiParserOptions;
+
+  constructor(config?: Partial<OpenApiParserOptions>) {
+    this._config = { ...defaultOpenApiParserOptions, ...config };
+  }
+
+  public async parseApisAndTransform(...fileNames: (string | string[])[]): Promise<ApiData> {
+    const flatFileNames = ([] as string[]).concat(...fileNames);
+    const apis = await Promise.all(flatFileNames.map((fileName) => this.parseApi(fileName)));
+
+    const transformed = this.transformApis(apis);
+
+    return transformed;
+  }
+
+  public async parseApi(fileName: string): Promise<Deref<OpenApiDocument>> {
+    const absoluteFilePath = this.isUrl(fileName) ? fileName : path.resolve(cwd(), fileName);
+    const doc = await this.loadDocument(absoluteFilePath);
+    return await this.dereference(absoluteFilePath, '', doc.document);
+  }
+
+  public transformApis(apis: Deref<OpenApiDocument>[]): ApiData {
+    const collectedData = collectOpenApi(apis);
+    const transformedData = transformOpenApi(collectedData, this._config);
+    return transformedData;
+  }
+
+  private async dereference<T extends OpenApiObject<string>>(file: string, path: string, value: T): Promise<Deref<T>> {
+    let existingDocument = this._loadedDocuments.get(file);
+    if (existingDocument) {
+      const existingComponent = existingDocument.dereferencedComponents.get(path);
+      if (existingComponent) {
+        return existingComponent as Deref<T>;
+      }
+    } else {
+      existingDocument = await this.loadDocument(file);
+    }
+
+    const result = createDerefProxy(value, {
+      file,
+      path,
+      document: existingDocument.dereferencedDocument,
+      originalComponent: value,
+    });
+    existingDocument.dereferencedComponents.set(path, result as Deref<OpenApiObject<string>>);
+
+    if (value.$ref) {
+      // deno-lint-ignore no-explicit-any
+      result.$ref = await this.resolveReference<T>(file, value as OpenApiReference) as any;
+    }
+    for (const key of Object.keys(value) as (keyof T)[]) {
+      if (key === '$ref') continue;
+      const v = value[key];
+      if (isNullish(v)) continue;
+      if (typeof v === 'object') {
+        if (Array.isArray(v)) {
+          (result as Record<keyof T, unknown>)[key] = await Promise.all(
+            v.map(async (v, index) => {
+              if (v && typeof v === 'object') {
+                return await this.dereference(file, `${path}/${String(key)}/${index}`, v);
+              } else {
+                return v;
+              }
+            }),
+          );
+        } else {
+          (result as Record<keyof T, unknown>)[key] = await this.dereference(
+            file,
+            `${path}/${String(key)}`,
+            v as Record<string, unknown>,
+          );
+        }
+      }
+      if (typeof v === 'string' && path.endsWith('/discriminator/mapping')) {
+        (result as Record<keyof T, unknown>)[key] = await this.resolveReference<OpenApiSchema>(file, { $ref: v });
+      }
+    }
+
+    return result;
+  }
+
+  private async resolveReference<T extends OpenApiObject<string>>(
+    file: string,
+    ref: OpenApiReference,
+  ): Promise<Deref<T> | undefined> {
+    const [refFile, refPath] = ref.$ref.split('#');
+
+    let absoluteRefFile: string = refFile;
+    if (!/\S/.test(refFile)) {
+      absoluteRefFile = file;
+    } else if (!this.isUrl(refFile)) {
+      absoluteRefFile = path.resolve(path.dirname(file), refFile);
+    }
+
+    const doc = await this.loadDocument(absoluteRefFile);
+
+    const value = refPath ? getDeepProperty(doc.document, refPath.replace(/[/]/g, '.')) : doc.document;
+    if (value && typeof value === 'object') {
+      return this.dereference(absoluteRefFile, refPath ?? '/', value as T);
+    }
+
+    return undefined;
+  }
+
+  private async loadDocument(fileOrUrl: string): Promise<LoadedDocument> {
+    const existingDocument = this._loadedDocuments.get(fileOrUrl);
+    if (existingDocument) {
+      return existingDocument;
+    }
+
+    const documentContent = await this.getDocumentContent(fileOrUrl);
+    const extname = path.extname(fileOrUrl).toLowerCase();
+
+    let parsedDocument: unknown;
+    if (extname === '.json') {
+      parsedDocument = this.tryParseJson(documentContent);
+    } else if (extname === '.yaml' || extname === '.yml') {
+      parsedDocument = this.tryParseYaml(documentContent);
+    } else {
+      parsedDocument = this.tryParseJson(documentContent);
+      if (parsedDocument !== undefined) {
+        parsedDocument = this.tryParseYaml(documentContent);
+      }
+    }
+
+    if (parsedDocument === undefined) {
+      throw new Error(`Unable to parse ${fileOrUrl}`);
+    }
+
+    const doc = (parsedDocument ?? {}) as OpenApiDocument;
+    const deref = createDerefProxy(doc, {
+      file: fileOrUrl,
+      path: '',
+      originalComponent: doc,
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      document: undefined!,
+    });
+    deref.$src.document = deref;
+    const loadedDocument = {
+      file: fileOrUrl,
+      document: doc,
+      dereferencedDocument: deref,
+      dereferencedComponents: new Map(),
+    };
+    this._loadedDocuments.set(fileOrUrl, loadedDocument);
+    return loadedDocument;
+  }
+
+  private async getDocumentContent(fileOrUrl: string): Promise<string> {
+    if (this.isUrl(fileOrUrl)) {
+      const res = await dntShim.fetch(fileOrUrl);
+      if (!res.ok) {
+        throw new Error(`Unable to download ${fileOrUrl}: ${res.statusText}`);
+      }
+      return await res.text();
+    } else {
+      return (await fs.readFile(fileOrUrl)).toString();
+    }
+  }
+
+  private isUrl(fileOrUrl: string): boolean {
+    return /^https?:\/\//i.test(fileOrUrl);
+  }
+
+  private tryParseJson(json: string): unknown {
+    try {
+      return JSON.parse(json);
+    } catch {
+      return undefined;
+    }
+  }
+
+  private tryParseYaml(yaml: string): unknown {
+    try {
+      return YAML.parse(yaml);
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+function getDeepProperty(value: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let result: unknown = value;
+  for (const part of parts) {
+    if (!/\S/.test(part)) continue;
+    if (typeof result === 'object') {
+      result = (result as Record<string, unknown>)[part];
+    } else {
+      return undefined;
+    }
+  }
+
+  return result;
+}

package/src/src/parse/types.ts

@@ -0,0 +1,27 @@
+import type { OpenApiDiscriminator, OpenApiDocument, OpenApiReference, OpenApiSchema } from './openapi-types.js';
+import { defaultOpenApiTransformerOptions, type OpenApiTransformerOptions } from '../transform/types.js';
+
+export type DerefSource<T> = {
+  file: string;
+  path: string;
+  document: Deref<OpenApiDocument>;
+  originalComponent: T;
+};
+
+type _DerefDiscriminator = Omit<OpenApiDiscriminator, 'mapping'> & {
+  mapping?: Record<string, Deref<OpenApiSchema>>;
+};
+type _Deref<T extends object> = T extends OpenApiDiscriminator ? _DerefDiscriminator
+  :
+    & {
+      [K in keyof T as K extends keyof OpenApiReference ? never : K]: Deref<T[K]>;
+    }
+    & {
+      $src: DerefSource<T>;
+      $ref?: Deref<T>;
+    };
+export type Deref<T> = T extends object ? (T extends (infer A)[] ? Deref<A>[] : _Deref<T>) : T;
+
+export type OpenApiParserOptions = OpenApiTransformerOptions;
+
+export const defaultOpenApiParserOptions = { ...defaultOpenApiTransformerOptions };

package/src/src/transform/api-types.ts

@@ -0,0 +1,243 @@
+import type {
+  KnownOpenApiParameterTarget,
+  OpenApiHeader,
+  OpenApiHttpMethod,
+  OpenApiMediaType,
+  OpenApiOperation,
+  OpenApiParameter,
+  OpenApiPathItem,
+  OpenApiRequestBody,
+  OpenApiResponse,
+  OpenApiSchema,
+  OpenApiTag,
+} from '../parse/openapi-types.js';
+import type { Deref, DerefSource } from '../parse/types.js';
+import type { OptionalProperties } from '../utils/type.utils.js';
+
+export type ApiData = {
+  services: ApiService[];
+  endpoints: ApiEndpoint[];
+  schemas: ApiSchema[];
+};
+
+export type ApiComponentSource<T> = DerefSource<T> & {
+  component: Deref<T>;
+};
+
+export type Transformed<T> = T extends OpenApiTag ? ApiService
+  : T extends OpenApiPathItem ? ApiPath
+  : T extends OpenApiParameter ? ApiParameter
+  : T extends OpenApiRequestBody ? ApiRequestBody
+  : T extends OpenApiResponse ? ApiResponse
+  : T extends OpenApiMediaType ? ApiContent
+  : T extends OpenApiHeader ? ApiHeader
+  : T extends OpenApiSchema ? ApiSchema
+  : undefined;
+
+export type ApiComponent<T> = {
+  id: string;
+  $src: ApiComponentSource<T>;
+  $ref: Transformed<T> | undefined;
+};
+
+export type ApiMethod = OpenApiHttpMethod;
+export type ApiParameterTarget = KnownOpenApiParameterTarget;
+
+export type ApiServiceComponent = OptionalProperties<ApiComponent<OpenApiTag>, '$src'>;
+export type ApiService = ApiServiceComponent & {
+  name: string;
+  description: string | undefined;
+  endpoints: ApiEndpoint[];
+};
+
+export type ApiPathComponent = ApiComponent<OpenApiPathItem>;
+export type ApiPath = ApiPathComponent & {
+  summary: string | undefined;
+  description: string | undefined;
+  path: string;
+  parameters: ApiParameter[];
+} & { [K in ApiMethod]: ApiEndpoint | undefined };
+
+export type ApiEndpointComponent = ApiComponent<OpenApiOperation>;
+export type ApiEndpoint = ApiEndpointComponent & {
+  name: string;
+  path: string;
+  pathInfo: ApiPath;
+  method: ApiMethod;
+  summary: string | undefined;
+  description: string | undefined;
+  parameters: ApiParameter[];
+  deprecated: boolean;
+  requestBody: ApiRequestBody | undefined;
+  responses: ApiResponse[];
+  tags: string[];
+  custom: Record<string, unknown>;
+};
+
+export type ApiParameterComponent = ApiComponent<OpenApiParameter>;
+export type ApiParameter = ApiParameterComponent & {
+  name: string;
+  target: ApiParameterTarget;
+  description: string | undefined;
+  required: boolean;
+  deprecated: boolean;
+  allowEmptyValue: boolean | undefined;
+  style: string | undefined;
+  explode: boolean | undefined;
+  allowReserved: boolean | undefined;
+  schema: ApiSchema | undefined;
+};
+
+export type ApiRequestBodyComponent = ApiComponent<OpenApiRequestBody>;
+export type ApiRequestBody = ApiRequestBodyComponent & {
+  description: string | undefined;
+  content: ApiContent[];
+  required: boolean;
+};
+
+export type ApiContentComponent = ApiComponent<OpenApiMediaType>;
+export type ApiContent = ApiContentComponent & {
+  type: string;
+  schema: ApiSchema | undefined;
+};
+
+export type ApiExampleComponent = ApiComponent<OpenApiResponse>;
+export type ApiResponse = ApiExampleComponent & {
+  statusCode: number | undefined;
+  description: string | undefined;
+  headers: ApiHeader[];
+  contentOptions: ApiContent[];
+};
+
+export type ApiHeaderComponent = Omit<ApiComponent<OpenApiHeader> | ApiComponent<OpenApiSchema>, '$ref'> & {
+  $ref: ApiHeader | undefined;
+};
+export type ApiHeader = ApiHeaderComponent & Omit<ApiParameter, 'target'>;
+
+export type ApiSchemaType = 'string' | 'number' | 'integer' | 'array' | 'boolean' | 'null' | 'object' | string;
+export type ApiSchemaKind =
+  | 'oneOf'
+  | 'multi-type'
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'array'
+  | 'boolean'
+  | 'null'
+  | 'object'
+  | 'combined'
+  | 'unknown';
+export type ApiSchemaAccessibility = 'all' | 'readOnly' | 'writeOnly' | 'none';
+export type ApiSchemaProperty = {
+  name: string;
+  schema: ApiSchema;
+};
+export type ApiSchemaDiscriminator = {
+  propertyName: string;
+  mapping: Record<string, ApiSchema>;
+};
+export type ApiSchemaComponent = ApiComponent<OpenApiSchema>;
+export type ApiSchemaBase = ApiSchemaComponent & {
+  name: string;
+  isNameGenerated: boolean;
+  description: string | undefined;
+  deprecated: boolean;
+  accessibility: ApiSchemaAccessibility;
+  enum: unknown[] | undefined;
+  const: unknown | undefined;
+  default: unknown | undefined;
+  example: unknown | undefined;
+  nullable: boolean;
+  required: Set<string>;
+  custom: Record<string, unknown>;
+  not: ApiSchema | undefined;
+  discriminator: ApiSchemaDiscriminator | undefined;
+  inheritedSchemas: (ApiSchema & { discriminator: NonNullable<ApiSchema['discriminator']> })[];
+};
+export type ApiSchema<T extends ApiSchemaKind = ApiSchemaKind> = ApiSchemaBase & ApiSchemaExtensions<T>;
+type AdditionalCombinedSchemaProperties = {
+  allOf: ApiSchema[];
+  anyOf: ApiSchema[];
+};
+type AdditionalArraySchemaProperties = {
+  items: ApiSchema | undefined;
+  minItems: number | undefined;
+  maxItems: number | undefined;
+};
+type AdditionalObjectSchemaProperties = {
+  properties: Map<string, ApiSchemaProperty>;
+  additionalProperties: boolean | undefined | ApiSchema;
+} & AdditionalCombinedSchemaProperties;
+type AdditionalNumberSchemaProperties = {
+  minimum: number | undefined;
+  maximum: number | undefined;
+};
+type AdditionalStringSchemaProperties = {
+  pattern: string | undefined;
+  minLength: number | undefined;
+  maxLength: number | undefined;
+};
+type AdditionalPrimitiveSchemaProperties = {
+  format: string | undefined;
+};
+export type ApiSchemaExtensions<T extends ApiSchemaKind> = T extends 'oneOf' ? { kind: 'oneOf'; oneOf: ApiSchema[] }
+  : T extends 'multi-type' ?
+      & {
+        kind: 'multi-type';
+        type: ApiSchemaType[];
+      }
+      & AdditionalArraySchemaProperties
+      & AdditionalObjectSchemaProperties
+      & AdditionalNumberSchemaProperties
+      & AdditionalStringSchemaProperties
+      & AdditionalPrimitiveSchemaProperties
+  : T extends 'string'
+    ? { kind: 'string'; type: 'string' } & AdditionalStringSchemaProperties & AdditionalPrimitiveSchemaProperties
+  : T extends 'boolean' ? { kind: 'boolean'; type: 'boolean' } & AdditionalPrimitiveSchemaProperties
+  : T extends 'null' ? { kind: 'null'; type: 'null' }
+  : T extends 'number' | 'integer'
+    ? { kind: 'number' | 'integer'; type: T } & AdditionalNumberSchemaProperties & AdditionalPrimitiveSchemaProperties
+  : T extends 'array' ? {
+      kind: 'array';
+      type: 'array';
+    } & AdditionalArraySchemaProperties
+  : T extends 'object' ? {
+      kind: 'object';
+      type: 'object';
+    } & AdditionalObjectSchemaProperties
+  : T extends 'combined' ? {
+      kind: 'combined';
+    } & AdditionalCombinedSchemaProperties
+  : { kind: 'unknown' };
+export type CombinedLikeApiSchema = ApiSchemaBase & {
+  kind: 'combined' | 'object' | 'multi-type';
+  type?: 'object' | string[];
+} & AdditionalCombinedSchemaProperties;
+export type NumberLikeApiSchema =
+  & ApiSchemaBase
+  & {
+    kind: 'number' | 'integer' | 'multi-type';
+    type: 'number' | 'integer' | string[];
+  }
+  & AdditionalNumberSchemaProperties
+  & AdditionalPrimitiveSchemaProperties;
+export type ArrayLikeApiSchema = ApiSchemaBase & {
+  kind: 'array' | 'multi-type';
+  type: 'array' | string[];
+} & AdditionalArraySchemaProperties;
+export type ObjectLikeApiSchema = ApiSchemaBase & {
+  kind: 'object' | 'multi-type';
+  type: 'object' | string[];
+} & AdditionalObjectSchemaProperties;
+export type StringLikeApiSchema =
+  & ApiSchemaBase
+  & {
+    kind: 'string' | 'multi-type';
+    type: 'string' | string[];
+  }
+  & AdditionalStringSchemaProperties
+  & AdditionalPrimitiveSchemaProperties;
+export type PrimitiveLikeApiSchema = ApiSchemaBase & {
+  kind: 'string' | 'number' | 'integer' | 'boolean' | 'null' | 'multi-type';
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'null' | string[];
+} & AdditionalPrimitiveSchemaProperties;