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

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

@@ -10,30 +10,43 @@ export class ApexFileReader {
   /**
    * Reads from .cls files and returns their raw body.
    */
-  static processFiles(fileSystem: FileSystem, rootPath: string, includeMetadata: boolean): UnparsedSourceFile[] {
-    let bundles: UnparsedSourceFile[] = [];
+  static async processFiles(
+    fileSystem: FileSystem,
+    rootPath: string,
+    includeMetadata: boolean,
+  ): Promise<UnparsedSourceFile[]> {
+    const filePaths = await this.getFilePaths(fileSystem, rootPath);
+    const apexFilePaths = filePaths.filter((filePath) => this.isApexFile(filePath));
+    const filePromises = apexFilePaths.map((filePath) => this.processFile(fileSystem, filePath, includeMetadata));
+    return Promise.all(filePromises);
+  }
 
-    const directoryContents = fileSystem.readDirectory(rootPath);
-    directoryContents.forEach((filePath) => {
+  private static async getFilePaths(fileSystem: FileSystem, rootPath: string): Promise<string[]> {
+    const directoryContents = await fileSystem.readDirectory(rootPath);
+    const paths: string[] = [];
+    for (const filePath of directoryContents) {
       const currentPath = fileSystem.joinPath(rootPath, filePath);
-      if (fileSystem.isDirectory(currentPath)) {
-        bundles = bundles.concat(this.processFiles(fileSystem, currentPath, includeMetadata));
-      }
-
-      if (!this.isApexFile(filePath)) {
-        return;
+      if (await fileSystem.isDirectory(currentPath)) {
+        paths.push(...(await this.getFilePaths(fileSystem, currentPath)));
       }
+      paths.push(currentPath);
+    }
+    return paths;
+  }
 
-      const rawTypeContent = fileSystem.readFile(currentPath);
-      const metadataPath = fileSystem.joinPath(rootPath, `${filePath}-meta.xml`);
-      let rawMetadataContent = null;
-      if (includeMetadata) {
-        rawMetadataContent = fileSystem.exists(metadataPath) ? fileSystem.readFile(metadataPath) : null;
-      }
+  private static async processFile(
+    fileSystem: FileSystem,
+    filePath: string,
+    includeMetadata: boolean,
+  ): Promise<UnparsedSourceFile> {
+    const rawTypeContent = await fileSystem.readFile(filePath);
+    const metadataPath = `${filePath}-meta.xml`;
+    let rawMetadataContent = null;
+    if (includeMetadata) {
+      rawMetadataContent = fileSystem.exists(metadataPath) ? await fileSystem.readFile(metadataPath) : null;
+    }
 
-      bundles.push({ filePath: currentPath, content: rawTypeContent, metadataContent: rawMetadataContent });
-    });
-    return bundles;
+    return { filePath, content: rawTypeContent, metadataContent: rawMetadataContent };
   }
 
   private static isApexFile(currentFile: string): boolean {

package/src/application/file-system.ts

@@ -2,25 +2,61 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 export interface FileSystem {
-  readDirectory: (sourceDirectory: string) => string[];
-  isDirectory: (path: string) => boolean;
-  readFile: (path: string) => string;
+  isDirectory: (path: string) => Promise<boolean>;
+  readDirectory: (sourceDirectory: string) => Promise<string[]>;
+  readFile: (path: string) => Promise<string>;
   joinPath: (...paths: string[]) => string;
   exists: (path: string) => boolean;
 }
 
+function stat(path: string): Promise<fs.Stats> {
+  return new Promise((resolve, reject) => {
+    fs.stat(path, (err, stats) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve(stats);
+      }
+    });
+  });
+}
+
+function readdir(path: string): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    fs.readdir(path, (err, files) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve(files);
+      }
+    });
+  });
+}
+
+function readFile(path: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    fs.readFile(path, (err, data) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve(data.toString());
+      }
+    });
+  });
+}
+
 export class DefaultFileSystem implements FileSystem {
-  isDirectory(pathToRead: string): boolean {
-    return fs.statSync(pathToRead).isDirectory();
+  async isDirectory(pathToRead: string): Promise<boolean> {
+    const stats = await stat(pathToRead);
+    return stats.isDirectory();
   }
 
-  readDirectory(sourceDirectory: string): string[] {
-    return fs.readdirSync(sourceDirectory);
+  readDirectory(sourceDirectory: string): Promise<string[]> {
+    return readdir(sourceDirectory);
   }
 
-  readFile(pathToRead: string): string {
-    const rawFile = fs.readFileSync(pathToRead);
-    return rawFile.toString();
+  readFile(pathToRead: string): Promise<string> {
+    return readFile(pathToRead);
   }
 
   joinPath(...paths: string[]): string {

package/src/application/file-writer.ts

@@ -1,21 +1,43 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as TE from 'fp-ts/lib/TaskEither';
 import { PageData } from '../core/shared/types';
+import { pipe } from 'fp-ts/function';
 
-export class FileWriter {
-  static write(files: PageData[], outputDir: string, onWriteCallback: (file: PageData) => void) {
-    files.forEach((file) => {
-      const { filePath, content } = this.getTargetLocation(file, outputDir);
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, content, 'utf8');
-      onWriteCallback(file);
-    });
-  }
+const mkdir: (path: fs.PathLike, options: fs.MakeDirectoryOptions) => TE.TaskEither<NodeJS.ErrnoException, void> =
+  TE.taskify(fs.mkdir);
 
-  private static getTargetLocation(file: PageData, outputDir: string): PageData {
-    return {
-      ...file,
-      filePath: path.join(outputDir, file.filePath),
-    };
-  }
+const writeFile: (
+  path: fs.PathOrFileDescriptor,
+  data: string,
+  options?: fs.WriteFileOptions,
+) => TE.TaskEither<NodeJS.ErrnoException, void> = TE.taskify(fs.writeFile);
+
+export function writeFiles(files: PageData[], outputDir: string, onWriteCallback?: (file: PageData) => void) {
+  return pipe(
+    files,
+    TE.traverseArray((file) => writeSingle(file, outputDir, onWriteCallback)),
+  );
+}
+
+function writeSingle(file: PageData, outputDir: string, onWriteCallback?: (file: PageData) => void) {
+  const ensureDirectoryExists = ({ outputDocPath }: PageData) =>
+    mkdir(path.dirname(outputDocPath), { recursive: true });
+
+  const writeContents = (file: PageData) => writeFile(file.outputDocPath, file.content, 'utf8');
+
+  return pipe(
+    resolveTargetLocation(file, outputDir),
+    (file) => TE.right(file),
+    TE.tapIO(ensureDirectoryExists),
+    TE.flatMap(writeContents),
+    TE.map(() => onWriteCallback?.(file)),
+  );
+}
+
+function resolveTargetLocation(file: PageData, outputDir: string): PageData {
+  return {
+    ...file,
+    outputDocPath: path.join(outputDir, file.outputDocPath),
+  };
 }

package/src/application/generators/markdown.ts

@@ -1,6 +1,4 @@
 import { generateDocs } from '../../core/markdown/generate-docs';
-import { FileWriter } from '../file-writer';
-import { Logger } from '#utils/logger';
 import { pipe } from 'fp-ts/function';
 import {
   PageData,
@@ -8,30 +6,25 @@ import {
   UnparsedSourceFile,
   UserDefinedMarkdownConfig,
 } from '../../core/shared/types';
-import { ReflectionError } from '../../core/markdown/reflection/error-handling';
 import { referenceGuideTemplate } from '../../core/markdown/templates/reference-guide';
 import * as TE from 'fp-ts/TaskEither';
 import { isSkip } from '../../core/shared/utils';
+import { writeFiles } from '../file-writer';
+
+class FileWritingError {
+  readonly _tag = 'FileWritingError';
+
+  constructor(
+    public message: string,
+    public error: unknown,
+  ) {}
+}
 
 export default function generate(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
   return pipe(
     generateDocumentationBundle(bundles, config),
-    TE.map((files) => writeFilesToSystem(files, config.targetDir)),
-    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;
-      }
-
-      const errorMessages = [
-        'Error(s) occurred while parsing files. Please review the following issues:',
-        ...error.errors.map(formatReflectionError),
-      ].join('\n');
-
-      Logger.error(errorMessages);
-    }),
-  )();
+    TE.flatMap((files) => writeFilesToSystem(files, config.targetDir)),
+  );
 }
 
 function generateDocumentationBundle(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
@@ -42,17 +35,11 @@ function generateDocumentationBundle(bundles: UnparsedSourceFile[], config: User
 }
 
 function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: string) {
-  FileWriter.write(
-    [files.referenceGuide, ...files.docs]
-      // Filter out any files that should be skipped
-      .filter((file) => !isSkip(file)) as PageData[],
-    outputDir,
-    (file: PageData) => {
-      Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
-    },
+  return pipe(
+    [files.referenceGuide, ...files.docs].filter((file) => !isSkip(file)),
+    (files) => writeFiles(files as PageData[], outputDir),
+    TE.mapLeft((error) => {
+      return new FileWritingError('An error occurred while writing files to the system.', error);
+    }),
   );
 }
-
-function formatReflectionError(error: ReflectionError) {
-  return `Source file: ${error.file}\n${error.message}\n`;
-}

package/src/application/generators/openapi.ts

@@ -2,13 +2,15 @@ import { createManifest } from '../../core/openapi/manifest-factory';
 import { RawBodyParser } from '../../core/openapi/parser';
 import { TypesRepository } from '../../core/openapi/types-repository';
 import Transpiler from '../../core/openapi/transpiler';
-import { FileWriter } from '../file-writer';
 import { Logger } from '#utils/logger';
 import ErrorLogger from '#utils/error-logger';
 import { reflect, ReflectionResult } from '@cparra/apex-reflection';
 import Manifest from '../../core/manifest';
 import { PageData, UnparsedSourceFile, UserDefinedOpenApiConfig } from '../../core/shared/types';
 import { OpenApiDocsProcessor } from '../../core/openapi/open-api-docs-processor';
+import { writeFiles } from '../file-writer';
+import { pipe } from 'fp-ts/function';
+import * as TE from 'fp-ts/TaskEither';
 
 export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDefinedOpenApiConfig) {
   const manifest = createManifest(new RawBodyParser(fileBodies), reflectionWithLogger);
@@ -18,11 +20,14 @@ export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDe
   Transpiler.generate(filteredTypes, processor);
   const generatedFiles = processor.fileBuilder().files();
 
-  FileWriter.write(generatedFiles, config.targetDir, (file: PageData) => {
-    Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
-  });
+  pipe(
+    writeFiles(generatedFiles, config.targetDir, (file: PageData) => {
+      Logger.logSingle(`${file.outputDocPath} processed.`, 'green');
+    }),
+    TE.mapError((error) => Logger.error(error)),
+  );
 
-  // Error logging
+  // Logs any errors that the types might have in their doc comment's error field
   ErrorLogger.logErrors(filteredTypes);
 }
 
@@ -48,9 +53,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,9 +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 generate the correct relative paths.',
-    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

@@ -12,7 +12,7 @@ describe('Generates interface documentation', () => {
 
       const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].filePath).toContain('MyClass'));
+      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyClass'));
     });
 
     it('returns the type as class', async () => {
@@ -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

@@ -17,7 +17,7 @@ describe('Generates enum documentation', () => {
 
       const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].filePath).toContain('MyEnum'));
+      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyEnum'));
     });
 
     it('returns the type as enum', async () => {
@@ -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 () => {
@@ -453,7 +451,9 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data.docs.find((doc) => doc.filePath.includes('AnotherInterface'))?.content).toContain('Inherited'),
+          expect(data.docs.find((doc) => doc.outputDocPath.includes('AnotherInterface'))?.content).toContain(
+            'Inherited',
+          ),
         );
       });
     });

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/documentables.ts

@@ -98,7 +98,6 @@ export function adaptDocumentable(
         .map((currentAnnotation) => currentAnnotation.body) ?? []
     );
   }
-
   return {
     ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),