@cparra/apexdocs 3.0.0-alpha.3 → 3.0.0-alpha.5

package/dist/cli/generate.js

@@ -10,10 +10,10 @@ var apexReflection = require('@cparra/apex-reflection');
 var O = require('fp-ts/Option');
 var fastXmlParser = require('fast-xml-parser');
 var Handlebars = require('handlebars');
-var defaults = require('../defaults-jLXD2y8-.js');
+var defaults = require('../defaults-DGKfeZq-.js');
 var fs = require('fs');
 var chalk = require('chalk');
-var logUpdate = require('log-update');
+var ora = require('ora');
 var cosmiconfig = require('cosmiconfig');
 var yargs = require('yargs');
 var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
@@ -569,8 +569,59 @@ function singleGroup(headingLevel, groupName, adapter, members, linkGenerator) {
   };
 }
 
+const generateLink = (strategy) => {
+  switch (strategy) {
+    case "relative":
+      return generateRelativeLink;
+    case "no-link":
+      return generateNoLink;
+    case "none":
+      return returnReferenceAsIs;
+  }
+};
+const generateRelativeLink = (references, from, referenceName) => {
+  function getRelativePath(fromPath, toPath) {
+    return path.relative(path.parse(path.join("/", fromPath)).dir, path.join("/", toPath));
+  }
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  if (referenceTo && from === "__base__") {
+    return {
+      __type: "link",
+      title: referenceTo.displayName,
+      url: getRelativePath("", referenceTo.referencePath)
+    };
+  }
+  const referenceFrom = references[from];
+  if (!referenceFrom) {
+    return referenceTo.displayName;
+  }
+  return {
+    __type: "link",
+    title: referenceTo.displayName,
+    url: getRelativePath(referenceFrom.referencePath, referenceTo.referencePath)
+  };
+};
+const generateNoLink = (references, _from, referenceName) => {
+  const referenceTo = references[referenceName];
+  return referenceTo ? referenceTo.displayName : referenceName;
+};
+const returnReferenceAsIs = (references, _from, referenceName) => {
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  return {
+    __type: "link",
+    title: referenceTo.displayName,
+    url: referenceTo.referencePath
+  };
+};
+
 function parsedFilesToRenderableBundle(config, parsedFiles, references) {
-  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
+  const referenceFinder = apply(generateLink(config.linkingStrategy), references);
   function toReferenceGuide(parsedFiles2) {
     return parsedFiles2.reduce(
       addToReferenceGuide(apply(referenceFinder, "__base__"), config, references),
@@ -604,28 +655,6 @@ function addToReferenceGuide(findLinkFromHome, config, references) {
     return acc;
   };
 }
-const linkGenerator = (references, documentationRootDir, from, referenceName) => {
-  const referenceTo = references[referenceName];
-  if (referenceTo && from === "__base__") {
-    return {
-      __type: "link",
-      title: referenceTo.displayName,
-      url: path__namespace.join(documentationRootDir, referenceTo.referencePath)
-    };
-  }
-  const referenceFrom = references[from];
-  if (!referenceFrom || !referenceTo) {
-    return referenceName;
-  }
-  const fromPath = path__namespace.parse(path__namespace.join("/", documentationRootDir, referenceFrom.referencePath)).dir;
-  const toPath = path__namespace.join("/", documentationRootDir, referenceTo.referencePath);
-  const relativePath = path__namespace.relative(fromPath, toPath);
-  return {
-    __type: "link",
-    title: referenceTo.displayName,
-    url: relativePath
-  };
-};
 function getTypeGroup$1(type, config) {
   var _a, _b;
   const groupAnnotation = (_a = type.docComment) == null ? void 0 : _a.annotations.find((annotation) => annotation.name.toLowerCase() === "group");
@@ -1689,36 +1718,32 @@ class Logger {
    * @param args Optional arguments.
    */
   static error(message, ...args) {
-    this.logSingle(message, false, "red", false);
+    this.logSingle(message, "red");
     args.forEach(() => {
-      this.logSingle(message, false, "red", false);
+      this.logSingle(message, "red");
     });
   }
-  static logSingle(text, showSpinner = true, color = "green", overrideConsole = true) {
+  static logSingle(text, color = "green") {
     if (this.currentFrame > 9) {
       this.currentFrame = 0;
     }
-    const spinner = showSpinner ? `${this.frames[this.currentFrame++]}` : "";
-    let logMessage;
-    if (color === "green") {
-      logMessage = `${chalk.green((/* @__PURE__ */ new Date()).toLocaleString() + ": ")}${text}
+    const logMessage = `${this.getChalkFn(color)((/* @__PURE__ */ new Date()).toLocaleString() + ": ")}${text}
 `;
-    } else {
-      logMessage = `${chalk.red((/* @__PURE__ */ new Date()).toLocaleString() + ": ")}${text}
-`;
-    }
-    if (overrideConsole) {
-      logUpdate(`${spinner} ${logMessage}`);
-    } else {
-      process.stdout.write(`${spinner} ${logMessage}`);
-    }
+    process.stdout.write(logMessage);
+  }
+  static getChalkFn(color) {
+    return color === "green" ? chalk.green : chalk.red;
   }
-  static clear() {
-    logUpdate.clear();
+  static startSpinner(text) {
+    this.spinner.text = text;
+    this.spinner.start();
+  }
+  static succeedSpinner(text) {
+    this.spinner.succeed(text);
   }
 }
 Logger.currentFrame = 0;
-Logger.frames = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+Logger.spinner = ora();
 
 const referenceGuideTemplate = `
 # Apex Reference Guide
@@ -1781,8 +1806,7 @@ function writeFilesToSystem(files, outputDir) {
   FileWriter.write(
     [files.referenceGuide, ...files.docs].filter((file) => !isSkip(file)),
     outputDir,
-    (file) => {
-      Logger.logSingle(`${file.outputDocPath} processed.`, false, "green", false);
+    () => {
     }
   );
 }
@@ -2692,7 +2716,7 @@ class OpenApiDocsProcessor {
   }
   onProcess(type) {
     var _a, _b;
-    Logger.logSingle(`Processing ${type.name}`, false, "green", false);
+    Logger.logSingle(`Processing ${type.name}`, "green");
     const endpointPath = this.getEndpointPath(type);
     if (!endpointPath) {
       return;
@@ -2740,7 +2764,7 @@ function openApi(fileBodies, config) {
   Transpiler.generate(filteredTypes, processor);
   const generatedFiles = processor.fileBuilder().files();
   FileWriter.write(generatedFiles, config.targetDir, (file) => {
-    Logger.logSingle(`${file.outputDocPath} processed.`, false, "green", false);
+    Logger.logSingle(`${file.outputDocPath} processed.`, "green");
   });
   ErrorLogger.logErrors(filteredTypes);
 }
@@ -2762,9 +2786,8 @@ function filterByScopes(manifest) {
     "httpput"
   ]);
   const filteredLogMessage = `Filtered ${manifest.types.length - filteredTypes.length} file(s), only keeping classes annotated as @RestResource.`;
-  Logger.clear();
-  Logger.logSingle(filteredLogMessage, false, "green", false);
-  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, false, "green", false);
+  Logger.logSingle(filteredLogMessage, "green");
+  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, "green");
   return filteredTypes;
 }
 
@@ -2844,15 +2867,20 @@ class Apexdocs {
    */
   static generate(config) {
     return __async$1(this, null, function* () {
-      Logger.logSingle("Initializing...", false);
-      const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
-      switch (config.targetGenerator) {
-        case "markdown":
-          yield generate(fileBodies, config);
-          break;
-        case "openapi":
-          openApi(fileBodies, config);
-          break;
+      Logger.logSingle("Initializing...");
+      Logger.startSpinner("Processing files...");
+      try {
+        const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
+        switch (config.targetGenerator) {
+          case "markdown":
+            yield generate(fileBodies, config);
+            break;
+          case "openapi":
+            openApi(fileBodies, config);
+            break;
+        }
+      } finally {
+        Logger.succeedSpinner("Files processed.");
       }
     });
   }
@@ -2897,10 +2925,11 @@ const markdownOptions = {
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.defaults.includeMetadata
   },
-  documentationRootDir: {
+  linkingStrategy: {
     type: "string",
-    describe: "The root directory of the documentation. This is used to create the correct relative paths when generating links between documents.",
-    default: defaults.defaults.documentationRootDir
+    describe: "The strategy to use when linking to other documentation pages.",
+    choices: ["relative", "no-link", "none"],
+    default: defaults.defaults.linkingStrategy
   }
 };
 

package/dist/defaults-DGKfeZq-.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const defaults = {
+  targetGenerator: "markdown",
+  targetDir: "./docs/",
+  scope: ["global"],
+  defaultGroupName: "Miscellaneous",
+  includeMetadata: false,
+  sortMembersAlphabetically: false,
+  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 = {
@@ -99,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/docs/miscellaneous/BaseClass.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.5",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -68,7 +68,7 @@
     "fp-ts": "^2.16.8",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
-    "log-update": "4.0.0",
+    "ora": "^5.4.1",
     "type-fest": "^4.23.0",
     "yargs": "^17.7.2"
   },

package/src/application/Apexdocs.ts

@@ -14,17 +14,23 @@ export class Apexdocs {
    * Generates documentation out of Apex source files.
    */
   static async generate(config: UserDefinedConfig): Promise<void> {
-    Logger.logSingle('Initializing...', false);
+    Logger.logSingle('Initializing...');
+    Logger.startSpinner('Processing files...');
 
-    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
+    try {
+      const fileBodies = 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 markdown(fileBodies, config);
+          break;
+        case 'openapi':
+          openApi(fileBodies, config);
+          break;
+      }
+    } finally {
+      // TODO: Allow for failures
+      Logger.succeedSpinner('Files processed.');
     }
   }
 }

package/src/application/generators/markdown.ts

@@ -47,8 +47,9 @@ function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: strin
       // Filter out any files that should be skipped
       .filter((file) => !isSkip(file)) as PageData[],
     outputDir,
-    (file: PageData) => {
-      Logger.logSingle(`${file.outputDocPath} processed.`, false, 'green', false);
+    () => {
+      // TODO: Don't do this here, send things back up.
+      //Logger.logSingle(`${file.outputDocPath} processed.`, 'green');
     },
   );
 }

package/src/application/generators/openapi.ts

@@ -19,7 +19,7 @@ export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDe
   const generatedFiles = processor.fileBuilder().files();
 
   FileWriter.write(generatedFiles, config.targetDir, (file: PageData) => {
-    Logger.logSingle(`${file.outputDocPath} processed.`, false, 'green', false);
+    Logger.logSingle(`${file.outputDocPath} processed.`, 'green');
   });
 
   // Error logging
@@ -48,9 +48,8 @@ function filterByScopes(manifest: Manifest) {
   const filteredLogMessage = `Filtered ${
     manifest.types.length - filteredTypes.length
   } file(s), only keeping classes annotated as @RestResource.`;
-  Logger.clear();
 
-  Logger.logSingle(filteredLogMessage, false, 'green', false);
-  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, false, 'green', false);
+  Logger.logSingle(filteredLogMessage, 'green');
+  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, 'green');
   return filteredTypes;
 }

package/src/cli/commands/markdown.ts

@@ -44,10 +44,10 @@ export const markdownOptions: { [key: string]: Options } = {
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.includeMetadata,
   },
-  documentationRootDir: {
+  linkingStrategy: {
     type: 'string',
-    describe:
-      'The root directory of the documentation. This is used to create the correct relative paths when generating links between documents.',
-    default: defaults.documentationRootDir,
+    describe: 'The strategy to use when linking to other documentation pages.',
+    choices: ['relative', 'no-link', 'none'],
+    default: defaults.linkingStrategy,
   },
 };

package/src/core/markdown/__test__/generating-class-docs.spec.ts

@@ -268,9 +268,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data).firstDocContains(
-            'This is a description with a [ClassRef](/miscellaneous/ClassRef.md) reference',
-          ),
+          expect(data).firstDocContains('This is a description with a [ClassRef](ClassRef.md) reference'),
         );
       });
 
@@ -304,7 +302,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('[ClassRef](/miscellaneous/ClassRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[ClassRef](ClassRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {

package/src/core/markdown/__test__/generating-enum-docs.spec.ts

@@ -211,7 +211,7 @@ describe('Generates enum documentation', () => {
       expect(result).documentationBundleHasLength(2);
       assertEither(result, (data) => expect(data).firstDocContains('Description'));
       assertEither(result, (data) =>
-        expect(data).firstDocContains('This is a description with a [EnumRef](/miscellaneous/EnumRef.md) reference'),
+        expect(data).firstDocContains('This is a description with a [EnumRef](EnumRef.md) reference'),
       );
     });
 
@@ -245,7 +245,7 @@ describe('Generates enum documentation', () => {
       const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
       expect(result).documentationBundleHasLength(2);
       assertEither(result, (data) => expect(data).firstDocContains('See'));
-      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](/miscellaneous/EnumRef.md)'));
+      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](EnumRef.md)'));
     });
 
     it('displays sees without links when the reference is not found', async () => {

package/src/core/markdown/__test__/generating-interface-docs.spec.ts

@@ -189,9 +189,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data).firstDocContains(
-            'This is a description with a [InterfaceRef](/miscellaneous/InterfaceRef.md) reference',
-          ),
+          expect(data).firstDocContains('This is a description with a [InterfaceRef](InterfaceRef.md) reference'),
         );
       });
 
@@ -225,7 +223,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](/miscellaneous/InterfaceRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](InterfaceRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {

package/src/core/markdown/__test__/generating-reference-guide.spec.ts

@@ -25,10 +25,10 @@ describe('Generates a Reference Guide', () => {
     expect(result).documentationBundleHasLength(2);
 
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](/miscellaneous/MyEnum.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](miscellaneous/MyEnum.md)'),
     );
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](/miscellaneous/MyClass.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](miscellaneous/MyClass.md)'),
     );
   });
 
@@ -174,7 +174,7 @@ describe('Generates a Reference Guide', () => {
     const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
     expect(result).documentationBundleHasLength(2);
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](/group2/MyClass.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](group2/MyClass.md)'),
     );
   });
 });

package/src/core/markdown/__test__/test-helpers.ts

@@ -17,7 +17,7 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial
     defaultGroupName: 'Miscellaneous',
     sortMembersAlphabetically: true,
     referenceGuideTemplate: referenceGuideTemplate,
+    linkingStrategy: 'relative',
     ...config,
-    documentationRootDir: '',
   });
 }

package/src/core/markdown/adapters/__tests__/interface-adapter.spec.ts

@@ -15,7 +15,7 @@ const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
   defaultGroupName: 'Miscellaneous',
   referenceGuideTemplate: '',
   sortMembersAlphabetically: false,
-  documentationRootDir: '',
+  linkingStrategy: 'relative',
 };
 
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {

package/src/core/markdown/adapters/__tests__/link-generator.spec.ts

@@ -0,0 +1,130 @@
+import { generateLink } from '../generate-link';
+
+describe('Generates links', () => {
+  describe('relative', () => {
+    it('generates relative links from the base when found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns a relative path when linking from a file', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+        from: {
+          referencePath: 'b/fromPath',
+          displayName: 'fromName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: '../a/referencePath',
+      });
+    });
+
+    it('returns the display name when the from reference is not found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('no-link', () => {
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns the display name of the reference when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('none', () => {
+    it('returns the path as is when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+  });
+});

package/src/core/markdown/adapters/generate-link.ts

@@ -0,0 +1,82 @@
+import { StringOrLink } from './types';
+import path from 'path';
+import { LinkingStrategy } from '../../shared/types';
+
+export type LinkingStrategyFn = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string,
+  referenceName: string,
+) => StringOrLink;
+
+export const generateLink = (strategy: LinkingStrategy): LinkingStrategyFn => {
+  switch (strategy) {
+    case 'relative':
+      return generateRelativeLink;
+    case 'no-link':
+      return generateNoLink;
+    case 'none':
+      return returnReferenceAsIs;
+  }
+};
+
+const generateRelativeLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string, // The name of the file for which the reference is being generated
+  referenceName: string,
+): StringOrLink => {
+  function getRelativePath(fromPath: string, toPath: string) {
+    return path.relative(path.parse(path.join('/', fromPath)).dir, path.join('/', toPath));
+  }
+
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  // When linking from the base path (e.g. the reference guide/index page), the reference path is the same as the output
+  // path.
+  if (referenceTo && from === '__base__') {
+    return {
+      __type: 'link',
+      title: referenceTo.displayName,
+      url: getRelativePath('', referenceTo.referencePath),
+    };
+  }
+
+  const referenceFrom = references[from];
+
+  if (!referenceFrom) {
+    return referenceTo.displayName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: getRelativePath(referenceFrom.referencePath, referenceTo.referencePath),
+  };
+};
+
+const generateNoLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  return referenceTo ? referenceTo.displayName : referenceName;
+};
+
+const returnReferenceAsIs = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: referenceTo.referencePath,
+  };
+};

package/src/core/markdown/adapters/renderable-bundle.ts

@@ -1,18 +1,18 @@
 import { DocPageReference, ParsedFile } from '../../shared/types';
-import { Link, ReferenceGuideReference, Renderable, RenderableBundle, StringOrLink } from './types';
+import { Link, ReferenceGuideReference, Renderable, RenderableBundle } from './types';
 import { typeToRenderable } from './apex-types';
 import { adaptDescribable } from './documentables';
 import { MarkdownGeneratorConfig } from '../generate-docs';
 import { apply } from '#utils/fp';
 import { Type } from '@cparra/apex-reflection';
-import * as path from 'path';
+import { generateLink } from './generate-link';
 
 export function parsedFilesToRenderableBundle(
   config: MarkdownGeneratorConfig,
   parsedFiles: ParsedFile[],
   references: Record<string, DocPageReference>,
 ): RenderableBundle {
-  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
+  const referenceFinder = apply(generateLink(config.linkingStrategy), references);
 
   function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
     return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
@@ -55,43 +55,6 @@ function addToReferenceGuide(
   };
 }
 
-const linkGenerator = (
-  references: Record<string, DocPageReference>,
-  documentationRootDir: string,
-  from: string, // The name of the file for which the reference is being generated
-  referenceName: string,
-): StringOrLink => {
-  const referenceTo: DocPageReference | undefined = references[referenceName];
-  // When linking from the base path (e.g. the reference guide/index page), the reference path is the same as the output
-  // path.
-  if (referenceTo && from === '__base__') {
-    return {
-      __type: 'link',
-      title: referenceTo.displayName,
-      url: path.join(documentationRootDir, referenceTo.referencePath),
-    };
-  }
-
-  const referenceFrom: DocPageReference | undefined = references[from];
-
-  if (!referenceFrom || !referenceTo) {
-    return referenceName;
-  }
-
-  // Gets the directory of the file that is being linked from.
-  // This is used to calculate the relative path to the file
-  // being linked to.
-  const fromPath = path.parse(path.join('/', documentationRootDir, referenceFrom.referencePath)).dir;
-  const toPath = path.join('/', documentationRootDir, referenceTo.referencePath);
-  const relativePath = path.relative(fromPath, toPath);
-
-  return {
-    __type: 'link',
-    title: referenceTo.displayName,
-    url: relativePath,
-  };
-};
-
 function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
   const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
   return groupAnnotation?.body ?? config.defaultGroupName;

package/src/core/markdown/generate-docs.ts

@@ -42,7 +42,7 @@ export type MarkdownGeneratorConfig = Pick<
   | 'transformDocs'
   | 'transformDocPage'
   | 'transformReference'
-  | 'documentationRootDir'
+  | 'linkingStrategy'
 > & {
   referenceGuideTemplate: string;
   sortMembersAlphabetically: boolean;

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

@@ -25,7 +25,7 @@ export class OpenApiDocsProcessor {
   }
 
   onProcess(type: Type): void {
-    Logger.logSingle(`Processing ${type.name}`, false, 'green', false);
+    Logger.logSingle(`Processing ${type.name}`, 'green');
 
     const endpointPath = this.getEndpointPath(type);
     if (!endpointPath) {

package/src/core/shared/types.d.ts

@@ -12,6 +12,17 @@ export 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';
+
 export type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   sourceDir: string;
@@ -21,7 +32,7 @@ export type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
-  documentationRootDir: string;
+  linkingStrategy: LinkingStrategy;
 } & Partial<ConfigurableHooks>;
 
 export type UserDefinedOpenApiConfig = {

package/src/defaults.ts

@@ -5,5 +5,5 @@ export const defaults = {
   defaultGroupName: 'Miscellaneous',
   includeMetadata: false,
   sortMembersAlphabetically: false,
-  documentationRootDir: '',
+  linkingStrategy: 'relative' as const,
 };

package/src/index.ts

@@ -12,12 +12,7 @@ import { defaults } from './defaults';
 type ConfigurableMarkdownConfig = Omit<
   SetOptional<
     UserDefinedMarkdownConfig,
-    | 'targetDir'
-    | 'scope'
-    | 'defaultGroupName'
-    | 'includeMetadata'
-    | 'sortMembersAlphabetically'
-    | 'documentationRootDir'
+    'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'
   >,
   'targetGenerator'
 >;

package/src/util/logger.ts

@@ -1,13 +1,11 @@
 import chalk from 'chalk';
-import logUpdate from 'log-update';
-
+import ora from 'ora';
 /**
  * Logs messages to the console.
  */
 export class Logger {
   static currentFrame = 0;
-
-  static frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  static spinner = ora();
 
   /**
    * Logs a message with optional arguments.
@@ -27,31 +25,31 @@ export class Logger {
    * @param args Optional arguments.
    */
   public static error(message: unknown, ...args: string[]) {
-    this.logSingle(message, false, 'red', false);
+    this.logSingle(message, 'red');
     args.forEach(() => {
-      this.logSingle(message, false, 'red', false);
+      this.logSingle(message, 'red');
     });
   }
 
-  public static logSingle(text: unknown, showSpinner = true, color: 'green' | 'red' = 'green', overrideConsole = true) {
+  public static logSingle(text: unknown, color: 'green' | 'red' = 'green') {
     if (this.currentFrame > 9) {
       this.currentFrame = 0;
     }
-    const spinner = showSpinner ? `${this.frames[this.currentFrame++]}` : '';
-    let logMessage;
-    if (color === 'green') {
-      logMessage = `${chalk.green(new Date().toLocaleString() + ': ')}${text}\n`;
-    } else {
-      logMessage = `${chalk.red(new Date().toLocaleString() + ': ')}${text}\n`;
-    }
-    if (overrideConsole) {
-      logUpdate(`${spinner} ${logMessage}`);
-    } else {
-      process.stdout.write(`${spinner} ${logMessage}`);
-    }
+
+    const logMessage = `${this.getChalkFn(color)(new Date().toLocaleString() + ': ')}${text}\n`;
+    process.stdout.write(logMessage);
+  }
+
+  private static getChalkFn(color: 'green' | 'red') {
+    return color === 'green' ? chalk.green : chalk.red;
+  }
+
+  public static startSpinner(text: string) {
+    this.spinner.text = text;
+    this.spinner.start();
   }
 
-  public static clear() {
-    logUpdate.clear();
+  public static succeedSpinner(text: string) {
+    this.spinner.succeed(text);
   }
 }