@cparra/apexdocs 3.15.0-beta.3 → 3.15.1

package/README.md

@@ -138,24 +138,25 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 
 #### Flags
 
-| Flag                              | Alias | Description                                                                                                                                                                                              | Default          | Required |
-|-----------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
-| `--sourceDir`                     | `-s`  | The directory or directories where the source files are located.                                                                                                                                         | N/A              | *        |
-| `--useSfdxProjectJson`            | N/A   | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir`.                                                                                                  | `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 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       |
-| `--lwcGroupName`                  | N/A   | The name under which Lightning Web Components 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 or directories where the source files are located.                                                                                                                                         | N/A                        | *        |
+| `--useSfdxProjectJson`            | N/A   | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir`.                                                                                                  | `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 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       |
+| `--experimentalLwcSupport`        | N/A   | Whether to document LWC files or not.                                                                                                                                                                    | `false`                    | No       |
+| `--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       |
 
 > **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
 > - `--sourceDir` (single directory or array of directories)
@@ -339,6 +340,9 @@ providing the subcommand, e.g `apexdocs markdown` or `apexdocs changelog`.
 
 ### LWC Documentation Limitations
 
+⚠️ LWC documentation is only enabled when providing the `--experimentalLwcSupport` flag or setting the
+`experimentalLwcSupport` property to `true` in the configuration file.
+
 ApexDocs supports generating documentation for Lightning Web Components (LWC) as well, but please
 be aware of the following limitations:
 

package/dist/cli/generate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-BoR2Jx4z.js');
+var logger$1 = require('../logger-BPNUptnX.js');
 var cosmiconfig = require('cosmiconfig');
 var yargs = require('yargs');
 var E = require('fp-ts/Either');
@@ -146,6 +146,11 @@ const markdownOptions = {
   includeInlineHelpTextMetadata: {
     type: "boolean",
     describe: "Whether to include the inline help text for fields in the generated files."
+  },
+  experimentalLwcSupport: {
+    type: "boolean",
+    describe: "Enable experimental support for documenting Lightning Web Components (LWC).",
+    default: logger$1.markdownDefaults.experimentalLwcSupport
   }
 };
 

package/dist/index.d.ts

@@ -180,6 +180,7 @@ type CliConfigurableMarkdownConfig = {
   referenceGuideTitle: string;
   includeFieldSecurityMetadata: boolean;
   includeInlineHelpTextMetadata: boolean;
+  experimentalLwcSupport: boolean;
 };
 
 type UserDefinedMarkdownConfig = {

package/dist/index.js

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

package/dist/{logger-BoR2Jx4z.js → logger-BPNUptnX.js}

@@ -1822,7 +1822,8 @@ const markdownDefaults = __spreadProps$j(__spreadValues$k({}, markdownAndChangel
   referenceGuideTitle: "Reference Guide",
   excludeTags: [],
   includeFieldSecurityMetadata: false,
-  includeInlineHelpTextMetadata: false
+  includeInlineHelpTextMetadata: false,
+  experimentalLwcSupport: false
 });
 const openApiDefaults = __spreadProps$j(__spreadValues$k({}, commonDefaults), {
   fileName: "openapi",
@@ -3110,6 +3111,9 @@ function generateDocs(unparsedBundles, config) {
       );
     }),
     TE__namespace.chain((parsedFiles) => {
+      if (!config.experimentalLwcSupport) {
+        return TE__namespace.right(parsedFiles);
+      }
       return _function.pipe(
         reflectLwcSource(filterLwcFiles(unparsedBundles)),
         TE__namespace.map((parsedFiles2) => parsedFiles2.filter((file) => file.type.isExposed)),
@@ -5163,18 +5167,19 @@ function getLightningComponentBundleSourceComponents(sourceComponents) {
 }
 function toUnparsedApexBundle(fileSystem, apexSourceComponents) {
   return apexSourceComponents.map((component) => {
-    const apexComponentTuple = [
-      fileSystem.readFile(component.contentPath),
-      component.xmlPath ? fileSystem.readFile(component.xmlPath) : null
-    ];
+    const content = fileSystem.readFile(component.contentPath);
+    if (content === null) {
+      return null;
+    }
+    const metadataContent = component.xmlPath ? fileSystem.readFile(component.xmlPath) : null;
     return {
       type: "apex",
       name: component.name,
       filePath: component.contentPath,
-      content: apexComponentTuple[0],
-      metadataContent: apexComponentTuple[1]
+      content,
+      metadataContent
     };
-  });
+  }).filter((bundle) => bundle !== null);
 }
 function getTriggerSourceComponents(sourceComponents) {
   return sourceComponents.filter((component) => component.type.name === "ApexTrigger").map((component) => ({
@@ -5184,12 +5189,18 @@ function getTriggerSourceComponents(sourceComponents) {
   }));
 }
 function toUnparsedTriggerBundle(fileSystem, triggerSourceComponents) {
-  return triggerSourceComponents.map((component) => ({
-    type: "trigger",
-    name: component.name,
-    filePath: component.contentPath,
-    content: fileSystem.readFile(component.contentPath)
-  }));
+  return triggerSourceComponents.map((component) => {
+    const content = fileSystem.readFile(component.contentPath);
+    if (content === null) {
+      return null;
+    }
+    return {
+      type: "trigger",
+      name: component.name,
+      filePath: component.contentPath,
+      content
+    };
+  }).filter((bundle) => bundle !== null);
 }
 function getCustomObjectSourceComponents(sourceComponents) {
   return sourceComponents.filter((component) => component.type.name === "CustomObject").map((component) => ({
@@ -5200,13 +5211,17 @@ function getCustomObjectSourceComponents(sourceComponents) {
 }
 function toUnparsedSObjectBundle(fileSystem, customObjectSourceComponents) {
   return customObjectSourceComponents.map((component) => {
+    const content = fileSystem.readFile(component.contentPath);
+    if (content === null) {
+      return null;
+    }
     return {
       type: "customobject",
       name: component.name,
       filePath: component.contentPath,
-      content: fileSystem.readFile(component.contentPath)
+      content
     };
-  });
+  }).filter((bundle) => bundle !== null);
 }
 function getCustomFieldSourceComponents(sourceComponents) {
   return sourceComponents.filter((component) => component.type.name === "CustomField").map((component) => ({
@@ -5217,13 +5232,19 @@ function getCustomFieldSourceComponents(sourceComponents) {
   }));
 }
 function toUnparsedCustomFieldBundle(fileSystem, customFieldSourceComponents) {
-  return customFieldSourceComponents.map((component) => ({
-    type: "customfield",
-    name: component.name,
-    filePath: component.contentPath,
-    content: fileSystem.readFile(component.contentPath),
-    parentName: component.parentName
-  }));
+  return customFieldSourceComponents.map((component) => {
+    const content = fileSystem.readFile(component.contentPath);
+    if (content === null) {
+      return null;
+    }
+    return {
+      type: "customfield",
+      name: component.name,
+      filePath: component.contentPath,
+      content,
+      parentName: component.parentName
+    };
+  }).filter((bundle) => bundle !== null);
 }
 function getCustomMetadataSourceComponents(sourceComponents) {
   function getParentAndNamePair(component) {
@@ -5239,25 +5260,38 @@ function getCustomMetadataSourceComponents(sourceComponents) {
   }));
 }
 function toUnparsedCustomMetadataBundle(fileSystem, customMetadataSourceComponents) {
-  return customMetadataSourceComponents.map((component) => ({
-    apiName: component.apiName,
-    type: "custommetadata",
-    name: component.name,
-    filePath: component.contentPath,
-    content: fileSystem.readFile(component.contentPath),
-    parentName: component.parentName
-  }));
+  return customMetadataSourceComponents.map((component) => {
+    const content = fileSystem.readFile(component.contentPath);
+    if (content === null) {
+      return null;
+    }
+    return {
+      apiName: component.apiName,
+      type: "custommetadata",
+      name: component.name,
+      filePath: component.contentPath,
+      content,
+      parentName: component.parentName
+    };
+  }).filter((bundle) => bundle !== null);
 }
 function toUnparsedLWCBundle(fileSystem, lwcSourceComponents) {
-  return lwcSourceComponents.map((component) => ({
-    type: "lwc",
-    name: component.name,
-    filePath: component.contentPath,
-    content: fileSystem.readFile(component.contentPath),
-    metadataContent: fileSystem.readFile(component.xmlPath)
-  }));
+  return lwcSourceComponents.map((component) => {
+    const content = fileSystem.readFile(component.contentPath);
+    const metadataContent = fileSystem.readFile(component.xmlPath);
+    if (content === null || metadataContent === null) {
+      return null;
+    }
+    return {
+      type: "lwc",
+      name: component.name,
+      filePath: component.contentPath,
+      content,
+      metadataContent
+    };
+  }).filter((bundle) => bundle !== null);
 }
-function processFiles(fileSystem) {
+function processFiles(fileSystem, config) {
   return (componentTypesToRetrieve, options = { includeMetadata: false }) => {
     const converters = {
       ApexClass: _function.flow(
@@ -5281,7 +5315,7 @@ function processFiles(fileSystem) {
         (triggerSourceComponents) => toUnparsedTriggerBundle(fileSystem, triggerSourceComponents)
       ),
       LightningComponentBundle: _function.flow(
-        getLightningComponentBundleSourceComponents,
+        config.experimentalLwcSupport ? getLightningComponentBundleSourceComponents : () => [],
         (lwcSourceComponents) => toUnparsedLWCBundle(fileSystem, lwcSourceComponents)
       )
     };
@@ -5332,7 +5366,11 @@ class DefaultFileSystem {
     return [...components, ...fieldComponents];
   }
   readFile(pathToRead) {
-    return fs__namespace.readFileSync(pathToRead, "utf8");
+    try {
+      return fs__namespace.readFileSync(pathToRead, "utf8");
+    } catch (error) {
+      return null;
+    }
   }
 }
 
@@ -5505,7 +5543,7 @@ class Apexdocs {
     });
   }
 }
-const readFiles = processFiles(new DefaultFileSystem());
+const readFiles = apply(processFiles, new DefaultFileSystem());
 function processMarkdown(config) {
   return __async(this, null, function* () {
     return _function.pipe(
@@ -5513,7 +5551,7 @@ function processMarkdown(config) {
       E__namespace.mapLeft((error) => new FileReadingError(`Failed to resolve source directories: ${error.message}`, error)),
       E__namespace.flatMap(
         (sourceDirs) => E__namespace.tryCatch(
-          () => readFiles(allComponentTypes, {
+          () => readFiles({ experimentalLwcSupport: config.experimentalLwcSupport })(allComponentTypes, {
             includeMetadata: config.includeMetadata
           })(sourceDirs, config.exclude),
           (e) => new FileReadingError("An error occurred while reading files.", e)
@@ -5535,7 +5573,10 @@ function processOpenApi(config, logger) {
       TE__namespace.flatMap(
         (sourceDirs) => TE__namespace.tryCatch(
           () => {
-            const fileBodies = readFiles(["ApexClass"])(sourceDirs, config.exclude);
+            const fileBodies = readFiles({ experimentalLwcSupport: false })(["ApexClass"])(
+              sourceDirs,
+              config.exclude
+            );
             return openApi(logger, fileBodies, config);
           },
           (e) => new FileReadingError("An error occurred while generating OpenAPI documentation.", e)
@@ -5574,8 +5615,8 @@ function processChangeLog(config) {
           )
         ),
         E__namespace.map(({ previousVersionDirs, currentVersionDirs }) => [
-          readFiles(allComponentTypes)(previousVersionDirs, config.exclude),
-          readFiles(allComponentTypes)(currentVersionDirs, config.exclude)
+          readFiles({ experimentalLwcSupport: false })(allComponentTypes)(previousVersionDirs, config.exclude),
+          readFiles({ experimentalLwcSupport: false })(allComponentTypes)(currentVersionDirs, config.exclude)
         ])
       );
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.15.0-beta.3",
+  "version": "3.15.1",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -92,7 +92,7 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.19.0",
+    "@cparra/apex-reflection": "2.21.1",
     "@salesforce/source-deploy-retrieve": "^12.20.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",
@@ -102,7 +102,7 @@
     "fast-xml-parser": "^4.4.0",
     "fp-ts": "^2.16.8",
     "handlebars": "^4.7.8",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "4.1.1",
     "minimatch": "^10.0.1",
     "yargs": "^17.7.2"
   },