@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

package/src/application/generators/openapi.ts

@@ -0,0 +1,60 @@
+import { createManifest } from '../../core/openapi/manifest-factory';
+import { RawBodyParser } from '../../core/openapi/parser';
+import { TypesRepository } from '../../core/openapi/types-repository';
+import Transpiler from '../../core/openapi/transpiler';
+import { Logger } from '#utils/logger';
+import ErrorLogger from '#utils/error-logger';
+import { reflect, ReflectionResult } from '@cparra/apex-reflection';
+import Manifest from '../../core/manifest';
+import { PageData, UnparsedSourceFile, UserDefinedOpenApiConfig } from '../../core/shared/types';
+import { OpenApiDocsProcessor } from '../../core/openapi/open-api-docs-processor';
+import { writeFiles } from '../file-writer';
+import { pipe } from 'fp-ts/function';
+import * as TE from 'fp-ts/TaskEither';
+
+export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDefinedOpenApiConfig) {
+  const manifest = createManifest(new RawBodyParser(fileBodies), reflectionWithLogger);
+  TypesRepository.getInstance().populateAll(manifest.types);
+  const filteredTypes = filterByScopes(manifest);
+  const processor = new OpenApiDocsProcessor();
+  Transpiler.generate(filteredTypes, processor);
+  const generatedFiles = processor.fileBuilder().files();
+
+  pipe(
+    writeFiles(generatedFiles, config.targetDir, (file: PageData) => {
+      Logger.logSingle(`${file.outputDocPath} processed.`, 'green');
+    }),
+    TE.mapError((error) => Logger.error(error)),
+  );
+
+  // Logs any errors that the types might have in their doc comment's error field
+  ErrorLogger.logErrors(filteredTypes);
+}
+
+function reflectionWithLogger(apexBundle: UnparsedSourceFile): ReflectionResult {
+  const result = reflect(apexBundle.content);
+  if (result.error) {
+    Logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
+  }
+  return result;
+}
+
+function filterByScopes(manifest: Manifest) {
+  // If we are dealing with an OpenApi generator, we ignore the passed in access modifiers, and instead
+  // we only keep classes annotated as @RestResource
+  const filteredTypes = manifest.filteredByAccessModifierAndAnnotations([
+    'restresource',
+    'httpdelete',
+    'httpget',
+    'httppatch',
+    'httppost',
+    'httpput',
+  ]);
+  const filteredLogMessage = `Filtered ${
+    manifest.types.length - filteredTypes.length
+  } file(s), only keeping classes annotated as @RestResource.`;
+
+  Logger.logSingle(filteredLogMessage, 'green');
+  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, 'green');
+  return filteredTypes;
+}

package/src/cli/args.ts

@@ -0,0 +1,43 @@
+import { cosmiconfig, CosmiconfigResult } from 'cosmiconfig';
+import * as yargs from 'yargs';
+import { UserDefinedMarkdownConfig } from '../core/shared/types';
+import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
+import { markdownOptions } from './commands/markdown';
+
+/**
+ * Extracts configuration from a configuration file or the package.json
+ * through cosmiconfig.
+ */
+function _extractConfig(): Promise<CosmiconfigResult> {
+  return cosmiconfig('apexdocs', {
+    loaders: {
+      '.ts': TypeScriptLoader(),
+    },
+  }).search();
+}
+
+/**
+ * Extracts arguments from the command line.
+ * @param config The configuration object from the configuration file, if any.
+ */
+function _extractYargs(config?: CosmiconfigResult) {
+  return yargs
+    .config(config?.config)
+    .command('markdown', 'Generate documentation from Apex classes as a Markdown site.', (yargs) =>
+      yargs.options(markdownOptions),
+    )
+    .command('openapi', 'Generate an OpenApi REST specification from Apex classes.') // TODO: Add OpenApi specific options
+    .demandCommand()
+    .parseSync();
+}
+
+/**
+ * Combines the extracted configuration and arguments.
+ */
+export async function extractArgs(): Promise<UserDefinedMarkdownConfig> {
+  const config = await _extractConfig();
+  const cliArgs = _extractYargs(config);
+  const commandName = cliArgs._[0];
+
+  return { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
+}

package/src/cli/commands/markdown.ts

@@ -0,0 +1,53 @@
+import { Options } from 'yargs';
+import { defaults } from '../../defaults';
+
+export const markdownOptions: { [key: string]: Options } = {
+  sourceDir: {
+    type: 'string',
+    alias: 's',
+    demandOption: true,
+    describe: 'The directory location which contains your apex .cls classes.',
+  },
+  targetDir: {
+    type: 'string',
+    alias: 't',
+    default: defaults.targetDir,
+    describe: 'The directory location where documentation will be generated to.',
+  },
+  scope: {
+    type: 'string',
+    array: true,
+    alias: 'p',
+    default: defaults.scope,
+    describe:
+      'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
+      'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled.',
+  },
+  defaultGroupName: {
+    type: 'string',
+    default: defaults.defaultGroupName,
+    describe: 'Defines the @group name to be used when a file does not specify it.',
+  },
+  namespace: {
+    type: 'string',
+    describe:
+      'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
+      "If generating an OpenApi definition, it will be added to the file's Server Url.",
+  },
+  sortMembersAlphabetically: {
+    type: 'boolean',
+    describe: 'Whether to sort members alphabetically.',
+    default: defaults.sortMembersAlphabetically,
+  },
+  includeMetadata: {
+    type: 'boolean',
+    describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
+    default: defaults.includeMetadata,
+  },
+  linkingStrategy: {
+    type: 'string',
+    describe: 'The strategy to use when linking to other documentation pages.',
+    choices: ['relative', 'no-link', 'none'],
+    default: defaults.linkingStrategy,
+  },
+};

package/src/cli/generate.ts

@@ -1,137 +1,16 @@
 #!/usr/bin/env node
-import * as yargs from 'yargs';
-
-import { Settings } from '../settings';
 import { Apexdocs } from '../application/Apexdocs';
-import { GeneratorChoices } from '../transpiler/generator-choices';
-import { cosmiconfig } from 'cosmiconfig';
-
-const result = cosmiconfig('apexdocs').search();
-result.then((config) => {
-  yargs.config(config?.config);
-  let argv = yargs.options({
-    sourceDir: {
-      type: 'string',
-      alias: 's',
-      demandOption: true,
-      describe: 'The directory location which contains your apex .cls classes.',
-    },
-    targetDir: {
-      type: 'string',
-      alias: 't',
-      default: './docs/',
-      describe: 'The directory location where documentation will be generated to.',
-    },
-    recursive: {
-      type: 'boolean',
-      alias: 'r',
-      default: true,
-      describe: 'Whether .cls classes will be searched for recursively in the directory provided.',
-    },
-    scope: {
-      type: 'array',
-      alias: 'p',
-      default: ['global'],
-      describe:
-        'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
-        'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled. ' +
-        'Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.',
-    },
-    targetGenerator: {
-      type: 'string',
-      alias: 'g',
-      default: 'jekyll',
-      choices: ['jekyll', 'docsify', 'plain-markdown', 'openapi'],
-      describe:
-        'Define the static file generator for which the documents will be created. ' +
-        'Currently supports jekyll, docsify, plain markdown, and OpenAPI v3.1.0.',
-    },
-    indexOnly: {
-      type: 'boolean',
-      default: false,
-      describe: 'Defines whether only the index file should be generated.',
-    },
-    defaultGroupName: {
-      type: 'string',
-      default: 'Miscellaneous',
-      describe: 'Defines the @group name to be used when a file does not specify it.',
-    },
-    sanitizeHtml: {
-      type: 'boolean',
-      default: true,
-      describe:
-        'When on, any special character within your ApexDocs is converted into its HTML code representation. ' +
-        'This is specially useful when generic objects are described within the docs, e.g. "List< Foo>", "Map<Foo, Bar>" ' +
-        'because otherwise the content within < and > would be treated as HTML tags and not shown in the output. ' +
-        'Content in @example blocks are never sanitized.',
-    },
-    openApiTitle: {
-      type: 'string',
-      default: 'Apex REST Api',
-      describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
-    },
-    title: {
-      type: 'string',
-      describe: "If this allows you to specify the title of the generated documentation's home file.",
-      default: 'Classes',
-    },
-    namespace: {
-      type: 'string',
-      describe:
-        'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
-        "If generating an OpenApi definition, it will be added to the file's Server Url.",
-    },
-    openApiFileName: {
-      type: 'string',
-      describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-      default: 'openapi',
-    },
-    sortMembersAlphabetically: {
-      type: 'boolean',
-      describe: 'Whether to sort members alphabetically.',
-      default: false,
-    },
-    includeMetadata: {
-      type: 'boolean',
-      describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
-      default: false,
-    },
-    documentationRootDir: {
-      type: 'string',
-      describe:
-        'Allows you to specify the root documentation directory where the files are being generated. This can be helpful when embedding the generated docs into an existing site so that the links are generated correctly.',
-    },
-  }).argv;
-
-  if (config) {
-    argv = { ...config.config, ...argv };
-  }
+import { extractArgs } from './args';
 
-  Settings.build({
-    sourceDirectory: argv.sourceDir,
-    recursive: argv.recursive,
-    scope: argv.scope,
-    outputDir: argv.targetDir,
-    targetGenerator: argv.targetGenerator as GeneratorChoices,
-    indexOnly: argv.indexOnly,
-    defaultGroupName: argv.defaultGroupName,
-    sanitizeHtml: argv.sanitizeHtml,
-    openApiTitle: argv.openApiTitle,
-    title: argv.title,
-    namespace: argv.namespace,
-    openApiFileName: argv.openApiFileName,
-    sortMembersAlphabetically: argv.sortMembersAlphabetically,
-    includeMetadata: argv.includeMetadata,
-    rootDir: argv.documentationRootDir,
-    onAfterProcess: config?.config?.onAfterProcess,
-    onBeforeFileWrite: config?.config?.onBeforeFileWrite,
-    frontMatterHeader: config?.config?.frontMatterHeader,
-  });
-
-  try {
-    Apexdocs.generate();
-  } catch (error) {
+function main() {
+  function catchError(error: Error) {
     console.error(error);
     process.exit(1);
   }
-});
+
+  extractArgs()
+    .then((config) => Apexdocs.generate(config).catch(catchError))
+    .catch(catchError);
+}
+
+main();

package/src/core/manifest.ts

@@ -0,0 +1,90 @@
+import {
+  Annotation,
+  ClassMirror,
+  DocComment,
+  DocCommentAnnotation,
+  EnumMirror,
+  InterfaceMirror,
+  Type,
+} from '@cparra/apex-reflection';
+
+type AccessAndDocAware = { access_modifier: string; annotations: Annotation[]; docComment?: DocComment };
+
+/**
+ * Represents the full library of Apex top-level types (classes, enums, and interface) for a Salesforce project.
+ */
+export default class Manifest {
+  /**
+   * Constructs a new Manifest object.
+   * @param types List of types to be wrapped by this object.
+   * @param isForInnerTypes Whether this manifest represent an inner type or not.
+   */
+  constructor(
+    public types: Type[],
+    public isForInnerTypes: boolean = false,
+  ) {}
+
+  filteredByAccessModifierAndAnnotations(modifiers: string[]): Type[] {
+    const filteredTypes = Manifest.filterAccessibleModifier(this.types, modifiers);
+    const typesToReturn: Type[] = [];
+    for (const filteredType of filteredTypes) {
+      typesToReturn.push(Manifest.filterSingleType(filteredType, modifiers, this.isForInnerTypes));
+    }
+
+    return typesToReturn;
+  }
+
+  static filterSingleType(currentType: Type, modifiers: string[], isForInnerTypes: boolean): Type {
+    if (currentType.type_name === 'enum') {
+      // Ignoring enum values is not supported.
+      return currentType;
+    }
+
+    if (currentType.type_name === 'interface') {
+      const currentInterface = currentType as InterfaceMirror;
+      return {
+        ...currentType,
+        methods: this.filterAccessibleModifier(currentInterface.methods, modifiers),
+      } as InterfaceMirror;
+    }
+
+    const currentClass = currentType as ClassMirror;
+    const filteredClass = {
+      ...currentType,
+      methods: this.filterAccessibleModifier(currentClass.methods, modifiers),
+      properties: this.filterAccessibleModifier(currentClass.properties, modifiers),
+      fields: this.filterAccessibleModifier(currentClass.fields, modifiers),
+      constructors: this.filterAccessibleModifier(currentClass.constructors, modifiers),
+    } as ClassMirror;
+
+    if (!isForInnerTypes) {
+      return {
+        ...filteredClass,
+        enums: this.filterAccessibleModifier(currentClass.enums, modifiers) as EnumMirror[],
+        interfaces: this.filterAccessibleModifier(currentClass.interfaces, modifiers) as InterfaceMirror[],
+        classes: new Manifest(currentClass.classes, true).filteredByAccessModifierAndAnnotations(
+          modifiers,
+        ) as ClassMirror[],
+      };
+    }
+
+    return filteredClass;
+  }
+
+  static filterAccessibleModifier<T extends AccessAndDocAware>(accessAndDocAware: T[], modifiers: string[]): T[] {
+    return accessAndDocAware.filter((type) => this.shouldFilterType(type, modifiers));
+  }
+
+  static shouldFilterType(accessAndDocAware: AccessAndDocAware, modifiers: string[]) {
+    const hasIgnoreDocAnnotation = accessAndDocAware.docComment?.annotations.some(
+      (annotation: DocCommentAnnotation) => annotation.name.toLowerCase() === 'ignore',
+    );
+    if (hasIgnoreDocAnnotation) {
+      return false;
+    }
+    return (
+      modifiers.includes(accessAndDocAware.access_modifier) ||
+      accessAndDocAware.annotations.some((annotation: Annotation) => modifiers.includes(annotation.type.toLowerCase()))
+    );
+  }
+}

package/src/core/markdown/__test__/expect-extensions.ts

@@ -0,0 +1,32 @@
+import * as E from 'fp-ts/Either';
+import { DocumentationBundle } from '../../shared/types';
+
+export function extendExpect() {
+  expect.extend({
+    documentationBundleHasLength(received: E.Either<string[], DocumentationBundle>, length: number) {
+      return {
+        pass: E.isRight(received) && received.right.docs.length === length,
+        message: () => `Expected documentation bundle to have length ${length}`,
+      };
+    },
+    firstDocContains(doc: DocumentationBundle, content: string) {
+      return {
+        pass: doc.docs[0].content.includes(content),
+        message: () => `Expected documentation to contain ${content}. Got ${doc.docs[0].content}`,
+      };
+    },
+    firstDocContainsNot(doc: DocumentationBundle, content: string) {
+      return {
+        pass: !doc.docs[0].content.includes(content),
+        message: () => `Expected documentation to not contain ${content}. Got ${doc.docs[0].content}`,
+      };
+    },
+  });
+}
+
+export function assertEither<T, U>(result: E.Either<T, U>, assertion: (data: U) => void): void {
+  E.match<T, U, void>(
+    (error) => fail(error),
+    (data) => assertion(data),
+  )(result);
+}