@cparra/apexdocs 3.0.0-rc.0 → 3.1.0

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

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

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

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

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

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