@cparra/apexdocs 3.17.0-beta.5 → 3.17.0-beta.7

package/README.md

@@ -89,6 +89,14 @@ Here are some live projects using ApexDocs:
 * Custom tag support
 * And much, much more!
 
+## ⚡ Parallel reflection (performance)
+
+ApexDocs can speed up documentation generation by running reflection work in parallel (enabled by default).
+If you run into issues or want deterministic behavior, you can disable it with:
+
+- `--parallelReflection false`
+- or via config: `parallelReflection: false`
+
 ## 💿 Installation
 
 ```bash
@@ -157,6 +165,8 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 | `--lwcGroupName`                  | N/A   | The name under which Lightning Web Components will be grouped in the Reference Guide                                                                                                                     | `Lightning Web Components` | No       |
 | `--includeFieldSecurityMetadata`  | N/A   | Whether to include the compliance category and security classification for fields in the generated files.                                                                                                | `false`                    | No       |
 | `--includeInlineHelpTextMetadata` | N/A   | Whether to include the inline help text for fields in the generated files.                                                                                                                               | `false`                    | No       |
+| `--parallelReflection`            | N/A   | Parallelize CPU-heavy reflection via worker threads.                                                                                                                                                     | `true`                     | No       |
+| `--parallelReflectionMaxWorkers`  | N/A   | Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value based on CPU count.                                                                                     | N/A                        | No       |
 
 > **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
 > - `--sourceDir` (single directory or array of directories)
@@ -204,14 +214,16 @@ apexdocs markdown -s force-app -t docs -p global public namespaceaccessible -n M
 
 #### Flags
 
-| Flag           | Alias | Description                                                                   | Default         | Required |
-|----------------|-------|-------------------------------------------------------------------------------|-----------------|----------|
-| `--sourceDir`  | `-s`  | The directory where the source files are located.                             | N/A             | Yes      |
-| `--targetDir`  | `-t`  | The directory where the generated files will be placed.                       | `docs`          | No       |
-| `--fileName`   | N/A   | The name of the OpenApi file.                                                 | `openapi.json`  | No       |
-| `--namespace`  | N/A   | The package namespace, if any. This will be added to the API file Server Url. | N/A             | No       |
-| `--title`      | N/A   | The title of the OpenApi file.                                                | `Apex REST API` | No       |
-| `--apiVersion` | N/A   | The version of the API.                                                       | `1.0.0`         | No       |
+| Flag                           | Alias | Description                                                                                              | Default         | Required |
+|--------------------------------|-------|----------------------------------------------------------------------------------------------------------|-----------------|----------|
+| `--sourceDir`                  | `-s`  | The directory where the source files are located.                                                        | N/A             | Yes      |
+| `--targetDir`                  | `-t`  | The directory where the generated files will be placed.                                                  | `docs`          | No       |
+| `--fileName`                   | N/A   | The name of the OpenApi file.                                                                            | `openapi.json`  | No       |
+| `--namespace`                  | N/A   | The package namespace, if any. This will be added to the API file Server Url.                            | N/A             | No       |
+| `--title`                      | N/A   | The title of the OpenApi file.                                                                           | `Apex REST API` | No       |
+| `--apiVersion`                 | N/A   | The version of the API.                                                                                  | `1.0.0`         | No       |
+| `--parallelReflection`         | N/A   | Parallelize CPU-heavy reflection via worker threads.                                                      | `true`          | No       |
+| `--parallelReflectionMaxWorkers` | N/A | Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value.         | N/A             | No       |
 
 #### Sample Usage
 
@@ -225,15 +237,17 @@ apexdocs openapi -s force-app -t docs -n MyNamespace --title "My Custom OpenApi
 
 #### Flags
 
-| Flag                       | Alias | Description                                                                          | Default     | Required |
-|----------------------------|-------|--------------------------------------------------------------------------------------|-------------|----------|
-| `--previousVersionDir`     | `-p`  | The directory location of the previous version of the source code.                   | N/A         | Yes      |
-| `--currentVersionDir`      | `-t`  | The directory location of the current version of the source code.                    | N/A         | Yes      |
-| `--targetDir`              | `-t`  | The directory location where the changelog file will be generated.                   | `./docs/`   | No       |
-| `--fileName`               | N/A   | The name of the changelog file to be generated.                                      | `changelog` | No       |
-| `--scope`                  | N/A   | The list of scope to respect when generating the changelog.                          | ['global']  | No       |
-| `--customObjectVisibility` | `-v`  | Controls which custom objects are documented. Values should be separated by a space. | ['public']  | No       |
-| `--skipIfNoChanges`        | N/A   | Whether to skip generating the changelog if there are no changes.                    | `true`      | No       |
+| Flag                           | Alias | Description                                                                                              | Default     | Required |
+|--------------------------------|-------|----------------------------------------------------------------------------------------------------------|-------------|----------|
+| `--previousVersionDir`         | `-p`  | The directory location of the previous version of the source code.                                       | N/A         | Yes      |
+| `--currentVersionDir`          | `-t`  | The directory location of the current version of the source code.                                        | N/A         | Yes      |
+| `--targetDir`                  | `-t`  | The directory location where the changelog file will be generated.                                       | `./docs/`   | No       |
+| `--fileName`                   | N/A   | The name of the changelog file to be generated.                                                          | `changelog` | No       |
+| `--scope`                      | N/A   | The list of scope to respect when generating the changelog.                                              | ['global']  | No       |
+| `--customObjectVisibility`     | `-v`  | Controls which custom objects are documented. Values should be separated by a space.                     | ['public']  | No       |
+| `--skipIfNoChanges`            | N/A   | Whether to skip generating the changelog if there are no changes.                                        | `true`      | No       |
+| `--parallelReflection`         | N/A   | Parallelize CPU-heavy reflection via worker threads.                                                      | `true`      | No       |
+| `--parallelReflectionMaxWorkers` | N/A | Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value.         | N/A         | No       |
 
 #### Sample Usage
 

package/dist/cli/generate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-D8cfCwLW.js');
+var logger$1 = require('../logger-H9NRKPFV.js');
 var cosmiconfig = require('cosmiconfig');
 var yargs = require('yargs');
 var E = require('fp-ts/Either');
@@ -221,6 +221,16 @@ const openApiOptions = {
     type: "string",
     default: logger$1.openApiDefaults.apiVersion,
     describe: "The version of the OpenApi file."
+  },
+  parallelReflection: {
+    type: "boolean",
+    describe: "Parallelize CPU-heavy reflection via worker threads.",
+    default: logger$1.openApiDefaults.parallelReflection
+  },
+  parallelReflectionMaxWorkers: {
+    type: "number",
+    describe: "Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value based on CPU count.",
+    default: logger$1.openApiDefaults.parallelReflectionMaxWorkers
   }
 };
 
@@ -236,6 +246,16 @@ function validateChangelogArgs(argv) {
   return true;
 }
 const changeLogOptions = {
+  parallelReflection: {
+    type: "boolean",
+    describe: "Parallelize CPU-heavy reflection via worker threads.",
+    default: logger$1.markdownDefaults.parallelReflection
+  },
+  parallelReflectionMaxWorkers: {
+    type: "number",
+    describe: "Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value based on CPU count.",
+    default: logger$1.markdownDefaults.parallelReflectionMaxWorkers
+  },
   previousVersionDir: {
     type: "string",
     array: true,

package/dist/index.d.ts

@@ -433,6 +433,18 @@ type UserDefinedOpenApiConfig = {
   title: string;
   apiVersion: string;
   exclude: string[];
+
+  /**
+   * Parallelize CPU-heavy reflection via worker threads.
+   * Defaults to true.
+   */
+  parallelReflection: boolean;
+
+  /**
+   * Maximum number of worker threads to use for parallel reflection.
+   * Defaults to a reasonable value based on CPU count.
+   */
+  parallelReflectionMaxWorkers?: number;
 };
 
 type UserDefinedChangelogConfig = {
@@ -446,6 +458,18 @@ type UserDefinedChangelogConfig = {
   exclude: string[];
   skipIfNoChanges: boolean;
   translations?: UserTranslations['changelog'];
+
+  /**
+   * Parallelize CPU-heavy reflection via worker threads.
+   * Defaults to true.
+   */
+  parallelReflection: boolean;
+
+  /**
+   * Maximum number of worker threads to use for parallel reflection.
+   * Defaults to a reasonable value based on CPU count.
+   */
+  parallelReflectionMaxWorkers?: number;
 } & Partial<ChangelogConfigurableHooks>;
 
 type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig | UserDefinedChangelogConfig;

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger = require('./logger-D8cfCwLW.js');
+var logger = require('./logger-H9NRKPFV.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');

package/dist/{logger-D8cfCwLW.js → logger-H9NRKPFV.js}

@@ -1465,7 +1465,7 @@ function isWorkerReflectionEnabled(config) {
   return (_b = config == null ? void 0 : config.parallelReflection) != null ? _b : true;
 }
 function getWorkerEntrypointPath() {
-  const candidate = path$1.resolve(__dirname, "../../../apex-reflection.worker.js");
+  const candidate = path$1.resolve(__dirname, "./apex-reflection.worker.js");
   if (fs.existsSync(candidate)) {
     return candidate;
   }
@@ -2193,11 +2193,19 @@ const openApiDefaults = __spreadProps$j(__spreadValues$k({}, commonDefaults), {
   fileName: "openapi",
   title: "Apex REST API",
   apiVersion: "1.0.0",
-  exclude: []
+  exclude: [],
+  // Performance: parallel reflection via worker threads (enabled by default).
+  parallelReflection: true,
+  // Default is computed at runtime if not provided.
+  parallelReflectionMaxWorkers: void 0
 });
 const changeLogDefaults = __spreadProps$j(__spreadValues$k({}, markdownAndChangelogDefaults), {
   fileName: "changelog",
-  skipIfNoChanges: true
+  skipIfNoChanges: true,
+  // Performance: parallel reflection via worker threads (enabled by default).
+  parallelReflection: true,
+  // Default is computed at runtime if not provided.
+  parallelReflectionMaxWorkers: void 0
 });
 
 const customObjectTemplate = `
@@ -4758,7 +4766,32 @@ function openApi(logger, fileBodies, config) {
       namespace: config.namespace,
       version: config.apiVersion
     });
-    const manifest = createManifest(new RawBodyParser(logger, fileBodies), apply(reflectionWithLogger, logger));
+    const parsedFilesEither = yield reflectApexSource(fileBodies, {
+      parallelReflection: config.parallelReflection,
+      parallelReflectionMaxWorkers: config.parallelReflectionMaxWorkers
+    })();
+    if (E__namespace.isLeft(parsedFilesEither)) {
+      const errors = parsedFilesEither.left;
+      logger.error(errors);
+      return;
+    }
+    const parsedFiles = parsedFilesEither.right;
+    const reflectionByPath = /* @__PURE__ */ new Map();
+    for (const parsed of parsedFiles) {
+      if (!("filePath" in parsed.source)) {
+        continue;
+      }
+      reflectionByPath.set(parsed.source.filePath, { typeMirror: parsed.type });
+    }
+    function reflectFromMap(apexBundle) {
+      const result = reflectionByPath.get(apexBundle.filePath);
+      if (result) {
+        return result;
+      }
+      logger.error(`${apexBundle.filePath} - Parsing error Unknown error`);
+      return { typeMirror: null, error: new Error("Unknown error") };
+    }
+    const manifest = createManifest(new RawBodyParser(logger, fileBodies), reflectFromMap);
     TypesRepository.getInstance().populateAll(manifest.types);
     const filteredTypes = filterByScopes(logger, manifest);
     const processor = new OpenApiDocsProcessor(logger);
@@ -4773,14 +4806,6 @@ function openApi(logger, fileBodies, config) {
     ErrorLogger.logErrors(logger, filteredTypes);
   });
 }
-function reflectionWithLogger(logger, apexBundle) {
-  var _a;
-  const result = apexReflection.reflect(apexBundle.content);
-  if (result.error) {
-    logger.error(`${apexBundle.filePath} - Parsing error ${(_a = result.error) == null ? void 0 : _a.message}`);
-  }
-  return result;
-}
 function filterByScopes(logger, manifest) {
   const filteredTypes = manifest.filteredByAccessModifierAndAnnotations([
     "restresource",
@@ -5434,9 +5459,12 @@ var __async$1 = (__this, __arguments, generator) => {
     step((generator = generator.apply(__this, __arguments)).next());
   });
 };
-const changelogReflectionConfig = {
-  parallelReflection: false
-};
+function changelogReflectionConfig(config) {
+  return {
+    parallelReflection: config.parallelReflection,
+    parallelReflectionMaxWorkers: config.parallelReflectionMaxWorkers
+  };
+}
 function generateChangeLog(oldBundles, newBundles, config) {
   const convertToPageData = apply(toPageData, config.fileName);
   function handleConversion({ changelog, newManifest }) {
@@ -5467,7 +5495,7 @@ function generateChangeLog(oldBundles, newBundles, config) {
 function reflect(bundles, config) {
   const filterOutOfScopeApex = apply(filterScope, config.scope);
   function reflectApexFiles(sourceFiles) {
-    return _function.pipe(reflectApexSource(sourceFiles, changelogReflectionConfig), TE__namespace.map(filterOutOfScopeApex));
+    return _function.pipe(reflectApexSource(sourceFiles, changelogReflectionConfig(config)), TE__namespace.map(filterOutOfScopeApex));
   }
   return _function.pipe(
     // Filter out LWC. These will be implemented at a later date

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.17.0-beta.5",
+  "version": "3.17.0-beta.7",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "engines": {
     "node": ">=18"
@@ -96,7 +96,7 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.21.1",
+    "@cparra/apex-reflection": "2.22.0",
     "@salesforce/source-deploy-retrieve": "^12.20.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",