@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

package/src/core/markdown/adapters/apex-types.ts

@@ -0,0 +1,238 @@
+import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
+import {
+  RenderableType,
+  RenderableClass,
+  RenderableEnum,
+  RenderableInterface,
+  RenderableSection,
+  GroupedMember,
+  ClassMirrorWithInheritanceChain,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  GetRenderableContentByTypeName,
+} from './types';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { adaptConstructor, adaptMethod } from './methods-and-constructors';
+import { adaptFieldOrProperty } from './fields-and-properties';
+import { MarkdownGeneratorConfig } from '../generate-docs';
+import { SourceFileMetadata } from '../../shared/types';
+
+type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
+  ? RenderableInterface
+  : T extends ClassMirror
+    ? RenderableClass
+    : RenderableEnum;
+
+export function typeToRenderable<T extends Type>(
+  parsedFile: { source: SourceFileMetadata; type: T },
+  linkGenerator: GetRenderableContentByTypeName,
+  config: MarkdownGeneratorConfig,
+): GetReturnRenderable<T> & { filePath: string; namespace?: string } {
+  function getRenderable(): RenderableInterface | RenderableClass | RenderableEnum {
+    const { type } = parsedFile;
+    switch (type.type_name) {
+      case 'enum':
+        return enumTypeToEnumSource(type as EnumMirror, linkGenerator) as RenderableEnum;
+      case 'interface':
+        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator) as RenderableInterface;
+      case 'class':
+        return classTypeToClassSource(type as ClassMirrorWithInheritanceChain, linkGenerator) as RenderableClass;
+    }
+  }
+
+  return {
+    ...(getRenderable() as GetReturnRenderable<T>),
+    filePath: parsedFile.source.filePath,
+    namespace: config.namespace,
+  };
+}
+
+function baseTypeAdapter(
+  type: EnumMirror | InterfaceMirror | ClassMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableType {
+  function getHeading(type: Type): string {
+    const suffixMap = {
+      class: 'Class',
+      interface: 'Interface',
+      enum: 'Enum',
+    };
+
+    return `${type.name} ${suffixMap[type.type_name]}`;
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    heading: getHeading(type),
+    doc: adaptDocumentable(type, linkGenerator, baseHeadingLevel + 1),
+    name: type.name,
+    meta: {
+      accessModifier: type.access_modifier,
+    },
+  };
+}
+
+function enumTypeToEnumSource(
+  enumType: EnumMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableEnum {
+  return {
+    type: 'enum',
+    ...baseTypeAdapter(enumType, linkGenerator, baseHeadingLevel),
+    values: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Values',
+      value: enumType.values.map((value) => ({
+        ...adaptDescribable(value.docComment?.descriptionLines, linkGenerator),
+        value: value.name,
+      })),
+    },
+  };
+}
+
+function interfaceTypeToInterfaceSource(
+  interfaceType: InterfaceMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableInterface {
+  return {
+    type: 'interface',
+    ...baseTypeAdapter(interfaceType, linkGenerator, baseHeadingLevel),
+    extends: interfaceType.extended_interfaces.map(linkGenerator),
+    methods: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Methods',
+      value: interfaceType.methods.map((method) => adaptMethod(method, linkGenerator, baseHeadingLevel + 2)),
+    },
+  };
+}
+
+function classTypeToClassSource(
+  classType: ClassMirrorWithInheritanceChain,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableClass {
+  return {
+    type: 'class',
+    ...baseTypeAdapter(classType, linkGenerator, baseHeadingLevel),
+    classModifier: classType.classModifier,
+    sharingModifier: classType.sharingModifier,
+    implements: classType.implemented_interfaces.map(linkGenerator),
+    extends: classType.inheritanceChain.map(linkGenerator),
+    methods: adaptMembers('Methods', classType.methods, adaptMethod, linkGenerator, baseHeadingLevel + 1),
+    constructors: adaptMembers(
+      'Constructors',
+      classType.constructors,
+      (constructor, linkGenerator, baseHeadingLevel) =>
+        adaptConstructor(classType.name, constructor, linkGenerator, baseHeadingLevel),
+      linkGenerator,
+      baseHeadingLevel + 1,
+    ),
+    fields: adaptMembers(
+      'Fields',
+      classType.fields as FieldMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkGenerator,
+      baseHeadingLevel + 1,
+    ),
+    properties: adaptMembers(
+      'Properties',
+      classType.properties as PropertyMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkGenerator,
+      baseHeadingLevel + 1,
+    ),
+    innerClasses: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Classes',
+      value: classType.classes.map((innerClass) =>
+        classTypeToClassSource({ ...innerClass, inheritanceChain: [] }, linkGenerator, baseHeadingLevel + 2),
+      ),
+    },
+    innerEnums: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Enums',
+      value: classType.enums.map((innerEnum) => enumTypeToEnumSource(innerEnum, linkGenerator, baseHeadingLevel + 2)),
+    },
+    innerInterfaces: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Interfaces',
+      value: classType.interfaces.map((innerInterface) =>
+        interfaceTypeToInterfaceSource(innerInterface, linkGenerator, baseHeadingLevel + 2),
+      ),
+    },
+  };
+}
+
+type Groupable = { group?: string; groupDescription?: string };
+
+function adaptMembers<T extends Groupable, K>(
+  heading: string,
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkFromTypeNameGenerator: GetRenderableContentByTypeName,
+  headingLevel: number,
+): RenderableSection<K[] | GroupedMember<K>[]> & { isGrouped: boolean } {
+  return {
+    headingLevel,
+    heading,
+    isGrouped: hasGroup(members),
+    value: hasGroup(members)
+      ? toGroupedMembers(members, adapter, linkFromTypeNameGenerator, headingLevel + 1)
+      : toFlat(members, adapter, linkFromTypeNameGenerator, headingLevel + 1),
+  };
+}
+
+function hasGroup(members: Groupable[]): boolean {
+  return members.some((member) => member.group);
+}
+
+function toFlat<T extends Groupable, K>(
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): K[] {
+  return members.map((member) => adapter(member, linkGenerator, baseHeadingLevel));
+}
+
+function toGroupedMembers<T extends Groupable, K>(
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): GroupedMember<K>[] {
+  const groupedMembers = groupByGroupName(members);
+  return Object.entries(groupedMembers).map(([groupName, members]) =>
+    singleGroup(baseHeadingLevel, groupName, adapter, members, linkGenerator),
+  );
+}
+
+function groupByGroupName<T extends Groupable>(members: T[]): Record<string, T[]> {
+  return members.reduce(
+    (acc, member) => {
+      const groupName = member.group ?? 'Other';
+      acc[groupName] = acc[groupName] ?? [];
+      acc[groupName].push(member);
+      return acc;
+    },
+    {} as Record<string, T[]>,
+  );
+}
+
+function singleGroup<T extends Groupable, K>(
+  headingLevel: number,
+  groupName: string,
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  members: T[],
+  linkGenerator: GetRenderableContentByTypeName,
+): GroupedMember<K> {
+  return {
+    headingLevel: headingLevel,
+    heading: groupName,
+    groupDescription: members[0].groupDescription, // All fields in the group have the same description
+    value: toFlat(members, adapter, linkGenerator, headingLevel + 1),
+  };
+}

package/src/core/markdown/adapters/documentables.ts

@@ -0,0 +1,115 @@
+import { CustomTag, RenderableDocumentation, RenderableContent } from './types';
+import { Describable, Documentable, GetRenderableContentByTypeName } from './types';
+import { replaceInlineReferences } from './inline';
+import { isEmptyLine } from './type-utils';
+
+export function adaptDescribable(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): {
+  description?: RenderableContent[];
+} {
+  return {
+    description: describableToRenderableContent(describable, linkGenerator),
+  };
+}
+
+export function describableToRenderableContent(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): RenderableContent[] | undefined {
+  if (!describable) {
+    return;
+  }
+
+  let content: RenderableContent[] = [];
+  for (let i = 0; i < describable.length; i++) {
+    const line = describable[i];
+    // The language might or might not be present after ```
+    const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
+    if (codeBlockMatch) {
+      // Check if the language is present, if not, fallback to "apex"
+      const language = codeBlockMatch[1] || 'apex';
+      const codeBlockLines: string[] = [];
+      i++;
+      while (i < describable.length) {
+        const currentLine = describable[i];
+        if (currentLine.trim() === '```') {
+          break;
+        }
+        codeBlockLines.push(currentLine);
+        i++;
+      }
+      content = [
+        ...content,
+        {
+          __type: 'code-block',
+          language,
+          content: codeBlockLines,
+        },
+        { __type: 'empty-line' },
+      ];
+      continue;
+    }
+
+    content = [
+      ...content,
+      ...replaceInlineReferences(line, linkGenerator),
+      {
+        __type: 'empty-line',
+      },
+    ];
+  }
+  return (
+    content
+      // If the last element is an empty line, remove it
+      .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
+  );
+}
+
+export function adaptDocumentable(
+  documentable: Documentable,
+  linkGenerator: GetRenderableContentByTypeName,
+  subHeadingLevel: number,
+): RenderableDocumentation {
+  function extractCustomTags(type: Documentable): CustomTag[] {
+    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'throws', 'exception'];
+
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase()))
+        .map<CustomTag>((currentAnnotation) => ({
+          ...adaptDescribable(currentAnnotation.bodyLines, linkGenerator),
+          name: currentAnnotation.name,
+        })) ?? []
+    );
+  }
+
+  function extractAnnotationBody(type: Documentable, annotationName: string): string | undefined {
+    return type.docComment?.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
+    )?.body;
+  }
+
+  function extractSeeAnnotations(type: Documentable): string[] {
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === 'see')
+        .map((currentAnnotation) => currentAnnotation.body) ?? []
+    );
+  }
+  return {
+    ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
+    annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
+    customTags: extractCustomTags(documentable),
+    example: {
+      headingLevel: subHeadingLevel,
+      heading: 'Example',
+      value: describableToRenderableContent(documentable.docComment?.exampleAnnotation?.bodyLines, linkGenerator),
+    },
+    group: extractAnnotationBody(documentable, 'group'),
+    author: extractAnnotationBody(documentable, 'author'),
+    date: extractAnnotationBody(documentable, 'date'),
+    sees: extractSeeAnnotations(documentable).map(linkGenerator),
+  };
+}

package/src/core/markdown/adapters/fields-and-properties.ts

@@ -0,0 +1,45 @@
+import {
+  CodeBlock,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  RenderableField,
+  GetRenderableContentByTypeName,
+} from './types';
+import { adaptDocumentable } from './documentables';
+
+export function adaptFieldOrProperty(
+  field: FieldMirrorWithInheritance | PropertyMirrorWithInheritance,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableField {
+  function buildSignature(): CodeBlock {
+    const { access_modifier, name } = field;
+    const memberModifiers = field.memberModifiers.join(' ');
+    const codeContents = `${access_modifier} ${memberModifiers} ${name}`
+      // remove double spaces
+      .replace(/ {2}/g, ' ');
+    return {
+      __type: 'code-block',
+      language: 'apex',
+      content: [codeContents],
+    };
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    doc: adaptDocumentable(field, linkGenerator, baseHeadingLevel + 1),
+    heading: field.name,
+    type: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Type',
+      value: linkGenerator(field.typeReference.rawDeclaration),
+    },
+    inherited: field.inherited,
+    accessModifier: field.access_modifier,
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: buildSignature(),
+    },
+  };
+}

package/src/core/markdown/adapters/generate-link.ts

@@ -0,0 +1,82 @@
+import { StringOrLink } from './types';
+import path from 'path';
+import { LinkingStrategy } from '../../shared/types';
+
+export type LinkingStrategyFn = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string,
+  referenceName: string,
+) => StringOrLink;
+
+export const generateLink = (strategy: LinkingStrategy): LinkingStrategyFn => {
+  switch (strategy) {
+    case 'relative':
+      return generateRelativeLink;
+    case 'no-link':
+      return generateNoLink;
+    case 'none':
+      return returnReferenceAsIs;
+  }
+};
+
+const generateRelativeLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string, // The name of the file for which the reference is being generated
+  referenceName: string,
+): StringOrLink => {
+  function getRelativePath(fromPath: string, toPath: string) {
+    return path.relative(path.parse(path.join('/', fromPath)).dir, path.join('/', toPath));
+  }
+
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  // When linking from the base path (e.g. the reference guide/index page), the reference path is the same as the output
+  // path.
+  if (referenceTo && from === '__base__') {
+    return {
+      __type: 'link',
+      title: referenceTo.displayName,
+      url: getRelativePath('', referenceTo.referencePath),
+    };
+  }
+
+  const referenceFrom = references[from];
+
+  if (!referenceFrom) {
+    return referenceTo.displayName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: getRelativePath(referenceFrom.referencePath, referenceTo.referencePath),
+  };
+};
+
+const generateNoLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  return referenceTo ? referenceTo.displayName : referenceName;
+};
+
+const returnReferenceAsIs = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: referenceTo.referencePath,
+  };
+};

package/src/core/markdown/adapters/inline.ts

@@ -0,0 +1,143 @@
+import { InlineCode, Link, RenderableContent } from './types';
+import { pipe } from 'fp-ts/function';
+import { apply } from '#utils/fp';
+
+type InlineRenderableContent = InlineCode | Link | string;
+
+type ToInlineRenderableContent = (typeName: string) => InlineRenderableContent;
+
+function defaultGetEmailByReference(email: string): Link {
+  return {
+    __type: 'link',
+    title: email,
+    url: `mailto:${email}`,
+  };
+}
+
+export function replaceInlineReferences(
+  text: string,
+  linkReplacer: ToInlineRenderableContent,
+  emailReplacer: ToInlineRenderableContent = defaultGetEmailByReference,
+): RenderableContent[] {
+  const inlineLinks = apply(replaceInlineLinks, linkReplacer);
+  const inlineEmails = apply(replaceInlineEmails, emailReplacer);
+
+  return pipe(inlineCode([text]), inlineLinks, inlineEmails);
+}
+
+function inlineCode(renderableContents: RenderableContent[]): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineCodeContent(renderableContent));
+}
+
+// Replace string that is inline code with InlineCode
+// Inline code is any text that backticks surround
+function inlineCodeContent(renderableContent: RenderableContent): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  function inlineCodeLink(text: string): InlineCode {
+    return {
+      __type: 'inline-code',
+      content: text,
+    };
+  }
+
+  const text = renderableContent;
+
+  // Matches any text surrounded by backticks
+  const codeFormatRegEx = '`([^`]*)`';
+  const matches = match(codeFormatRegEx, text);
+  return createRenderableContents(matches, text, inlineCodeLink);
+}
+
+function replaceInlineLinks(
+  getLinkByTypeName: ToInlineRenderableContent,
+  renderableContents: RenderableContent[],
+): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineLinkContent(renderableContent, getLinkByTypeName));
+}
+
+function inlineLinkContent(
+  renderableContent: RenderableContent,
+  getLinkByTypeName: ToInlineRenderableContent,
+): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  const text = renderableContent;
+
+  // Matches either `<<ClassName>>` or `{@link ClassName}`
+  const linkFormatRegEx = '{@link (.*?)}|<<([^>]+)>>';
+  const matches = match(linkFormatRegEx, text);
+  return createRenderableContents(matches, text, getLinkByTypeName);
+}
+
+export function replaceInlineEmails(
+  getLinkByTypeName: ToInlineRenderableContent,
+  renderableContents: RenderableContent[],
+): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineEmailContent(renderableContent, getLinkByTypeName));
+}
+
+function inlineEmailContent(
+  renderableContent: RenderableContent,
+  getLinkByTypeName: ToInlineRenderableContent,
+): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  const text = renderableContent;
+
+  // Parsing references using the format '{@email email}'
+  const linkFormatRegEx = '{@email (.*?)}';
+  const matches = match(linkFormatRegEx, text);
+  return createRenderableContents(matches, text, getLinkByTypeName);
+}
+
+function match(regex: string, text: string) {
+  const expression = new RegExp(regex, 'gi');
+  let match;
+  const matches = [];
+
+  do {
+    match = expression.exec(text);
+    if (match) {
+      matches.push(match);
+    }
+  } while (match);
+
+  return matches;
+}
+
+function createRenderableContents(matches: RegExpExecArray[], text: string, linker: ToInlineRenderableContent) {
+  if (matches.length === 0) {
+    return [text];
+  }
+
+  const result: RenderableContent[] = [];
+  let lastIndex = 0;
+  for (const match of matches) {
+    const index = match.index;
+    const length = match[0].length;
+
+    // loop through the matches (skip the first one, which is the full match)
+    // until we find the first capturing group that has a value
+    const capturedGroup = match.slice(1).find((group) => group);
+    if (!capturedGroup) {
+      continue;
+    }
+    result.push(text.slice(lastIndex, index));
+    result.push(linker(capturedGroup));
+
+    lastIndex = index + length;
+  }
+
+  if (lastIndex < text.length) {
+    result.push(text.slice(lastIndex));
+  }
+
+  return result;
+}