@cparra/apexdocs 3.12.1 → 3.13.0

package/README.md

@@ -84,6 +84,12 @@ Run the following command to generate markdown files for your global Salesforce
 
 ```bash
 apexdocs markdown -s force-app
+
+# Use sfdx-project.json as the source of directories
+apexdocs markdown --useSfdxProjectJson
+
+# Specify multiple source directories
+apexdocs markdown --sourceDirs force-app force-lwc force-utils
 ```
 
 #### OpenApi
@@ -111,21 +117,31 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 
 #### 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       |
-| `--scope`                  | `-p`  | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible.                                                                                      | `[global]`       | No       |
-| `--customObjectVisibility` | `-v`  | Controls which custom objects are documented. Values should be separated by a space.                                                                                                                     | `[public]`       | No       |
-| `--defaultGroupName`       | N/A   | The default group name to use when a group is not specified.                                                                                                                                             | `Miscellaneous`  | No       |
-| `--namespace`              | N/A   | The package namespace, if any. If provided, it will be added to the generated files.                                                                                                                     | N/A              | No       |
-| `--sortAlphabetically`     | N/A   | Sorts files appearing in the Reference Guide alphabetically, as well as the members of a class, interface or enum alphabetically. If false, the members will be displayed in the same order as the code. | `false`          | No       |
-| `--includeMetadata `       | N/A   | Whether to include the file's meta.xml information: Whether it is active and and the API version                                                                                                         | `false`          | No       |
-| `--linkingStrategy`        | N/A   | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none`                                                                                                 | `relative`       | No       |
-| `--customObjectsGroupName` | N/A   | The name under which custom objects will be grouped in the Reference Guide                                                                                                                               | `Custom Objects` | No       |
-| `--triggersGroupName`      | N/A   | The name under which triggers will be grouped in the Reference Guide                                                                                                                                     | `Triggers`       | 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       |
+| Flag                              | Alias | Description                                                                                                                                                                                              | Default          | Required |
+|-----------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
+| `--sourceDir`                     | `-s`  | The directory where the source files are located.                                                                                                                                                        | N/A              | *        |
+| `--sourceDirs`                    | N/A   | Multiple source directories (space-separated). Cannot be used with `--sourceDir` or `--useSfdxProjectJson`.                                                                                              | N/A              | *        |
+| `--useSfdxProjectJson`            | N/A   | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir` or `--sourceDirs`.                                                                                | `false`          | *        |
+| `--sfdxProjectPath`               | N/A   | Path to directory containing `sfdx-project.json` (defaults to current directory). Only used with `--useSfdxProjectJson`.                                                                                 | `process.cwd()`  | No       |
+| `--targetDir`                     | `-t`  | The directory where the generated files will be placed.                                                                                                                                                  | `docs`           | No       |
+| `--scope`                         | `-p`  | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible.                                                                                      | `[global]`       | No       |
+| `--customObjectVisibility`        | `-v`  | Controls which custom objects are documented. Values should be separated by a space.                                                                                                                     | `[public]`       | No       |
+| `--defaultGroupName`              | N/A   | The default group name to use when a group is not specified.                                                                                                                                             | `Miscellaneous`  | No       |
+| `--namespace`                     | N/A   | The package namespace, if any. If provided, it will be added to the generated files.                                                                                                                     | N/A              | No       |
+| `--sortAlphabetically`            | N/A   | Sorts files appearing in the Reference Guide alphabetically, as well as the members of a class, interface or enum alphabetically. If false, the members will be displayed in the same order as the code. | `false`          | No       |
+| `--includeMetadata `              | N/A   | Whether to include the file's meta.xml information: Whether it is active and and the API version                                                                                                         | `false`          | No       |
+| `--linkingStrategy`               | N/A   | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none`                                                                                                 | `relative`       | No       |
+| `--customObjectsGroupName`        | N/A   | The name under which custom objects will be grouped in the Reference Guide                                                                                                                               | `Custom Objects` | No       |
+| `--triggersGroupName`             | N/A   | The name under which triggers will be grouped in the Reference Guide                                                                                                                                     | `Triggers`       | 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       |
+
+> **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
+> - `--sourceDir` (single directory)
+> - `--sourceDirs` (multiple directories)
+> - `--useSfdxProjectJson` (read from sfdx-project.json)
+>
+> These options are mutually exclusive - you cannot use more than one at the same time.
 
 ##### Linking Strategy
 
@@ -365,7 +381,8 @@ having to copy-paste the same text across multiple classes, polluting your
 source code.
 
 A macro can be defined in your documentation using the `{{macro_name}}` syntax.
-In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the macro, and the value is a function that returns the text to inject in place of the macro.
+In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the
+macro, and the value is a function that returns the text to inject in place of the macro.
 
 **Type**
 
@@ -379,7 +396,8 @@ type MacroSourceMetadata = {
 type MacroFunction = (metadata: MacroSourceMetadata) => string;
 ```
 
-Notice that the `metadata` object contains information about the source of the file for which the macro is being injected. This allows you to optionally
+Notice that the `metadata` object contains information about the source of the file for which the macro is being
+injected. This allows you to optionally
 return different text based on the source of the file.
 
 Example: Injecting a copyright notice
@@ -402,13 +420,14 @@ And then in your source code, you can use the macro like this:
  * @description This is a class
  */
 public class MyClass {
-  //...
+    //...
 }
 ```
 
 ##### **transformReferenceGuide**
 
-Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether should be skipped.
+Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether
+should be skipped.
 
 **Type**
 

package/dist/cli/generate.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-dCI_xpGU.js');
-var module$1 = require('module');
+var logger$1 = require('../logger-BiPQ_i9-.js');
+var require$$0 = require('yargs');
 var cosmiconfig = require('cosmiconfig');
 var E = require('fp-ts/Either');
 var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
@@ -24,38 +24,53 @@ require('minimatch');
 require('@salesforce/source-deploy-retrieve');
 require('chalk');
 
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopNamespaceDefault(e) {
-	var n = Object.create(null);
-	if (e) {
-		Object.keys(e).forEach(function (k) {
-			if (k !== 'default') {
-				var d = Object.getOwnPropertyDescriptor(e, k);
-				Object.defineProperty(n, k, d.get ? d : {
-					enumerable: true,
-					get: function () { return e[k]; }
-				});
-			}
-		});
-	}
-	n.default = e;
-	return Object.freeze(n);
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
 }
 
 var E__namespace = /*#__PURE__*/_interopNamespaceDefault(E);
 
-var require$1 = (
-			false
-				? /* @__PURE__ */ module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli/generate.js', document.baseURI).href)))
-				: require
-		);
-
+function validateMarkdownArgs(argv) {
+  const hasSourceDir = argv.sourceDir && (typeof argv.sourceDir === "string" || Array.isArray(argv.sourceDir) && argv.sourceDir.length > 0);
+  const hasUseSfdxProjectJson = argv.useSfdxProjectJson;
+  if (!hasSourceDir && !hasUseSfdxProjectJson) {
+    throw new Error("Must specify one of: --sourceDir or --useSfdxProjectJson");
+  }
+  return true;
+}
 const markdownOptions = {
   sourceDir: {
     type: "string",
+    array: true,
     alias: "s",
-    demandOption: true,
-    describe: "The directory location which contains your apex .cls classes."
+    demandOption: false,
+    describe: "The directory location(s) which contain your apex .cls classes. Can specify a single directory or multiple directories. Cannot be used with useSfdxProjectJson.",
+    conflicts: ["useSfdxProjectJson"]
+  },
+  useSfdxProjectJson: {
+    type: "boolean",
+    demandOption: false,
+    describe: "Read source directories from sfdx-project.json packageDirectories. Cannot be used with sourceDir.",
+    conflicts: ["sourceDir"]
+  },
+  sfdxProjectPath: {
+    type: "string",
+    demandOption: false,
+    describe: "Path to the directory containing sfdx-project.json (defaults to current working directory). Only used with useSfdxProjectJson.",
+    implies: "useSfdxProjectJson"
   },
   targetDir: {
     type: "string",
@@ -129,12 +144,34 @@ const markdownOptions = {
   }
 };
 
+function validateOpenApiArgs(argv) {
+  const hasSourceDir = argv.sourceDir && (typeof argv.sourceDir === "string" || Array.isArray(argv.sourceDir) && argv.sourceDir.length > 0);
+  const hasUseSfdxProjectJson = argv.useSfdxProjectJson;
+  if (!hasSourceDir && !hasUseSfdxProjectJson) {
+    throw new Error("Must specify one of: --sourceDir or --useSfdxProjectJson");
+  }
+  return true;
+}
 const openApiOptions = {
   sourceDir: {
     type: "string",
+    array: true,
     alias: "s",
-    demandOption: true,
-    describe: "The directory location which contains your apex .cls classes."
+    demandOption: false,
+    describe: "The directory location(s) which contain your apex .cls classes. Can specify a single directory or multiple directories. Cannot be used with useSfdxProjectJson.",
+    conflicts: ["useSfdxProjectJson"]
+  },
+  useSfdxProjectJson: {
+    type: "boolean",
+    demandOption: false,
+    describe: "Read source directories from sfdx-project.json packageDirectories. Cannot be used with sourceDir.",
+    conflicts: ["sourceDir"]
+  },
+  sfdxProjectPath: {
+    type: "string",
+    demandOption: false,
+    describe: "Path to the directory containing sfdx-project.json (defaults to current working directory). Only used with useSfdxProjectJson.",
+    implies: "useSfdxProjectJson"
   },
   targetDir: {
     type: "string",
@@ -163,18 +200,31 @@ const openApiOptions = {
   }
 };
 
+function validateChangelogArgs(argv) {
+  const hasPreviousVersionDir = argv.previousVersionDir && (typeof argv.previousVersionDir === "string" || Array.isArray(argv.previousVersionDir) && argv.previousVersionDir.length > 0);
+  const hasCurrentVersionDir = argv.currentVersionDir && (typeof argv.currentVersionDir === "string" || Array.isArray(argv.currentVersionDir) && argv.currentVersionDir.length > 0);
+  if (!hasPreviousVersionDir) {
+    throw new Error("Must specify --previousVersionDir");
+  }
+  if (!hasCurrentVersionDir) {
+    throw new Error("Must specify --currentVersionDir");
+  }
+  return true;
+}
 const changeLogOptions = {
   previousVersionDir: {
     type: "string",
+    array: true,
     alias: "p",
-    demandOption: true,
-    describe: "The directory location of the previous version of the source code."
+    demandOption: false,
+    describe: "The directory location(s) of the previous version of the source code. Can specify a single directory or multiple directories."
   },
   currentVersionDir: {
     type: "string",
+    array: true,
     alias: "c",
-    demandOption: true,
-    describe: "The directory location of the current version of the source code."
+    demandOption: false,
+    describe: "The directory location(s) of the current version of the source code. Can specify a single directory or multiple directories."
   },
   targetDir: {
     type: "string",
@@ -248,7 +298,7 @@ var __async$1 = (__this, __arguments, generator) => {
     step((generator = generator.apply(__this, __arguments)).next());
   });
 };
-const yargs = require$1("yargs");
+const yargs = require$$0;
 const configOnlyMarkdownDefaults = {
   targetGenerator: "markdown",
   excludeTags: [],
@@ -304,11 +354,23 @@ function extractArgsForCommandProvidedThroughCli(extractFromProcessFn, config) {
   const mergedConfig = __spreadProps(__spreadValues(__spreadValues({}, config.config), cliArgs), { targetGenerator: commandName });
   switch (mergedConfig.targetGenerator) {
     case "markdown":
-      return E__namespace.right(__spreadValues(__spreadValues({}, configOnlyMarkdownDefaults), mergedConfig));
+      return _function.pipe(
+        logger$1.validateSourceDirectoryConfig(extractSourceDirectoryConfig(mergedConfig)),
+        E__namespace.mapLeft((error) => new Error(`Invalid markdown configuration: ${error.message}`)),
+        E__namespace.map(() => __spreadValues(__spreadValues({}, configOnlyMarkdownDefaults), mergedConfig))
+      );
     case "openapi":
-      return E__namespace.right(__spreadValues(__spreadValues({}, configOnlyOpenApiDefaults), mergedConfig));
+      return _function.pipe(
+        logger$1.validateSourceDirectoryConfig(extractSourceDirectoryConfig(mergedConfig)),
+        E__namespace.mapLeft((error) => new Error(`Invalid openapi configuration: ${error.message}`)),
+        E__namespace.map(() => __spreadValues(__spreadValues({}, configOnlyOpenApiDefaults), mergedConfig))
+      );
     case "changelog":
-      return E__namespace.right(__spreadValues(__spreadValues({}, configOnlyChangelogDefaults), mergedConfig));
+      return _function.pipe(
+        validateChangelogConfig(mergedConfig),
+        E__namespace.mapLeft((error) => new Error(`Invalid changelog configuration: ${error.message}`)),
+        E__namespace.map(() => __spreadValues(__spreadValues({}, configOnlyChangelogDefaults), mergedConfig))
+      );
     default:
       return E__namespace.left(new Error(`Invalid command provided: ${mergedConfig.targetGenerator}`));
   }
@@ -324,12 +386,26 @@ function extractArgsForCommandsProvidedInConfig(extractFromProcessFn, config) {
           E__namespace.map((cliArgs) => {
             return cliArgs;
           }),
-          E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyMarkdownDefaults), generatorConfig), cliArgs))
+          E__namespace.flatMap((cliArgs) => {
+            const mergedConfig = __spreadValues(__spreadValues(__spreadValues({}, configOnlyMarkdownDefaults), generatorConfig), cliArgs);
+            return _function.pipe(
+              logger$1.validateSourceDirectoryConfig(extractSourceDirectoryConfig(mergedConfig)),
+              E__namespace.mapLeft((error) => new Error(`Invalid markdown configuration: ${error.message}`)),
+              E__namespace.map(() => mergedConfig)
+            );
+          })
         );
       case "openapi":
         return _function.pipe(
           extractMultiCommandConfig(extractFromProcessFn, "openapi", generatorConfig),
-          E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyOpenApiDefaults), generatorConfig), cliArgs))
+          E__namespace.flatMap((cliArgs) => {
+            const mergedConfig = __spreadValues(__spreadValues(__spreadValues({}, configOnlyOpenApiDefaults), generatorConfig), cliArgs);
+            return _function.pipe(
+              logger$1.validateSourceDirectoryConfig(extractSourceDirectoryConfig(mergedConfig)),
+              E__namespace.mapLeft((error) => new Error(`Invalid openapi configuration: ${error.message}`)),
+              E__namespace.map(() => mergedConfig)
+            );
+          })
         );
       case "changelog":
         return _function.pipe(
@@ -337,7 +413,14 @@ function extractArgsForCommandsProvidedInConfig(extractFromProcessFn, config) {
           E__namespace.map((cliArgs) => {
             return cliArgs;
           }),
-          E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyChangelogDefaults), generatorConfig), cliArgs))
+          E__namespace.flatMap((cliArgs) => {
+            const mergedConfig = __spreadValues(__spreadValues(__spreadValues({}, configOnlyChangelogDefaults), generatorConfig), cliArgs);
+            return _function.pipe(
+              validateChangelogConfig(mergedConfig),
+              E__namespace.mapLeft((error) => new Error(`Invalid changelog configuration: ${error.message}`)),
+              E__namespace.map(() => mergedConfig)
+            );
+          })
         );
     }
   });
@@ -367,15 +450,15 @@ function extractYargsDemandingCommand(extractFromProcessFn, config) {
   return yargs.config(config.config).command(
     "markdown",
     "Generate documentation from Apex classes as a Markdown site.",
-    (yargs2) => yargs2.options(markdownOptions)
+    (yargs2) => yargs2.options(markdownOptions).check(validateMarkdownArgs)
   ).command(
     "openapi",
     "Generate an OpenApi REST specification from Apex classes.",
-    () => yargs.options(openApiOptions)
+    (yargs2) => yargs2.options(openApiOptions).check(validateOpenApiArgs)
   ).command(
     "changelog",
     "Generate a changelog from 2 versions of the source code.",
-    () => yargs.options(changeLogOptions)
+    (yargs2) => yargs2.options(changeLogOptions).check(validateChangelogArgs)
   ).demandCommand().parseSync(extractFromProcessFn());
 }
 function extractMultiCommandConfig(extractFromProcessFn, command, config) {
@@ -389,13 +472,45 @@ function extractMultiCommandConfig(extractFromProcessFn, command, config) {
         return changeLogOptions;
     }
   }
+  function getValidationFunction(generator) {
+    switch (generator) {
+      case "markdown":
+        return validateMarkdownArgs;
+      case "openapi":
+        return validateOpenApiArgs;
+      case "changelog":
+        return validateChangelogArgs;
+    }
+  }
   const options = getOptions(command);
+  const validator = getValidationFunction(command);
   return E__namespace.tryCatch(() => {
-    return yargs(extractFromProcessFn()).config(config).options(options).fail((msg) => {
+    return yargs(extractFromProcessFn()).config(config).options(options).check(validator).fail((msg) => {
       throw new Error(`Invalid configuration for command "${command}": ${msg}`);
     }).parseSync();
   }, E__namespace.toError);
 }
+function extractSourceDirectoryConfig(config) {
+  return {
+    sourceDir: config.sourceDir,
+    useSfdxProjectJson: config.useSfdxProjectJson,
+    sfdxProjectPath: config.sfdxProjectPath
+  };
+}
+function validateChangelogConfig(config) {
+  const previousVersionConfig = {
+    sourceDir: config.previousVersionDir
+  };
+  const currentVersionConfig = {
+    sourceDir: config.currentVersionDir
+  };
+  return _function.pipe(
+    E__namespace.Do,
+    E__namespace.bind("previousValid", () => logger$1.validateSourceDirectoryConfig(previousVersionConfig)),
+    E__namespace.bind("currentValid", () => logger$1.validateSourceDirectoryConfig(currentVersionConfig)),
+    E__namespace.map(() => config)
+  );
+}
 
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
@@ -428,8 +543,8 @@ function main() {
     logger.error(`\u274C An error occurred while processing the request: ${error}`);
     process.exit(1);
   }
-  extractArgs().then((maybeConfigs) => __async(this, null, function* () {
-    E__namespace.match(catchUnexpectedError, (configs) => __async(this, null, function* () {
+  extractArgs().then((maybeConfigs) => __async(null, null, function* () {
+    E__namespace.match(catchUnexpectedError, (configs) => __async(null, null, function* () {
       for (const config of configs) {
         yield logger$1.Apexdocs.generate(config, logger).then(parseResult);
       }

package/dist/index.d.ts

@@ -20,7 +20,9 @@ type MacroSourceMetadata = {
 type MacroFunction = (metadata: MacroSourceMetadata) => string;
 
 type CliConfigurableMarkdownConfig = {
-  sourceDir: string;
+  sourceDir?: string | string[];
+  useSfdxProjectJson?: boolean;
+  sfdxProjectPath?: string;
   targetDir: string;
   scope: string[];
   customObjectVisibility: string[];
@@ -45,7 +47,9 @@ type UserDefinedMarkdownConfig = {
 
 type UserDefinedOpenApiConfig = {
   targetGenerator: 'openapi';
-  sourceDir: string;
+  sourceDir?: string | string[];
+  useSfdxProjectJson?: boolean;
+  sfdxProjectPath?: string;
   targetDir: string;
   fileName: string;
   namespace?: string;
@@ -56,8 +60,8 @@ type UserDefinedOpenApiConfig = {
 
 type UserDefinedChangelogConfig = {
   targetGenerator: 'changelog';
-  previousVersionDir: string;
-  currentVersionDir: string;
+  previousVersionDir?: string | string[];
+  currentVersionDir?: string | string[];
   targetDir: string;
   fileName: string;
   scope: string[];

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var logger = require('./logger-dCI_xpGU.js');
+var logger = require('./logger-BiPQ_i9-.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');

package/dist/{logger-dCI_xpGU.js → logger-BiPQ_i9-.js}

@@ -2719,8 +2719,8 @@ function transformDocumentationBundleHook(config) {
     (error) => new HookError(error)
   );
 }
-const execTransformReferenceHook = (_0, ..._1) => __async$3(void 0, [_0, ..._1], function* (references, hook = passThroughHook) {
-  const hooked = references.map((reference) => __async$3(void 0, null, function* () {
+const execTransformReferenceHook = (_0, ..._1) => __async$3(null, [_0, ..._1], function* (references, hook = passThroughHook) {
+  const hooked = references.map((reference) => __async$3(null, null, function* () {
     const hookedResult = yield hook(reference);
     return __spreadValues$8(__spreadValues$8({}, reference), hookedResult);
   }));
@@ -2730,24 +2730,24 @@ const execTransformReferenceHook = (_0, ..._1) => __async$3(void 0, [_0, ..._1],
     return acc;
   }, {});
 });
-const documentationBundleHook = (bundle, config) => __async$3(void 0, null, function* () {
+const documentationBundleHook = (bundle, config) => __async$3(null, null, function* () {
   return {
     referenceGuide: yield transformReferenceGuide(bundle.referenceGuide, config.transformReferenceGuide),
     docs: yield transformDocs(bundle.docs, config.transformDocs, config.transformDocPage)
   };
 });
-const transformReferenceGuide = (_0, ..._1) => __async$3(void 0, [_0, ..._1], function* (referenceGuide, hook = passThroughHook) {
+const transformReferenceGuide = (_0, ..._1) => __async$3(null, [_0, ..._1], function* (referenceGuide, hook = passThroughHook) {
   const result = yield hook(referenceGuide);
   if (isSkip(result)) {
     return result;
   }
   return __spreadValues$8(__spreadValues$8({}, referenceGuide), yield hook(referenceGuide));
 });
-const transformDocs = (_0, ..._1) => __async$3(void 0, [_0, ..._1], function* (docs, transformDocsHook = passThroughHook, transformDocPageHook = passThroughHook) {
+const transformDocs = (_0, ..._1) => __async$3(null, [_0, ..._1], function* (docs, transformDocsHook = passThroughHook, transformDocPageHook = passThroughHook) {
   const transformed = yield transformDocsHook(docs);
   return Promise.all(transformed.map((doc) => transformDocPage(doc, transformDocPageHook)));
 });
-const transformDocPage = (_0, ..._1) => __async$3(void 0, [_0, ..._1], function* (doc, hook = passThroughHook) {
+const transformDocPage = (_0, ..._1) => __async$3(null, [_0, ..._1], function* (doc, hook = passThroughHook) {
   return __spreadValues$8(__spreadValues$8({}, doc), yield hook(doc));
 });
 function postHookCompile$1(bundle) {
@@ -3829,8 +3829,9 @@ var __async$2 = (__this, __arguments, generator) => {
 };
 function openApi(logger, fileBodies, config) {
   return __async$2(this, null, function* () {
+    const sourceDirectory = (Array.isArray(config.sourceDir) ? config.sourceDir[0] : config.sourceDir) || (fileBodies.length > 0 ? fileBodies[0].filePath.split("/").slice(0, -1).join("/") : process.cwd());
     OpenApiSettings.build({
-      sourceDirectory: config.sourceDir,
+      sourceDirectory,
       outputDir: config.targetDir,
       openApiFileName: config.fileName,
       openApiTitle: config.title,
@@ -4779,9 +4780,11 @@ function processFiles(fileSystem) {
       )
     };
     const convertersToUse = componentTypesToRetrieve.map((componentType) => converters[componentType]);
-    return (rootPath, exclude) => {
+    return (rootPaths, exclude) => {
+      const paths = Array.isArray(rootPaths) ? rootPaths : [rootPaths];
+      const allComponents = paths.flatMap((path) => fileSystem.getComponents(path));
       return _function.pipe(
-        fileSystem.getComponents(rootPath),
+        allComponents,
         (components) => {
           return components.map((component) => {
             const pathLocation = component.type.name === "ApexClass" ? component.content : component.xml;
@@ -4827,6 +4830,132 @@ class DefaultFileSystem {
   }
 }
 
+function createSfdxProjectReadError(message, cause) {
+  return {
+    _tag: "SfdxProjectReadError",
+    message,
+    cause
+  };
+}
+function readSfdxProjectConfig(projectRoot) {
+  const sfdxProjectPath = path__namespace.join(projectRoot, "sfdx-project.json");
+  return _function.pipe(
+    E__namespace.tryCatch(
+      () => {
+        if (!fs__namespace.existsSync(sfdxProjectPath)) {
+          throw new Error(`sfdx-project.json not found at ${sfdxProjectPath}`);
+        }
+        return fs__namespace.readFileSync(sfdxProjectPath, "utf8");
+      },
+      (error) => createSfdxProjectReadError(`Failed to read sfdx-project.json: ${error}`, error)
+    ),
+    E__namespace.flatMap(
+      (content) => E__namespace.tryCatch(
+        () => JSON.parse(content),
+        (error) => createSfdxProjectReadError(`Failed to parse sfdx-project.json: ${error}`, error)
+      )
+    ),
+    E__namespace.flatMap((config) => {
+      if (!config.packageDirectories || !Array.isArray(config.packageDirectories)) {
+        return E__namespace.left(
+          createSfdxProjectReadError("sfdx-project.json does not contain a valid packageDirectories array")
+        );
+      }
+      return E__namespace.right(config);
+    })
+  );
+}
+function getSfdxSourceDirectories(projectRoot, absolutePaths = true) {
+  return _function.pipe(
+    readSfdxProjectConfig(projectRoot),
+    E__namespace.map((config) => config.packageDirectories.map((dir) => dir.path)),
+    E__namespace.map((paths) => {
+      if (absolutePaths) {
+        return paths.map((dirPath) => path__namespace.resolve(projectRoot, dirPath));
+      }
+      return paths;
+    }),
+    E__namespace.flatMap((paths) => {
+      const nonExistentPaths = paths.filter((dirPath) => !fs__namespace.existsSync(dirPath));
+      if (nonExistentPaths.length > 0) {
+        return E__namespace.left(
+          createSfdxProjectReadError(
+            `The following package directories do not exist: ${nonExistentPaths.join(", ")}`
+          )
+        );
+      }
+      return E__namespace.right(paths);
+    })
+  );
+}
+
+function createSourceDirectoryResolutionError(message, cause) {
+  return {
+    _tag: "SourceDirectoryResolutionError",
+    message,
+    cause
+  };
+}
+function resolveSourceDirectories(config) {
+  const { sourceDir, useSfdxProjectJson, sfdxProjectPath } = config;
+  const hasSourceDir = sourceDir && (typeof sourceDir === "string" || Array.isArray(sourceDir) && sourceDir.length > 0);
+  const methodsSpecified = [hasSourceDir, useSfdxProjectJson].filter(Boolean).length;
+  if (methodsSpecified === 0) {
+    return E__namespace.left(
+      createSourceDirectoryResolutionError(
+        "No source directory method specified. Must provide one of: sourceDir or useSfdxProjectJson."
+      )
+    );
+  }
+  if (methodsSpecified > 1) {
+    return E__namespace.left(
+      createSourceDirectoryResolutionError(
+        "Multiple source directory methods specified. Only one of sourceDir or useSfdxProjectJson can be used."
+      )
+    );
+  }
+  if (sourceDir) {
+    if (typeof sourceDir === "string") {
+      return E__namespace.right([sourceDir]);
+    } else if (Array.isArray(sourceDir)) {
+      return E__namespace.right(sourceDir);
+    }
+  }
+  if (useSfdxProjectJson) {
+    const projectPath = sfdxProjectPath || process.cwd();
+    return _function.pipe(
+      getSfdxSourceDirectories(projectPath),
+      E__namespace.mapLeft(
+        (sfdxError) => createSourceDirectoryResolutionError(
+          `Failed to read source directories from sfdx-project.json: ${sfdxError.message}`,
+          sfdxError
+        )
+      )
+    );
+  }
+  return E__namespace.left(createSourceDirectoryResolutionError("Invalid source directory configuration."));
+}
+function validateSourceDirectoryConfig(config) {
+  const { sourceDir, useSfdxProjectJson, sfdxProjectPath } = config;
+  if (sourceDir && useSfdxProjectJson) {
+    return E__namespace.left(
+      createSourceDirectoryResolutionError("Cannot specify both sourceDir and useSfdxProjectJson. Use only one.")
+    );
+  }
+  if (sfdxProjectPath && !useSfdxProjectJson) {
+    return E__namespace.left(createSourceDirectoryResolutionError("sfdxProjectPath can only be used with useSfdxProjectJson."));
+  }
+  if (Array.isArray(sourceDir) && sourceDir.length === 0) {
+    return E__namespace.left(
+      createSourceDirectoryResolutionError("sourceDir array cannot be empty. Provide at least one directory.")
+    );
+  }
+  return E__namespace.right(config);
+}
+function resolveAndValidateSourceDirectories(config) {
+  return _function.pipe(validateSourceDirectoryConfig(config), E__namespace.flatMap(resolveSourceDirectories));
+}
+
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -4874,11 +5003,15 @@ const readFiles = processFiles(new DefaultFileSystem());
 function processMarkdown(config) {
   return __async(this, null, function* () {
     return _function.pipe(
-      E__namespace.tryCatch(
-        () => readFiles(allComponentTypes, {
-          includeMetadata: config.includeMetadata
-        })(config.sourceDir, config.exclude),
-        (e) => new FileReadingError("An error occurred while reading files.", e)
+      resolveAndValidateSourceDirectories(config),
+      E__namespace.mapLeft((error) => new FileReadingError(`Failed to resolve source directories: ${error.message}`, error)),
+      E__namespace.flatMap(
+        (sourceDirs) => E__namespace.tryCatch(
+          () => readFiles(allComponentTypes, {
+            includeMetadata: config.includeMetadata
+          })(sourceDirs, config.exclude),
+          (e) => new FileReadingError("An error occurred while reading files.", e)
+        )
       ),
       TE__namespace.fromEither,
       TE__namespace.flatMap((fileBodies) => generate$1(fileBodies, config)),
@@ -4889,20 +5022,59 @@ function processMarkdown(config) {
 }
 function processOpenApi(config, logger) {
   return __async(this, null, function* () {
-    const fileBodies = readFiles(["ApexClass"])(config.sourceDir, config.exclude);
-    return openApi(logger, fileBodies, config);
+    return _function.pipe(
+      resolveAndValidateSourceDirectories(config),
+      E__namespace.mapLeft((error) => new FileReadingError(`Failed to resolve source directories: ${error.message}`, error)),
+      TE__namespace.fromEither,
+      TE__namespace.flatMap(
+        (sourceDirs) => TE__namespace.tryCatch(
+          () => {
+            const fileBodies = readFiles(["ApexClass"])(sourceDirs, config.exclude);
+            return openApi(logger, fileBodies, config);
+          },
+          (e) => new FileReadingError("An error occurred while generating OpenAPI documentation.", e)
+        )
+      )
+    );
   });
 }
 function processChangeLog(config) {
   return __async(this, null, function* () {
     function loadFiles() {
-      return [
-        readFiles(allComponentTypes)(config.previousVersionDir, config.exclude),
-        readFiles(allComponentTypes)(config.currentVersionDir, config.exclude)
-      ];
+      const previousVersionConfig = {
+        sourceDir: config.previousVersionDir
+      };
+      const currentVersionConfig = {
+        sourceDir: config.currentVersionDir
+      };
+      return _function.pipe(
+        E__namespace.Do,
+        E__namespace.bind(
+          "previousVersionDirs",
+          () => _function.pipe(
+            resolveAndValidateSourceDirectories(previousVersionConfig),
+            E__namespace.mapLeft(
+              (error) => new FileReadingError(`Failed to resolve previous version source directories: ${error.message}`, error)
+            )
+          )
+        ),
+        E__namespace.bind(
+          "currentVersionDirs",
+          () => _function.pipe(
+            resolveAndValidateSourceDirectories(currentVersionConfig),
+            E__namespace.mapLeft(
+              (error) => new FileReadingError(`Failed to resolve current version source directories: ${error.message}`, error)
+            )
+          )
+        ),
+        E__namespace.map(({ previousVersionDirs, currentVersionDirs }) => [
+          readFiles(allComponentTypes)(previousVersionDirs, config.exclude),
+          readFiles(allComponentTypes)(currentVersionDirs, config.exclude)
+        ])
+      );
     }
     return _function.pipe(
-      E__namespace.tryCatch(loadFiles, (e) => new FileReadingError("An error occurred while reading files.", e)),
+      loadFiles(),
       TE__namespace.fromEither,
       TE__namespace.flatMap(([previous, current]) => generate(previous, current, config)),
       TE__namespace.mapLeft(toErrors)
@@ -4978,3 +5150,4 @@ exports.changeLogDefaults = changeLogDefaults;
 exports.markdownDefaults = markdownDefaults;
 exports.openApiDefaults = openApiDefaults;
 exports.skip = skip;
+exports.validateSourceDirectoryConfig = validateSourceDirectoryConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -94,7 +94,7 @@
   },
   "dependencies": {
     "@cparra/apex-reflection": "2.19.0",
-    "@salesforce/source-deploy-retrieve": "^12.8.1",
+    "@salesforce/source-deploy-retrieve": "^12.20.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",
     "chalk": "^4.1.2",