@cparra/apexdocs 3.0.0-alpha.9 → 3.0.0-rc.0

package/src/core/markdown/reflection/__test__/filter-scope.spec.ts

@@ -0,0 +1,306 @@
+import { ParsedFile } from '../../../shared/types';
+import { ClassMirror, EnumMirror, InterfaceMirror, reflect } from '@cparra/apex-reflection';
+import { filterScope } from '../filter-scope';
+
+function parsedFileFromRawString(raw: string): ParsedFile {
+  const { error, typeMirror } = reflect(raw);
+  if (error) {
+    throw new Error(error.message);
+  }
+
+  return {
+    source: {
+      filePath: 'test.cls',
+      name: typeMirror!.name,
+      type: typeMirror!.type_name,
+    },
+    type: typeMirror!,
+  };
+}
+
+describe('When filtering scope', () => {
+  it('filters out files with the @ignore annotation', () => {
+    const properties: [string, number][] = [
+      [
+        `
+        /**
+         * @ignore
+         */
+        global class MyClass {}
+        `,
+        0,
+      ],
+      ['global class MyClass {}', 1],
+    ];
+
+    for (const [input, expected] of properties) {
+      const parsedFile = parsedFileFromRawString(input);
+
+      const result = filterScope(['global'], [parsedFile]);
+
+      expect(result).toHaveLength(expected);
+    }
+  });
+
+  describe('when scoping a class', () => {
+    it('filters out methods tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global void myMethod() {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global void myMethod() {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).methods).toHaveLength(expected);
+      }
+    });
+
+    it('filters out properties tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global Integer myProperty { get; set; }
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global Integer myProperty { get; set; }
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).properties).toHaveLength(expected);
+      }
+    });
+
+    it('filters out fields tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global Integer myField;
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global Integer myField;
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).fields).toHaveLength(expected);
+      }
+    });
+
+    it('filters out inner classes tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global class InnerClass {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global class InnerClass {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).classes).toHaveLength(expected);
+      }
+    });
+
+    it('filters out inner interfaces tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global interface InnerInterface {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global interface InnerInterface {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).interfaces).toHaveLength(expected);
+      }
+    });
+
+    it('filters out inner enums tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global enum InnerEnum {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global enum InnerEnum {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).enums).toHaveLength(expected);
+      }
+    });
+  });
+
+  describe('when scoping an interface', () => {
+    it('filters out methods tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global interface MyInterface {
+            /**
+             * @ignore
+             */
+            void myMethod();
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global interface MyInterface {
+            void myMethod();
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as InterfaceMirror).methods).toHaveLength(expected);
+      }
+    });
+  });
+
+  describe('when scoping an enum', () => {
+    it('never filters out enum values, even if tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global enum MyEnum {
+            /**
+             * @ignore
+             */
+            VALUE
+          }
+          `,
+          1,
+        ],
+        [
+          `
+          global enum MyEnum {
+            VALUE
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as EnumMirror).values).toHaveLength(expected);
+      }
+    });
+  });
+});

package/src/core/markdown/reflection/reflect-source.ts

@@ -1,13 +1,13 @@
 import { ParsedFile, UnparsedSourceFile } from '../../shared/types';
-//import * as E from 'fp-ts/Either';
 import * as TE from 'fp-ts/TaskEither';
+import * as E from 'fp-ts/Either';
 import * as T from 'fp-ts/Task';
 import * as A from 'fp-ts/lib/Array';
-import { reflect as mirrorReflection, Type } from '@cparra/apex-reflection';
+import { Annotation, reflect as mirrorReflection, Type } from '@cparra/apex-reflection';
 import { pipe } from 'fp-ts/function';
 import * as O from 'fp-ts/Option';
 import { parseApexMetadata } from '../../parse-apex-metadata';
-import { ParsingError } from '@cparra/apex-reflection/index';
+import { ParsingError } from '@cparra/apex-reflection';
 import { apply } from '#utils/fp';
 import { Semigroup } from 'fp-ts/Semigroup';
 
@@ -37,20 +37,20 @@ async function reflectAsync(rawSource: string): Promise<Type> {
   });
 }
 
-export function myPipeSeq(apexBundles: UnparsedSourceFile[]) {
+export function reflectBundles(apexBundles: UnparsedSourceFile[]) {
   const semiGroupReflectionError: Semigroup<ReflectionErrors> = {
     concat: (x, y) => new ReflectionErrors([...x.errors, ...y.errors]),
   };
   const Ap = TE.getApplicativeTaskValidation(T.ApplyPar, semiGroupReflectionError);
 
-  return pipe(apexBundles, A.traverse(Ap)(myPipe));
+  return pipe(apexBundles, A.traverse(Ap)(reflectBundle));
 }
 
-function myPipe(apexBundle: UnparsedSourceFile): TE.TaskEither<ReflectionErrors, ParsedFile> {
+function reflectBundle(apexBundle: UnparsedSourceFile): TE.TaskEither<ReflectionErrors, ParsedFile> {
   const convertToParsedFile: (typeMirror: Type) => ParsedFile = apply(toParsedFile, apexBundle.filePath);
-  const withMetadata: (parsedFile: ParsedFile) => ParsedFile = apply(addMetadata, apexBundle.metadataContent);
+  const withMetadata = apply(addMetadata, apexBundle.metadataContent);
 
-  return pipe(apexBundle, reflectAsTask, TE.map(convertToParsedFile), TE.map(withMetadata));
+  return pipe(apexBundle, reflectAsTask, TE.map(convertToParsedFile), TE.flatMap(withMetadata));
 }
 
 function reflectAsTask(apexBundle: UnparsedSourceFile): TE.TaskEither<ReflectionErrors, Type> {
@@ -72,51 +72,52 @@ function toParsedFile(filePath: string, typeMirror: Type): ParsedFile {
   };
 }
 
-function addMetadata(rawMetadataContent: string | null, parsedFile: ParsedFile) {
-  return {
-    ...parsedFile,
-    type: addFileMetadataToTypeAnnotation(parsedFile.type, rawMetadataContent),
-  };
+function addMetadata(
+  rawMetadataContent: string | null,
+  parsedFile: ParsedFile,
+): TE.TaskEither<ReflectionErrors, ParsedFile> {
+  return TE.fromEither(
+    pipe(
+      parsedFile.type,
+      (type) => addFileMetadataToTypeAnnotation(type, rawMetadataContent),
+      E.map((type) => ({ ...parsedFile, type })),
+      E.mapLeft((error) => errorToReflectionErrors(error, parsedFile.source.filePath)),
+    ),
+  );
 }
 
-// TODO: Not Async below
-
-// export function reflectSourceCode(apexBundles: UnparsedSourceFile[]) {
-//   return apexBundles.map(reflectSourceBody);
-// }
-//
-// function reflectSourceBody(apexBundle: UnparsedSourceFile): E.Either<ReflectionError, ParsedFile> {
-//   const { filePath, content: input, metadataContent: metadata } = apexBundle;
-//   const result = mirrorReflection(input);
-//   return result.error
-//     ? E.left(new ReflectionError(filePath, result.error.message))
-//     : E.right({
-//         source: {
-//           filePath,
-//           name: result.typeMirror!.name,
-//           type: result.typeMirror!.type_name,
-//         },
-//         type: addFileMetadataToTypeAnnotation(result.typeMirror!, metadata),
-//       });
-// }
-
-function addFileMetadataToTypeAnnotation(type: Type, metadata: string | null): Type {
+function errorToReflectionErrors(error: Error, filePath: string): ReflectionErrors {
+  return new ReflectionErrors([new ReflectionError(filePath, error.message)]);
+}
+
+function addFileMetadataToTypeAnnotation(type: Type, metadata: string | null): E.Either<Error, Type> {
+  const concatAnnotationToType = apply(concatAnnotations, type);
+
   return pipe(
     O.fromNullable(metadata),
-    O.map((metadata) => {
-      // TODO: Do we need to error check this, as it is coming from an external library?
-      // Or maybe what we do is return the Either from the parse-apex-metadata function?
-      const metadataParams = parseApexMetadata(metadata);
-      metadataParams.forEach((value, key) => {
-        const declaration = `${key}: ${value}`;
-        type.annotations.push({
-          rawDeclaration: declaration,
-          name: declaration,
-          type: declaration,
-        });
-      });
-      return type;
-    }),
-    O.getOrElse(() => type),
+    O.map(concatAnnotationToType),
+    O.getOrElse(() => E.right(type)),
   );
 }
+
+function concatAnnotations(type: Type, metadataInput: string): E.Either<Error, Type> {
+  return pipe(
+    metadataInput,
+    parseApexMetadata,
+    E.map((metadataMap) => ({
+      ...type,
+      annotations: [...type.annotations, ...mapToAnnotations(metadataMap)],
+    })),
+  );
+}
+
+function mapToAnnotations(metadata: Map<string, string>): Annotation[] {
+  return Array.from(metadata.entries()).map(([key, value]) => {
+    const declaration = `${key}: ${value}`;
+    return {
+      name: declaration,
+      type: declaration,
+      rawDeclaration: declaration,
+    };
+  });
+}

package/src/core/openApiSettings.ts

@@ -0,0 +1,41 @@
+export interface SettingsConfig {
+  sourceDirectory: string;
+  outputDir: string;
+  openApiFileName: string;
+  namespace?: string;
+  openApiTitle?: string;
+  version: string;
+}
+
+export class OpenApiSettings {
+  private static instance: OpenApiSettings;
+
+  private constructor(public config: SettingsConfig) {}
+
+  public static build(config: SettingsConfig) {
+    OpenApiSettings.instance = new OpenApiSettings(config);
+  }
+
+  public static getInstance(): OpenApiSettings {
+    if (!OpenApiSettings.instance) {
+      throw new Error('Settings has not been initialized');
+    }
+    return OpenApiSettings.instance;
+  }
+
+  public getOpenApiTitle(): string | undefined {
+    return this.config.openApiTitle;
+  }
+
+  public getNamespace(): string | undefined {
+    return this.config.namespace;
+  }
+
+  public openApiFileName(): string {
+    return this.config.openApiFileName;
+  }
+
+  public getVersion(): string {
+    return this.config.version;
+  }
+}

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

@@ -1,12 +1,12 @@
 import { OpenApiDocsProcessor } from '../open-api-docs-processor';
-import { Settings } from '../../settings';
+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(() => {
-  Settings.build(new SettingsBuilder().build());
+  OpenApiSettings.build(new SettingsBuilder().build());
 });
 
 it('should add a path based on the @UrlResource annotation on the class', function () {

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

@@ -2,7 +2,7 @@ import { FileContainer } from './file-container';
 import { ClassMirror, Type } from '@cparra/apex-reflection';
 import { Logger } from '#utils/logger';
 import { OpenApi } from './open-api';
-import { Settings } from '../settings';
+import { OpenApiSettings } from '../openApiSettings';
 import { MethodParser } from './parsers/MethodParser';
 import { camel2title } from '#utils/string-utils';
 import { createOpenApiFile } from './openapi-type-file';
@@ -13,11 +13,15 @@ export class OpenApiDocsProcessor {
 
   constructor() {
     this._fileContainer = new FileContainer();
-    const title = Settings.getInstance().getOpenApiTitle();
+    const title = OpenApiSettings.getInstance().getOpenApiTitle();
     if (!title) {
       throw Error('No OpenApi title was provided.');
     }
-    this.openApiModel = new OpenApi(title, '1.0.0', Settings.getInstance().getNamespace());
+    this.openApiModel = new OpenApi(
+      title,
+      OpenApiSettings.getInstance().getVersion(),
+      OpenApiSettings.getInstance().getNamespace(),
+    );
   }
 
   fileBuilder(): FileContainer {
@@ -66,7 +70,7 @@ export class OpenApiDocsProcessor {
   }
 
   onAfterProcess: ((types: Type[]) => void) | undefined = () => {
-    const page = createOpenApiFile(Settings.getInstance().openApiFileName(), this.openApiModel);
+    const page = createOpenApiFile(OpenApiSettings.getInstance().openApiFileName(), this.openApiModel);
     this._fileContainer.pushFile(page);
   };
 

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

@@ -15,7 +15,11 @@ export class OpenApi {
   servers: ServerObject[];
   components?: ComponentsObject;
 
-  constructor(title: string, version: string, private namespace?: string) {
+  constructor(
+    title: string,
+    version: string,
+    private namespace?: string,
+  ) {
     this.info = {
       title: title,
       version: version,

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

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

package/src/core/openapi/parser.ts

@@ -1,5 +1,4 @@
 import { ClassMirror, InterfaceMirror, ReflectionResult, Type } from '@cparra/apex-reflection';
-import { parseApexMetadata } from '../parse-apex-metadata';
 import { Logger } from '#utils/logger';
 import { UnparsedSourceFile } from '../shared/types';
 
@@ -16,20 +15,7 @@ export class RawBodyParser implements TypeParser {
     const types = this.typeBundles
       .map((currentBundle) => {
         Logger.log(`Parsing file: ${currentBundle.filePath}`);
-        const result = reflect(currentBundle);
-        if (!!result.typeMirror && !!currentBundle.metadataContent) {
-          // If successful and there is a metadata file
-          const metadataParams = parseApexMetadata(currentBundle.metadataContent);
-          metadataParams.forEach((value, key) => {
-            const declaration = `${key}: ${value}`;
-            result.typeMirror?.annotations.push({
-              rawDeclaration: declaration,
-              name: declaration,
-              type: declaration,
-            });
-          });
-        }
-        return result;
+        return reflect(currentBundle);
       })
       .filter((reflectionResult) => {
         return reflectionResult.typeMirror;

package/src/core/openapi/transpiler.ts

@@ -1,5 +1,4 @@
 import { Type } from '@cparra/apex-reflection';
-import { Settings } from '../settings';
 import { OpenApiDocsProcessor } from './open-api-docs-processor';
 
 export default class Transpiler {
@@ -10,10 +9,6 @@ export default class Transpiler {
       return 0;
     });
 
-    if (Settings.getInstance().indexOnly) {
-      return;
-    }
-
     sortedTypes.forEach((currentType) => {
       processor.onProcess(currentType);
     });

package/src/core/parse-apex-metadata.ts

@@ -1,13 +1,29 @@
 import { XMLParser } from 'fast-xml-parser';
+import * as E from 'fp-ts/Either';
+import { pipe } from 'fp-ts/function';
+
+type ApexMetadata = {
+  ApexClass: ApexClassMetadata;
+};
+
+type ApexClassMetadata = {
+  apiVersion: string;
+  status?: string;
+};
 
 export function parseApexMetadata(input: string) {
-  const map = new Map<string, string>();
-  const xml = new XMLParser().parse(input);
+  return pipe(input, parse, E.map(toMap));
+}
 
-  map.set('apiVersion', xml.ApexClass.apiVersion ?? '');
+function parse(input: string): E.Either<Error, ApexMetadata> {
+  return E.tryCatch(() => new XMLParser().parse(input), E.toError);
+}
 
-  if (xml.ApexClass.status) {
-    map.set('status', xml.ApexClass.status);
+function toMap(metadata: ApexMetadata): Map<string, string> {
+  const map = new Map<string, string>();
+  map.set('apiVersion', String(metadata.ApexClass.apiVersion));
+  if (metadata.ApexClass.status) {
+    map.set('status', String(metadata.ApexClass.status));
   }
 
   return map;