@cparra/apexdocs 3.10.0 → 3.12.0

package/README.md

@@ -351,10 +351,62 @@ There are hooks for both Markdown and Changelog operations (but not for OpenApi)
 
 #### Markdown Hooks
 
+##### **macros**
+
+Allows defining custom macros that can be used in the documentation.
+
+Macros are reusable pieces of text that can be injected into the documentation,
+allowing you to define common pieces of text that you can use across multiple files.
+
+A common use case is injecting copyright or license information, without
+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.
+
+**Type**
+
+```typescript
+type MacroSourceMetadata = {
+  type: 'apex' | 'customobject' | 'customfield' | 'custommetadata' | 'trigger';
+  name: string;
+  filePath: string;
+};
+
+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
+return different text based on the source of the file.
+
+Example: Injecting a copyright notice
+
+```typescript
+//...
+macros: {
+  copyright: () => {
+    return `@copyright Copyright (c) ${new Date().getFullYear()} My Name`;
+  }
+}
+//...
+```
+
+And then in your source code, you can use the macro like this:
+
+```apex
+/**
+ * {{copyright}}
+ * @description This is a class
+ */
+public class MyClass {
+  //...
+}
+```
+
 ##### **transformReferenceGuide**
 
-Allows changing the Allows changing the frontmatter and content of the reference guide, or even if creating a reference
-guide page 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,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-D2kLvcfb.js');
+var logger$1 = require('../logger-DZpyHcLp.js');
 var module$1 = require('module');
 var cosmiconfig = require('cosmiconfig');
 var E = require('fp-ts/Either');
@@ -117,6 +117,11 @@ const markdownOptions = {
     type: "string",
     describe: "The title of the reference guide.",
     default: logger$1.markdownDefaults.referenceGuideTitle
+  },
+  includeFieldSecurityMetadata: {
+    type: "boolean",
+    describe: "Whether to include the compliance category and security classification for fields in the generated files.",
+    default: logger$1.markdownDefaults.includeFieldSecurityMetadata
   }
 };
 

package/dist/index.d.ts

@@ -11,6 +11,14 @@ type LinkingStrategy =
   // No logic will be applied, the reference path will be used as is.
   | 'none';
 
+type MacroSourceMetadata = {
+  type: 'apex' | 'customobject' | 'customfield' | 'custommetadata' | 'trigger';
+  name: string;
+  filePath: string;
+};
+
+type MacroFunction = (metadata: MacroSourceMetadata) => string;
+
 type CliConfigurableMarkdownConfig = {
   sourceDir: string;
   targetDir: string;
@@ -24,6 +32,7 @@ type CliConfigurableMarkdownConfig = {
   includeMetadata: boolean;
   linkingStrategy: LinkingStrategy;
   referenceGuideTitle: string;
+  includeFieldSecurityMetadata: boolean;
 };
 
 type UserDefinedMarkdownConfig = {
@@ -152,6 +161,7 @@ type Skip = {
  * The configurable hooks that can be used to modify the output of the Markdown generator.
  */
 type MarkdownConfigurableHooks = {
+  macros: Record<string, MacroFunction>;
   transformReferenceGuide: TransformReferenceGuide;
   transformDocs: TransformDocs;
   transformDocPage: TransformDocPage;
@@ -232,4 +242,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 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, defineChangelogConfig, defineMarkdownConfig, defineOpenApiConfig, process, skip };

package/dist/index.js

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

package/dist/{logger-D2kLvcfb.js → logger-DZpyHcLp.js}

@@ -714,6 +714,8 @@ function fieldMetadataToRenderable(field, config, headingLevel) {
     apiName: getApiName(field.name, config),
     fieldType: field.type,
     required: field.required,
+    complianceCategory: renderComplianceCategory(field.complianceCategory, config),
+    securityClassification: renderComplianceCategory(field.securityClassification, config),
     pickListValues: field.pickListValues ? {
       headingLevel: headingLevel + 1,
       heading: "Possible values are",
@@ -742,6 +744,13 @@ function getApiName(currentName, config) {
   }
   return currentName;
 }
+function renderComplianceCategory(complianceCategory, config) {
+  if (config.includeFieldSecurityMetadata) {
+    return complianceCategory;
+  } else {
+    return null;
+  }
+}
 
 const generateLink = (strategy) => {
   switch (strategy) {
@@ -1527,7 +1536,8 @@ const markdownDefaults = __spreadProps$i(__spreadValues$i({}, markdownAndChangel
   sortAlphabetically: false,
   linkingStrategy: "relative",
   referenceGuideTitle: "Reference Guide",
-  excludeTags: []
+  excludeTags: [],
+  includeFieldSecurityMetadata: false
 });
 const openApiDefaults = __spreadProps$i(__spreadValues$i({}, commonDefaults), {
   fileName: "openapi",
@@ -1566,6 +1576,16 @@ const customObjectTemplate = `
 {{{renderContent description}}}
 {{/if}}
 
+{{#if complianceCategory}}
+**Compliance Category**
+{{complianceCategory}}
+{{/if}}
+
+{{#if securityClassification}}
+**Security Classification**
+{{securityClassification}}
+{{/if}}
+
 **API Name**
 
 \`{{{apiName}}}\`
@@ -2162,6 +2182,8 @@ function convertInlineFieldsToCustomFieldMetadata(inlineField, parentName) {
   const label = inlineField.label ? inlineField.label : name;
   const type = inlineField.type ? inlineField.type : null;
   const required = inlineField.required ? inlineField.required : false;
+  const securityClassification = inlineField.securityClassification ? inlineField.securityClassification : null;
+  const complianceCategory = inlineField.complianceCategory ? inlineField.complianceCategory : null;
   return {
     type_name: "customfield",
     description,
@@ -2170,6 +2192,8 @@ function convertInlineFieldsToCustomFieldMetadata(inlineField, parentName) {
     parentName,
     type,
     required,
+    securityClassification,
+    complianceCategory,
     pickListValues: getPickListValues(inlineField)
   };
 }
@@ -2241,7 +2265,9 @@ function toCustomFieldMetadata(parserResult) {
   const customField = (parserResult == null ? void 0 : parserResult.CustomField) != null && typeof parserResult.CustomField === "object" ? parserResult.CustomField : {};
   const defaultValues = {
     description: null,
-    required: false
+    required: false,
+    securityClassification: null,
+    complianceCategory: null
   };
   return __spreadProps$c(__spreadValues$c(__spreadValues$c({}, defaultValues), customField), {
     type_name: "customfield",
@@ -2590,7 +2616,8 @@ function generateDocs(unparsedBundles, config) {
     );
   }
   return _function.pipe(
-    generateForApex(filterApexSourceFiles(unparsedBundles), config),
+    TE__namespace.right(replaceMacros(unparsedBundles, config.macros)),
+    TE__namespace.flatMap((unparsedBundles2) => generateForApex(filterApexSourceFiles(unparsedBundles2), config)),
     TE__namespace.chain((parsedApexFiles) => {
       return _function.pipe(
         reflectCustomFieldsAndObjectsAndMetadataRecords(
@@ -2624,6 +2651,25 @@ function generateDocs(unparsedBundles, config) {
     TE__namespace.map(postHookCompile$1)
   );
 }
+function replaceMacros(unparsedBundles, macros) {
+  if (!macros) {
+    return unparsedBundles;
+  }
+  return unparsedBundles.map((bundle) => {
+    return __spreadProps$8(__spreadValues$8({}, bundle), {
+      content: Object.entries(macros).reduce((acc, [macroName, macroFunction]) => {
+        return acc.replace(
+          new RegExp(`{{${macroName}}}`, "g"),
+          macroFunction({
+            type: bundle.type,
+            name: bundle.name,
+            filePath: bundle.filePath
+          })
+        );
+      }, bundle.content)
+    });
+  });
+}
 function generateForApex(apexBundles, config) {
   const filterOutOfScope = apply(filterScope, config.scope);
   const removeExcluded = apply(removeExcludedTags, config.excludeTags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -80,7 +80,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^7.16.0",
-    "wireit": "^0.14.10"
+    "wireit": "^0.14.12"
   },
   "husky": {
     "hooks": {