@cparra/apexdocs 3.13.0 → 3.15.0-alpha.0

package/README.md

@@ -12,6 +12,26 @@ ApexDocs is a non-opinionated documentation generator for Salesforce Apex classe
 It can output documentation in Markdown format, which allows you to use the Static Site Generator of your choice to
 create a documentation site that fits your needs, hosted in any static web hosting service.
 
+## Table of Contents
+
+- [👀 Examples](#-examples)
+- [🚀 Features](#-features)
+- [💿 Installation](#-installation)
+- [⚡ Quick Start](#-quick-start)
+  - [CLI](#cli)
+    - [Markdown](#markdown)
+    - [OpenApi](#openapi)
+    - [Changelog](#changelog)
+- [▶️ Available Commands](#️-available-commands)
+  - [Markdown](#markdown-1)
+  - [OpenApi](#openapi-1)
+  - [Changelog](#changelog-1)
+- [🔬 Defining a configuration file](#-defining-a-configuration-file)
+- [🌐 Translation](#-translation)
+- [⤵︎ Importing to your project](#︎-importing-to-your-project)
+- [📖 Documentation Guide](#-documentation-guide)
+- [📄 Generating OpenApi REST Definitions](#-generating-openapi-rest-definitions)
+
 ## 👀 Examples
 
 ApexDocs generates Markdown files, which can be integrated into any Static Site Generation (SSG) engine,
@@ -64,6 +84,7 @@ Here are some live projects using ApexDocs:
 * Support for ignoring files and members from being documented
 * Namespace support
 * Configuration file support
+* Translation support for different languages and custom terminology
 * Single line ApexDoc Blocks
 * Custom tag support
 * And much, much more!
@@ -134,7 +155,9 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 | `--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       |
+|| `--includeInlineHelpTextMetadata` | N/A   | Whether to include the inline help text for fields in the generated files.                                                                                                                               | `false`          | No       |
+|| `--parallelProcessing`            | N/A   | Whether to use parallel processing for reflection operations.                                                                                                                                            | `true`           | No       |
+|| `--workerThreads`                 | N/A   | Number of worker threads to use for parallel processing (defaults to number of CPU cores).                                                                                                              | CPU cores        | No       |
 
 > **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
 > - `--sourceDir` (single directory)
@@ -212,7 +235,9 @@ apexdocs openapi -s force-app -t docs -n MyNamespace --title "My Custom OpenApi
 | `--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       |
+|| `--skipIfNoChanges`        | N/A   | Whether to skip generating the changelog if there are no changes.                    | `true`      | No       |
+|| `--parallelProcessing`     | N/A   | Whether to use parallel processing for reflection operations.                         | `true`      | No       |
+|| `--workerThreads`          | N/A   | Number of worker threads to use for parallel processing (defaults to number of CPU cores). | CPU cores   | No       |
 
 #### Sample Usage
 
@@ -222,6 +247,62 @@ apexdocs changelog -p force-app-previous -t force-app
 
 ---
 
+## ⚡ Parallel Processing
+
+ApexDocs supports parallel processing for reflection operations, significantly improving performance when processing large numbers of Apex files. This feature uses Node.js Worker Threads to process files in parallel while maintaining full compatibility with existing configurations.
+
+### Key Features
+
+- **Automatic**: Enabled by default in production environments
+- **Adaptive**: Automatically chooses between parallel and sequential processing based on file count and environment
+- **Configurable**: Control the number of worker threads used
+- **Safe**: Automatically disabled during tests to prevent interference
+
+### Configuration
+
+```typescript
+import { defineMarkdownConfig } from '@cparra/apexdocs';
+
+export default defineMarkdownConfig({
+  sourceDir: 'force-app',
+  targetDir: 'docs',
+  
+  // Enable/disable parallel processing (default: true in production)
+  parallelProcessing: true,
+  
+  // Set number of worker threads (default: CPU cores)
+  workerThreads: 4,
+});
+```
+
+### CLI Usage
+
+```bash
+# Use parallel processing (default)
+apexdocs markdown -s force-app
+
+# Disable parallel processing
+apexdocs markdown -s force-app --parallelProcessing false
+
+# Set custom worker thread count
+apexdocs markdown -s force-app --workerThreads 8
+```
+
+### Performance Benefits
+
+- **Large codebases**: Significant performance improvements for projects with many files
+- **Multi-core systems**: Better utilization of available CPU cores
+- **CI/CD pipelines**: Faster documentation generation in automated environments
+
+### When It's Used
+
+- **Parallel**: Multiple files + production environment + parallel enabled
+- **Sequential**: Single file OR test environment OR parallel disabled
+
+For more detailed information, see [PARALLEL_PROCESSING.md](PARALLEL_PROCESSING.md).
+
+---
+
 ## 🔬 Defining a configuration file
 
 You can also use a configuration file to define the parameters that will be used when generating the documentation.
@@ -274,6 +355,12 @@ export default defineMarkdownConfig({
   sourceDir: 'force-app',
   targetDir: 'docs',
   scope: ['global', 'public'],
+  translations: {
+    sections: {
+      methods: 'Methods',
+      properties: 'Properties',
+    },
+  },
   ...
 });
 ```
@@ -595,6 +682,74 @@ export default {
 };
 ```
 
+## 🌐 Translation
+
+ApexDocs supports translations to customize the language and terminology used in the generated documentation.
+This feature allows you to:
+
+- **Translate documentation to different languages** (Spanish, French, etc.)
+- **Use custom business terminology** (e.g., "Business Operations" instead of "Methods")
+- **Partially override specific terms** while keeping the rest in English
+
+### How It Works
+
+The translation system uses:
+
+- **Default English translations** built into the system
+- **User-provided overrides** that can be partial or complete
+
+### Configuration
+
+Add a `translations` property to your ApexDocs configuration (JS or TS file) and pass
+the appropriate translation object, depending on the generator you're using:
+
+```javascript
+import { defineMarkdownConfig } from '@cparra/apexdocs';
+
+export default defineMarkdownConfig({
+  sourceDir: 'src',
+  targetDir: 'docs',
+  scope: ['public', 'global'],
+  translations: {
+    sections: {
+      methods: 'Métodos',
+      properties: 'Propiedades',
+      fields: 'Campos',
+    },
+  },
+});
+```
+
+### TypeScript Support
+
+For TypeScript projects, import the translation types for better autocomplete and type safety:
+
+```typescript
+import { defineMarkdownConfig } from '@cparra/apexdocs';
+import type { UserTranslations } from '@cparra/apexdocs';
+
+const markdownTranslations: UserTranslations['markdown'] = {
+  sections: {
+    methods: 'Functions',
+  },
+  // ...other translation keys as needed
+};
+
+export default defineMarkdownConfig({
+  sourceDir: 'src',
+  targetDir: 'docs',
+  scope: ['public', 'global'],
+  translations: markdownTranslations,
+});
+```
+
+### Notes
+
+- Only the **markdown** and **changelog** generators support translations
+- All translations are optional - anything not specified uses the English default
+
+For a complete example, see the [translation example](examples/translation/) in this repository.
+
 ## ⤵︎ Importing to your project
 
 ### Reflection

package/dist/cli/generate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-BiPQ_i9-.js');
+var logger$1 = require('../logger-BbAtfln6.js');
 var require$$0 = require('yargs');
 var cosmiconfig = require('cosmiconfig');
 var E = require('fp-ts/Either');
@@ -10,14 +10,17 @@ var _function = require('fp-ts/function');
 require('fp-ts/TaskEither');
 require('js-yaml');
 require('path');
-require('fp-ts/Task');
-require('fp-ts/lib/Array');
-require('@cparra/apex-reflection');
 require('fp-ts/Option');
-require('fast-xml-parser');
 require('handlebars');
 require('fp-ts/boolean');
+require('fast-xml-parser');
+require('fp-ts/Task');
 require('fp-ts/Array');
+require('worker_threads');
+require('os');
+require('fp-ts/lib/Array');
+require('@cparra/apex-reflection');
+require('uuid');
 require('fs');
 require('fp-ts/lib/TaskEither');
 require('minimatch');
@@ -141,6 +144,15 @@ const markdownOptions = {
   includeInlineHelpTextMetadata: {
     type: "boolean",
     describe: "Whether to include the inline help text for fields in the generated files."
+  },
+  parallelProcessing: {
+    type: "boolean",
+    describe: "Whether to use parallel processing for reflection operations.",
+    default: logger$1.markdownDefaults.parallelProcessing
+  },
+  workerThreads: {
+    type: "number",
+    describe: "Number of worker threads to use for parallel processing (defaults to number of CPU cores)."
   }
 };
 
@@ -256,6 +268,15 @@ const changeLogOptions = {
     type: "boolean",
     default: logger$1.changeLogDefaults.skipIfNoChanges,
     describe: "Skip the changelog generation if there are no changes between the previous and current version."
+  },
+  parallelProcessing: {
+    type: "boolean",
+    describe: "Whether to use parallel processing for reflection operations.",
+    default: logger$1.changeLogDefaults.parallelProcessing
+  },
+  workerThreads: {
+    type: "number",
+    describe: "Number of worker threads to use for parallel processing (defaults to number of CPU cores)."
   }
 };
 

package/dist/core/reflection/worker-thread/reflection-worker.js

@@ -0,0 +1,58 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const worker_threads_1 = require("worker_threads");
+const apex_reflection_1 = require("@cparra/apex-reflection");
+function processReflectionTask(task) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            let result;
+            if (task.type === 'apex') {
+                const reflectionResult = (0, apex_reflection_1.reflect)(task.content);
+                if (reflectionResult.error) {
+                    throw reflectionResult.error;
+                }
+                result = reflectionResult.typeMirror;
+            }
+            else if (task.type === 'trigger') {
+                const reflectionResult = yield (0, apex_reflection_1.reflectTriggerAsync)(task.content);
+                if (reflectionResult.error) {
+                    throw reflectionResult.error;
+                }
+                result = reflectionResult.triggerMirror;
+            }
+            else {
+                throw new Error(`Unknown reflection type: ${task.type}`);
+            }
+            return {
+                id: task.id,
+                success: true,
+                result,
+            };
+        }
+        catch (error) {
+            return {
+                id: task.id,
+                success: false,
+                error: {
+                    message: error.message,
+                    filePath: task.filePath,
+                },
+            };
+        }
+    });
+}
+if (worker_threads_1.parentPort) {
+    worker_threads_1.parentPort.on('message', (task) => __awaiter(void 0, void 0, void 0, function* () {
+        const result = yield processReflectionTask(task);
+        worker_threads_1.parentPort.postMessage(result);
+    }));
+}

package/dist/index.d.ts

@@ -1,3 +1,140 @@
+/**
+ * Default English translations for ApexDocs.
+ * These can be overridden by users in their configuration.
+ */
+type Translations = {
+    changelog: {
+        title: string;
+        newClasses: {
+            heading: string;
+            description: string;
+        };
+        newInterfaces: {
+            heading: string;
+            description: string;
+        };
+        newEnums: {
+            heading: string;
+            description: string;
+        };
+        newCustomObjects: {
+            heading: string;
+            description: string;
+        };
+        newTriggers: {
+            heading: string;
+            description: string;
+        };
+        removedTypes: {
+            heading: string;
+            description: string;
+        };
+        removedCustomObjects: {
+            heading: string;
+            description: string;
+        };
+        removedTriggers: {
+            heading: string;
+            description: string;
+        };
+        newOrModifiedMembers: {
+            heading: string;
+            description: string;
+        };
+        newOrRemovedCustomFields: {
+            heading: string;
+            description: string;
+        };
+        newOrRemovedCustomMetadataTypeRecords: {
+            heading: string;
+            description: string;
+        };
+        memberModifications: {
+            newEnumValue: string;
+            removedEnumValue: string;
+            newMethod: string;
+            removedMethod: string;
+            newProperty: string;
+            removedProperty: string;
+            newField: string;
+            removedField: string;
+            newType: string;
+            removedType: string;
+            newCustomMetadataRecord: string;
+            removedCustomMetadataRecord: string;
+            newTrigger: string;
+            removedTrigger: string;
+        };
+    };
+    markdown: {
+        sections: {
+            methods: string;
+            properties: string;
+            fields: string;
+            constructors: string;
+            values: string;
+            classes: string;
+            enums: string;
+            interfaces: string;
+            namespace: string;
+            records: string;
+            publishBehavior: string;
+        };
+        details: {
+            type: string;
+            signature: string;
+            group: string;
+            author: string;
+            date: string;
+            see: string;
+            possibleValues: string;
+            parameters: string;
+            throws: string;
+            returnType: string;
+            apiName: string;
+            required: string;
+            inlineHelpText: string;
+            complianceGroup: string;
+            securityClassification: string;
+            protected: string;
+        };
+        typeSuffixes: {
+            class: string;
+            interface: string;
+            enum: string;
+            trigger: string;
+        };
+        triggerEvents: {
+            beforeInsert: string;
+            beforeUpdate: string;
+            beforeDelete: string;
+            afterInsert: string;
+            afterUpdate: string;
+            afterDelete: string;
+            afterUndelete: string;
+        };
+        publishBehaviors: {
+            publishImmediately: string;
+            publishAfterCommit: string;
+        };
+        inheritance: {
+            inheritance: string;
+            implements: string;
+        };
+    };
+};
+
+/**
+ * User-provided partial translations that can override the defaults.
+ */
+type UserTranslations = DeepPartial<Translations>;
+/**
+ * Utility type to make all properties in T optional recursively.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
 type Generators = 'markdown' | 'openapi' | 'changelog';
 
 type LinkingStrategy =
@@ -36,12 +173,15 @@ type CliConfigurableMarkdownConfig = {
   referenceGuideTitle: string;
   includeFieldSecurityMetadata: boolean;
   includeInlineHelpTextMetadata: boolean;
+  parallelProcessing?: boolean;
+  workerThreads?: number;
 };
 
 type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   excludeTags: string[];
   exclude: string[];
+  translations?: UserTranslations['markdown'];
 } & CliConfigurableMarkdownConfig &
   Partial<MarkdownConfigurableHooks>;
 
@@ -68,6 +208,9 @@ type UserDefinedChangelogConfig = {
   customObjectVisibility: string[];
   exclude: string[];
   skipIfNoChanges: boolean;
+  translations?: UserTranslations['changelog'];
+  parallelProcessing?: boolean;
+  workerThreads?: number;
 } & Partial<ChangelogConfigurableHooks>;
 
 type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig | UserDefinedChangelogConfig;
@@ -247,4 +390,4 @@ type ConfigurableChangelogConfig = Omit<Partial<UserDefinedChangelogConfig>, 'ta
  */
 declare function defineChangelogConfig(config: ConfigurableChangelogConfig): Partial<UserDefinedChangelogConfig>;
 
-export { type ChangeLogPageData, type ChangelogConfigurableHooks, type ConfigurableChangelogConfig, type ConfigurableDocPageData, type ConfigurableDocPageReference, type ConfigurableMarkdownConfig, type ConfigurableOpenApiConfig, type DocPageData, type DocPageReference, type MacroFunction, type MacroSourceMetadata, type MarkdownConfigurableHooks, type ReferenceGuidePageData, type Skip, type SourceChangelog, type TransformChangelogPage, type TransformDocPage, type TransformDocs, type TransformReference, type TransformReferenceGuide, defineChangelogConfig, defineMarkdownConfig, defineOpenApiConfig, process, skip };
+export { type ChangeLogPageData, type ChangelogConfigurableHooks, type ConfigurableChangelogConfig, type ConfigurableDocPageData, type ConfigurableDocPageReference, type ConfigurableMarkdownConfig, type ConfigurableOpenApiConfig, type DocPageData, type DocPageReference, type MacroFunction, type MacroSourceMetadata, type MarkdownConfigurableHooks, type ReferenceGuidePageData, type Skip, type SourceChangelog, type TransformChangelogPage, type TransformDocPage, type TransformDocs, type TransformReference, type TransformReferenceGuide, type Translations, type UserTranslations, defineChangelogConfig, defineMarkdownConfig, defineOpenApiConfig, process, skip };

package/dist/index.js

@@ -1,19 +1,22 @@
 'use strict';
 
-var logger = require('./logger-BiPQ_i9-.js');
+var logger = require('./logger-BbAtfln6.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');
 require('js-yaml');
 require('path');
-require('fp-ts/Task');
-require('fp-ts/lib/Array');
-require('@cparra/apex-reflection');
 require('fp-ts/Option');
-require('fast-xml-parser');
 require('handlebars');
 require('fp-ts/boolean');
+require('fast-xml-parser');
+require('fp-ts/Task');
 require('fp-ts/Array');
+require('worker_threads');
+require('os');
+require('fp-ts/lib/Array');
+require('@cparra/apex-reflection');
+require('uuid');
 require('fs');
 require('fp-ts/lib/TaskEither');
 require('minimatch');