@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

package/src/model/markdown-generation-util/method-declaration-util.ts

@@ -1,166 +0,0 @@
-import { ConstructorMirror, DocComment } from '@cparra/apex-reflection';
-import { MarkdownFile } from '../markdown-file';
-import { ParameterMirror } from '@cparra/apex-reflection';
-import { addCustomDocCommentAnnotations, addMermaid } from './doc-comment-annotation-util';
-import { MethodMirrorWithInheritance } from '../inheritance';
-
-export function declareMethod(
-  markdownFile: MarkdownFile,
-  methods: ConstructorMirror[] | MethodMirrorWithInheritance[],
-  startingHeadingLevel: number,
-  className = '',
-): void {
-  methods.forEach((currentMethod) => {
-    const signatureName = isMethod(currentMethod)
-      ? `${(currentMethod as MethodMirrorWithInheritance).typeReference.rawDeclaration} ${
-          (currentMethod as MethodMirrorWithInheritance).name
-        }`
-      : className;
-
-    markdownFile.addTitle(
-      `\`${buildSignature(currentMethod.access_modifier, signatureName, currentMethod)}\``,
-      startingHeadingLevel + 2,
-    );
-
-    // Inheritance tag
-    if (isMethod(currentMethod)) {
-      const asMethodMirror = currentMethod as MethodMirrorWithInheritance;
-      if (asMethodMirror.inherited) {
-        markdownFile.addBlankLine();
-        markdownFile.addText('*Inherited*');
-        markdownFile.addBlankLine();
-      }
-    }
-
-    currentMethod.annotations.forEach((annotation) => {
-      markdownFile.addBlankLine();
-      markdownFile.addText(`\`${annotation.type.toUpperCase()}\``);
-    });
-
-    if (currentMethod.docComment?.description) {
-      markdownFile.addBlankLine();
-      markdownFile.addText(currentMethod.docComment.description);
-      markdownFile.addBlankLine();
-    }
-
-    if (currentMethod.parameters.length) {
-      addParameters(markdownFile, currentMethod, startingHeadingLevel);
-    }
-
-    if (isMethod(currentMethod)) {
-      addReturns(markdownFile, currentMethod as MethodMirrorWithInheritance, startingHeadingLevel);
-    }
-
-    addThrowsBlock(markdownFile, currentMethod, startingHeadingLevel);
-
-    addCustomDocCommentAnnotations(markdownFile, currentMethod);
-
-    addMermaid(markdownFile, currentMethod);
-
-    if (currentMethod.docComment?.exampleAnnotation) {
-      addExample(markdownFile, currentMethod, startingHeadingLevel);
-    }
-  });
-
-  markdownFile.addHorizontalRule();
-}
-
-type ParameterAware = {
-  parameters: ParameterMirror[];
-};
-
-type DocCommentAware = {
-  docComment?: DocComment;
-};
-
-function buildSignature(accessModifier: string, name: string, parameterAware: ParameterAware): string {
-  let signature = `${name}(`;
-  if (isMethod(parameterAware) && (parameterAware as MethodMirrorWithInheritance).memberModifiers.length) {
-    signature =
-      accessModifier +
-      ' ' +
-      (parameterAware as MethodMirrorWithInheritance).memberModifiers.join(' ') +
-      ' ' +
-      signature;
-  } else {
-    signature = accessModifier + ' ' + signature;
-  }
-  const signatureParameters = parameterAware.parameters.map(
-    (param) => `${param.typeReference.rawDeclaration} ${param.name}`,
-  );
-  signature += signatureParameters.join(', ');
-  return `${signature})`;
-}
-
-function addParameters(
-  markdownFile: MarkdownFile,
-  methodModel: MethodMirrorWithInheritance | ConstructorMirror,
-  startingHeadingLevel: number,
-) {
-  if (!methodModel.docComment?.paramAnnotations.length) {
-    // If there are no parameters defined in the docs then we don't want to display this section
-    return;
-  }
-
-  markdownFile.addTitle('Parameters', startingHeadingLevel + 3);
-  markdownFile.initializeTable('Param', 'Description');
-
-  methodModel.docComment?.paramAnnotations.forEach((paramAnnotation) => {
-    const paramName = paramAnnotation.paramName;
-    const paramDescription = paramAnnotation.bodyLines.join(' ');
-    markdownFile.addTableRow(`\`${paramName}\``, paramDescription);
-  });
-
-  markdownFile.addBlankLine();
-}
-
-function addReturns(
-  markdownFile: MarkdownFile,
-  methodModel: MethodMirrorWithInheritance,
-  startingHeadingLevel: number,
-) {
-  if (!methodModel.docComment?.returnAnnotation) {
-    return;
-  }
-
-  markdownFile.addTitle('Returns', startingHeadingLevel + 3);
-  markdownFile.initializeTable('Type', 'Description');
-  markdownFile.addTableRow(
-    `\`${methodModel.typeReference.rawDeclaration}\``,
-    methodModel.docComment?.returnAnnotation.bodyLines.join(' '),
-  );
-  markdownFile.addBlankLine();
-}
-
-function addThrowsBlock(markdownFile: MarkdownFile, docCommentAware: DocCommentAware, startingHeadingLevel: number) {
-  if (!docCommentAware.docComment?.throwsAnnotations.length) {
-    return;
-  }
-  markdownFile.addTitle('Throws', startingHeadingLevel + 3);
-  markdownFile.initializeTable('Exception', 'Description');
-
-  docCommentAware.docComment?.throwsAnnotations.forEach((annotation) => {
-    const exceptionName = annotation.exceptionName;
-    const exceptionDescription = annotation.bodyLines.join(' ');
-
-    markdownFile.addTableRow(`\`${exceptionName}\``, exceptionDescription);
-  });
-
-  markdownFile.addBlankLine();
-}
-
-function addExample(markdownFile: MarkdownFile, docCommentAware: DocCommentAware, startingHeadingLevel: number) {
-  markdownFile.addTitle('Example', startingHeadingLevel + 3);
-  markdownFile.startCodeBlock();
-  docCommentAware.docComment?.exampleAnnotation.bodyLines.forEach((line) => {
-    markdownFile.addText(line, false);
-  });
-  markdownFile.endCodeBlock();
-  markdownFile.addBlankLine();
-}
-
-function isMethod(
-  method: MethodMirrorWithInheritance | ConstructorMirror | ParameterAware,
-): method is MethodMirrorWithInheritance {
-  return (method as MethodMirrorWithInheritance).typeReference !== undefined;
-}

package/src/model/markdown-generation-util/type-declaration-util.ts

@@ -1,91 +0,0 @@
-import { MarkdownFile } from '../markdown-file';
-import { addCustomDocCommentAnnotations, addMermaid } from './doc-comment-annotation-util';
-import { Annotation, ClassMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
-import { TypesRepository } from '../types-repository';
-
-export function declareType(markdownFile: MarkdownFile, typeMirror: Type): void {
-  typeMirror.annotations.forEach((currentAnnotation: Annotation) => {
-    markdownFile.addBlankLine();
-    markdownFile.addText(`\`${currentAnnotation.type.toUpperCase()}\``);
-  });
-
-  if (typeMirror.docComment?.descriptionLines) {
-    markdownFile.addBlankLine();
-    for (const currentLine of typeMirror.docComment.descriptionLines) {
-      markdownFile.addText(currentLine);
-    }
-    markdownFile.addBlankLine();
-  }
-
-  if (typeMirror.type_name === 'class') {
-    addInheritanceSectionForClass(typeMirror, markdownFile);
-  }
-
-  if (typeMirror.type_name === 'interface') {
-    addInheritanceSectionForInterface(typeMirror, markdownFile);
-  }
-
-  addCustomDocCommentAnnotations(markdownFile, typeMirror);
-
-  addMermaid(markdownFile, typeMirror);
-}
-
-function addInheritanceSectionForClass(typeMirror: Type, markdownFile: MarkdownFile) {
-  const typeAsClass = typeMirror as ClassMirror;
-  if (typeAsClass.extended_class) {
-    markdownFile.addBlankLine();
-    markdownFile.addText('**Inheritance**');
-    markdownFile.addBlankLine();
-    addParent(markdownFile, typeAsClass);
-    markdownFile.addText(typeMirror.name);
-    markdownFile.addBlankLine();
-  }
-
-  if (typeAsClass.implemented_interfaces.length) {
-    markdownFile.addBlankLine();
-    markdownFile.addText('**Implemented types**');
-    markdownFile.addBlankLine();
-    for (let i = 0; i < typeAsClass.implemented_interfaces.length; i++) {
-      const currentName = typeAsClass.implemented_interfaces[i];
-      markdownFile.addLink(currentName);
-      if (i < typeAsClass.implemented_interfaces.length - 1) {
-        markdownFile.addText(', ');
-      }
-    }
-    markdownFile.addBlankLine();
-  }
-}
-
-function addInheritanceSectionForInterface(typeMirror: Type, markdownFile: MarkdownFile) {
-  const typeAsInterface = typeMirror as InterfaceMirror;
-  if (typeAsInterface.extended_interfaces.length) {
-    markdownFile.addBlankLine();
-    markdownFile.addText('**Extended types**');
-    markdownFile.addBlankLine();
-    for (let i = 0; i < typeAsInterface.extended_interfaces.length; i++) {
-      const currentName = typeAsInterface.extended_interfaces[i];
-      markdownFile.addLink(currentName);
-      if (i < typeAsInterface.extended_interfaces.length - 1) {
-        markdownFile.addText(', ');
-      }
-    }
-  }
-}
-
-function addParent(markdownFile: MarkdownFile, classMirror: ClassMirror) {
-  if (!classMirror.extended_class) {
-    return;
-  }
-
-  const parentType = TypesRepository.getInstance().getFromScopedByName(classMirror.extended_class);
-  if (!parentType) {
-    return;
-  }
-
-  if (parentType.type_name === 'class') {
-    addParent(markdownFile, parentType as ClassMirror);
-  }
-
-  markdownFile.addLink(parentType.name);
-  markdownFile.addText(' > ');
-}

package/src/model/markdown-home-file.ts

@@ -1,58 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
-import { MarkdownFile } from './markdown-file';
-import { truncate } from '../util/string-utils';
-import { Settings } from '../settings';
-
-export class MarkdownHomeFile extends MarkdownFile {
-  constructor(public fileName: string, public types: Type[], headerContent?: string) {
-    super(fileName, '');
-    if (headerContent) {
-      this.addText(headerContent);
-    }
-    this.addTitle(Settings.getInstance().getTitle());
-    this.addTypeEntries(types);
-  }
-
-  private addTypeEntries(types: Type[]) {
-    const groupedClasses: Map<string, Type[]> = this.group(types);
-    groupedClasses.forEach((value: Type[], key: string) => {
-      this.addTitle(key, 2);
-      value.forEach((typeMirror) => {
-        this.addTypeEntry(typeMirror);
-      });
-    });
-  }
-
-  private addTypeEntry(typeMirror: Type) {
-    this.addBlankLine();
-    this.addTitle(ClassFileGeneratorHelper.getFileLink(typeMirror), 3);
-    this.addBlankLine();
-
-    if (typeMirror.docComment?.descriptionLines) {
-      const description = typeMirror.docComment.descriptionLines.reduce(
-        (previous, current) => previous + current + '\n',
-        '',
-      );
-      this.addText(truncate(description, 300));
-      this.addBlankLine();
-    }
-  }
-
-  private group(classes: Type[]): Map<string, Type[]> {
-    return classes.reduce((groups, currentClass) => {
-      const key = this.getClassGroup(currentClass);
-      const group: Type[] = groups.get(key) || [];
-      group.push(currentClass);
-      groups.set(key, group);
-      return groups;
-    }, new Map());
-  }
-
-  private getClassGroup(classModel: Type): string {
-    return (
-      classModel.docComment?.annotations.find((annotation) => annotation.name === 'group')?.body ??
-      Settings.getInstance().getDefaultGroupName()
-    );
-  }
-}

package/src/model/markdown-type-file.ts

@@ -1,165 +0,0 @@
-import {
-  ClassMirror,
-  ConstructorMirror,
-  EnumMirror,
-  InterfaceMirror,
-  MethodMirror,
-  Type,
-} from '@cparra/apex-reflection';
-import { WalkerFactory } from '../service/walkers/walker-factory';
-import { WalkerListener } from '../service/walkers/walker';
-import { MarkdownFile } from './markdown-file';
-import { declareType, declareMethod, declareField } from './markdown-generation-util';
-import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
-import { FieldMirrorWithInheritance, MethodMirrorWithInheritance, PropertyMirrorWithInheritance } from './inheritance';
-import { Settings } from '../settings';
-
-interface GroupAware {
-  group?: string;
-  groupDescription?: string;
-}
-
-interface GroupMap {
-  [key: string]: GroupAware[];
-}
-
-export class MarkdownTypeFile extends MarkdownFile implements WalkerListener {
-  constructor(private type: Type, private headingLevel: number = 1, headerContent?: string, private isInner = false) {
-    super(
-      `${Settings.getInstance().getNamespacePrefix()}${type.name}`,
-      ClassFileGeneratorHelper.getSanitizedGroup(type),
-    );
-    if (headerContent) {
-      this.addText(headerContent);
-    }
-    const walker = WalkerFactory.get(type);
-    walker.walk(this);
-  }
-
-  public onTypeDeclaration(typeMirror: Type): void {
-    let fullTypeName;
-    if (this.isInner) {
-      fullTypeName = typeMirror.name;
-    } else {
-      // If we are dealing with a class, we want to check if it has a class
-      // modifier and add it to the name.
-      if (this.isClass(typeMirror) && typeMirror.classModifier) {
-        fullTypeName = `${typeMirror.classModifier} ${Settings.getInstance().getNamespacePrefix()}${typeMirror.name}`;
-      } else {
-        fullTypeName = `${Settings.getInstance().getNamespacePrefix()}${typeMirror.name}`;
-      }
-    }
-    this.addTitle(fullTypeName, this.headingLevel);
-    declareType(this, typeMirror);
-  }
-
-  private isClass(typeMirror: Type): typeMirror is ClassMirror {
-    return typeMirror.type_name === 'class';
-  }
-
-  public onConstructorDeclaration(className: string, constructors: ConstructorMirror[]): void {
-    this.addTitle('Constructors', this.headingLevel + 1);
-    this.declareMethodWithGroupings(constructors, className);
-  }
-
-  public onFieldsDeclaration(fields: FieldMirrorWithInheritance[]): void {
-    this.addTitle('Fields', this.headingLevel + 1);
-    this.declareFieldOrProperty(fields);
-  }
-
-  public onPropertiesDeclaration(properties: PropertyMirrorWithInheritance[]): void {
-    this.addTitle('Properties', this.headingLevel + 1);
-    this.declareFieldOrProperty(properties);
-  }
-
-  public onMethodsDeclaration(methods: MethodMirror[]): void {
-    this.addTitle('Methods', this.headingLevel + 1);
-    this.declareMethodWithGroupings(methods);
-  }
-
-  public onInnerEnumsDeclaration(enums: EnumMirror[]): void {
-    this.addInnerTypes('Enums', enums);
-  }
-
-  public onInnerClassesDeclaration(classes: ClassMirror[]): void {
-    this.addInnerTypes('Classes', classes);
-  }
-
-  public onInnerInterfacesDeclaration(interfaces: InterfaceMirror[]): void {
-    this.addInnerTypes('Interfaces', interfaces, false);
-  }
-
-  private addInnerTypes(title: string, types: Type[], addSeparator = true) {
-    this.addTitle(title, this.headingLevel + 1);
-    types.forEach((currentType) => {
-      const innerFile = new MarkdownTypeFile(currentType, this.headingLevel + 2, undefined, true);
-      this.addText(innerFile._contents);
-    });
-    if (addSeparator) {
-      this.addHorizontalRule();
-    }
-  }
-
-  private hasGroupings(groupAware: GroupAware[]): boolean {
-    return !!groupAware.find((current) => !!current.group);
-  }
-
-  private declareMethodWithGroupings(
-    methods: ConstructorMirror[] | MethodMirrorWithInheritance[],
-    className = '',
-  ): void {
-    const hasGroupings = this.hasGroupings(methods);
-    if (!hasGroupings) {
-      declareMethod(this, methods, this.headingLevel, className);
-    } else {
-      const groupedConstructors = this.group(methods);
-      for (const key in groupedConstructors) {
-        // For the group description, we can take the first one, since they all have the same description.
-        this.startGroup(key, groupedConstructors[key][0].groupDescription);
-        const constructorsForGroup = groupedConstructors[key] as (ConstructorMirror | MethodMirrorWithInheritance)[];
-        declareMethod(this, constructorsForGroup, this.headingLevel, className);
-        this.endGroup();
-      }
-    }
-  }
-
-  private declareFieldOrProperty(
-    fieldsOrProperties: FieldMirrorWithInheritance[] | PropertyMirrorWithInheritance[],
-  ): void {
-    const hasGroupings = this.hasGroupings(fieldsOrProperties);
-    if (!hasGroupings) {
-      declareField(this, fieldsOrProperties, this.headingLevel, false);
-    } else {
-      const groupedFields = this.group(fieldsOrProperties);
-      for (const key in groupedFields) {
-        // For the group description, we can take the first one, since they all have the same description.
-        this.startGroup(key, groupedFields[key][0].groupDescription);
-        const fieldsForGroup = groupedFields[key] as (FieldMirrorWithInheritance | PropertyMirrorWithInheritance)[];
-        declareField(this, fieldsForGroup, this.headingLevel, true);
-        this.endGroup();
-      }
-    }
-  }
-
-  private startGroup(groupName: string, groupDescription?: string) {
-    this.headingLevel = this.headingLevel + 2;
-    this.addTitle(groupName, this.headingLevel);
-    if (groupDescription) {
-      this.addText(groupDescription);
-    }
-  }
-
-  private endGroup() {
-    this.headingLevel = this.headingLevel - 2;
-  }
-
-  private group(list: GroupAware[]) {
-    return list.reduce((groups: GroupMap, item) => {
-      const groupName: string = item.group ?? 'Other';
-      const group: GroupAware[] = groups[groupName] || [];
-      group.push(item);
-      groups[groupName] = group;
-      return groups;
-    }, {});
-  }
-}

package/src/model/openapi/openapi-type-file.ts

@@ -1,14 +0,0 @@
-import { OutputFile } from '../outputFile';
-import { OpenApi } from './open-api';
-import { Settings } from '../../settings';
-
-export class OpenapiTypeFile extends OutputFile {
-  constructor(public openApiModel: OpenApi) {
-    super(Settings.getInstance().openApiFileName(), '');
-    this.addText(JSON.stringify({ ...openApiModel, namespace: undefined }, null, 2));
-  }
-
-  fileExtension(): string {
-    return '.json';
-  }
-}

package/src/model/outputFile.ts

@@ -1,29 +0,0 @@
-import xss = require('xss');
-import { Settings } from '../settings';
-
-const xssFilter = new xss.FilterXSS({
-  whiteList: { br: [], p: [], ul: [], li: [], code: [], pre: [] },
-});
-
-export abstract class OutputFile {
-  _contents = '';
-
-  constructor(public fileName: string, public dir: string) {}
-
-  abstract fileExtension(): string;
-
-  get body() {
-    return this._contents;
-  }
-
-  addText(text: string, encodeHtml = true) {
-    const shouldEncode = encodeHtml && Settings.getInstance().sanitizeHtml;
-    const textToAdd = shouldEncode ? xssFilter.process(text) : text;
-    this._contents += textToAdd;
-    this.addBlankLine();
-  }
-
-  addBlankLine() {
-    this._contents += '\n';
-  }
-}

package/src/service/__tests__/apex-file-reader.spec.ts

@@ -1,92 +0,0 @@
-import { Settings, SettingsConfig } from '../../settings';
-import { ApexFileReader } from '../apex-file-reader';
-
-describe('File Reader', () => {
-  beforeEach(() => {
-    Settings.build({
-      sourceDirectory: '',
-      recursive: true,
-      scope: [],
-      outputDir: '',
-      targetGenerator: 'jekyll',
-      indexOnly: false,
-      defaultGroupName: 'Misc',
-      sanitizeHtml: true,
-      openApiFileName: 'openapi',
-      title: 'Classes',
-      includeMetadata: false,
-    } as SettingsConfig);
-  });
-
-  it('returns an empty list when there are no files in the directory', () => {
-    const result = ApexFileReader.processFiles({
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      isDirectory(_: string): boolean {
-        return false;
-      },
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      joinPath(_: string): string {
-        return '';
-      },
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      readDirectory(_: string): string[] {
-        return [];
-      },
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      readFile(_: string): string {
-        return '';
-      },
-      exists(): boolean {
-        return true;
-      },
-    });
-    expect(result.length).toBe(0);
-  });
-
-  it('returns an empty list when there are no Apex files in the directory', () => {
-    const result = ApexFileReader.processFiles({
-      isDirectory(_: string): boolean {
-        return false;
-      },
-      joinPath(_: string): string {
-        return '';
-      },
-      readDirectory(_: string): string[] {
-        return ['SomeFile.md'];
-      },
-      readFile(_: string): string {
-        return '';
-      },
-      exists(): boolean {
-        return true;
-      },
-    });
-    expect(result.length).toBe(0);
-  });
-
-  it('returns the file contents for an Apex file', () => {
-    const result = ApexFileReader.processFiles({
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      isDirectory(_: string): boolean {
-        return false;
-      },
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      joinPath(_: string): string {
-        return '';
-      },
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      readDirectory(_: string): string[] {
-        return ['SomeApexFile.cls'];
-      },
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      readFile(_: string): string {
-        return 'public class MyClass{}';
-      },
-      exists(): boolean {
-        return true;
-      },
-    });
-    expect(result.length).toBe(1);
-    expect(result[0].rawTypeContent).toBe('public class MyClass{}');
-  });
-});

package/src/service/apex-file-reader.ts

@@ -1,51 +0,0 @@
-import { Settings } from '../settings';
-import { FileSystem } from './file-system';
-import ApexBundle from '../model/apex-bundle';
-
-const APEX_FILE_EXTENSION = '.cls';
-
-/**
- * Reads from .cls files and returns their raw body.
- */
-export class ApexFileReader {
-  /**
-   * Reads from .cls files and returns their raw body.
-   */
-  static processFiles(fileSystem: FileSystem, rootPath: string = this.sourceDirectory): ApexBundle[] {
-    let bundles: ApexBundle[] = [];
-
-    const directoryContents = fileSystem.readDirectory(rootPath);
-    directoryContents.forEach((currentFilePath) => {
-      const currentPath = fileSystem.joinPath(rootPath, currentFilePath);
-      if (this.readRecursively && fileSystem.isDirectory(currentPath)) {
-        bundles = bundles.concat(this.processFiles(fileSystem, currentPath));
-      }
-
-      if (!this.isApexFile(currentFilePath)) {
-        return;
-      }
-
-      const rawApexFile = fileSystem.readFile(currentPath);
-      const metadataPath = fileSystem.joinPath(rootPath, `${currentFilePath}-meta.xml`);
-      let rawMetadataFile = null;
-      if (Settings.getInstance().includeMetadata()) {
-        rawMetadataFile = fileSystem.exists(metadataPath) ? fileSystem.readFile(metadataPath) : null;
-      }
-
-      bundles.push(new ApexBundle(currentFilePath, rawApexFile, rawMetadataFile));
-    });
-    return bundles;
-  }
-
-  private static isApexFile(currentFile: string): boolean {
-    return currentFile.endsWith(APEX_FILE_EXTENSION);
-  }
-
-  private static get sourceDirectory() {
-    return Settings.getInstance().sourceDirectory;
-  }
-
-  private static get readRecursively() {
-    return Settings.getInstance().recursive;
-  }
-}