@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

package/examples/vitepress/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "vitepress-example",
+  "scripts": {
+    "docs:clean": "rimraf --glob 'docs/!(.vitepress|index-frontmatter.md|api-examples.md|markdown-examples.md)'",
+    "apexdocs:build": "npm run docs:clean && ts-node ../../src/cli/generate.ts markdown",
+    "docs:build": "vitepress build docs",
+    "docs:gen": "npm run docs:clean && npm run docs:build",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "vitepress": "^1.3.1"
+  },
+  "dependencies": {
+    "rimraf": "^5.0.7"
+  }
+}

package/examples/vitepress/sfdx-project.json

@@ -0,0 +1,12 @@
+{
+  "packageDirectories": [
+    {
+      "path": "force-app",
+      "default": true
+    }
+  ],
+  "name": "vitepress",
+  "namespace": "",
+  "sfdcLoginUrl": "https://login.salesforce.com",
+  "sourceApiVersion": "61.0"
+}

package/jest.config.js

@@ -1,5 +1,10 @@
 module.exports = {
   preset: 'ts-jest',
   testEnvironment: 'node',
-  modulePathIgnorePatterns: ['<rootDir>/lib/'],
+  modulePathIgnorePatterns: ['<rootDir>/dist/'],
+  moduleNameMapper: {
+    '^chalk$': '<rootDir>/__mocks__/chalk.js',
+    '^log-update$': '<rootDir>/__mocks__/log-update.js',
+    '#utils/(.*)$': '<rootDir>/src/util/$1',
+  },
 };

package/jest.d.ts

@@ -0,0 +1,7 @@
+declare namespace jest {
+  interface Matchers<R> {
+    documentationBundleHasLength(length: number): R;
+    firstDocContains(content: string): R;
+    firstDocContainsNot(content: string): R;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "2.25.0",
+  "version": "3.0.0-alpha.10",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -10,23 +10,18 @@
     "apex-docs",
     "docs"
   ],
-  "main": "lib/index.js",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "bin": {
-    "apexdocs-generate": "lib/cli/generate.js"
+    "apexdocs": "./dist/cli/generate.js"
   },
-  "types": "lib/index.d.ts",
   "scripts": {
-    "test": "jest --coverage",
-    "build": "rimraf ./lib && npm run lint && tsc --declaration",
+    "test": "npm run build && jest",
+    "build": "rimraf ./lib && npm run lint && tsc --noEmit && pkgroll",
     "lint": "eslint \"./src/**/*.{js,ts}\" --quiet --fix",
     "prepare": "npm run build",
     "version": "npm run format && git add -A src",
-    "postversion": "git push && git push --tags",
-    "docs:init": "docsify init docs",
-    "docs:serve": "docsify serve docs",
-    "execute:example": "rimraf ./docs/types && node lib/cli/generate.js -s examples/force-app -t docs/types --scope global public private protected -g docsify --defaultGroupName \"Misc Group\" --namespace nspc --title \"Sample Documentation\" --documentationRootDir types",
-    "execute:example:index:only": "node lib/cli/generate.js -s examples/force-app -t docs --scope global public private -g docsify --indexOnly",
-    "execute:example:openapi": "node lib/cli/generate.js -s examples/force-app -t docs -g openapi --openApiTitle \"Sample REST Api\" --namespace nspc --openApiFileName restapi"
+    "postversion": "git push && git push --tags"
   },
   "author": "Cesar Parra",
   "license": "MIT",
@@ -35,26 +30,22 @@
     "url": "https://github.com/cesarParra/apexdocs"
   },
   "devDependencies": {
-    "@types/html-entities": "^1.3.4",
-    "@types/jest": "^27.4.1",
-    "@types/js-yaml": "^4.0.5",
-    "@types/node": "^13.7.4",
-    "@types/shelljs": "^0.8.6",
-    "@types/yargs": "^15.0.3",
-    "@typescript-eslint/eslint-plugin": "^5.41.0",
-    "@typescript-eslint/parser": "^5.41.0",
-    "docsify": "^4.13.1",
-    "docsify-cli": "^4.4.4",
-    "eslint": "^8.0.1",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "husky": "^8.0.3",
-    "jest": "^27.5.1",
-    "lint-staged": "^13.2.1",
-    "prettier": "^2.4.1",
-    "rimraf": "^3.0.2",
-    "ts-jest": "^27.1.3",
-    "typescript": "^4.8.4"
+    "@eslint/js": "^9.6.0",
+    "@types/eslint__js": "^8.42.3",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.10",
+    "@types/shelljs": "^0.8.15",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^9.0.11",
+    "jest": "^29.7.0",
+    "lint-staged": "^15.2.7",
+    "pkgroll": "^2.4.2",
+    "prettier": "^3.3.2",
+    "rimraf": "^6.0.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.5.3",
+    "typescript-eslint": "^7.16.0"
   },
   "husky": {
     "hooks": {
@@ -68,12 +59,19 @@
   },
   "dependencies": {
     "@cparra/apex-reflection": "2.12.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/yargs": "^17.0.32",
     "chalk": "^4.1.2",
     "cosmiconfig": "^9.0.0",
-    "fast-xml-parser": "^4.0.1",
+    "cosmiconfig-typescript-loader": "^5.0.0",
+    "fast-xml-parser": "^4.4.0",
+    "fp-ts": "^2.16.8",
+    "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
-    "log-update": "4.0.0",
-    "xss": "^1.0.11",
-    "yargs": "^16.0.3"
+    "type-fest": "^4.23.0",
+    "yargs": "^17.7.2"
+  },
+  "imports": {
+    "#utils/*": "./src/util/*.ts"
   }
 }

package/src/application/Apexdocs.ts

@@ -1,17 +1,13 @@
-import { ApexFileReader } from '../service/apex-file-reader';
-import { DefaultFileSystem } from '../service/file-system';
-import { ReflectionResult, reflect, Type } from '@cparra/apex-reflection';
-import { Logger } from '../util/logger';
-import { createManifest } from '../service/manifest-factory';
-import { RawBodyParser } from '../service/parser';
-import { Settings, TargetFile } from '../settings';
-import Transpiler from '../transpiler/transpiler';
-import { FileWriter } from '../service/file-writer';
-import ErrorLogger from '../util/error-logger';
-import ApexBundle from '../model/apex-bundle';
-import Manifest from '../model/manifest';
-import { TypesRepository } from '../model/types-repository';
-import { TypeTranspilerFactory } from '../transpiler/factory';
+import markdown from './generators/markdown';
+import openApi from './generators/openapi';
+
+import { ApexFileReader } from './apex-file-reader';
+import { DefaultFileSystem } from './file-system';
+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 { ReflectionError } from '../core/markdown/reflection/reflect-source';
 
 /**
  * Application entry-point to generate documentation out of Apex source files.
@@ -20,64 +16,58 @@ export class Apexdocs {
   /**
    * Generates documentation out of Apex source files.
    */
-  static generate(): void {
-    Logger.log('Initializing...');
-    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem());
-    const manifest = createManifest(new RawBodyParser(fileBodies), this._reflectionWithLogger);
-    TypesRepository.getInstance().populateAll(manifest.types);
-    const filteredTypes = this.filterByScopes(manifest);
-    TypesRepository.getInstance().populateScoped(filteredTypes);
-    const processor = TypeTranspilerFactory.get(Settings.getInstance().targetGenerator);
-    Transpiler.generate(filteredTypes, processor);
-    const generatedFiles = processor.fileBuilder().files();
-
-    const files: TargetFile[] = [];
-    FileWriter.write(generatedFiles, (file: TargetFile) => {
-      Logger.logSingle(`${file.name} processed.`, false, 'green', false);
-      files.push(file);
-    });
+  static async generate(config: UserDefinedConfig): Promise<void> {
+    Logger.logSingle(`Generating ${config.targetGenerator} documentation...`);
 
-    Settings.getInstance().onAfterProcess(files);
+    try {
+      const fileBodies = await ApexFileReader.processFiles(
+        new DefaultFileSystem(),
+        config.sourceDir,
+        config.includeMetadata,
+      );
 
-    // Error logging
-    ErrorLogger.logErrors(filteredTypes);
+      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');
+    }
   }
+}
 
-  private static filterByScopes(manifest: Manifest) {
-    let filteredTypes: Type[];
-    let filteredLogMessage;
-    if (Settings.getInstance().config.targetGenerator !== 'openapi') {
-      filteredTypes = manifest.filteredByAccessModifierAndAnnotations(Settings.getInstance().scope);
-      filteredLogMessage = `Filtered ${manifest.types.length - filteredTypes.length} file(s) based on scope: ${
-        Settings.getInstance().scope
-      }`;
-    } else {
-      // If we are dealing with an OpenApi generator, we ignore the passed in access modifiers, and instead
-      // we only keep classes annotated as @RestResource
-      filteredTypes = manifest.filteredByAccessModifierAndAnnotations([
-        'restresource',
-        'httpdelete',
-        'httpget',
-        'httppatch',
-        'httppost',
-        'httpput',
-      ]);
-      filteredLogMessage = `Filtered ${
-        manifest.types.length - filteredTypes.length
-      } file(s), only keeping classes annotated as @RestResource.`;
-    }
-    Logger.clear();
+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;
+      }
 
-    Logger.logSingle(filteredLogMessage, false, 'green', false);
-    Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, false, 'green', false);
-    return filteredTypes;
-  }
+      if (error._tag === 'FileWritingError') {
+        Logger.error(error.message);
+        Logger.error(error.error);
+        return;
+      }
 
-  static _reflectionWithLogger = (apexBundle: ApexBundle): ReflectionResult => {
-    const result = reflect(apexBundle.rawTypeContent);
-    if (result.error) {
-      Logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
-    }
-    return result;
-  };
+      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

@@ -0,0 +1,104 @@
+import { Settings, SettingsConfig } from '../../core/settings';
+import { ApexFileReader } from '../apex-file-reader';
+
+describe('File Reader', () => {
+  beforeEach(() => {
+    Settings.build({
+      sourceDirectory: '',
+      recursive: true,
+      scope: [],
+      outputDir: '',
+      targetGenerator: 'markdown',
+      indexOnly: false,
+      defaultGroupName: 'Misc',
+      sanitizeHtml: true,
+      openApiFileName: 'openapi',
+      title: 'Classes',
+      includeMetadata: false,
+    } as SettingsConfig);
+  });
+
+  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): 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;
+        },
+      },
+      '',
+      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(
+      {
+        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;
+        },
+      },
+      '',
+      false,
+    );
+    expect(result.length).toBe(0);
+  });
+
+  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): 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;
+        },
+      },
+      '',
+      false,
+    );
+    expect(result.length).toBe(1);
+    expect(result[0].content).toBe('public class MyClass{}');
+  });
+});

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

@@ -0,0 +1,55 @@
+import { FileSystem } from './file-system';
+import { UnparsedSourceFile } from '../core/shared/types';
+
+const APEX_FILE_EXTENSION = '.cls';
+
+/**
+ * Reads from .cls files and returns their raw body.
+ */
+export class ApexFileReader {
+  /**
+   * Reads from .cls files and returns their raw body.
+   */
+  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);
+  }
+
+  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 (await fileSystem.isDirectory(currentPath)) {
+        paths.push(...(await this.getFilePaths(fileSystem, currentPath)));
+      }
+      paths.push(currentPath);
+    }
+    return paths;
+  }
+
+  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;
+    }
+
+    return { filePath, content: rawTypeContent, metadataContent: rawMetadataContent };
+  }
+
+  private static isApexFile(currentFile: string): boolean {
+    return currentFile.endsWith(APEX_FILE_EXTENSION);
+  }
+}

package/src/application/file-system.ts

@@ -0,0 +1,69 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface FileSystem {
+  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 {
+  async isDirectory(pathToRead: string): Promise<boolean> {
+    const stats = await stat(pathToRead);
+    return stats.isDirectory();
+  }
+
+  readDirectory(sourceDirectory: string): Promise<string[]> {
+    return readdir(sourceDirectory);
+  }
+
+  readFile(pathToRead: string): Promise<string> {
+    return readFile(pathToRead);
+  }
+
+  joinPath(...paths: string[]): string {
+    return path.join(...paths);
+  }
+
+  exists(path: string): boolean {
+    return fs.existsSync(path);
+  }
+}

package/src/application/file-writer.ts

@@ -0,0 +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';
+
+const mkdir: (path: fs.PathLike, options: fs.MakeDirectoryOptions) => TE.TaskEither<NodeJS.ErrnoException, void> =
+  TE.taskify(fs.mkdir);
+
+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

@@ -0,0 +1,45 @@
+import { generateDocs } from '../../core/markdown/generate-docs';
+import { pipe } from 'fp-ts/function';
+import {
+  PageData,
+  PostHookDocumentationBundle,
+  UnparsedSourceFile,
+  UserDefinedMarkdownConfig,
+} from '../../core/shared/types';
+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.flatMap((files) => writeFilesToSystem(files, config.targetDir)),
+  );
+}
+
+function generateDocumentationBundle(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
+  return generateDocs(bundles, {
+    ...config,
+    referenceGuideTemplate: referenceGuideTemplate,
+  });
+}
+
+function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: string) {
+  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);
+    }),
+  );
+}