@cparra/apexdocs 2.25.0-alpha.1 → 2.25.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,9 +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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "2.25.0-alpha.1",
+  "version": "2.25.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",
-    "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",
@@ -37,18 +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/js-yaml": "^4.0.9",
     "@types/node": "^20.14.10",
     "@types/shelljs": "^0.8.15",
-    "@types/yargs": "^17.0.32",
-    "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.4.2",
     "prettier": "^3.3.2",
     "rimraf": "^6.0.0",
     "ts-jest": "^29.2.0",
@@ -66,14 +58,21 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.9.3",
-    "chalk": "^5.3.0",
+    "@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": "6.0.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,17 +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 '../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 { UserDefinedConfig } from '../core/shared/types';
 
 /**
  * Application entry-point to generate documentation out of Apex source files.
@@ -20,64 +13,18 @@ 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('Initializing...', false);
 
-    Settings.getInstance().onAfterProcess(files);
-
-    // Error logging
-    ErrorLogger.logErrors(filteredTypes);
-  }
+    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
 
-  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.`;
+    switch (config.targetGenerator) {
+      case 'markdown':
+        await markdown(fileBodies, config);
+        break;
+      case 'openapi':
+        openApi(fileBodies, config);
+        break;
     }
-    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 { 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 processFiles(fileSystem: FileSystem, rootPath: string, includeMetadata: boolean): UnparsedSourceFile[] {
+    let bundles: UnparsedSourceFile[] = [];
+
+    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,21 @@
+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 { filePath, content } = this.getTargetLocation(file, outputDir);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, content, 'utf8');
+      onWriteCallback(file);
+    });
+  }
+
+  private static getTargetLocation(file: PageData, outputDir: string): PageData {
+    return {
+      ...file,
+      filePath: path.join(outputDir, file.filePath),
+    };
+  }
+}

package/src/application/generators/markdown.ts

@@ -0,0 +1,58 @@
+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,
+  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';
+
+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);
+    }),
+  )();
+}
+
+function generateDocumentationBundle(bundles: UnparsedSourceFile[], 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.filePath} 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, UnparsedSourceFile, UserDefinedOpenApiConfig } from '../../core/shared/types';
+import { OpenApiDocsProcessor } from '../../core/openapi/open-api-docs-processor';
+
+export default function openApi(fileBodies: UnparsedSourceFile[], 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.filePath} processed.`, false, 'green', false);
+  });
+
+  // Error logging
+  ErrorLogger.logErrors(filteredTypes);
+}
+
+function reflectionWithLogger(apexBundle: UnparsedSourceFile): 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;
+}

package/src/cli/args.ts

@@ -0,0 +1,43 @@
+import { cosmiconfig, CosmiconfigResult } from 'cosmiconfig';
+import * as yargs from 'yargs';
+import { UserDefinedMarkdownConfig } from '../core/shared/types';
+import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
+import { markdownOptions } from './commands/markdown';
+
+/**
+ * Extracts configuration from a configuration file or the package.json
+ * through cosmiconfig.
+ */
+function _extractConfig(): Promise<CosmiconfigResult> {
+  return cosmiconfig('apexdocs', {
+    loaders: {
+      '.ts': TypeScriptLoader(),
+    },
+  }).search();
+}
+
+/**
+ * Extracts arguments from the command line.
+ * @param config The configuration object from the configuration file, if any.
+ */
+function _extractYargs(config?: CosmiconfigResult) {
+  return yargs
+    .config(config?.config)
+    .command('markdown', 'Generate documentation from Apex classes as a Markdown site.', (yargs) =>
+      yargs.options(markdownOptions),
+    )
+    .command('openapi', 'Generate an OpenApi REST specification from Apex classes.') // TODO: Add OpenApi specific options
+    .demandCommand()
+    .parseSync();
+}
+
+/**
+ * Combines the extracted configuration and arguments.
+ */
+export async function extractArgs(): Promise<UserDefinedMarkdownConfig> {
+  const config = await _extractConfig();
+  const cliArgs = _extractYargs(config);
+  const commandName = cliArgs._[0];
+
+  return { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
+}

package/src/cli/commands/markdown.ts

@@ -0,0 +1,52 @@
+import { Options } from 'yargs';
+import { defaults } from '../../defaults';
+
+export const markdownOptions: { [key: string]: Options } = {
+  sourceDir: {
+    type: 'string',
+    alias: 's',
+    demandOption: true,
+    describe: 'The directory location which contains your apex .cls classes.',
+  },
+  targetDir: {
+    type: 'string',
+    alias: 't',
+    default: defaults.targetDir,
+    describe: 'The directory location where documentation will be generated to.',
+  },
+  scope: {
+    type: 'string',
+    array: true,
+    alias: 'p',
+    default: defaults.scope,
+    describe:
+      'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
+      'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled.',
+  },
+  defaultGroupName: {
+    type: 'string',
+    default: defaults.defaultGroupName,
+    describe: 'Defines the @group name to be used when a file does not specify it.',
+  },
+  namespace: {
+    type: 'string',
+    describe:
+      'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
+      "If generating an OpenApi definition, it will be added to the file's Server Url.",
+  },
+  sortMembersAlphabetically: {
+    type: 'boolean',
+    describe: 'Whether to sort members alphabetically.',
+    default: defaults.sortMembersAlphabetically,
+  },
+  includeMetadata: {
+    type: 'boolean',
+    describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
+    default: defaults.includeMetadata,
+  },
+  documentationRootDir: {
+    type: 'string',
+    describe: 'The root directory of the documentation. This is used to generate the correct relative paths.',
+    default: defaults.documentationRootDir,
+  },
+};