@cparra/apexdocs 2.25.0-alpha.8 → 2.25.0

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

@@ -0,0 +1,165 @@
+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/{core → model}/openapi/open-api-types.ts

@@ -56,14 +56,14 @@ export type RequestBodyContent = {
 
 export type MediaTypeObject = {
   schema?: SchemaObject;
-  example?: unknown;
+  example?: any;
   examples?: { [index: string]: ExampleObject };
 };
 
 export type ExampleObject = {
   summary?: string;
   description?: string;
-  value?: unknown;
+  value?: any;
 };
 
 // Responses

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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,29 @@
+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/{core/openapi → model}/types-repository.ts

@@ -4,6 +4,7 @@ export type TypeBundle = { type: Type; isChild: boolean; parentType?: Type };
 
 export class TypesRepository {
   private static instance: TypesRepository;
+  private scopedTypes: Type[] = [];
   private allTypes: Type[] = [];
 
   public static getInstance(): TypesRepository {
@@ -51,4 +52,12 @@ export class TypesRepository {
     }
     return { type: foundType, isChild: false };
   }
+
+  public populateScoped(types: Type[]) {
+    this.scopedTypes = types;
+  }
+
+  public getFromScopedByName(typeName: string): Type | undefined {
+    return this.scopedTypes.find((currentType: Type) => currentType.name === typeName);
+  }
 }

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

@@ -0,0 +1,92 @@
+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/{core/openapi → service}/__tests__/manifest-factory.spec.ts

@@ -1,6 +1,7 @@
 import { createManifest } from '../manifest-factory';
 import { Type } from '@cparra/apex-reflection';
 import { TypeParser } from '../parser';
+import ApexBundle from '../../model/apex-bundle';
 
 class TestParser implements TypeParser {
   parse(): Type[] {
@@ -9,7 +10,7 @@ class TestParser implements TypeParser {
 }
 
 it('creates a manifest from the result of a type parser', () => {
-  const manifest = createManifest(new TestParser(), () => {
+  const manifest = createManifest(new TestParser(), (bundle: ApexBundle) => {
     return {};
   });
   expect(manifest.types.length).toBe(0);

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

@@ -0,0 +1,51 @@
+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;
+  }
+}

package/src/service/file-writer.ts

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { OutputFile } from '../model/outputFile';
+import { OnBeforeFileWrite, Settings, TargetFile } from '../settings';
+
+export class FileWriter {
+  static write(files: OutputFile[], onWriteCallback: (file: TargetFile) => void) {
+    const onBeforeFileWrite: OnBeforeFileWrite = (file: TargetFile) => Settings.getInstance().onBeforeFileWrite(file);
+    files.forEach((file) => {
+      const resolvedFile = this.getTargetLocation(file, onBeforeFileWrite);
+      const fullDir = path.join(resolvedFile.dir.baseDir, resolvedFile.dir.fileDir);
+      if (!fs.existsSync(fullDir)) {
+        fs.mkdirSync(fullDir, { recursive: true });
+      }
+
+      const filePath = path.join(fullDir, `${resolvedFile.name}${resolvedFile.extension}`);
+      fs.writeFileSync(filePath, file.body, 'utf8');
+      onWriteCallback(resolvedFile);
+    });
+  }
+
+  private static getTargetLocation(file: OutputFile, onBeforeFileWrite: OnBeforeFileWrite): TargetFile {
+    const targetFile: TargetFile = {
+      name: file.fileName,
+      extension: file.fileExtension(),
+      dir: {
+        baseDir: Settings.getInstance().outputDir,
+        fileDir: file.dir,
+      },
+    };
+
+    return onBeforeFileWrite(targetFile);
+  }
+}

package/src/{core/openapi → service}/manifest-factory.ts

@@ -1,7 +1,7 @@
-import Manifest from '../manifest';
+import Manifest from '../model/manifest';
 import { TypeParser } from './parser';
 import { ReflectionResult } from '@cparra/apex-reflection';
-import { SourceFile } from '../shared/types';
+import ApexBundle from '../model/apex-bundle';
 
 /**
  * Builds a new Manifest object, sourcing its types from the received TypeParser.
@@ -10,7 +10,7 @@ import { SourceFile } from '../shared/types';
  */
 export function createManifest(
   typeParser: TypeParser,
-  reflect: (apexBundle: SourceFile) => ReflectionResult,
+  reflect: (apexBundle: ApexBundle) => ReflectionResult,
 ): Manifest {
   return new Manifest(typeParser.parse(reflect));
 }

package/src/service/metadata-processor.ts

@@ -0,0 +1,16 @@
+import { XMLParser } from 'fast-xml-parser';
+
+export default class MetadataProcessor {
+  public static process(input: string) {
+    const map = new Map<string, string>();
+    const xml = new XMLParser().parse(input);
+
+    map.set('apiVersion', xml.ApexClass.apiVersion ?? '');
+
+    if (xml.ApexClass.status) {
+      map.set('status', xml.ApexClass.status);
+    }
+
+    return map;
+  }
+}

package/src/{core/openapi → service}/parser.ts

@@ -1,25 +1,25 @@
 import { ClassMirror, InterfaceMirror, ReflectionResult, Type } from '@cparra/apex-reflection';
-import { parseApexMetadata } from '../parse-apex-metadata';
-import { Logger } from '#utils/logger';
-import { SourceFile } from '../shared/types';
+import ApexBundle from '../model/apex-bundle';
+import MetadataProcessor from './metadata-processor';
+import { Logger } from '../util/logger';
 
 export interface TypeParser {
-  parse(reflect: (apexBundle: SourceFile) => ReflectionResult): Type[];
+  parse(reflect: (apexBundle: ApexBundle) => ReflectionResult): Type[];
 }
 
 type NameAware = { name: string };
 
 export class RawBodyParser implements TypeParser {
-  constructor(public typeBundles: SourceFile[]) {}
+  constructor(public typeBundles: ApexBundle[]) {}
 
-  parse(reflect: (apexBundle: SourceFile) => ReflectionResult): Type[] {
+  parse(reflect: (apexBundle: ApexBundle) => ReflectionResult): Type[] {
     const types = this.typeBundles
       .map((currentBundle) => {
         Logger.log(`Parsing file: ${currentBundle.filePath}`);
         const result = reflect(currentBundle);
-        if (!!result.typeMirror && !!currentBundle.metadataContent) {
+        if (!!result.typeMirror && !!currentBundle.rawMetadataContent) {
           // If successful and there is a metadata file
-          const metadataParams = parseApexMetadata(currentBundle.metadataContent);
+          const metadataParams = MetadataProcessor.process(currentBundle.rawMetadataContent);
           metadataParams.forEach((value, key) => {
             const declaration = `${key}: ${value}`;
             result.typeMirror?.annotations.push({
@@ -60,7 +60,7 @@ export class RawBodyParser implements TypeParser {
         continue;
       }
 
-      // At this stage, we can be sure we are dealing with an interface
+      // If reaching here then we are dealing with an interface
       let typeAsInterface = currentType as InterfaceMirror;
       if (!typeAsInterface.extended_interfaces.length) {
         typesWithFields.push(currentType);

package/src/service/state.ts

@@ -0,0 +1,24 @@
+import { Type } from '@cparra/apex-reflection';
+
+export default class State {
+  private static instance: State;
+  private typeBeingProcessed?: Type;
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  public static getInstance(): State {
+    if (!State.instance) {
+      State.instance = new State();
+    }
+    return State.instance;
+  }
+
+  public setTypeBeingProcessed(typeToSet: Type): void {
+    this.typeBeingProcessed = typeToSet;
+  }
+
+  public getTypeBeingProcessed(): Type | undefined {
+    return this.typeBeingProcessed;
+  }
+}

package/src/service/walkers/class-walker.ts

@@ -0,0 +1,30 @@
+import { Walker, WalkerListener } from './walker';
+import { ClassMirror } from '@cparra/apex-reflection';
+
+export class ClassWalker extends Walker {
+  walk(listener: WalkerListener): void {
+    listener.onTypeDeclaration(this.type);
+    const classMirror = this.type as ClassMirror;
+    if (classMirror.constructors.length) {
+      listener.onConstructorDeclaration(this.type.name, classMirror.constructors);
+    }
+    if (classMirror.fields.length) {
+      listener.onFieldsDeclaration(this.sortType(classMirror.fields));
+    }
+    if (classMirror.properties.length) {
+      listener.onPropertiesDeclaration(this.sortType(classMirror.properties));
+    }
+    if (classMirror.methods.length) {
+      listener.onMethodsDeclaration(this.sortType(classMirror.methods));
+    }
+    if (classMirror.enums.length) {
+      listener.onInnerEnumsDeclaration(this.sortType(classMirror.enums));
+    }
+    if (classMirror.classes.length) {
+      listener.onInnerClassesDeclaration(this.sortType(classMirror.classes));
+    }
+    if (classMirror.interfaces.length) {
+      listener.onInnerInterfacesDeclaration(this.sortType(classMirror.interfaces));
+    }
+  }
+}

package/src/service/walkers/enum-walker.ts

@@ -0,0 +1,7 @@
+import { Walker, WalkerListener } from './walker';
+
+export class EnumWalker extends Walker {
+  walk(listener: WalkerListener): void {
+    listener.onTypeDeclaration(this.type);
+  }
+}

package/src/service/walkers/interface-walker.ts

@@ -0,0 +1,12 @@
+import { Walker, WalkerListener } from './walker';
+import { InterfaceMirror } from '@cparra/apex-reflection';
+
+export class InterfaceWalker extends Walker {
+  walk(listener: WalkerListener): void {
+    listener.onTypeDeclaration(this.type);
+    const interfaceMirror = this.type as InterfaceMirror;
+    if (interfaceMirror.methods.length) {
+      listener.onMethodsDeclaration(this.sortType(interfaceMirror.methods));
+    }
+  }
+}

package/src/service/walkers/walker-factory.ts

@@ -0,0 +1,19 @@
+import { Type } from '@cparra/apex-reflection';
+import { Walker } from './walker';
+import { ClassWalker } from './class-walker';
+import { EnumWalker } from './enum-walker';
+import { InterfaceWalker } from './interface-walker';
+
+export class WalkerFactory {
+  static get(type: Type): Walker {
+    switch (type.type_name) {
+      case 'class':
+        return new ClassWalker(type);
+      case 'enum':
+        return new EnumWalker(type);
+      case 'interface':
+        return new InterfaceWalker(type);
+    }
+    throw Error('Walker not found for type.');
+  }
+}

package/src/service/walkers/walker.ts

@@ -0,0 +1,42 @@
+import {
+  ClassMirror,
+  ConstructorMirror,
+  EnumMirror,
+  FieldMirror,
+  InterfaceMirror,
+  MethodMirror,
+  PropertyMirror,
+  Type,
+} from '@cparra/apex-reflection';
+import { Settings } from '../../settings';
+
+export interface WalkerListener {
+  onTypeDeclaration(typeMirror: Type): void;
+
+  onConstructorDeclaration(className: string, constructors: ConstructorMirror[]): void;
+
+  onFieldsDeclaration(fields: FieldMirror[]): void;
+
+  onPropertiesDeclaration(properties: PropertyMirror[]): void;
+
+  onMethodsDeclaration(methods: MethodMirror[]): void;
+
+  onInnerEnumsDeclaration(enums: EnumMirror[]): void;
+
+  onInnerClassesDeclaration(classes: ClassMirror[]): void;
+
+  onInnerInterfacesDeclaration(interfaces: InterfaceMirror[]): void;
+}
+
+export abstract class Walker {
+  constructor(public type: Type) {}
+
+  abstract walk(listener: WalkerListener): void;
+
+  protected sortType<T extends { name: string }>(types: T[]): T[] {
+    if (Settings.getInstance().sortMembersAlphabetically()) {
+      return types.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    return types;
+  }
+}