@cparra/apexdocs 2.25.0-alpha.4 → 2.25.0-alpha.6

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

@@ -5,5 +5,6 @@ module.exports = {
   moduleNameMapper: {
     '^chalk$': '<rootDir>/__mocks__/chalk.js',
     '^log-update$': '<rootDir>/__mocks__/log-update.js',
+    '#utils/(.*)$': '<rootDir>/src/util/$1',
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "2.25.0-alpha.4",
+  "version": "2.25.0-alpha.6",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -13,17 +13,15 @@
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "apexdocs-generate": "./dist/cli/generate.js"
+    "apexdocs": "./dist/cli/generate.js"
   },
   "scripts": {
     "test": "npm run build && jest",
-    "build": "rimraf ./lib && npm run lint && pkgroll --minify",
+    "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"
+    "postversion": "git push && git push --tags"
   },
   "author": "Cesar Parra",
   "license": "MIT",
@@ -34,17 +32,15 @@
   "devDependencies": {
     "@eslint/js": "^9.6.0",
     "@types/eslint__js": "^8.42.3",
-    "@types/html-entities": "^1.3.4",
     "@types/jest": "^29.5.12",
     "@types/node": "^20.14.10",
     "@types/shelljs": "^0.8.15",
-    "docsify": "^4.13.1",
     "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.1.1",
+    "pkgroll": "^2.4.2",
     "prettier": "^3.3.2",
     "rimraf": "^6.0.0",
     "ts-jest": "^29.2.0",
@@ -62,16 +58,21 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.9.5",
+    "@cparra/apex-reflection": "2.11.3",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",
     "chalk": "^4.1.2",
     "cosmiconfig": "^9.0.0",
+    "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",
+    "type-fest": "^4.23.0",
     "yargs": "^17.7.2"
+  },
+  "imports": {
+    "#utils/*": "./src/util/*.ts"
   }
 }

package/src/application/Apexdocs.ts

@@ -1,20 +1,10 @@
-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 '../core/apex-bundle';
-import Manifest from '../core/manifest';
-import { TypesRepository } from '../model/types-repository';
-import { TypeTranspilerFactory } from '../transpiler/factory';
-import { generateMarkdownFiles } from './generators/generate-markdown-files';
-import { AllConfigurableOptions } from '../cli/args';
-import { GeneratorChoices } from '../transpiler/generator-choices';
+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 { UserDefinedConfig } from '../core/shared/types';
 
 /**
  * Application entry-point to generate documentation out of Apex source files.
@@ -23,96 +13,18 @@ export class Apexdocs {
   /**
    * Generates documentation out of Apex source files.
    */
-  static generate(config: AllConfigurableOptions): void {
+  static async generate(config: UserDefinedConfig): Promise<void> {
     Logger.logSingle('Initializing...', false);
-    this.initializeSettings(config);
-    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem());
-
-    if (Settings.getInstance().targetGenerator === 'plain-markdown') {
-      generateMarkdownFiles(fileBodies);
-    } else {
-      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);
-      });
 
-      Settings.getInstance().onAfterProcess(files);
+    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
 
-      // Error logging
-      ErrorLogger.logErrors(filteredTypes);
+    switch (config.targetGenerator) {
+      case 'markdown':
+        await markdown(fileBodies, config);
+        break;
+      case 'openapi':
+        openApi(fileBodies, config);
+        break;
     }
   }
-
-  private static initializeSettings(argv: AllConfigurableOptions) {
-    const targetGenerator = argv.targetGenerator as GeneratorChoices;
-    Settings.build({
-      sourceDirectory: argv.sourceDir,
-      scope: argv.scope,
-      outputDir: argv.targetDir,
-      targetGenerator: targetGenerator,
-      indexOnly: argv.indexOnly,
-      defaultGroupName: argv.defaultGroupName,
-      openApiTitle: argv.openApiTitle,
-      title: argv.title,
-      namespace: argv.namespace,
-      openApiFileName: argv.openApiFileName,
-      sortMembersAlphabetically: argv.sortMembersAlphabetically,
-      includeMetadata: argv.includeMetadata,
-      rootDir: argv.documentationRootDir,
-      onAfterProcess: argv.onAfterProcess,
-      onBeforeFileWrite: argv.onBeforeFileWrite,
-      frontMatterHeader: argv.frontMatterHeader,
-      linkingStrategy:
-        targetGenerator === 'plain-markdown'
-          ? 'path-relative'
-          : TypeTranspilerFactory.get(targetGenerator).getLinkingStrategy(),
-    });
-  }
-
-  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();
-
-    Logger.logSingle(filteredLogMessage, false, 'green', false);
-    Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, false, 'green', false);
-    return filteredTypes;
-  }
-
-  static _reflectionWithLogger = (apexBundle: ApexBundle): ReflectionResult => {
-    const result = reflect(apexBundle.rawTypeContent);
-    if (result.error) {
-      Logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
-    }
-    return result;
-  };
 }

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', () => {
+    const result = ApexFileReader.processFiles(
+      {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        isDirectory(_: string): boolean {
+          return 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 [];
+        },
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        readFile(_: string): string {
+          return '';
+        },
+        exists(): boolean {
+          return true;
+        },
+      },
+      '',
+      false,
+    );
+    expect(result.length).toBe(0);
+  });
+
+  it('returns an empty list when there are no Apex files in the directory', () => {
+    const result = ApexFileReader.processFiles(
+      {
+        isDirectory(): boolean {
+          return false;
+        },
+        joinPath(): string {
+          return '';
+        },
+        readDirectory(): string[] {
+          return ['SomeFile.md'];
+        },
+        readFile(): string {
+          return '';
+        },
+        exists(): boolean {
+          return true;
+        },
+      },
+      '',
+      false,
+    );
+    expect(result.length).toBe(0);
+  });
+
+  it('returns the file contents for an Apex file', () => {
+    const result = ApexFileReader.processFiles(
+      {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        isDirectory(_: string): boolean {
+          return 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 ['SomeApexFile.cls'];
+        },
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        readFile(_: string): string {
+          return '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,42 @@
+import { FileSystem } from './file-system';
+import { SourceFile } 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 processFiles(fileSystem: FileSystem, rootPath: string, includeMetadata: boolean): SourceFile[] {
+    let bundles: SourceFile[] = [];
+
+    const directoryContents = fileSystem.readDirectory(rootPath);
+    directoryContents.forEach((filePath) => {
+      const currentPath = fileSystem.joinPath(rootPath, filePath);
+      if (fileSystem.isDirectory(currentPath)) {
+        bundles = bundles.concat(this.processFiles(fileSystem, currentPath, includeMetadata));
+      }
+
+      if (!this.isApexFile(filePath)) {
+        return;
+      }
+
+      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;
+      }
+
+      bundles.push({ filePath: currentPath, content: rawTypeContent, metadataContent: rawMetadataContent });
+    });
+    return bundles;
+  }
+
+  private static isApexFile(currentFile: string): boolean {
+    return currentFile.endsWith(APEX_FILE_EXTENSION);
+  }
+}

package/src/application/file-writer.ts

@@ -0,0 +1,25 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { PageData } from '../core/shared/types';
+
+export class FileWriter {
+  static write(files: PageData[], outputDir: string, onWriteCallback: (file: PageData) => void) {
+    files.forEach((file) => {
+      const resolvedFile = this.getTargetLocation(file, outputDir);
+      if (!fs.existsSync(resolvedFile.directory)) {
+        fs.mkdirSync(resolvedFile.directory, { recursive: true });
+      }
+
+      const filePath = path.join(resolvedFile.directory, `${resolvedFile.fileName}.${resolvedFile.fileExtension}`);
+      fs.writeFileSync(filePath, resolvedFile.content, 'utf8');
+      onWriteCallback(resolvedFile);
+    });
+  }
+
+  private static getTargetLocation(file: PageData, outputDir: string): PageData {
+    return {
+      ...file,
+      directory: path.join(outputDir, file.directory),
+    };
+  }
+}

package/src/application/generators/markdown.ts

@@ -0,0 +1,53 @@
+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, PostHookDocumentationBundle, SourceFile, 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';
+
+export default function generate(bundles: SourceFile[], 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);
+    }),
+  )();
+}
+
+function generateDocumentationBundle(bundles: SourceFile[], config: UserDefinedMarkdownConfig) {
+  return generateDocs(bundles, {
+    ...config,
+    referenceGuideTemplate: referenceGuideTemplate,
+  });
+}
+
+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.fileName} processed.`, false, 'green', false);
+    },
+  );
+}
+
+function formatReflectionError(error: ReflectionError) {
+  return `Source file: ${error.file}\n${error.message}\n`;
+}

package/src/application/generators/openapi.ts

@@ -0,0 +1,56 @@
+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, SourceFile, UserDefinedOpenApiConfig } from '../../core/shared/types';
+import { OpenApiDocsProcessor } from '../../core/openapi/open-api-docs-processor';
+
+export default function openApi(fileBodies: SourceFile[], config: UserDefinedOpenApiConfig) {
+  const manifest = createManifest(new RawBodyParser(fileBodies), reflectionWithLogger);
+  TypesRepository.getInstance().populateAll(manifest.types);
+  const filteredTypes = filterByScopes(manifest);
+  const processor = new OpenApiDocsProcessor();
+  Transpiler.generate(filteredTypes, processor);
+  const generatedFiles = processor.fileBuilder().files();
+
+  FileWriter.write(generatedFiles, config.targetDir, (file: PageData) => {
+    Logger.logSingle(`${file.fileName} processed.`, false, 'green', false);
+  });
+
+  // Error logging
+  ErrorLogger.logErrors(filteredTypes);
+}
+
+function reflectionWithLogger(apexBundle: SourceFile): ReflectionResult {
+  const result = reflect(apexBundle.content);
+  if (result.error) {
+    Logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
+  }
+  return result;
+}
+
+function filterByScopes(manifest: Manifest) {
+  // If we are dealing with an OpenApi generator, we ignore the passed in access modifiers, and instead
+  // we only keep classes annotated as @RestResource
+  const filteredTypes = manifest.filteredByAccessModifierAndAnnotations([
+    'restresource',
+    'httpdelete',
+    'httpget',
+    'httppatch',
+    'httppost',
+    '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);
+  return filteredTypes;
+}