@cparra/apexdocs 2.24.0 → 2.25.0-alpha.1

package/src/core/renderable/types.d.ts

@@ -0,0 +1,131 @@
+export type Link = {
+  title: string;
+  url: string;
+};
+
+export type EmptyLine = {
+  type: 'empty-line';
+};
+
+export type StringOrLink = string | Link;
+
+export type RenderableContent = StringOrLink | EmptyLine;
+
+type EnumValue = {
+  value: string;
+  description?: RenderableContent[];
+};
+
+type CustomTag = {
+  name: string;
+  description?: RenderableContent[];
+};
+
+/**
+ * Represents an annotation to a top-level type. For example @NamespaceAccessible.
+ */
+type Annotation = string;
+
+type CodeBlock = string[];
+
+type RenderableDocumentation = {
+  annotations?: Annotation[];
+  description?: RenderableContent[];
+  customTags?: CustomTag[];
+  mermaid: RenderableSection<CodeBlock | undefined>;
+  example: RenderableSection<CodeBlock | undefined>;
+  group?: string;
+  author?: string;
+  date?: string;
+  sees?: StringOrLink[];
+};
+
+type RenderableType = {
+  namespace?: string;
+  headingLevel: number;
+  heading: string;
+  name: string;
+  meta: {
+    accessModifier: string;
+  };
+  doc: RenderableDocumentation;
+};
+
+type RenderableMethodParameter = {
+  name: string;
+  type: StringOrLink;
+  description?: RenderableContent[];
+};
+
+type TypeSource = {
+  type: StringOrLink;
+  description?: RenderableContent[];
+};
+
+type RenderableConstructor = {
+  headingLevel: number;
+  heading: string;
+  signature: RenderableSection<CodeBlock>;
+  parameters?: RenderableSection<RenderableMethodParameter[] | undefined>;
+  throws?: RenderableSection<TypeSource[] | undefined>;
+  doc: RenderableDocumentation;
+};
+
+type RenderableMethod = {
+  doc: RenderableDocumentation;
+  headingLevel: number;
+  heading: string;
+  signature: RenderableSection<CodeBlock>;
+  parameters: RenderableSection<RenderableMethodParameter[] | undefined>;
+  returnType: RenderableSection<TypeSource>;
+  throws: RenderableSection<TypeSource[] | undefined>;
+  inherited?: boolean;
+};
+
+type RenderableField = {
+  headingLevel: number;
+  heading: string;
+  type: RenderableSection<StringOrLink>;
+  accessModifier: string;
+  inherited?: boolean;
+  signature: RenderableSection<CodeBlock>;
+  doc: RenderableDocumentation;
+};
+
+export type RenderableSection<T> = {
+  headingLevel: number;
+  heading: string;
+  value: T;
+};
+
+export type GroupedMember<T> = RenderableSection<T[]> & { groupDescription: string | undefined };
+
+export type RenderableClass = RenderableType & {
+  type: 'class';
+  extends?: StringOrLink;
+  implements?: StringOrLink[];
+  classModifier?: string;
+  sharingModifier?: string;
+  constructors: RenderableSection<RenderableConstructor[] | GroupedMember<RenderableConstructor>[]> & {
+    isGrouped: boolean;
+  };
+  methods: RenderableSection<RenderableMethod[] | GroupedMember<RenderableMethod>[]> & { isGrouped: boolean };
+  fields: RenderableSection<RenderableField[] | GroupedMember<RenderableField>[]> & { isGrouped: boolean };
+  properties: RenderableSection<RenderableField[] | GroupedMember<RenderableField>[]> & { isGrouped: boolean };
+  innerClasses: RenderableSection<RenderableClass[]>;
+  innerEnums: RenderableSection<RenderableEnum[]>;
+  innerInterfaces: RenderableSection<RenderableInterface[]>;
+};
+
+export type RenderableInterface = RenderableType & {
+  type: 'interface';
+  extends?: StringOrLink[];
+  methods: RenderableSection<RenderableMethod[]>;
+};
+
+export type RenderableEnum = RenderableType & {
+  type: 'enum';
+  values: RenderableSection<EnumValue[]>;
+};
+
+export type Renderable = RenderableClass | RenderableInterface | RenderableEnum;

package/src/core/template.ts

@@ -0,0 +1,108 @@
+import Handlebars from 'handlebars';
+import { typeDocPartial } from '../transpiler/markdown/plain-markdown/type-doc-partial';
+import { documentablePartialTemplate } from '../transpiler/markdown/plain-markdown/documentable-partial-template';
+import { methodsPartialTemplate } from '../transpiler/markdown/plain-markdown/methods-partial-template';
+import { constructorsPartialTemplate } from '../transpiler/markdown/plain-markdown/constructors-partial-template';
+import { fieldsPartialTemplate } from '../transpiler/markdown/plain-markdown/fieldsPartialTemplate';
+import { classMarkdownTemplate } from '../transpiler/markdown/plain-markdown/class-template';
+import { enumMarkdownTemplate } from '../transpiler/markdown/plain-markdown/enum-template';
+import { interfaceMarkdownTemplate } from '../transpiler/markdown/plain-markdown/interface-template';
+import { RenderableContent, StringOrLink } from './renderable/types';
+import { isEmptyLine } from '../adapters/type-utils';
+import { groupedMembersPartialTemplate } from '../transpiler/markdown/plain-markdown/grouped-members-partial-template';
+
+export type CompilationRequest = {
+  template: string;
+  source: unknown;
+};
+
+export class Template {
+  private static instance: Template;
+
+  private constructor() {
+    Handlebars.registerPartial('typeDocumentation', typeDocPartial);
+    Handlebars.registerPartial('documentablePartialTemplate', documentablePartialTemplate);
+    Handlebars.registerPartial('methodsPartialTemplate', methodsPartialTemplate);
+    Handlebars.registerPartial('constructorsPartialTemplate', constructorsPartialTemplate);
+    Handlebars.registerPartial('groupedMembersPartialTemplate', groupedMembersPartialTemplate);
+    Handlebars.registerPartial('fieldsPartialTemplate', fieldsPartialTemplate);
+    Handlebars.registerPartial('classTemplate', classMarkdownTemplate);
+    Handlebars.registerPartial('enumTemplate', enumMarkdownTemplate);
+    Handlebars.registerPartial('interfaceTemplate', interfaceMarkdownTemplate);
+
+    Handlebars.registerHelper('link', link);
+    Handlebars.registerHelper('code', convertCodeBlock);
+    Handlebars.registerHelper('withLinks', resolveLinksInContent);
+    Handlebars.registerHelper('heading', heading);
+    Handlebars.registerHelper('inlineCode', inlineCode);
+    Handlebars.registerHelper('splitAndCapitalize', splitAndCapitalize);
+  }
+
+  public static getInstance(): Template {
+    if (!Template.instance) {
+      Template.instance = new Template();
+    }
+    return Template.instance;
+  }
+
+  compile(request: CompilationRequest): string {
+    const compiled = Handlebars.compile(request.template);
+    return (
+      compiled(request.source)
+        .trim()
+        // clean up extra newlines
+        .replace(/\n{3,}/g, '\n\n')
+    );
+  }
+}
+
+const splitAndCapitalize = (text: string) => {
+  const words = text.split(/[-_]+/);
+  const capitalizedWords = [];
+  for (const word of words) {
+    capitalizedWords.push(word.charAt(0).toUpperCase() + word.slice(1));
+  }
+  return capitalizedWords.join(' ');
+};
+
+const heading = (level: number, text: string) => {
+  return `${'#'.repeat(level)} ${text}`;
+};
+
+const inlineCode = (text: string) => {
+  return new Handlebars.SafeString(`\`${text}\``);
+};
+
+const convertCodeBlock = (language: string, lines: string[]): Handlebars.SafeString => {
+  return new Handlebars.SafeString(
+    `
+\`\`\`${language}
+${lines.join('\n')}
+\`\`\`
+  `.trim(),
+  );
+};
+
+const resolveLinksInContent = (description?: RenderableContent[]): string => {
+  if (!description) {
+    return '';
+  }
+
+  function reduceDescription(acc: string, curr: RenderableContent) {
+    if (isEmptyLine(curr)) {
+      return acc + '\n\n';
+    }
+
+    return acc + link(curr).trim() + ' ';
+  }
+
+  return description.reduce(reduceDescription, '').trim();
+};
+
+const link = (source: StringOrLink): string => {
+  if (typeof source === 'string') {
+    return source;
+  } else {
+    return `[${source.title}](${source.url})`;
+  }
+};

package/src/core/templates/reference-guide.ts

@@ -0,0 +1,14 @@
+export const referenceGuideTemplate = `
+# Apex Reference Guide
+
+{{#each this}}
+## {{@key}}
+
+{{#each this}}
+### {{link title}}
+
+{{withLinks description}}
+
+{{/each}}
+{{/each}}
+`.trim();

package/src/index.ts

@@ -1 +1,3 @@
-export * from './service/manifest-factory';
+import * as reflection from '@cparra/apex-reflection';
+
+export { reflection };

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

@@ -6,6 +6,7 @@ const sampleEnum: EnumMirror = {
   name: 'SampleEnum',
   type_name: 'enum',
   access_modifier: 'public',
+  values: [],
 };
 
 it('holds a list of types', () => {

package/src/model/manifest.ts

@@ -26,11 +26,21 @@ export default class Manifest {
     const typesToReturn: Type[] = [];
     for (const filteredType of filteredTypes) {
       const currentType = filteredType as Type;
-      if (currentType.type_name !== 'class') {
+      if (currentType.type_name === 'enum') {
+        // Ignoring enum values is not supported.
         typesToReturn.push(currentType);
         continue;
       }
 
+      if (currentType.type_name === 'interface') {
+        const currentInterface = currentType as InterfaceMirror;
+        typesToReturn.push({
+          ...currentType,
+          methods: this.filterAccessibleModifier(currentInterface.methods, modifiers),
+        } as InterfaceMirror);
+        continue;
+      }
+
       const currentClass = currentType as ClassMirror;
       let filteredClass = {
         ...currentType,
@@ -38,7 +48,7 @@ export default class Manifest {
         properties: this.filterAccessibleModifier(currentClass.properties, modifiers),
         fields: this.filterAccessibleModifier(currentClass.fields, modifiers),
         constructors: this.filterAccessibleModifier(currentClass.constructors, modifiers),
-      };
+      } as ClassMirror;
 
       if (!this.isForInnerTypes) {
         filteredClass = {
@@ -57,10 +67,10 @@ export default class Manifest {
     return typesToReturn;
   }
 
-  filterAccessibleModifier(accessAndDocAwares: AccessAndDocAware[], modifiers: string[]) {
-    return accessAndDocAwares.filter((currentType) => {
+  filterAccessibleModifier(accessAndDocAware: AccessAndDocAware[], modifiers: string[]) {
+    return accessAndDocAware.filter((currentType) => {
       const hasIgnoreDocAnnotation = currentType.docComment?.annotations.some(
-        (annotation: DocCommentAnnotation) => annotation.name === 'ignore',
+        (annotation: DocCommentAnnotation) => annotation.name.toLowerCase() === 'ignore',
       );
       if (hasIgnoreDocAnnotation) {
         return false;

package/src/model/markdown-file.ts

@@ -18,12 +18,13 @@ export class MarkdownFile extends OutputFile {
     this.addBlankLine();
   }
 
-  public addText(text: string, encodeHtml = true) {
-    super.addText(this._replaceInlineReferences(text), encodeHtml);
+  public addText(text: string) {
+    //super.addText(this._replaceInlineReferences(text), encodeHtml);
+    super.addText(text);
   }
 
-  public addLink(text: string, encodeHtml = true) {
-    this.addText(`\{@link ${text}\}`, encodeHtml);
+  public addLink(text: string) {
+    this.addText(`{@link ${text}}`);
   }
 
   startCodeBlock(language = 'apex') {
@@ -48,7 +49,7 @@ export class MarkdownFile extends OutputFile {
     });
     this.addBlankLine();
     this._contents += '|';
-    headers.forEach((_) => {
+    headers.forEach(() => {
       this._contents += '---' + '|';
     });
     this.addBlankLine();

package/src/model/markdown-generation-util/doc-comment-annotation-util.ts

@@ -15,7 +15,7 @@ export function addMermaid(markdownFile: MarkdownFile, docCommentAware: DocComme
   markdownFile.addBlankLine();
   markdownFile.startCodeBlock('mermaid');
   mermaid.bodyLines.forEach((line) => {
-    markdownFile.addText(line, false);
+    markdownFile.addText(line);
   });
   markdownFile.endCodeBlock();
   markdownFile.addBlankLine();

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

@@ -153,7 +153,7 @@ function addExample(markdownFile: MarkdownFile, docCommentAware: DocCommentAware
   markdownFile.addTitle('Example', startingHeadingLevel + 3);
   markdownFile.startCodeBlock();
   docCommentAware.docComment?.exampleAnnotation.bodyLines.forEach((line) => {
-    markdownFile.addText(line, false);
+    markdownFile.addText(line);
   });
   markdownFile.endCodeBlock();
   markdownFile.addBlankLine();

package/src/model/openapi/open-api-types.ts

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

package/src/model/outputFile.ts

@@ -1,10 +1,3 @@
-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 = '';
 
@@ -16,10 +9,8 @@ export abstract class OutputFile {
     return this._contents;
   }
 
-  addText(text: string, encodeHtml = true) {
-    const shouldEncode = encodeHtml && Settings.getInstance().sanitizeHtml;
-    const textToAdd = shouldEncode ? xssFilter.process(text) : text;
-    this._contents += textToAdd;
+  addText(text: string) {
+    this._contents += text;
     this.addBlankLine();
   }
 

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

@@ -45,16 +45,16 @@ describe('File Reader', () => {
 
   it('returns an empty list when there are no Apex files in the directory', () => {
     const result = ApexFileReader.processFiles({
-      isDirectory(_: string): boolean {
+      isDirectory(): boolean {
         return false;
       },
-      joinPath(_: string): string {
+      joinPath(): string {
         return '';
       },
-      readDirectory(_: string): string[] {
+      readDirectory(): string[] {
         return ['SomeFile.md'];
       },
-      readFile(_: string): string {
+      readFile(): string {
         return '';
       },
       exists(): boolean {

package/src/service/__tests__/manifest-factory.spec.ts

@@ -1,7 +1,6 @@
 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[] {
@@ -10,7 +9,7 @@ class TestParser implements TypeParser {
 }
 
 it('creates a manifest from the result of a type parser', () => {
-  const manifest = createManifest(new TestParser(), (bundle: ApexBundle) => {
+  const manifest = createManifest(new TestParser(), () => {
     return {};
   });
   expect(manifest.types.length).toBe(0);

package/src/service/parser.ts

@@ -60,7 +60,7 @@ export class RawBodyParser implements TypeParser {
         continue;
       }
 
-      // If reaching here then we are dealing with an interface
+      // At this stage, we can be sure we are dealing with an interface
       let typeAsInterface = currentType as InterfaceMirror;
       if (!typeAsInterface.extended_interfaces.length) {
         typesWithFields.push(currentType);

package/src/test-helpers/FieldMirrorBuilder.ts

@@ -1,5 +1,5 @@
 import { DocComment, FieldMirror } from '@cparra/apex-reflection';
-import { ReferencedType } from '@cparra/apex-reflection/index';
+import { ReferencedType } from '@cparra/apex-reflection';
 
 type MemberModifier = 'static' | 'webservice' | 'final' | 'override' | 'testmethod' | 'transient';
 

package/src/test-helpers/InterfaceMirrorBuilder.ts

@@ -0,0 +1,44 @@
+import { Annotation, DocComment, InterfaceMirror, MethodMirror } from '@cparra/apex-reflection';
+
+/**
+ * Builder class to create Interface objects.
+ * For testing purposes only.
+ */
+export class InterfaceMirrorBuilder {
+  private name = 'SampleClass';
+  private annotations: Annotation[] = [];
+  private docComment?: DocComment;
+  private methods: MethodMirror[] = [];
+
+  withName(name: string): InterfaceMirrorBuilder {
+    this.name = name;
+    return this;
+  }
+
+  addAnnotation(annotation: Annotation): InterfaceMirrorBuilder {
+    this.annotations.push(annotation);
+    return this;
+  }
+
+  withDocComment(docComment: DocComment): InterfaceMirrorBuilder {
+    this.docComment = docComment;
+    return this;
+  }
+
+  addMethod(method: MethodMirror): InterfaceMirrorBuilder {
+    this.methods.push(method);
+    return this;
+  }
+
+  build(): InterfaceMirror {
+    return {
+      annotations: this.annotations,
+      name: this.name,
+      type_name: 'interface',
+      methods: this.methods,
+      access_modifier: 'public',
+      docComment: this.docComment,
+      extended_interfaces: [],
+    };
+  }
+}

package/src/test-helpers/MethodMirrorBuilder.ts

@@ -1,9 +1,16 @@
-import { Annotation, DocComment, MethodMirror } from '@cparra/apex-reflection';
+import { Annotation, DocComment, MethodMirror, ParameterMirror } from '@cparra/apex-reflection';
+
+type Parameter = ParameterMirror;
 
 export class MethodMirrorBuilder {
   private name = 'sampleMethod';
   private annotations: Annotation[] = [];
   private docComment?: DocComment;
+  private typeReference: { type: string; rawDeclaration: string } = {
+    type: 'void',
+    rawDeclaration: 'void',
+  };
+  private parameters: Parameter[] = [];
 
   withName(name: string): MethodMirrorBuilder {
     this.name = name;
@@ -20,18 +27,51 @@ export class MethodMirrorBuilder {
     return this;
   }
 
+  withTypeReference(param: { type: string; rawDeclaration: string }) {
+    this.typeReference = param;
+    return this;
+  }
+
+  addParameter(parameter: Parameter): MethodMirrorBuilder {
+    this.parameters.push(parameter);
+    return this;
+  }
+
   build(): MethodMirror {
     return {
       access_modifier: 'public',
       annotations: this.annotations,
       name: this.name,
       memberModifiers: [],
-      typeReference: {
-        type: 'void',
-        rawDeclaration: 'void',
-      },
-      parameters: [],
+      typeReference: this.typeReference,
+      parameters: this.parameters,
       docComment: this.docComment,
     };
   }
 }
+
+export class ParameterBuilder {
+  private name = 'param';
+  private typeReference: { type: string; rawDeclaration: string } = {
+    type: 'String',
+    rawDeclaration: 'String',
+  };
+
+  withName(name: string): ParameterBuilder {
+    this.name = name;
+    return this;
+  }
+
+  withTypeReference(param: { type: string; rawDeclaration: string }) {
+    this.typeReference = param;
+    return this;
+  }
+
+  build(): Parameter {
+    return {
+      memberModifiers: [],
+      name: this.name,
+      typeReference: this.typeReference,
+    };
+  }
+}

package/src/transpiler/markdown/class-file-generatorHelper.ts

@@ -3,6 +3,7 @@ import { TypesRepository } from '../../model/types-repository';
 import { Settings } from '../../settings';
 import State from '../../service/state';
 import { TypeTranspilerFactory } from '../factory';
+import { StringOrLink } from '../../core/renderable/types';
 
 export default class ClassFileGeneratorHelper {
   public static getSanitizedGroup(classModel: Type) {
@@ -10,13 +11,18 @@ export default class ClassFileGeneratorHelper {
   }
 
   public static getFileLink(classModel: Type) {
+    const [fullClassName, fileLink] = ClassFileGeneratorHelper.getFileLinkTuple(classModel);
+    return `[${fullClassName}](${fileLink})`;
+  }
+
+  private static getFileLinkTuple(classModel: Type): [string, string] {
     const documentationRoot = Settings.getInstance().getRootDir() ?? '';
     const directoryRoot = `${documentationRoot}${this.getDirectoryRoot(classModel)}`;
     const fullClassName = `${Settings.getInstance().getNamespacePrefix()}${classModel.name}`;
-    return `[${fullClassName}](${directoryRoot}${fullClassName}.md)`;
+    return [fullClassName, `${directoryRoot}${fullClassName}.md`];
   }
 
-  public static getFileLinkByTypeName(typeName: string) {
+  public static getFileLinkByTypeName(typeName: string): string {
     const type = TypesRepository.getInstance().getFromScopedByName(typeName);
     if (!type) {
       // If the type is not found, we return a Markdown hyperlink with whatever we received.
@@ -26,6 +32,20 @@ export default class ClassFileGeneratorHelper {
     return this.getFileLink(type);
   }
 
+  public static getRenderableLinkByTypeName(typeName: string): StringOrLink {
+    const type = TypesRepository.getInstance().getFromScopedByName(typeName);
+    if (!type) {
+      // If the type is not found, we return the type name as a string.
+      return typeName;
+    }
+
+    const [fullClassName, fileLink] = ClassFileGeneratorHelper.getFileLinkTuple(type);
+    return {
+      title: fullClassName,
+      url: fileLink,
+    };
+  }
+
   private static getDirectoryRoot(classModel: Type) {
     // root-relative links start from the root by using a leading '/'
     const generator = Settings.getInstance().targetGenerator;