@cparra/apexdocs 3.0.0-beta.1 → 3.0.0

package/examples/vitepress/docs/miscellaneous/MultiInheritanceClass.md

@@ -9,7 +9,7 @@ apexdocs
 
 **Inheritance**
 
-[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
+[SampleClass](../samplegroup/SampleClass) < [BaseClass](BaseClass)
 
 ## Fields
 ### `sampleEnumFromBase`
@@ -22,7 +22,7 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](../sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum)
 
 ## Properties
 ### Group Name

package/examples/vitepress/docs/miscellaneous/SampleException.md

@@ -9,7 +9,7 @@ This is a sample exception.
 **Usage** 
 
 You can use the exception the following way. 
-You can also take a look at [SampleClass](../samplegroup/SampleClass.md) to see how it is used. 
+You can also take a look at [SampleClass](../samplegroup/SampleClass) to see how it is used. 
 This is a dangerous HTML tag: <script>alert('Hello');</script> 
  
 ```apex

package/examples/vitepress/docs/miscellaneous/SampleInterface.md

@@ -19,9 +19,9 @@ C -->|extends| D[GreatGrandParentInterface]
 
 **Date** 2020-01-01
 
-**See** [SampleEnum](../sample-enums/SampleEnum.md)
+**See** [SampleEnum](../sample-enums/SampleEnum)
 
-**See** [ReferencedEnum](ReferencedEnum.md)
+**See** [ReferencedEnum](ReferencedEnum)
 
 ## Namespace
 apexdocs
@@ -31,7 +31,7 @@ SampleInterface sampleInterface = new SampleInterface();
 sampleInterface.sampleMethod();
 
 **Extends**
-[ParentInterface](ParentInterface.md)
+[ParentInterface](ParentInterface)
 
 ## Methods
 ### `sampleMethod()`
@@ -66,7 +66,7 @@ public String sampleMethod()
 Some return value
 
 #### Throws
-[SampleException](SampleException.md): This is a sample exception
+[SampleException](SampleException): This is a sample exception
 
 AnotherSampleException: This is another sample exception
 
@@ -94,10 +94,10 @@ public SampleEnum sampleMethodWithParams(String param1, Integer param2, SampleEn
 |------|------|-------------|
 | param1 | String | This is the first parameter |
 | param2 | Integer | This is the second parameter |
-| theEnum | [SampleEnum](../sample-enums/SampleEnum.md) | This is an enum parameter |
+| theEnum | [SampleEnum](../sample-enums/SampleEnum) | This is an enum parameter |
 
 #### Return Type
-**[SampleEnum](../sample-enums/SampleEnum.md)**
+**[SampleEnum](../sample-enums/SampleEnum)**
 
 Some return value
 

package/examples/vitepress/docs/miscellaneous/Url.md

@@ -120,7 +120,7 @@ global Url(Url context, String spec)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| context | [Url](Url.md) | The context in which to parse the specification. |
+| context | [Url](Url) | The context in which to parse the specification. |
 | spec | String | The string to parse as a URL. |
 
 ---
@@ -191,7 +191,7 @@ global static Url getCurrentRequestUrl()
 ```
 
 #### Return Type
-**[Url](Url.md)**
+**[Url](Url)**
 
 The URL of the entire request.
 
@@ -299,7 +299,7 @@ global static Url getOrgDomainUrl()
 ```
 
 #### Return Type
-**[Url](Url.md)**
+**[Url](Url)**
 
 getOrgDomainUrl() always returns the login URL for your org, regardless of context. Use that URL when making API calls to your org.
 

package/examples/vitepress/docs/sample-enums/SampleEnum.md

@@ -6,13 +6,13 @@ title: SampleEnum
 
 `NAMESPACEACCESSIBLE`
 
-This is a sample enum. This references [ReferencedEnum](../miscellaneous/ReferencedEnum.md) . 
+This is a sample enum. This references [ReferencedEnum](../miscellaneous/ReferencedEnum) . 
  
 This description has several lines
 
 **Some Custom** 
 
-Test. I can also have a [ReferencedEnum](../miscellaneous/ReferencedEnum.md) here. 
+Test. I can also have a [ReferencedEnum](../miscellaneous/ReferencedEnum) here. 
 And it can be multiline.
 
 **Mermaid** 
@@ -27,7 +27,7 @@ B -->|referenced by| A
 
 **Date** 2022-01-01
 
-**See** [ReferencedEnum](../miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](../miscellaneous/ReferencedEnum)
 
 ## Namespace
 apexdocs

package/examples/vitepress/docs/samplegroup/SampleClass.md

@@ -6,7 +6,7 @@ title: SampleClass
 `virtual`
 
 aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
-deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+**deserunt** ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
 
 **Group** SampleGroup
 
@@ -19,12 +19,12 @@ sample.doSomething();
 
 **Inheritance**
 
-[BaseClass](../miscellaneous/BaseClass.md)
+[BaseClass](../miscellaneous/BaseClass)
 
 **Implements**
 
-[SampleInterface](../miscellaneous/SampleInterface.md), 
-[ParentInterface](../miscellaneous/ParentInterface.md)
+[SampleInterface](../miscellaneous/SampleInterface), 
+[ParentInterface](../miscellaneous/ParentInterface)
 
 ## Fields
 ### Group Name
@@ -51,7 +51,7 @@ public sampleEnumFromBase
 ```
 
 ##### Type
-[SampleEnum](../sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum)
 
 ## Properties
 ### Group Name

package/examples/vitepress/force-app/main/default/classes/feature-a/SampleClass.cls

@@ -0,0 +1,73 @@
+/**
+ * @description aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex
+ *              **deserunt** ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+ * @group SampleGroup
+ * @example
+ * SampleClass sample = new SampleClass();
+ * sample.doSomething();
+ * @internal This should not appear in the docs
+ */
+public with sharing virtual class SampleClass extends BaseClass implements SampleInterface, ParentInterface {
+    // @start-group Group Name
+    /**
+     * @description This is a sample field.
+     */
+    private final String name;
+    public String someProperty { get; private set; }
+    // @end-group
+
+    /**
+     * @description This is a sample constructor.
+     */
+    public SampleClass() {}
+
+    // @start-group Other Constructors
+    public SampleClass(String name) {
+        this.name = name;
+    }
+    // @end-group
+
+    // @start-group Available Methods
+    public void doSomething() {
+        System.debug('Doing something');
+    }
+    // @end-group
+
+    // @start-group Deprecated Methods
+
+    /**
+     * @description This is a sample method.
+     * @return A string value.
+     * @example
+     * SampleClass sample = new SampleClass();
+     * sample.doSomething();
+     */
+    @Deprecated
+    public virtual String sayHello() {
+        return 'Hello';
+    }
+
+    // @end-group
+
+    public class SomeInnerClass {
+        public String someInnerField;
+
+        public void doSomething() {
+            System.debug('Doing something');
+        }
+    }
+
+    /**
+     * @description This enum is used for foo and bar.
+     */
+    public enum SomeEnum {
+        /** @description This is a test. */
+        TEST_1,
+        TEST_2,
+        TEST_3
+    }
+
+    public interface SomeInterface {
+        void doSomething();
+    }
+}

package/examples/vitepress/force-app/main/default/classes/feature-a/SampleEnum.cls

@@ -0,0 +1,30 @@
+/**
+ * @description This is a sample enum. This references {@link ReferencedEnum}.
+ *
+ * This description has several lines
+ * @group Sample Enums
+ * @author John Doe
+ * @date 2022-01-01
+ * @some-custom Test. I can also have a {@link ReferencedEnum} here.
+ *                    And it can be multiline.
+ * @see ReferencedEnum
+ * @mermaid
+ * graph TD
+ *  A[SampleEnum] -->|references| B[ReferencedEnum]
+ *  B -->|referenced by| A
+ */
+@NamespaceAccessible
+public enum SampleEnum {
+    /**
+     * @description This is value 1
+     */
+    VALUE1,
+    /**
+     * @description This is value 2
+     */
+    VALUE2,
+    /**
+     * @description This is value 3
+     */
+    VALUE3
+}

package/examples/vitepress/force-app/main/default/classes/feature-a/SampleException.cls

@@ -0,0 +1,17 @@
+/**
+ * @description This is a sample exception.
+ * @usage
+ *
+ * You can use the exception the following way.
+ * You can also take a look at {@link SampleClass} to see how it is used.
+ * This is a dangerous HTML tag: <script>alert('Hello');</script>
+ *
+ * ```
+ * try {
+ *    throw new SampleException();
+ * } catch (SampleException e) {
+ *   System.debug('Caught exception');
+ * }
+ * ```
+ */
+public class SampleException extends Exception {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -17,6 +17,7 @@
   },
   "scripts": {
     "test": "npm run build && jest",
+    "test:cov": "npm run build && jest --coverage",
     "build": "rimraf ./lib && npm run lint && tsc --noEmit && pkgroll",
     "lint": "eslint \"./src/**/*.{js,ts}\" --quiet --fix",
     "prepare": "npm run build",
@@ -58,7 +59,7 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.12.1",
+    "@cparra/apex-reflection": "2.13.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",
     "chalk": "^4.1.2",
@@ -68,7 +69,6 @@
     "fp-ts": "^2.16.8",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
-    "type-fest": "^4.23.0",
     "yargs": "^17.7.2"
   },
   "imports": {

package/src/application/Apexdocs.ts

@@ -7,6 +7,7 @@ import { Logger } from '#utils/logger';
 import { UnparsedSourceFile, UserDefinedConfig, UserDefinedMarkdownConfig } from '../core/shared/types';
 import { pipe } from 'fp-ts/function';
 import * as TE from 'fp-ts/TaskEither';
+import * as E from 'fp-ts/Either';
 import { ReflectionError } from '../core/markdown/reflection/reflect-source';
 
 /**
@@ -16,8 +17,8 @@ export class Apexdocs {
   /**
    * Generates documentation out of Apex source files.
    */
-  static async generate(config: UserDefinedConfig): Promise<void> {
-    Logger.logSingle(`Generating ${config.targetGenerator} documentation...`);
+  static async generate(config: UserDefinedConfig, logger: Logger): Promise<E.Either<unknown[], string>> {
+    logger.logSingle(`Generating ${config.targetGenerator} documentation...`);
 
     try {
       const fileBodies = await ApexFileReader.processFiles(
@@ -28,41 +29,37 @@ export class Apexdocs {
 
       switch (config.targetGenerator) {
         case 'markdown':
-          await generateMarkdownDocumentation(fileBodies, config)();
-          break;
+          return await generateMarkdownDocumentation(fileBodies, config)();
         case 'openapi':
-          await openApi(fileBodies, config);
-          break;
+          await openApi(logger, fileBodies, config);
+          return E.right('✔️ Documentation generated successfully!');
       }
     } catch (error) {
-      Logger.logSingle(`❌ An error occurred while generating the documentation: ${error}`, 'red');
+      return E.left([error]);
     }
   }
 }
 
-function generateMarkdownDocumentation(fileBodies: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
+function generateMarkdownDocumentation(
+  fileBodies: UnparsedSourceFile[],
+  config: UserDefinedMarkdownConfig,
+): TE.TaskEither<unknown[], string> {
   return pipe(
     markdown(fileBodies, config),
-    TE.map(() => Logger.logSingle('✔️ Documentation generated successfully!')),
+    TE.map(() => '✔️ Documentation generated successfully!'),
     TE.mapLeft((error) => {
       if (error._tag === 'HookError') {
-        Logger.error('Error(s) occurred while processing hooks. Please review the following issues:');
-        Logger.error(error.error);
-        return;
+        return ['Error(s) occurred while processing hooks. Please review the following issues:', error.error];
       }
 
       if (error._tag === 'FileWritingError') {
-        Logger.error(error.message);
-        Logger.error(error.error);
-        return;
+        return ['Error(s) occurred while writing files. Please review the following issues:', error.error];
       }
 
-      const errorMessages = [
+      return [
         'Error(s) occurred while parsing files. Please review the following issues:',
         ...error.errors.map(formatReflectionError),
-      ].join('\n');
-
-      Logger.error(errorMessages);
+      ];
     }),
   );
 }

package/src/application/__tests__/apex-file-reader.spec.ts

@@ -1,87 +1,128 @@
 import { ApexFileReader } from '../apex-file-reader';
+import { FileSystem } from '../file-system';
+
+type File = {
+  type: 'file';
+  path: string;
+  content: string;
+};
+
+type Directory = {
+  type: 'directory';
+  path: string;
+  files: (File | Directory)[];
+};
+
+type Path = File | Directory;
+
+class TestFileSystem implements FileSystem {
+  constructor(private readonly paths: Path[]) {}
+
+  async isDirectory(path: string): Promise<boolean> {
+    const directory = this.findPath(path);
+    return directory ? directory.type === 'directory' : false;
+  }
+
+  joinPath(...paths: string[]): string {
+    return paths.join('/');
+  }
+
+  async readDirectory(sourceDirectory: string): Promise<string[]> {
+    const directory = this.findPath(sourceDirectory);
+    if (!directory || directory.type !== 'directory') {
+      throw new Error('Directory not found');
+    }
+    return directory.files.map((f) => f.path);
+  }
+
+  async readFile(path: string): Promise<string> {
+    const file = this.findPath(path);
+    if (!file || file.type !== 'file') {
+      throw new Error('File not found');
+    }
+    return file.content;
+  }
+
+  exists(path: string): boolean {
+    return this.paths.some((p) => p.path === path);
+  }
+
+  findPath(path: string): Path | undefined {
+    const splitPath = path.split('/');
+    let currentPath = this.paths.find((p) => p.path === splitPath[0]);
+    for (let i = 1; i < splitPath.length; i++) {
+      if (!currentPath || currentPath.type !== 'directory') {
+        return undefined;
+      }
+      currentPath = currentPath.files.find((f) => f.path === splitPath[i]);
+    }
+    return currentPath;
+  }
+}
 
 describe('File Reader', () => {
   it('returns an empty list when there are no files in the directory', async () => {
-    const result = await ApexFileReader.processFiles(
+    const fileSystem = new TestFileSystem([
       {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        isDirectory(_: string): Promise<boolean> {
-          return Promise.resolve(false);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        joinPath(_: string): string {
-          return '';
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readDirectory(_: string): Promise<string[]> {
-          return Promise.resolve([]);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readFile(_: string): Promise<string> {
-          return Promise.resolve('');
-        },
-        exists(): boolean {
-          return true;
-        },
+        type: 'directory',
+        path: '',
+        files: [],
       },
-      '',
-      false,
-    );
+    ]);
+
+    const result = await ApexFileReader.processFiles(fileSystem, '', false);
+
     expect(result.length).toBe(0);
   });
 
   it('returns an empty list when there are no Apex files in the directory', async () => {
-    const result = await ApexFileReader.processFiles(
+    const fileSystem = new TestFileSystem([
       {
-        isDirectory(): Promise<boolean> {
-          return Promise.resolve(false);
-        },
-        joinPath(): string {
-          return '';
-        },
-        readDirectory(): Promise<string[]> {
-          return Promise.resolve(['SomeFile.md']);
-        },
-        readFile(): Promise<string> {
-          return Promise.resolve('');
-        },
-        exists(): boolean {
-          return true;
-        },
+        type: 'directory',
+        path: '',
+        files: [
+          {
+            type: 'file',
+            path: 'SomeFile.md',
+            content: '## Some Markdown',
+          },
+        ],
       },
-      '',
-      false,
-    );
+    ]);
+
+    const result = await ApexFileReader.processFiles(fileSystem, '', false);
     expect(result.length).toBe(0);
   });
 
-  it('returns the file contents for an Apex file', async () => {
-    const result = await ApexFileReader.processFiles(
+  it('returns the file contents for all Apex files', async () => {
+    const fileSystem = new TestFileSystem([
       {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        isDirectory(_: string): Promise<boolean> {
-          return Promise.resolve(false);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        joinPath(_: string): string {
-          return 'SomeApexFile.cls';
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readDirectory(_: string): Promise<string[]> {
-          return Promise.resolve(['SomeApexFile.cls']);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readFile(_: string): Promise<string> {
-          return Promise.resolve('public class MyClass{}');
-        },
-        exists(): boolean {
-          return true;
-        },
+        type: 'directory',
+        path: '',
+        files: [
+          {
+            type: 'file',
+            path: 'SomeFile.cls',
+            content: 'public class MyClass{}',
+          },
+          {
+            type: 'directory',
+            path: 'subdir',
+            files: [
+              {
+                type: 'file',
+                path: 'AnotherFile.cls',
+                content: 'public class AnotherClass{}',
+              },
+            ],
+          },
+        ],
       },
-      '',
-      false,
-    );
-    expect(result.length).toBe(1);
+    ]);
+
+    const result = await ApexFileReader.processFiles(fileSystem, '', false);
+    expect(result.length).toBe(2);
     expect(result[0].content).toBe('public class MyClass{}');
+    expect(result[1].content).toBe('public class AnotherClass{}');
   });
 });

package/src/application/apex-file-reader.ts

@@ -28,6 +28,7 @@ export class ApexFileReader {
       const currentPath = fileSystem.joinPath(rootPath, filePath);
       if (await fileSystem.isDirectory(currentPath)) {
         paths.push(...(await this.getFilePaths(fileSystem, currentPath)));
+        return paths;
       }
       paths.push(currentPath);
     }

package/src/application/generators/openapi.ts

@@ -12,8 +12,13 @@ import { writeFiles } from '../file-writer';
 import { pipe } from 'fp-ts/function';
 import * as TE from 'fp-ts/TaskEither';
 import { OpenApiSettings } from '../../core/openApiSettings';
+import { apply } from '#utils/fp';
 
-export default async function openApi(fileBodies: UnparsedSourceFile[], config: UserDefinedOpenApiConfig) {
+export default async function openApi(
+  logger: Logger,
+  fileBodies: UnparsedSourceFile[],
+  config: UserDefinedOpenApiConfig,
+) {
   OpenApiSettings.build({
     sourceDirectory: config.sourceDir,
     outputDir: config.targetDir,
@@ -23,34 +28,33 @@ export default async function openApi(fileBodies: UnparsedSourceFile[], config:
     version: config.apiVersion,
   });
 
-  const manifest = createManifest(new RawBodyParser(fileBodies), reflectionWithLogger);
+  const manifest = createManifest(new RawBodyParser(logger, fileBodies), apply(reflectionWithLogger, logger));
   TypesRepository.getInstance().populateAll(manifest.types);
-  const filteredTypes = filterByScopes(manifest);
-  const processor = new OpenApiDocsProcessor();
+  const filteredTypes = filterByScopes(logger, manifest);
+  const processor = new OpenApiDocsProcessor(logger);
   Transpiler.generate(filteredTypes, processor);
   const generatedFiles = processor.fileBuilder().files();
 
   await pipe(
     writeFiles(generatedFiles, config.targetDir, (file: PageData) => {
-      Logger.logSingle(`${file.outputDocPath} processed.`, 'green');
+      logger.logSingle(`${file.outputDocPath} processed.`, 'green');
     }),
-    TE.map(() => Logger.logSingle('✔️ Documentation generated successfully!')),
-    TE.mapError((error) => Logger.error(error)),
+    TE.mapError((error) => logger.error(error)),
   )();
 
   // Logs any errors that the types might have in their doc comment's error field
-  ErrorLogger.logErrors(filteredTypes);
+  ErrorLogger.logErrors(logger, filteredTypes);
 }
 
-function reflectionWithLogger(apexBundle: UnparsedSourceFile): ReflectionResult {
+function reflectionWithLogger(logger: Logger, apexBundle: UnparsedSourceFile): ReflectionResult {
   const result = reflect(apexBundle.content);
   if (result.error) {
-    Logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
+    logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
   }
   return result;
 }
 
-function filterByScopes(manifest: Manifest) {
+function filterByScopes(logger: Logger, manifest: Manifest) {
   // If we are dealing with an OpenApi generator, we ignore the passed in access modifiers, and instead
   // we only keep classes annotated as @RestResource
   const filteredTypes = manifest.filteredByAccessModifierAndAnnotations([
@@ -65,7 +69,7 @@ function filterByScopes(manifest: Manifest) {
     manifest.types.length - filteredTypes.length
   } file(s), only keeping classes annotated as @RestResource.`;
 
-  Logger.logSingle(filteredLogMessage, 'green');
-  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, 'green');
+  logger.logSingle(filteredLogMessage, 'green');
+  logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, 'green');
   return filteredTypes;
 }