@cparra/apexdocs 3.0.0-rc.0 → 3.1.0

package/src/core/openapi/__tests__/open-api-docs-processor.spec.ts

@@ -1,56 +0,0 @@
-import { OpenApiDocsProcessor } from '../open-api-docs-processor';
-import { OpenApiSettings } from '../../openApiSettings';
-import { SettingsBuilder } from '../../../test-helpers/SettingsBuilder';
-import { DocCommentBuilder } from '../../../test-helpers/DocCommentBuilder';
-import { AnnotationBuilder } from '../../../test-helpers/AnnotationBuilder';
-import { ClassMirrorBuilder } from '../../../test-helpers/ClassMirrorBuilder';
-
-beforeEach(() => {
-  OpenApiSettings.build(new SettingsBuilder().build());
-});
-
-it('should add a path based on the @UrlResource annotation on the class', function () {
-  const annotationElementValue = {
-    key: 'urlMapping',
-    value: "'/Account/*'",
-  };
-  const classMirror = new ClassMirrorBuilder()
-    .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
-    .build();
-
-  const processor = new OpenApiDocsProcessor();
-  processor.onProcess(classMirror);
-
-  expect(processor.openApiModel.paths).toHaveProperty('Account/');
-});
-
-it('should respect slashes', function () {
-  const annotationElementValue = {
-    key: 'urlMapping',
-    value: "'v1/Account/*'",
-  };
-  const classMirror = new ClassMirrorBuilder()
-    .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
-    .build();
-
-  const processor = new OpenApiDocsProcessor();
-  processor.onProcess(classMirror);
-
-  expect(processor.openApiModel.paths).toHaveProperty('v1/Account/');
-});
-
-it('should contain a path with a description when the class has an ApexDoc comment', function () {
-  const annotationElementValue = {
-    key: 'urlMapping',
-    value: "'/Account/*'",
-  };
-  const classMirror = new ClassMirrorBuilder()
-    .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
-    .withDocComment(new DocCommentBuilder().withDescription('My Description').build())
-    .build();
-
-  const processor = new OpenApiDocsProcessor();
-  processor.onProcess(classMirror);
-
-  expect(processor.openApiModel.paths['Account/'].description).toBe('My Description');
-});

package/src/core/openapi/__tests__/open-api.spec.ts

@@ -1,22 +0,0 @@
-import { OpenApi } from '../open-api';
-
-it('should get created with a title and a version', function () {
-  const openApi = new OpenApi('Test Spec', '1.0.0');
-
-  expect(openApi.info.title).toBe('Test Spec');
-  expect(openApi.info.version).toBe('1.0.0');
-});
-
-it('should contain a single server, which points to the correct server URL', function () {
-  const openApi = new OpenApi('Test Spec', '1.0.0');
-
-  expect(openApi.servers.length).toBe(1);
-  expect(openApi.servers[0].url).toBe('/services/apexrest/');
-});
-
-it('should optionally allow for a namespace to be passed in as part of the server', function () {
-  const openApi = new OpenApi('Test Spec', '1.0.0', 'Namespace');
-
-  expect(openApi.servers.length).toBe(1);
-  expect(openApi.servers[0].url).toBe('/services/apexrest/Namespace/');
-});

package/src/core/openapi/apex-doc-types.ts

@@ -1,26 +0,0 @@
-// These are types that represent how the data is expected to be created in the ApexDoc (as YAML), which
-// in some cases might be different from the official OpenApi spec for simplicity when writing the ApexDoc.
-
-import { SchemaObjectArray, SchemaObjectObject } from './open-api-types';
-
-export type ApexDocHttpResponse = {
-  statusCode: number;
-  description?: string;
-  schema: ApexDocSchemaObject;
-};
-
-export type ApexDocHttpRequestBody = {
-  description?: string;
-  schema: ApexDocSchemaObject;
-  required?: boolean;
-};
-
-export type ApexDocParameterObject = {
-  name: string;
-  in: 'query' | 'header' | 'path' | 'cookie';
-  description?: string;
-  required?: boolean;
-  schema: ApexDocSchemaObject;
-};
-
-export type ApexDocSchemaObject = SchemaObjectObject | SchemaObjectArray | string;

package/src/core/openapi/apex-type-wrappers/ClassMirrorWrapper.ts

@@ -1,12 +0,0 @@
-import { ClassMirror, MethodMirror } from '@cparra/apex-reflection';
-
-export class ClassMirrorWrapper {
-  constructor(public classMirror: ClassMirror) {}
-
-  getMethodsByAnnotation(annotation: string): MethodMirror[] {
-    return this.classMirror.methods.filter((method) => this.hasAnnotation(method, annotation));
-  }
-
-  private hasAnnotation = (method: MethodMirror, annotationName: string) =>
-    method.annotations.some((annotation) => annotation.name.toLowerCase() === annotationName);
-}

package/src/core/openapi/apex-type-wrappers/MethodMirrorWrapper.ts

@@ -1,11 +0,0 @@
-import { DocCommentAnnotation, MethodMirror } from '@cparra/apex-reflection';
-
-export class MethodMirrorWrapper {
-  constructor(public methodMirror: MethodMirror) {}
-
-  public hasDocCommentAnnotation = (annotationName: string) =>
-    this.methodMirror.docComment?.annotations.some((annotation) => annotation.name.toLowerCase() === annotationName);
-
-  public getDocCommentAnnotation = (annotationName: string): DocCommentAnnotation | undefined =>
-    this.methodMirror.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === annotationName);
-}

package/src/core/openapi/apex-type-wrappers/__tests__/ClassMirrorWrapper.spec.ts

@@ -1,15 +0,0 @@
-import { ClassMirrorWrapper } from '../ClassMirrorWrapper';
-import { ClassMirrorBuilder } from '../../../../test-helpers/ClassMirrorBuilder';
-import { MethodMirrorBuilder } from '../../../../test-helpers/MethodMirrorBuilder';
-import { AnnotationBuilder } from '../../../../test-helpers/AnnotationBuilder';
-
-it('should return methods by annotation when they exist', function () {
-  const classMirror = new ClassMirrorBuilder()
-    .addMethod(new MethodMirrorBuilder().addAnnotation(new AnnotationBuilder().withName('httpget').build()).build())
-    .build();
-
-  const classMirrorWrapper = new ClassMirrorWrapper(classMirror);
-  const foundMethods = classMirrorWrapper.getMethodsByAnnotation('httpget');
-
-  expect(foundMethods.length).toBe(1);
-});

package/src/core/openapi/file-container.ts

@@ -1,13 +0,0 @@
-import { PageData } from '../shared/types';
-
-export class FileContainer {
-  _files: PageData[] = [];
-
-  files(): PageData[] {
-    return this._files;
-  }
-
-  pushFile(file: PageData): void {
-    this._files.push(file);
-  }
-}

package/src/core/openapi/manifest-factory.ts

@@ -1,16 +0,0 @@
-import Manifest from '../manifest';
-import { TypeParser } from './parser';
-import { ReflectionResult } from '@cparra/apex-reflection';
-import { UnparsedSourceFile } from '../shared/types';
-
-/**
- * Builds a new Manifest object, sourcing its types from the received TypeParser.
- * @param typeParser In charge of returning the list of reflected types.
- * @param reflect Reflection function.
- */
-export function createManifest(
-  typeParser: TypeParser,
-  reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult,
-): Manifest {
-  return new Manifest(typeParser.parse(reflect));
-}

package/src/core/openapi/open-api-docs-processor.ts

@@ -1,93 +0,0 @@
-import { FileContainer } from './file-container';
-import { ClassMirror, Type } from '@cparra/apex-reflection';
-import { Logger } from '#utils/logger';
-import { OpenApi } from './open-api';
-import { OpenApiSettings } from '../openApiSettings';
-import { MethodParser } from './parsers/MethodParser';
-import { camel2title } from '#utils/string-utils';
-import { createOpenApiFile } from './openapi-type-file';
-
-export class OpenApiDocsProcessor {
-  protected readonly _fileContainer: FileContainer;
-  openApiModel: OpenApi;
-
-  constructor() {
-    this._fileContainer = new FileContainer();
-    const title = OpenApiSettings.getInstance().getOpenApiTitle();
-    if (!title) {
-      throw Error('No OpenApi title was provided.');
-    }
-    this.openApiModel = new OpenApi(
-      title,
-      OpenApiSettings.getInstance().getVersion(),
-      OpenApiSettings.getInstance().getNamespace(),
-    );
-  }
-
-  fileBuilder(): FileContainer {
-    return this._fileContainer;
-  }
-
-  onProcess(type: Type): void {
-    Logger.logSingle(`Processing ${type.name}`, 'green');
-
-    const endpointPath = this.getEndpointPath(type);
-    if (!endpointPath) {
-      return;
-    }
-
-    this.openApiModel.paths[endpointPath] = {};
-    if (type.docComment?.description) {
-      this.openApiModel.paths[endpointPath].description = type.docComment.description;
-    }
-
-    // We can safely cast to a ClassMirror, since only these support the @RestResource annotation
-    const typeAsClass = type as ClassMirror;
-
-    // Add tags for this Apex class to the OpenApi model
-    const tagName = camel2title(endpointPath);
-    this.openApiModel.tags.push({
-      name: tagName,
-      description: type.docComment?.description,
-    });
-
-    const parser = new MethodParser(this.openApiModel);
-
-    // GET
-    parser.parseMethod(typeAsClass, endpointPath, 'get', tagName);
-
-    // PATCH
-    parser.parseMethod(typeAsClass, endpointPath, 'patch', tagName);
-
-    // POST
-    parser.parseMethod(typeAsClass, endpointPath, 'post', tagName);
-
-    // PUT
-    parser.parseMethod(typeAsClass, endpointPath, 'put', tagName);
-
-    // DELETE
-    parser.parseMethod(typeAsClass, endpointPath, 'delete', tagName);
-  }
-
-  onAfterProcess: ((types: Type[]) => void) | undefined = () => {
-    const page = createOpenApiFile(OpenApiSettings.getInstance().openApiFileName(), this.openApiModel);
-    this._fileContainer.pushFile(page);
-  };
-
-  private getEndpointPath(type: Type): string | null {
-    const restResourceAnnotation = type.annotations.find((element) => element.name.toLowerCase() === 'restresource');
-    const urlMapping = restResourceAnnotation?.elementValues?.find(
-      (element) => element.key.toLowerCase() === 'urlmapping',
-    );
-    if (!urlMapping) {
-      Logger.error(`Type does not contain urlMapping annotation ${type.name}`);
-      return null;
-    }
-
-    let endpointPath = urlMapping.value.replaceAll('"', '').replaceAll("'", '').replaceAll('/*', '/');
-    if (endpointPath.startsWith('/')) {
-      endpointPath = endpointPath.substring(1);
-    }
-    return endpointPath;
-  }
-}

package/src/core/openapi/open-api-types.ts

@@ -1,119 +0,0 @@
-// verified
-export type InfoObject = {
-  title: string;
-  version: string;
-};
-
-// verified
-export type ServerObject = {
-  url: string;
-};
-
-// verified
-export type PathsObject = {
-  [index: string]: PathItemObject;
-};
-
-// verified
-export type PathItemObject = {
-  description?: string;
-  get?: OperationObject;
-  put?: OperationObject;
-  post?: OperationObject;
-  delete?: OperationObject;
-  patch?: OperationObject;
-};
-
-// verified
-export type OperationObject = {
-  tags?: string[];
-  description?: string;
-  summary?: string;
-  requestBody?: RequestBody;
-  parameters?: ParameterObject[];
-  responses?: ResponsesObject;
-};
-
-// Parameters
-export type ParameterObject = {
-  name: string;
-  in: 'query' | 'header' | 'path' | 'cookie';
-  description?: string;
-  required?: boolean;
-  schema?: SchemaObject;
-};
-
-// Request Body
-export type RequestBody = {
-  description?: string;
-  content: RequestBodyContent;
-  required?: boolean;
-};
-
-export type RequestBodyContent = {
-  [index: string]: MediaTypeObject; // Only key supported is "application/json" for now.
-};
-
-export type MediaTypeObject = {
-  schema?: SchemaObject;
-  example?: unknown;
-  examples?: { [index: string]: ExampleObject };
-};
-
-export type ExampleObject = {
-  summary?: string;
-  description?: string;
-  value?: unknown;
-};
-
-// Responses
-export type ResponsesObject = {
-  [index: string]: ResponseObject; // The key will be the status code number
-};
-
-export type ResponseObject = {
-  description: string;
-  content?: ContentObject;
-};
-
-export type ContentObject = {
-  [index: string]: { schema: SchemaObject }; // key is usually 'application/json'
-};
-
-// Common
-export type SchemaObject = SchemaObjectObject | SchemaObjectArray | ReferenceObject;
-
-export type SchemaObjectObject = {
-  type: string; // This can be "object" (which would require properties), or a primitive
-  properties?: PropertiesObject;
-  format?: string;
-  description?: string;
-};
-
-export type PropertiesObject = {
-  [index: string]: SchemaObject;
-};
-
-export type SchemaObjectArray = {
-  type: 'array';
-  items: SchemaObject;
-  description?: string;
-};
-
-// Reference and components
-
-export type ReferenceObject = {
-  $ref: string;
-  description?: string;
-};
-
-export type ComponentsObject = {
-  schemas: {
-    [index: string]: SchemaObject;
-  };
-};
-
-export type TagObject = {
-  name: string;
-  description?: string;
-};

package/src/core/openapi/open-api.ts

@@ -1,45 +0,0 @@
-import { ComponentsObject, InfoObject, PathsObject, ServerObject, TagObject } from './open-api-types';
-
-const OPEN_API_VERSION = '3.1.0';
-const SERVER_URL = '/services/apexrest/';
-
-/**
- * Represents the OpenApi 3.1.0 spec
- * https://spec.openapis.org/oas/v3.1.0
- */
-export class OpenApi {
-  openapi = OPEN_API_VERSION;
-  info: InfoObject;
-  tags: TagObject[];
-  paths: PathsObject;
-  servers: ServerObject[];
-  components?: ComponentsObject;
-
-  constructor(
-    title: string,
-    version: string,
-    private namespace?: string,
-  ) {
-    this.info = {
-      title: title,
-      version: version,
-    };
-
-    this.servers = [
-      {
-        url: this.getServerUrl(),
-      },
-    ];
-
-    this.paths = {};
-    this.tags = [];
-  }
-
-  private getServerUrl(): string {
-    if (!this.namespace) {
-      return SERVER_URL;
-    }
-
-    return `${SERVER_URL}${this.namespace}/`;
-  }
-}

package/src/core/openapi/openapi-type-file.ts

@@ -1,12 +0,0 @@
-import { OpenApi } from './open-api';
-import { OpenApiPageData } from '../shared/types';
-
-export function createOpenApiFile(fileName: string, openApiModel: OpenApi): OpenApiPageData {
-  const content = JSON.stringify({ ...openApiModel, namespace: undefined }, null, 2);
-  return {
-    outputDocPath: `${fileName}.json`,
-    content,
-    frontmatter: null,
-    group: null,
-  };
-}

package/src/core/openapi/parser.ts

@@ -1,160 +0,0 @@
-import { ClassMirror, InterfaceMirror, ReflectionResult, Type } from '@cparra/apex-reflection';
-import { Logger } from '#utils/logger';
-import { UnparsedSourceFile } from '../shared/types';
-
-export interface TypeParser {
-  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[];
-}
-
-type NameAware = { name: string };
-
-export class RawBodyParser implements TypeParser {
-  constructor(public typeBundles: UnparsedSourceFile[]) {}
-
-  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[] {
-    const types = this.typeBundles
-      .map((currentBundle) => {
-        Logger.log(`Parsing file: ${currentBundle.filePath}`);
-        return reflect(currentBundle);
-      })
-      .filter((reflectionResult) => {
-        return reflectionResult.typeMirror;
-      })
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      .map((reflectionResult) => reflectionResult.typeMirror!);
-
-    return this.addFieldsFromParent(types);
-  }
-
-  addFieldsFromParent(types: Type[]): Type[] {
-    const typesWithFields: Type[] = [];
-    for (const currentType of types) {
-      if (currentType.type_name !== 'class' && currentType.type_name !== 'interface') {
-        typesWithFields.push(currentType);
-        continue;
-      }
-
-      if (currentType.type_name === 'class') {
-        let typeAsClass = currentType as ClassMirror;
-        if (!typeAsClass.extended_class) {
-          typesWithFields.push(currentType);
-          continue;
-        }
-
-        typeAsClass = this.addMembersFromParent(typeAsClass, types);
-        typesWithFields.push(typeAsClass);
-        continue;
-      }
-
-      // At this stage, we can be sure we are dealing with an interface
-      let typeAsInterface = currentType as InterfaceMirror;
-      if (!typeAsInterface.extended_interfaces.length) {
-        typesWithFields.push(currentType);
-        continue;
-      }
-
-      typeAsInterface = this.addMethodsFromParent(typeAsInterface, types);
-      typesWithFields.push(typeAsInterface);
-    }
-
-    return typesWithFields;
-  }
-
-  addMembersFromParent(currentClass: ClassMirror, allTypes: Type[]): ClassMirror {
-    if (!currentClass.extended_class) {
-      return currentClass;
-    }
-    const parent = allTypes.find((currentType: Type) => currentType.name === currentClass.extended_class);
-    if (!parent || parent.type_name !== 'class') {
-      return currentClass;
-    }
-
-    let parentAsClass = parent as ClassMirror;
-    if (parentAsClass.extended_class) {
-      parentAsClass = this.addMembersFromParent(parentAsClass, allTypes);
-    }
-
-    currentClass.fields = [...currentClass.fields, ...this.getInheritedFields(parentAsClass, currentClass)];
-    currentClass.properties = [...currentClass.properties, ...this.getInheritedProperties(parentAsClass, currentClass)];
-    currentClass.methods = [...currentClass.methods, ...this.getInheritedMethods(parentAsClass, currentClass)];
-    return currentClass;
-  }
-
-  addMethodsFromParent(currentInterface: InterfaceMirror, allTypes: Type[]): InterfaceMirror {
-    if (!currentInterface.extended_interfaces.length) {
-      return currentInterface;
-    }
-
-    const parents = [];
-    for (const currentInterfaceName of currentInterface.extended_interfaces) {
-      const parent = allTypes.find((currentType: Type) => currentType.name === currentInterfaceName);
-      if (parent) {
-        parents.push(parent);
-      }
-    }
-
-    for (const parent of parents) {
-      let parentAsInterface = parent as InterfaceMirror;
-      if (parentAsInterface.extended_interfaces.length) {
-        parentAsInterface = this.addMethodsFromParent(parentAsInterface, allTypes);
-      }
-
-      currentInterface.methods = [
-        ...currentInterface.methods,
-        ...this.getInheritedMethods(parentAsInterface, currentInterface),
-      ];
-    }
-
-    return currentInterface;
-  }
-
-  private getInheritedFields(parentAsClass: ClassMirror, currentClass: ClassMirror) {
-    return (
-      parentAsClass.fields
-        // Filter out private fields
-        .filter((currentField) => currentField.access_modifier.toLowerCase() !== 'private')
-        // Filter out fields that also exist on the child
-        .filter((currentField) => !this.memberExists(currentClass.fields, currentField.name))
-        .map((currentField) => ({
-          ...currentField,
-          inherited: true,
-        }))
-    );
-  }
-
-  private getInheritedProperties(parentAsClass: ClassMirror, currentClass: ClassMirror) {
-    return (
-      parentAsClass.properties
-        // Filter out private properties
-        .filter((currentProperty) => currentProperty.access_modifier.toLowerCase() !== 'private')
-        // Filter out properties that also exist on the child
-        .filter((currentProperty) => !this.memberExists(currentClass.properties, currentProperty.name))
-        .map((currentProperty) => ({
-          ...currentProperty,
-          inherited: true,
-        }))
-    );
-  }
-
-  private getInheritedMethods(
-    parentAsClass: ClassMirror | InterfaceMirror,
-    currentClass: ClassMirror | InterfaceMirror,
-  ) {
-    return (
-      parentAsClass.methods
-        // Filter out private methods
-        .filter((currentMethod) => currentMethod.access_modifier.toLowerCase() !== 'private')
-        // Filter out methods that also exist on the child
-        .filter((currentMethod) => !this.memberExists(currentClass.methods, currentMethod.name))
-        .map((currentMethod) => ({
-          ...currentMethod,
-          inherited: true,
-        }))
-    );
-  }
-
-  memberExists(members: NameAware[], fieldName: string): boolean {
-    const fieldNames = members.map((currentMember) => currentMember.name);
-    return fieldNames.includes(fieldName);
-  }
-}

package/src/core/openapi/parsers/Builder.ts

@@ -1,40 +0,0 @@
-import { Reference, ReferenceBuilder } from './ReferenceBuilder';
-import { ApexDocSchemaObject } from '../../../core/openapi/apex-doc-types';
-import { SchemaObject } from '../../../core/openapi/open-api-types';
-
-export type ApexDocSchemaAware = {
-  schema: ApexDocSchemaObject;
-};
-
-export abstract class Builder<T, K> {
-  build(schemaAware: ApexDocSchemaAware): Response<T> {
-    let reference: Reference | undefined;
-    if (this.isReferenceString(schemaAware.schema)) {
-      reference = new ReferenceBuilder().build(schemaAware.schema);
-    }
-
-    return {
-      reference: reference,
-      body: this.buildBody(schemaAware as K, reference),
-    };
-  }
-
-  abstract buildBody(apexDocObject: K, reference?: Reference): T;
-
-  protected getOpenApiSchemaFromApexDocSchema(schemaAware: ApexDocSchemaAware, reference?: Reference): SchemaObject {
-    if (this.isReferenceString(schemaAware.schema)) {
-      // We are dealing with a reference
-      return reference!.entrypointReferenceObject;
-    }
-    return schemaAware.schema;
-  }
-
-  private isReferenceString = (targetObject: unknown): targetObject is string => {
-    return typeof targetObject === 'string' || targetObject instanceof String;
-  };
-}
-
-export interface Response<T> {
-  reference?: Reference;
-  body: T;
-}