@cparra/apexdocs 3.17.0-beta.7 → 3.17.0

package/README.md

@@ -89,14 +89,6 @@ 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
@@ -166,7 +158,7 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 | `--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       |
+| `--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)
@@ -214,16 +206,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       |
-| `--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       |
+| 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
 
@@ -237,17 +229,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       |
-| `--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       |
+| 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
 
@@ -591,12 +583,14 @@ public class MyClass {
 
 ##### **templates**
 
-Allows providing custom templates for generating Markdown documentation, giving you control over the output format. 
+Allows providing custom templates for generating Markdown documentation, giving you control over the output format.
 You can define templates for each type of metadata
 supported by the `markdown` command (class, interface, enum, trigger, LWC, custom object, and reference guide) .
 
-For detailed information about creating custom templates, including examples, available helpers, and configuration options, 
-please refer to the [wiki documentation](https://github.com/cesarParra/apexdocs/wiki/5.-Custom-Templates). You can also find a working example in the 
+For detailed information about creating custom templates, including examples, available helpers, and configuration
+options,
+please refer to the [wiki documentation](https://github.com/cesarParra/apexdocs/wiki/5.-Custom-Templates). You can also
+find a working example in the
 `examples/markdown-custom-templates` directory.
 
 #### Changelog Hooks

package/dist/apex-reflection.worker.js

@@ -2,23 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_worker_threads_1 = require("node:worker_threads");
 const apex_reflection_1 = require("@cparra/apex-reflection");
-function isRequestMessage(msg) {
-    if (!msg || typeof msg !== 'object')
+function isRequestMessage(message) {
+    if (!message || typeof message !== 'object') {
         return false;
-    const m = msg;
-    if (typeof m.id !== 'number')
+    }
+    const candidateMessage = message;
+    if (typeof candidateMessage.id !== 'number') {
         return false;
-    if (!m.payload || typeof m.payload !== 'object')
+    }
+    if (!candidateMessage.payload || typeof candidateMessage.payload !== 'object') {
         return false;
-    const p = m.payload;
-    return typeof p.content === 'string';
+    }
+    const candidatePayload = candidateMessage.payload;
+    return typeof candidatePayload.content === 'string';
 }
-function post(msg) {
+function post(responseMessage) {
     // `parentPort` should always exist in a worker, but guard anyway.
     if (!node_worker_threads_1.parentPort) {
         return;
     }
-    node_worker_threads_1.parentPort.postMessage(msg);
+    node_worker_threads_1.parentPort.postMessage(responseMessage);
 }
 function reflectOrThrow(rawSource) {
     const result = (0, apex_reflection_1.reflect)(rawSource);
@@ -33,25 +36,23 @@ function reflectOrThrow(rawSource) {
 if (!node_worker_threads_1.parentPort) {
     throw new Error('apex-reflection.worker started without a parentPort');
 }
-node_worker_threads_1.parentPort.on('message', (msg) => {
-    if (!isRequestMessage(msg)) {
+node_worker_threads_1.parentPort.on('message', (message) => {
+    if (!isRequestMessage(message)) {
         // Can't correlate without a valid id; ignore.
         return;
     }
-    const { id, payload } = msg;
+    const { id, payload } = message;
     try {
         const typeMirror = reflectOrThrow(payload.content);
         post({ id, ok: true, result: typeMirror });
     }
-    catch (e) {
-        const message = (e === null || e === void 0 ? void 0 : e.message) &&
-            typeof e.message === 'string'
-            ? e.message
-            : 'Unknown error';
+    catch (caughtError) {
+        const candidateMessage = caughtError === null || caughtError === void 0 ? void 0 : caughtError.message;
+        const errorMessage = typeof candidateMessage === 'string' ? candidateMessage : 'Unknown error';
         post({
             id,
             ok: false,
-            error: { message },
+            error: { message: errorMessage },
         });
     }
 });

package/dist/cli/generate.js

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

package/dist/index.d.ts

@@ -400,17 +400,7 @@ type CliConfigurableMarkdownConfig = {
   includeFieldSecurityMetadata: boolean;
   includeInlineHelpTextMetadata: boolean;
   experimentalLwcSupport: boolean;
-
-  /**
-   * Whether to parallelize CPU-heavy reflection steps via worker threads.
-   * Defaults to true.
-   */
   parallelReflection: boolean;
-
-  /**
-   * Max number of worker threads to use for parallel reflection.
-   * Defaults to a reasonable value based on CPU count.
-   */
   parallelReflectionMaxWorkers?: number;
 };
 
@@ -433,17 +423,7 @@ 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;
 };
 
@@ -458,17 +438,7 @@ 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>;
 

package/dist/index.js

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

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

@@ -1198,21 +1198,6 @@ class WorkerPool {
       this.pump();
     });
   }
-  /**
-   * Returns current pool stats.
-   */
-  stats() {
-    return {
-      maxWorkers: this.maxWorkers,
-      activeWorkers: this.allWorkers.size,
-      idleWorkers: this.idleWorkers.length,
-      queuedTasks: this.queue.length,
-      inFlightTasks: this.inFlightByWorker.size,
-      createdWorkers: this.createdWorkers,
-      completedTasks: this.completedTasks,
-      failedTasks: this.failedTasks
-    };
-  }
   /**
    * Terminates all workers and rejects queued tasks (unless drainOnTerminate=true).
    *
@@ -1277,8 +1262,7 @@ class WorkerPool {
     const idleWorker = this.idleWorkers.pop();
     if (idleWorker) return idleWorker;
     if (this.allWorkers.size < this.maxWorkers) {
-      const spawnedWorker = this.spawnWorker();
-      return spawnedWorker;
+      return this.spawnWorker();
     }
     return null;
   }
@@ -1460,8 +1444,12 @@ function supportsWorkerThreads() {
 function isWorkerReflectionEnabled(config) {
   var _a, _b;
   const env = ((_a = process.env.APEXDOCS_WORKER_REFLECTION) != null ? _a : "").toLowerCase();
-  if (env === "true" || env === "1") return true;
-  if (env === "false" || env === "0") return false;
+  if (env === "true" || env === "1") {
+    return true;
+  }
+  if (env === "false" || env === "0") {
+    return false;
+  }
   return (_b = config == null ? void 0 : config.parallelReflection) != null ? _b : true;
 }
 function getWorkerEntrypointPath() {
@@ -1480,16 +1468,13 @@ function reflectAsTaskParallel(apexBundles, config) {
       const maxWorkers = Math.max(1, (_c = config == null ? void 0 : config.parallelReflectionMaxWorkers) != null ? _c : defaultMax);
       const pool = new WorkerPool(() => new node_worker_threads.Worker(getWorkerEntrypointPath()), {
         maxWorkers
-        // Keep default queue size (Infinity) unless we later decide to bound it via config.
       });
       try {
-        const results = yield Promise.all(
+        return yield Promise.all(
           apexBundles.map((bundle) => __async$5(null, null, function* () {
-            const typeMirror = yield pool.run({ content: bundle.content });
-            return typeMirror;
+            return yield pool.run({ content: bundle.content });
           }))
         );
-        return results;
       } finally {
         yield pool.terminate();
       }
@@ -2184,9 +2169,7 @@ const markdownDefaults = __spreadProps$j(__spreadValues$k({}, markdownAndChangel
   includeFieldSecurityMetadata: false,
   includeInlineHelpTextMetadata: false,
   experimentalLwcSupport: false,
-  // Performance: parallel reflection via worker threads (enabled by default).
   parallelReflection: true,
-  // Default is computed at runtime if not provided.
   parallelReflectionMaxWorkers: void 0
 });
 const openApiDefaults = __spreadProps$j(__spreadValues$k({}, commonDefaults), {
@@ -2194,17 +2177,13 @@ const openApiDefaults = __spreadProps$j(__spreadValues$k({}, commonDefaults), {
   title: "Apex REST API",
   apiVersion: "1.0.0",
   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,
-  // Performance: parallel reflection via worker threads (enabled by default).
   parallelReflection: true,
-  // Default is computed at runtime if not provided.
   parallelReflectionMaxWorkers: void 0
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.17.0-beta.7",
+  "version": "3.17.0",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "engines": {
     "node": ">=18"