@cparra/apexdocs 3.0.0-alpha.1 → 3.0.0-alpha.10

package/dist/{defaults-jLXD2y8-.js → defaults-DGKfeZq-.js}

@@ -7,7 +7,7 @@ const defaults = {
   defaultGroupName: "Miscellaneous",
   includeMetadata: false,
   sortMembersAlphabetically: false,
-  documentationRootDir: ""
+  linkingStrategy: "relative"
 };
 
 exports.defaults = defaults;

package/dist/index.d.ts

@@ -10,6 +10,17 @@ type ConfigurableHooks = {
   transformReference: TransformReference;
 };
 
+type LinkingStrategy =
+  // Links will be generated using relative paths.
+  | 'relative'
+  // No links will be generated.
+  // If the reference is found, the display name will be used.
+  // Otherwise, the name
+  // of the reference itself will be used.
+  | 'no-link'
+  // No logic will be applied, the reference path will be used as is.
+  | 'none';
+
 type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   sourceDir: string;
@@ -19,7 +30,7 @@ type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
-  documentationRootDir: string;
+  linkingStrategy: LinkingStrategy;
 } & Partial<ConfigurableHooks>;
 
 type SourceFileMetadata = {
@@ -33,8 +44,13 @@ type DocPageReference = {
   // The name under which the type should be displayed in the documentation.
   // By default, this will match the source.name, but it can be configured by the user.
   displayName: string;
-  // The location of the file relative to the root of the documentation.
-  pathFromRoot: string;
+  // The location where the file will be written.
+  outputDocPath: string;
+  // The path to the file relative to the documentation root directory. This is used when linking to the file.
+  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
+  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
+  // the path where the file is written.
+  referencePath: string;
 };
 
 type Frontmatter = string | Record<string, unknown> | null;
@@ -42,13 +58,13 @@ type Frontmatter = string | Record<string, unknown> | null;
 type ReferenceGuidePageData = {
   frontmatter: Frontmatter;
   content: string;
-  filePath: string;
+  outputDocPath: string;
 };
 
 type DocPageData = {
   source: SourceFileMetadata;
   group: string | null;
-  filePath: string;
+  outputDocPath: string;
   frontmatter: Frontmatter;
   content: string;
 };
@@ -64,7 +80,7 @@ type Skip = {
 
 type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
 
-type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'filePath'>;
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
 
 /**
  * Allows changing where the files are written to.
@@ -94,7 +110,7 @@ type TransformDocPage = (
   doc: DocPageData,
 ) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
 
-type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'documentationRootDir'>, 'targetGenerator'>;
+type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'>, 'targetGenerator'>;
 declare function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig;
 declare function skip(): Skip;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var defaults = require('./defaults-jLXD2y8-.js');
+var defaults = require('./defaults-DGKfeZq-.js');
 
 var __defProp = Object.defineProperty;
 var __defProps = Object.defineProperties;

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

@@ -5,7 +5,7 @@ ns
 
 **Inheritance**
 
-[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](../miscellaneous/BaseClass.md)
+[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
 
 ## Fields
 ### `sampleEnumFromBase`

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

@@ -6,10 +6,12 @@ This is a sample interface
 
 **Mermaid** 
 
-graph TD 
-A[SampleInterface] -->|extends| B[ParentInterface] 
-B -->|extends| C[GrandParentInterface] 
-C -->|extends| D[GreatGrandParentInterface]
+```mermaid
+graph TD
+   A[SampleInterface] -->|extends| B[ParentInterface]
+   B -->|extends| C[GrandParentInterface]
+   C -->|extends| D[GreatGrandParentInterface]
+```
 
 **Author** John Doe
 
@@ -17,17 +19,19 @@ C -->|extends| D[GreatGrandParentInterface]
 
 **See** [SampleEnum](../sample-enums/SampleEnum.md)
 
-**See** [ReferencedEnum](../miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](ReferencedEnum.md)
 
 ## Namespace
 ns
 
 ## Example
-SampleInterface sampleInterface = new SampleInterface(); 
+```apex
+SampleInterface sampleInterface = new SampleInterface();
 sampleInterface.sampleMethod();
+```
 
 **Extends**
-[ParentInterface](../miscellaneous/ParentInterface.md)
+[ParentInterface](ParentInterface.md)
 
 ## Methods
 ### `sampleMethod()`
@@ -62,7 +66,7 @@ public String sampleMethod()
 Some return value
 
 #### Throws
-[SampleException](../miscellaneous/SampleException.md): This is a sample exception
+[SampleException](SampleException.md): This is a sample exception
 
 AnotherSampleException: This is another sample exception
 

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

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

package/examples/markdown/force-app/classes/SampleInterface.cls

@@ -5,13 +5,17 @@
  * @see SampleEnum
  * @see ReferencedEnum
  * @mermaid
+ * ```mermaid
  * graph TD
  *    A[SampleInterface] -->|extends| B[ParentInterface]
  *    B -->|extends| C[GrandParentInterface]
  *    C -->|extends| D[GreatGrandParentInterface]
+ * ```
  * @example
+ * ```apex
  * SampleInterface sampleInterface = new SampleInterface();
  * sampleInterface.sampleMethod();
+ * ```
  */
 @NamespaceAccessible
 public interface SampleInterface extends ParentInterface {

package/examples/vitepress/apexdocs.config.ts

@@ -86,7 +86,7 @@ export default defineMarkdownConfig({
 function toSidebarLink(doc: DocPageData) {
   return {
     text: doc.source.name,
-    link: doc.filePath,
+    link: doc.outputDocPath,
   };
 }
 

package/examples/vitepress/docs/index.md

@@ -19,38 +19,38 @@ hero:
 
 ## Miscellaneous
 
-### [BaseClass](/miscellaneous/BaseClass.md)
+### [BaseClass](miscellaneous/BaseClass.md)
 
-### [MultiInheritanceClass](/miscellaneous/MultiInheritanceClass.md)
+### [MultiInheritanceClass](miscellaneous/MultiInheritanceClass.md)
 
-### [ParentInterface](/miscellaneous/ParentInterface.md)
+### [ParentInterface](miscellaneous/ParentInterface.md)
 
-### [ReferencedEnum](/miscellaneous/ReferencedEnum.md)
+### [ReferencedEnum](miscellaneous/ReferencedEnum.md)
 
-### [SampleException](/miscellaneous/SampleException.md)
+### [SampleException](miscellaneous/SampleException.md)
 
 This is a sample exception.
 
-### [SampleInterface](/miscellaneous/SampleInterface.md)
+### [SampleInterface](miscellaneous/SampleInterface.md)
 
 This is a sample interface
 
-### [Url](/miscellaneous/Url.md)
+### [Url](miscellaneous/Url.md)
 
 Represents a uniform resource locator (URL) and provides access to parts of the URL. 
 Enables access to the base URL used to access your Salesforce org.
 
 ## Sample Enums
 
-### [SampleEnum](/sample-enums/SampleEnum.md)
+### [SampleEnum](sample-enums/SampleEnum.md)
 
-This is a sample enum. This references [ReferencedEnum](/miscellaneous/ReferencedEnum.md) . 
+This is a sample enum. This references [ReferencedEnum](miscellaneous/ReferencedEnum.md) . 
  
 This description has several lines
 
 ## SampleGroup
 
-### [SampleClass](/samplegroup/SampleClass.md)
+### [SampleClass](samplegroup/SampleClass.md)
 
 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.

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

@@ -17,4 +17,4 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](/sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum.md)

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

@@ -9,7 +9,7 @@ apexdocs
 
 **Inheritance**
 
-[SampleClass](/samplegroup/SampleClass.md) < [BaseClass](/miscellaneous/BaseClass.md)
+[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
 
 ## Fields
 ### `sampleEnumFromBase`
@@ -22,7 +22,7 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](/sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum.md)
 
 ## 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.md) 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.md)
 
-**See** [ReferencedEnum](/miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](ReferencedEnum.md)
 
 ## Namespace
 apexdocs
@@ -31,7 +31,7 @@ SampleInterface sampleInterface = new SampleInterface();
 sampleInterface.sampleMethod();
 
 **Extends**
-[ParentInterface](/miscellaneous/ParentInterface.md)
+[ParentInterface](ParentInterface.md)
 
 ## Methods
 ### `sampleMethod()`
@@ -66,7 +66,7 @@ public String sampleMethod()
 Some return value
 
 #### Throws
-[SampleException](/miscellaneous/SampleException.md): This is a sample exception
+[SampleException](SampleException.md): 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.md) | This is an enum parameter |
 
 #### Return Type
-**[SampleEnum](/sample-enums/SampleEnum.md)**
+**[SampleEnum](../sample-enums/SampleEnum.md)**
 
 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](/miscellaneous/Url.md) | The context in which to parse the specification. |
+| context | [Url](Url.md) | 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](/miscellaneous/Url.md)**
+**[Url](Url.md)**
 
 The URL of the entire request.
 
@@ -299,7 +299,7 @@ global static Url getOrgDomainUrl()
 ```
 
 #### Return Type
-**[Url](/miscellaneous/Url.md)**
+**[Url](Url.md)**
 
 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.md) . 
  
 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.md) 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.md)
 
 ## Namespace
 apexdocs

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

@@ -19,12 +19,12 @@ sample.doSomething();
 
 **Inheritance**
 
-[BaseClass](/miscellaneous/BaseClass.md)
+[BaseClass](../miscellaneous/BaseClass.md)
 
 **Implements**
 
-[SampleInterface](/miscellaneous/SampleInterface.md), 
-[ParentInterface](/miscellaneous/ParentInterface.md)
+[SampleInterface](../miscellaneous/SampleInterface.md), 
+[ParentInterface](../miscellaneous/ParentInterface.md)
 
 ## Fields
 ### Group Name
@@ -51,7 +51,7 @@ public sampleEnumFromBase
 ```
 
 ##### Type
-[SampleEnum](/sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum.md)
 
 ## Properties
 ### Group Name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.10",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -58,7 +58,7 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.11.3",
+    "@cparra/apex-reflection": "2.12.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",
     "chalk": "^4.1.2",
@@ -68,7 +68,6 @@
     "fp-ts": "^2.16.8",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
-    "log-update": "4.0.0",
     "type-fest": "^4.23.0",
     "yargs": "^17.7.2"
   },

package/src/application/Apexdocs.ts

@@ -4,7 +4,10 @@ import openApi from './generators/openapi';
 import { ApexFileReader } from './apex-file-reader';
 import { DefaultFileSystem } from './file-system';
 import { Logger } from '#utils/logger';
-import { UserDefinedConfig } from '../core/shared/types';
+import { UnparsedSourceFile, UserDefinedConfig, UserDefinedMarkdownConfig } from '../core/shared/types';
+import { pipe } from 'fp-ts/function';
+import * as TE from 'fp-ts/TaskEither';
+import { ReflectionError } from '../core/markdown/reflection/reflect-source';
 
 /**
  * Application entry-point to generate documentation out of Apex source files.
@@ -14,17 +17,57 @@ export class Apexdocs {
    * Generates documentation out of Apex source files.
    */
   static async generate(config: UserDefinedConfig): Promise<void> {
-    Logger.logSingle('Initializing...', false);
+    Logger.logSingle(`Generating ${config.targetGenerator} documentation...`);
 
-    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
+    try {
+      const fileBodies = await ApexFileReader.processFiles(
+        new DefaultFileSystem(),
+        config.sourceDir,
+        config.includeMetadata,
+      );
 
-    switch (config.targetGenerator) {
-      case 'markdown':
-        await markdown(fileBodies, config);
-        break;
-      case 'openapi':
-        openApi(fileBodies, config);
-        break;
+      switch (config.targetGenerator) {
+        case 'markdown':
+          await generateMarkdownDocumentation(fileBodies, config)();
+          break;
+        case 'openapi':
+          openApi(fileBodies, config);
+          Logger.logSingle('✔️ Documentation generated successfully!');
+          break;
+      }
+    } catch (error) {
+      Logger.logSingle(`❌ An error occurred while generating the documentation: ${error}`, 'red');
     }
   }
 }
+
+function generateMarkdownDocumentation(fileBodies: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
+  return pipe(
+    markdown(fileBodies, config),
+    TE.map(() => Logger.logSingle('✔️ 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;
+      }
+
+      if (error._tag === 'FileWritingError') {
+        Logger.error(error.message);
+        Logger.error(error.error);
+        return;
+      }
+
+      const errorMessages = [
+        'Error(s) occurred while parsing files. Please review the following issues:',
+        ...error.errors.map(formatReflectionError),
+      ].join('\n');
+
+      Logger.error(errorMessages);
+    }),
+  );
+}
+
+function formatReflectionError(error: ReflectionError) {
+  return `Source file: ${error.file}\n${error.message}\n`;
+}

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

@@ -18,24 +18,24 @@ describe('File Reader', () => {
     } as SettingsConfig);
   });
 
-  it('returns an empty list when there are no files in the directory', () => {
-    const result = ApexFileReader.processFiles(
+  it('returns an empty list when there are no files in the directory', async () => {
+    const result = await ApexFileReader.processFiles(
       {
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        isDirectory(_: string): boolean {
-          return false;
+        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): string[] {
-          return [];
+        readDirectory(_: string): Promise<string[]> {
+          return Promise.resolve([]);
         },
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readFile(_: string): string {
-          return '';
+        readFile(_: string): Promise<string> {
+          return Promise.resolve('');
         },
         exists(): boolean {
           return true;
@@ -47,20 +47,20 @@ describe('File Reader', () => {
     expect(result.length).toBe(0);
   });
 
-  it('returns an empty list when there are no Apex files in the directory', () => {
-    const result = ApexFileReader.processFiles(
+  it('returns an empty list when there are no Apex files in the directory', async () => {
+    const result = await ApexFileReader.processFiles(
       {
-        isDirectory(): boolean {
-          return false;
+        isDirectory(): Promise<boolean> {
+          return Promise.resolve(false);
         },
         joinPath(): string {
           return '';
         },
-        readDirectory(): string[] {
-          return ['SomeFile.md'];
+        readDirectory(): Promise<string[]> {
+          return Promise.resolve(['SomeFile.md']);
         },
-        readFile(): string {
-          return '';
+        readFile(): Promise<string> {
+          return Promise.resolve('');
         },
         exists(): boolean {
           return true;
@@ -72,24 +72,24 @@ describe('File Reader', () => {
     expect(result.length).toBe(0);
   });
 
-  it('returns the file contents for an Apex file', () => {
-    const result = ApexFileReader.processFiles(
+  it('returns the file contents for an Apex file', async () => {
+    const result = await ApexFileReader.processFiles(
       {
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        isDirectory(_: string): boolean {
-          return false;
+        isDirectory(_: string): Promise<boolean> {
+          return Promise.resolve(false);
         },
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         joinPath(_: string): string {
-          return '';
+          return 'SomeApexFile.cls';
         },
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readDirectory(_: string): string[] {
-          return ['SomeApexFile.cls'];
+        readDirectory(_: string): Promise<string[]> {
+          return Promise.resolve(['SomeApexFile.cls']);
         },
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readFile(_: string): string {
-          return 'public class MyClass{}';
+        readFile(_: string): Promise<string> {
+          return Promise.resolve('public class MyClass{}');
         },
         exists(): boolean {
           return true;