@cparra/apexdocs 1.13.4 → 2.0.0-alpha.14

package/src/cli/generate.ts

@@ -1,64 +1,52 @@
-#!/usr/bin/env node
-import * as yargs from 'yargs';
-
-import { generate } from '../command/Generate';
-import FileManager from '../FileManager';
-
-const 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', 'public', 'namespaceaccessible'],
-    describe: 'A list of scopes to document. Values should be separated by a space, e.g --scope public private.',
-  },
-  targetGenerator: {
-    type: 'string',
-    alias: 'g',
-    default: 'jekyll',
-    choices: ['jekyll', 'docsify', 'jsdoc'],
-    describe:
-      'Define the static file generator for which the documents will be created. Currently supports jekyll and docsify.',
-  },
-  configPath: {
-    type: 'string',
-    alias: 'c',
-    describe: 'The path to the JSON configuration file that defines the structure of the documents to generate.',
-  },
-  group: {
-    type: 'boolean',
-    alias: 'o',
-    default: true,
-    describe:
-      'Define whether the generated files should be grouped by the @group tag on the top level classes.' +
-      'If set to true, a sub directory will be created per group inside of the specified target directory.',
-  },
-}).argv;
-
-const generatedClassModels = generate(
-  argv.sourceDir,
-  argv.recursive,
-  argv.scope,
-  argv.targetDir,
-  argv.targetGenerator,
-  argv.configPath,
-  argv.group,
-);
-new FileManager(generatedClassModels).generate();
+#!/usr/bin/env node
+import * as yargs from 'yargs';
+
+import { GeneratorChoices, Settings } from '../settings';
+import { Apexdocs } from '../application/Apexdocs';
+
+const 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',
+  },
+  targetGenerator: {
+    type: 'string',
+    alias: 'g',
+    default: 'jekyll',
+    choices: ['jekyll', 'docsify'],
+    describe:
+      'Define the static file generator for which the documents will be created. Currently supports jekyll, and docsify.',
+  },
+}).argv;
+
+Settings.build({
+  sourceDirectory: argv.sourceDir,
+  recursive: argv.recursive,
+  scope: argv.scope,
+  outputDir: argv.targetDir,
+  targetGenerator: argv.targetGenerator as GeneratorChoices,
+});
+
+Apexdocs.generate();

package/src/index.ts

@@ -1 +1 @@
-export * from './command/Generate';
+export * from './service/manifest-factory';

package/src/model/__tests__/manifest.spec.ts

@@ -0,0 +1,15 @@
+import Manifest from '../manifest';
+import { EnumMirror } from '@cparra/apex-reflection';
+
+const sampleEnum: EnumMirror = {
+  annotations: [],
+  name: 'SampleEnum',
+  type_name: 'enum',
+  access_modifier: 'public',
+};
+
+it('holds a list of types', () => {
+  const types = [sampleEnum];
+  const manifest = new Manifest(types);
+  expect(manifest.types).toBe(types);
+});

package/src/model/file.ts

@@ -0,0 +1,23 @@
+import { encode } from 'html-entities';
+
+export abstract class File {
+  _contents = '';
+
+  constructor(public fileName: string, public dir: string) {}
+
+  abstract fileExtension(): string;
+
+  get body() {
+    return this._contents;
+  }
+
+  addText(text: string, encodeHtml = true) {
+    const textToAdd = encodeHtml ? encode(text) : text;
+    this._contents += textToAdd;
+    this.addBlankLine();
+  }
+
+  addBlankLine() {
+    this._contents += '\n';
+  }
+}

package/src/model/manifest.ts

@@ -0,0 +1,60 @@
+import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
+import { Annotation } from '@cparra/apex-reflection/index';
+
+type AccessAware = { access_modifier: string } & { annotations: Annotation[] };
+
+/**
+ * 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.
+   */
+  constructor(public types: Type[], public isForInnerTypes: boolean = false) {}
+
+  filteredByAccessModifierAndAnnotations(modifiers: string[]): Type[] {
+    const filteredTypes = this.filterAccessibleModifier(this.types, modifiers);
+    const typesToReturn: Type[] = [];
+    for (const filteredType of filteredTypes) {
+      const currentType = filteredType as Type;
+      if (currentType.type_name !== 'class') {
+        typesToReturn.push(currentType);
+        continue;
+      }
+
+      const currentClass = currentType as ClassMirror;
+      let 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),
+      };
+
+      if (!this.isForInnerTypes) {
+        filteredClass = {
+          ...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[],
+        };
+      }
+
+      typesToReturn.push(filteredClass);
+    }
+
+    return typesToReturn;
+  }
+
+  filterAccessibleModifier(accessAware: AccessAware[], modifiers: string[]) {
+    return accessAware.filter((currentType) => {
+      return (
+        modifiers.includes(currentType.access_modifier) ||
+        currentType.annotations.some((annotation: Annotation) => modifiers.includes(annotation.type.toLowerCase()))
+      );
+    });
+  }
+}

package/src/model/markdown-file.ts

@@ -0,0 +1,56 @@
+import { File } from './file';
+
+export class MarkdownFile extends File {
+  fileExtension(): string {
+    return '.md';
+  }
+
+  addTitle(text: string, level = 1) {
+    let title = '';
+    for (let i = 0; i < level; i++) {
+      title += '#';
+    }
+
+    title += ' ';
+    title += text;
+    this._contents += title;
+    this.addBlankLine();
+  }
+
+  startCodeBlock() {
+    this._contents += '```';
+    const sourceLanguage = 'apex';
+    this._contents += sourceLanguage;
+    this.addBlankLine();
+  }
+
+  endCodeBlock() {
+    this._contents += '```';
+    this.addBlankLine();
+  }
+
+  addHorizontalRule() {
+    this._contents += '---';
+    this.addBlankLine();
+  }
+
+  initializeTable(...headers: string[]) {
+    this._contents += '|';
+    headers.forEach((header) => {
+      this._contents += header + '|';
+    });
+    this.addBlankLine();
+    this._contents += '|';
+    headers.forEach((_) => {
+      this._contents += '---' + '|';
+    });
+    this.addBlankLine();
+  }
+
+  addTableRow(...columns: string[]) {
+    this._contents += '|';
+    columns.forEach((column) => {
+      this._contents += column + '|';
+    });
+  }
+}

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

@@ -0,0 +1,42 @@
+import { MarkdownFile } from '../markdown-file';
+import { FieldMirror, PropertyMirror } from '@cparra/apex-reflection';
+
+export function declareField(
+  title: string,
+  markdownFile: MarkdownFile,
+  fields: FieldMirror[] | PropertyMirror[],
+  startingHeadingLevel: number,
+) {
+  markdownFile.addTitle(title, startingHeadingLevel + 1);
+  markdownFile.addBlankLine();
+  fields
+    .sort((propA, propB) => {
+      if (propA.name < propB.name) return -1;
+      if (propA.name > propB.name) return 1;
+      return 0;
+    })
+    .forEach((propertyModel) => {
+      addFieldSection(markdownFile, propertyModel, startingHeadingLevel);
+    });
+
+  markdownFile.addHorizontalRule();
+}
+
+function addFieldSection(
+  markdownFile: MarkdownFile,
+  propertyModel: FieldMirror | PropertyMirror,
+  startingHeadingLevel: number,
+) {
+  markdownFile.addTitle(`\`${propertyModel.name}\` → \`${propertyModel.type}\``, startingHeadingLevel + 2);
+
+  propertyModel.annotations.forEach((annotation) => {
+    markdownFile.addBlankLine();
+    markdownFile.addText(`\`${annotation.type.toUpperCase()}\``);
+  });
+
+  if (propertyModel.docComment?.description) {
+    markdownFile.addBlankLine();
+    markdownFile.addText(propertyModel.docComment.description);
+  }
+  markdownFile.addBlankLine();
+}

package/src/model/markdown-generation-util/index.ts

@@ -0,0 +1,3 @@
+export * from './type-declaration-util';
+export * from './method-declaration-util';
+export * from './field-declaration-util';

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

@@ -0,0 +1,128 @@
+import { ConstructorMirror, DocComment, MethodMirror } from '@cparra/apex-reflection';
+import { MarkdownFile } from '../markdown-file';
+import { ParameterMirror } from '@cparra/apex-reflection/index';
+
+export function declareMethod(
+  title: string,
+  markdownFile: MarkdownFile,
+  methods: ConstructorMirror[] | MethodMirror[],
+  startingHeadingLevel: number,
+  className = '',
+): void {
+  markdownFile.addTitle(title, startingHeadingLevel + 1);
+  methods.forEach((currentMethod) => {
+    const signatureName = isMethod(currentMethod) ? (currentMethod as MethodMirror).name : className;
+    markdownFile.addTitle(`\`${buildSignature(signatureName, currentMethod)}\``, startingHeadingLevel + 2);
+    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 MethodMirror, startingHeadingLevel);
+    }
+
+    addThrowsBlock(markdownFile, currentMethod, startingHeadingLevel);
+
+    if (currentMethod.docComment?.exampleAnnotation) {
+      addExample(markdownFile, currentMethod, startingHeadingLevel);
+    }
+  });
+
+  markdownFile.addHorizontalRule();
+}
+
+type ParameterAware = {
+  parameters: ParameterMirror[];
+};
+
+type DocCommentAware = {
+  docComment?: DocComment;
+};
+
+function buildSignature(name: string, parameterAware: ParameterAware): string {
+  let signature = `${name}(`;
+  if (isMethod(parameterAware) && (parameterAware as MethodMirror).memberModifiers.length) {
+    signature = (parameterAware as MethodMirror).memberModifiers.join(' ') + ' ' + signature;
+  }
+  const signatureParameters = parameterAware.parameters.map((param) => {
+    signature += `${param.type} ${param.name}`;
+  });
+  signature += signatureParameters.join(', ');
+  return (signature += ')');
+}
+
+function addParameters(
+  markdownFile: MarkdownFile,
+  methodModel: MethodMirror | ConstructorMirror,
+  startingHeadingLevel: number,
+) {
+  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: MethodMirror, startingHeadingLevel: number) {
+  if (!methodModel.docComment?.returnAnnotation) {
+    return;
+  }
+
+  markdownFile.addTitle('Return', startingHeadingLevel + 3);
+  markdownFile.addBlankLine();
+  markdownFile.addText('**Type**');
+  markdownFile.addBlankLine();
+  markdownFile.addText(methodModel.type);
+  markdownFile.addBlankLine();
+  markdownFile.addText('**Description**');
+  markdownFile.addBlankLine();
+  markdownFile.addText(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: MethodMirror | ConstructorMirror | ParameterAware): method is ConstructorMirror {
+  return (method as MethodMirror).type !== undefined;
+}

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

@@ -0,0 +1,29 @@
+import { MarkdownFile } from '../markdown-file';
+import { Type } from '@cparra/apex-reflection';
+
+export function declareType(markdownFile: MarkdownFile, typeMirror: Type, startingHeadingLevel: number): void {
+  markdownFile.addTitle(typeMirror.name, startingHeadingLevel);
+
+  typeMirror.annotations.forEach((currentAnnotation) => {
+    markdownFile.addBlankLine();
+    markdownFile.addText(`\`${currentAnnotation.type.toUpperCase()}\``);
+  });
+
+  if (typeMirror.docComment?.description) {
+    markdownFile.addBlankLine();
+    markdownFile.addText(typeMirror.docComment.description);
+    markdownFile.addBlankLine();
+  }
+
+  function capitalizeFirstLetter(text: string) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+  }
+
+  typeMirror.docComment?.annotations
+    .filter((currentAnnotation) => currentAnnotation.name !== 'description')
+    .forEach((currentAnnotation) => {
+      markdownFile.addBlankLine();
+      markdownFile.addText(`**${capitalizeFirstLetter(currentAnnotation.name)}** ${currentAnnotation.body}`);
+      markdownFile.addBlankLine();
+    });
+}

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

@@ -0,0 +1,48 @@
+import { Type } from '@cparra/apex-reflection';
+import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
+import { MarkdownFile } from './markdown-file';
+
+export class MarkdownHomeFile extends MarkdownFile {
+  constructor(public fileName: string, public types: Type[], headerContent?: string) {
+    super(fileName, '');
+    if (headerContent) {
+      this.addText(headerContent);
+    }
+    this.addTitle('Classes');
+    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), 2);
+    this.addBlankLine();
+    this.addBlankLine();
+    this.addText(typeMirror.docComment?.description ?? '');
+    this.addBlankLine();
+    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 ?? '';
+  }
+}

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

@@ -0,0 +1,75 @@
+import {
+  ClassMirror,
+  ConstructorMirror,
+  EnumMirror,
+  FieldMirror,
+  InterfaceMirror,
+  MethodMirror,
+  PropertyMirror,
+  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';
+
+export class MarkdownTypeFile extends MarkdownFile implements WalkerListener {
+  constructor(public type: Type, public startingHeadingLevel: number = 1, headerContent?: string) {
+    super(`${type.name}`, ClassFileGeneratorHelper.getSanitizedGroup(type));
+    if (headerContent) {
+      this.addText(headerContent);
+    }
+    const walker = WalkerFactory.get(type);
+    walker.walk(this);
+  }
+
+  public onTypeDeclaration(typeMirror: Type, headingLevel?: 1): void {
+    declareType(this, typeMirror, this.startingHeadingLevel);
+  }
+
+  public onConstructorDeclaration(className: string, constructors: ConstructorMirror[]): void {
+    declareMethod('Constructors', this, constructors, this.startingHeadingLevel, className);
+  }
+
+  public onFieldsDeclaration(fields: FieldMirror[]): void {
+    declareField('Fields', this, fields, this.startingHeadingLevel);
+  }
+
+  public onPropertiesDeclaration(properties: PropertyMirror[]): void {
+    declareField('Properties', this, properties, this.startingHeadingLevel);
+  }
+
+  public onMethodsDeclaration(methods: MethodMirror[]): void {
+    declareMethod('Methods', this, methods, this.startingHeadingLevel);
+  }
+
+  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.startingHeadingLevel + 1);
+    types
+      .sort((typeA, typeB) => {
+        if (typeA.name < typeB.name) return -1;
+        if (typeA.name > typeB.name) return 1;
+        return 0;
+      })
+      .forEach((currentType) => {
+        const innerFile = new MarkdownTypeFile(currentType, this.startingHeadingLevel + 2);
+        this.addText(innerFile._contents);
+      });
+    if (addSeparator) {
+      this.addHorizontalRule();
+    }
+  }
+}