@cparra/apexdocs 3.17.0-beta.6 → 3.17.0

package/README.md

@@ -157,6 +157,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 +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       |
+| 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 +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       |
+| 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
 
@@ -577,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-PMTbceqG.js');
+var logger$1 = require('../logger-Cr1iCXZc.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

@@ -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,6 +423,8 @@ type UserDefinedOpenApiConfig = {
   title: string;
   apiVersion: string;
   exclude: string[];
+  parallelReflection: boolean;
+  parallelReflectionMaxWorkers?: number;
 };
 
 type UserDefinedChangelogConfig = {
@@ -446,6 +438,8 @@ type UserDefinedChangelogConfig = {
   exclude: string[];
   skipIfNoChanges: boolean;
   translations?: UserTranslations['changelog'];
+  parallelReflection: boolean;
+  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-PMTbceqG.js');
+var logger = require('./logger-Cr1iCXZc.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');

package/dist/{logger-PMTbceqG.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,20 +2169,22 @@ 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), {
   fileName: "openapi",
   title: "Apex REST API",
   apiVersion: "1.0.0",
-  exclude: []
+  exclude: [],
+  parallelReflection: true,
+  parallelReflectionMaxWorkers: void 0
 });
 const changeLogDefaults = __spreadProps$j(__spreadValues$k({}, markdownAndChangelogDefaults), {
   fileName: "changelog",
-  skipIfNoChanges: true
+  skipIfNoChanges: true,
+  parallelReflection: true,
+  parallelReflectionMaxWorkers: void 0
 });
 
 const customObjectTemplate = `
@@ -4758,7 +4745,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 +4785,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 +5438,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 +5474,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.6",
+  "version": "3.17.0",
   "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",