@cparra/apexdocs/dist/index.d.ts

Library with CLI capabilities to generate documentation for Salesforce Apex classes.

/**
 * 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 =
  // Links will be generated using relative paths.
  | 'relative'
  // No links will be generated.
  // If the reference is found, the display name will be used.
  // Otherwise, the name
  // of the reference itself will be used.
  | 'no-link'
  // 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 | string[];
  useSfdxProjectJson?: boolean;
  sfdxProjectPath?: string;
  targetDir: string;
  scope: string[];
  customObjectVisibility: string[];
  namespace?: string;
  defaultGroupName: string;
  customObjectsGroupName: string;
  triggersGroupName: string;
  sortAlphabetically: boolean;
  includeMetadata: boolean;
  linkingStrategy: LinkingStrategy;
  referenceGuideTitle: string;
  includeFieldSecurityMetadata: boolean;
  includeInlineHelpTextMetadata: boolean;
};

type UserDefinedMarkdownConfig = {
  targetGenerator: 'markdown';
  excludeTags: string[];
  exclude: string[];
  translations?: UserTranslations['markdown'];
} & CliConfigurableMarkdownConfig &
  Partial<MarkdownConfigurableHooks>;

type UserDefinedOpenApiConfig = {
  targetGenerator: 'openapi';
  sourceDir?: string | string[];
  useSfdxProjectJson?: boolean;
  sfdxProjectPath?: string;
  targetDir: string;
  fileName: string;
  namespace?: string;
  title: string;
  apiVersion: string;
  exclude: string[];
};

type UserDefinedChangelogConfig = {
  targetGenerator: 'changelog';
  previousVersionDir?: string | string[];
  currentVersionDir?: string | string[];
  targetDir: string;
  fileName: string;
  scope: string[];
  customObjectVisibility: string[];
  exclude: string[];
  skipIfNoChanges: boolean;
  translations?: UserTranslations['changelog'];
} & Partial<ChangelogConfigurableHooks>;

type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig | UserDefinedChangelogConfig;

type MetadataTypes = 'interface' | 'class' | 'enum' | 'customobject' | 'customfield' | 'custommetadata' | 'trigger';

type SourceFileMetadata = {
  filePath: string;
  name: string;
  type: MetadataTypes;
};

// External metadata is metadata that does not live directly in the source code, and thus we don't
// have a file path for it.
// This is metadata derived from other information.
// For example, for an "extension"
// field that extends a Salesforce object or object in a different package, we want to capture the parent
// object, even if the file for that object was not parsed.
type ExternalMetadata = {
  name: string;
  type: MetadataTypes;
};

type DocPageReference = {
  source: SourceFileMetadata | ExternalMetadata;
  // The name under which the type should be displayed in the documentation.
  // By default, this will match the source.name, but it can be configured by the user.
  displayName: string;
  // The location where the file will be written.
  outputDocPath: string;
  // The path to the file relative to the documentation root directory. This is used when linking to the file.
  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
  // the path where the file is written.
  referencePath: string;
};

type Frontmatter = string | Record<string, unknown> | null;

type ReferenceGuidePageData = {
  frontmatter: Frontmatter;
  content: string;
  outputDocPath: string;
};

type DocPageData = {
  source: SourceFileMetadata | ExternalMetadata;
  group: string | null;
  outputDocPath: string;
  frontmatter: Frontmatter;
  content: string;
  type: 'class' | 'interface' | 'enum' | 'customobject' | 'trigger';
};

type FileChange = {
  name: string;
  fileType: 'apex' | 'customobject';
  changeType: 'added' | 'removed' | 'changed';
  changes?: {
    addedMethods?: string[];
    removedMethods?: string[];
    addedFields?: string[];
    removedFields?: string[];
    addedProperties?: string[];
    removedProperties?: string[];
    addedCustomFields?: string[];
    removedCustomFields?: string[];
    addedSubtypes?: string[];
    removedSubtypes?: string[];
    addedEnumValues?: string[];
    removedEnumValues?: string[];
  };
};

type SourceChangelog = {
  fileChanges: FileChange[];
};

type ChangeLogPageData = {
  source: SourceChangelog;
  frontmatter: Frontmatter;
  content: string;
  outputDocPath: string;
};

/**
 * Represents a file to be skipped.
 */
type Skip = {
  readonly _tag: 'Skip';
};

// CONFIGURABLE HOOKS

/**
 * 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;
  transformReference: TransformReference;
};

type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;

type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;

/**
 * Allows changing where the files are written to.
 */
type TransformReference = (
  reference: DocPageReference,
) => Partial<ConfigurableDocPageReference> | Promise<ConfigurableDocPageReference>;

/**
 * Allows changing the frontmatter and content of the reference guide, or even if creating a reference
 * guide will be skipped altogether.
 */
type TransformReferenceGuide = (
  referenceGuide: ReferenceGuidePageData,
) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;

/**
 * The main purpose if for allowing for doc pages to be skipped, but it can also be used to change the frontmatter
 * and content of the doc pages.
 */
type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>;

/**
 * Allows changing the frontmatter and content of the doc pages.
 */
type TransformDocPage = (
  doc: DocPageData,
) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;

type ChangelogConfigurableHooks = {
  transformChangeLogPage: TransformChangelogPage;
};

type TransformChangelogPage = (
  page: ChangeLogPageData,
) => Partial<ChangeLogPageData> | Promise<Partial<ChangeLogPageData>>;

/**
 * Represents a file to be skipped.
 */
declare function skip(): Skip;

type CallableConfig = Partial<UserDefinedConfig> & {
    sourceDir: string;
    targetGenerator: Generators;
};
/**
 * Processes the documentation generation, similar to the main function in the CLI.
 * @param config The configuration to use.
 */
declare function process(config: CallableConfig): Promise<void>;

type ConfigurableMarkdownConfig = Omit<Partial<UserDefinedMarkdownConfig>, 'targetGenerator'>;
/**
 * Helper function to define a configuration to generate Markdown documentation.
 * @param config The configuration to use.
 */
declare function defineMarkdownConfig(config: ConfigurableMarkdownConfig): Partial<UserDefinedMarkdownConfig>;
type ConfigurableOpenApiConfig = Omit<Partial<UserDefinedOpenApiConfig>, 'targetGenerator'>;
/**
 * Helper function to define a configuration to generate OpenAPI documentation.
 * @param config The configuration to use.
 */
declare function defineOpenApiConfig(config: ConfigurableOpenApiConfig): Partial<UserDefinedOpenApiConfig>;
type ConfigurableChangelogConfig = Omit<Partial<UserDefinedChangelogConfig>, 'targetGenerator'>;
/**
 * Helper function to define a configuration to generate a changelog.
 * @param config The configuration to use.
 */
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, type Translations, type UserTranslations, defineChangelogConfig, defineMarkdownConfig, defineOpenApiConfig, process, skip };