@cparra/apexdocs 3.0.0-rc.0 → 3.0.0

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

@@ -5,6 +5,7 @@
  * @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

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-rc.0",
+  "version": "3.0.0",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -59,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",

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;
 }

package/src/cli/args.ts

@@ -1,10 +1,14 @@
 import { cosmiconfig, CosmiconfigResult } from 'cosmiconfig';
 import * as yargs from 'yargs';
-import { UserDefinedMarkdownConfig } from '../core/shared/types';
+import { UserDefinedConfig, UserDefinedMarkdownConfig } from '../core/shared/types';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
 import { markdownOptions } from './commands/markdown';
 import { openApiOptions } from './commands/openapi';
 
+const configOnlyDefaults: Partial<UserDefinedMarkdownConfig> = {
+  excludeTags: [],
+};
+
 /**
  * Extracts configuration from a configuration file or the package.json
  * through cosmiconfig.
@@ -37,10 +41,15 @@ function _extractYargs(config?: CosmiconfigResult) {
 /**
  * Combines the extracted configuration and arguments.
  */
-export async function extractArgs(): Promise<UserDefinedMarkdownConfig> {
+export async function extractArgs(): Promise<UserDefinedConfig> {
   const config = await _extractConfig();
   const cliArgs = _extractYargs(config);
   const commandName = cliArgs._[0];
 
-  return { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
+  const mergedConfig = { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
+  if (mergedConfig.targetGenerator === 'markdown') {
+    return { ...configOnlyDefaults, ...mergedConfig };
+  } else {
+    return mergedConfig;
+  }
 }

package/src/cli/commands/markdown.ts

@@ -1,5 +1,5 @@
 import { Options } from 'yargs';
-import { defaults } from '../../defaults';
+import { markdownDefaults } from '../../defaults';
 
 export const markdownOptions: { [key: string]: Options } = {
   sourceDir: {
@@ -11,41 +11,46 @@ export const markdownOptions: { [key: string]: Options } = {
   targetDir: {
     type: 'string',
     alias: 't',
-    default: defaults.targetDir,
+    default: markdownDefaults.targetDir,
     describe: 'The directory location where documentation will be generated to.',
   },
   scope: {
     type: 'string',
     array: true,
     alias: 'p',
-    default: defaults.scope,
+    default: markdownDefaults.scope,
     describe:
       'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
       'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled.',
   },
   defaultGroupName: {
     type: 'string',
-    default: defaults.defaultGroupName,
+    default: markdownDefaults.defaultGroupName,
     describe: 'Defines the @group name to be used when a file does not specify it.',
   },
   namespace: {
     type: 'string',
     describe: 'The package namespace, if any. If provided, it will be added to the generated files.',
   },
-  sortMembersAlphabetically: {
+  sortAlphabetically: {
     type: 'boolean',
-    describe: 'Whether to sort members alphabetically.',
-    default: defaults.sortMembersAlphabetically,
+    describe: 'Whether to sort files and members alphabetically.',
+    default: markdownDefaults.sortAlphabetically,
   },
   includeMetadata: {
     type: 'boolean',
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
-    default: defaults.includeMetadata,
+    default: markdownDefaults.includeMetadata,
   },
   linkingStrategy: {
     type: 'string',
     describe: 'The strategy to use when linking to other documentation pages.',
     choices: ['relative', 'no-link', 'none'],
-    default: defaults.linkingStrategy,
+    default: markdownDefaults.linkingStrategy,
+  },
+  referenceGuideTitle: {
+    type: 'string',
+    describe: 'The title of the reference guide.',
+    default: markdownDefaults.referenceGuideTitle,
   },
 };

package/src/cli/commands/openapi.ts

@@ -1,5 +1,5 @@
 import { Options } from 'yargs';
-import { defaults } from '../../defaults';
+import { markdownDefaults, openApiDefaults } from '../../defaults';
 
 export const openApiOptions: { [key: string]: Options } = {
   sourceDir: {
@@ -11,12 +11,12 @@ export const openApiOptions: { [key: string]: Options } = {
   targetDir: {
     type: 'string',
     alias: 't',
-    default: defaults.targetDir,
+    default: markdownDefaults.targetDir,
     describe: 'The directory location where the OpenApi file will be generated.',
   },
   fileName: {
     type: 'string',
-    default: 'openapi',
+    default: openApiDefaults.fileName,
     describe: 'The name of the OpenApi file to be generated.',
   },
   namespace: {
@@ -25,12 +25,12 @@ export const openApiOptions: { [key: string]: Options } = {
   },
   title: {
     type: 'string',
-    default: 'Apex REST API',
+    default: openApiDefaults.title,
     describe: 'The title of the OpenApi file.',
   },
   apiVersion: {
     type: 'string',
-    default: '1.0.0',
+    default: openApiDefaults.apiVersion,
     describe: 'The version of the OpenApi file.',
   },
 };

package/src/cli/generate.ts

@@ -1,16 +1,32 @@
 #!/usr/bin/env node
 import { Apexdocs } from '../application/Apexdocs';
 import { extractArgs } from './args';
+import { StdOutLogger } from '#utils/logger';
+import * as E from 'fp-ts/Either';
+
+const logger = new StdOutLogger();
 
 function main() {
-  function catchError(error: Error) {
-    console.error(error);
+  function parseResult(result: E.Either<unknown, string>) {
+    E.match(
+      (error) => {
+        logger.error(`❌ An error occurred while generating the documentation: ${error}`);
+        process.exit(1);
+      },
+      (successMessage: string) => {
+        logger.logSingle(successMessage);
+      },
+    )(result);
+  }
+
+  function catchUnexpectedError(error: Error) {
+    logger.error(`❌ An unexpected error occurred: ${error.message}`);
     process.exit(1);
   }
 
   extractArgs()
-    .then((config) => Apexdocs.generate(config).catch(catchError))
-    .catch(catchError);
+    .then((config) => Apexdocs.generate(config, logger).then(parseResult))
+    .catch(catchUnexpectedError);
 }
 
 main();