@cparra/apexdocs 2.25.0-alpha.9 → 2.25.0

package/src/core/markdown/__test__/test-helpers.ts

@@ -1,22 +0,0 @@
-import { UnparsedSourceFile } from '../../shared/types';
-import { generateDocs as gen, MarkdownGeneratorConfig } from '../generate-docs';
-import { referenceGuideTemplate } from '../templates/reference-guide';
-
-export function apexBundleFromRawString(raw: string, rawMetadata?: string): UnparsedSourceFile {
-  return {
-    filePath: 'test.cls',
-    content: raw,
-    metadataContent: rawMetadata ?? null,
-  };
-}
-
-export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial<MarkdownGeneratorConfig>) {
-  return gen(apexBundles, {
-    targetDir: 'target',
-    scope: ['global', 'public'],
-    defaultGroupName: 'Miscellaneous',
-    sortMembersAlphabetically: true,
-    referenceGuideTemplate: referenceGuideTemplate,
-    ...config,
-  });
-}

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

@@ -1,109 +0,0 @@
-import { adaptDescribable } from '../documentables';
-
-function linkGenerator(typeName: string) {
-  return typeName;
-}
-
-describe('describable', () => {
-  it('returns undefined if describable is undefined', () => {
-    const result = adaptDescribable(undefined, linkGenerator);
-
-    expect(result).toEqual({
-      description: undefined,
-    });
-  });
-
-  it('returns an empty array if describable is an empty array', () => {
-    const result = adaptDescribable([], linkGenerator);
-
-    expect(result).toEqual({
-      description: [],
-    });
-  });
-
-  it('returns a string if describable contains a string', () => {
-    const describable = ['This is a test'];
-
-    const result = adaptDescribable(describable, linkGenerator);
-
-    expect(result).toEqual({
-      description: ['This is a test'],
-    });
-  });
-
-  it('separates strings with an empty line', () => {
-    const describable = ['This is a test', 'This is another test'];
-
-    const result = adaptDescribable(describable, linkGenerator);
-
-    expect(result).toEqual({
-      description: ['This is a test', { __type: 'empty-line' }, 'This is another test'],
-    });
-  });
-
-  it('returns a code block if describable contains code', () => {
-    const describable = ['```typescript', 'const a = 1;', '```'];
-
-    const result = adaptDescribable(describable, linkGenerator);
-
-    expect(result).toEqual({
-      description: [
-        {
-          __type: 'code-block',
-          language: 'typescript',
-          content: ['const a = 1;'],
-        },
-      ],
-    });
-  });
-
-  it('sets the code blocks language to apex if one is not provided', () => {
-    const describable = ['```', 'const a = 1;', '```'];
-
-    const result = adaptDescribable(describable, linkGenerator);
-
-    expect(result).toEqual({
-      description: [
-        {
-          __type: 'code-block',
-          language: 'apex',
-          content: ['const a = 1;'],
-        },
-      ],
-    });
-  });
-
-  it('returns a code block followed by an empty line and then whatever content is in the describable', () => {
-    const describable = ['```typescript', 'const a = 1;', '```', 'This is a test'];
-
-    const result = adaptDescribable(describable, linkGenerator);
-
-    expect(result).toEqual({
-      description: [
-        {
-          __type: 'code-block',
-          language: 'typescript',
-          content: ['const a = 1;'],
-        },
-        { __type: 'empty-line' },
-        'This is a test',
-      ],
-    });
-  });
-
-  it('returns a code block even when there is no closing tag', () => {
-    const describable = ['```typescript', 'const a = 1;'];
-
-    const result = adaptDescribable(describable, linkGenerator);
-
-    expect(result).toEqual({
-      description: [
-        {
-          __type: 'code-block',
-          language: 'typescript',
-          content: ['const a = 1;'],
-        },
-      ],
-    });
-  });
-});

package/src/core/markdown/adapters/__tests__/interface-adapter.spec.ts

@@ -1,147 +0,0 @@
-import { typeToRenderable } from '../apex-types';
-import { InterfaceMirrorBuilder } from '../../../../test-helpers/InterfaceMirrorBuilder';
-import { AnnotationBuilder } from '../../../../test-helpers/AnnotationBuilder';
-import { MethodMirrorBuilder, ParameterBuilder } from '../../../../test-helpers/MethodMirrorBuilder';
-import { MarkdownGeneratorConfig } from '../../generate-docs';
-
-function linkGenerator(type: string): string {
-  return type;
-}
-
-const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
-  targetDir: '',
-  scope: ['global', 'public'],
-  namespace: '',
-  defaultGroupName: 'Miscellaneous',
-  referenceGuideTemplate: '',
-  sortMembersAlphabetically: false,
-};
-
-describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {
-  it('converts the name', () => {
-    const interfaceMirror = new InterfaceMirrorBuilder().withName('SampleInterface').build();
-    const interfaceSource = typeToRenderable(
-      {
-        source: {
-          filePath: '',
-          type: 'interface',
-          name: 'SampleInterface',
-        },
-        type: interfaceMirror,
-      },
-      linkGenerator,
-      defaultMarkdownGeneratorConfig,
-    );
-
-    expect(interfaceSource.name).toBe('SampleInterface');
-  });
-
-  it('converts the access modifier', () => {
-    const interfaceMirror = new InterfaceMirrorBuilder().build();
-    const interfaceSource = typeToRenderable(
-      {
-        source: {
-          filePath: '',
-          type: 'interface',
-          name: 'SampleInterface',
-        },
-        type: interfaceMirror,
-      },
-      linkGenerator,
-      defaultMarkdownGeneratorConfig,
-    );
-
-    expect(interfaceSource.meta.accessModifier).toBe('public');
-  });
-
-  it('converts annotations', () => {
-    const interfaceMirror = new InterfaceMirrorBuilder()
-      .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
-      .build();
-    const interfaceSource = typeToRenderable(
-      {
-        source: {
-          filePath: '',
-          type: 'interface',
-          name: 'SampleInterface',
-        },
-        type: interfaceMirror,
-      },
-      linkGenerator,
-      defaultMarkdownGeneratorConfig,
-    );
-
-    expect(interfaceSource.doc.annotations).toEqual(['MYANNOTATION']);
-  });
-
-  it('converts method declarations. Method with no parameters', () => {
-    const interfaceMirror = new InterfaceMirrorBuilder()
-      .addMethod(
-        new MethodMirrorBuilder()
-          .withName('sampleMethod')
-          .withTypeReference({
-            type: 'String',
-            rawDeclaration: 'String',
-          })
-          .build(),
-      )
-      .build();
-
-    const interfaceSource = typeToRenderable(
-      {
-        source: {
-          filePath: '',
-          type: 'interface',
-          name: 'SampleInterface',
-        },
-        type: interfaceMirror,
-      },
-      linkGenerator,
-      defaultMarkdownGeneratorConfig,
-    );
-
-    expect(interfaceSource.methods.value).toHaveLength(1);
-    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe('public String sampleMethod()');
-  });
-
-  it('converts method declarations. Method with parameters', () => {
-    const interfaceMirror = new InterfaceMirrorBuilder()
-      .addMethod(
-        new MethodMirrorBuilder()
-          .withName('sampleMethod')
-          .withTypeReference({
-            type: 'String',
-            rawDeclaration: 'String',
-          })
-          .addParameter(
-            new ParameterBuilder()
-              .withName('param1')
-              .withTypeReference({
-                type: 'String',
-                rawDeclaration: 'String',
-              })
-              .build(),
-          )
-          .build(),
-      )
-      .build();
-
-    const interfaceSource = typeToRenderable(
-      {
-        source: {
-          filePath: '',
-          type: 'interface',
-          name: 'SampleInterface',
-        },
-        type: interfaceMirror,
-      },
-      linkGenerator,
-      defaultMarkdownGeneratorConfig,
-    );
-
-    expect(interfaceSource.methods.value).toHaveLength(1);
-    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe(
-      'public String sampleMethod(String param1)',
-    );
-  });
-});

package/src/core/markdown/adapters/__tests__/references.spec.ts

@@ -1,136 +0,0 @@
-import { replaceInlineReferences } from '../inline';
-import { Link } from '../types';
-
-function getFileLink(typeName: string): Link {
-  return {
-    __type: 'link' as const,
-    title: typeName,
-    url: `/api/${typeName}.html`,
-  };
-}
-
-function getEmailLink(typeName: string) {
-  return {
-    __type: 'link' as const,
-    title: typeName,
-    url: `mailto:${typeName}`,
-  };
-}
-
-describe('reference utilities', () => {
-  it('returns a RenderableContent array with the full string when there are no links', () => {
-    const text = 'This is a test';
-    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
-
-    const expected = ['This is a test'];
-
-    expect(result).toEqual(expected);
-  });
-
-  describe('replace inline code', () => {
-    it('replaces inline code with InlineCode', () => {
-      const text = 'This is a test `ClassName`.';
-      const result = replaceInlineReferences(text, getFileLink, getEmailLink);
-
-      const expected = ['This is a test ', { __type: 'inline-code', content: 'ClassName' }, '.'];
-
-      expect(result).toEqual(expected);
-    });
-  });
-
-  describe('replace inline links', () => {
-    it('replaces links in the format of <<ClassName>>', () => {
-      const text = 'This is a test <<ClassName>>.';
-      const result = replaceInlineReferences(text, getFileLink, getEmailLink);
-
-      const expected = [
-        'This is a test ',
-        {
-          __type: 'link',
-          title: 'ClassName',
-          url: '/api/ClassName.html',
-        },
-        '.',
-      ];
-
-      expect(result).toEqual(expected);
-    });
-    it('replaces links in the format of {@link ClassName}', () => {
-      function getFileLinkByTypeName(typeName: string): Link {
-        return {
-          __type: 'link' as const,
-          title: typeName,
-          url: `/api/${typeName}.html`,
-        };
-      }
-
-      const text = 'This is a test {@link ClassName}';
-      const result = replaceInlineReferences(text, getFileLinkByTypeName, getEmailLink);
-
-      const expected = [
-        'This is a test ',
-        {
-          __type: 'link',
-          title: 'ClassName',
-          url: '/api/ClassName.html',
-        },
-      ];
-
-      expect(result).toEqual(expected);
-    });
-  });
-
-  describe('replace inline emails', () => {
-    it('replaces emails in the format of {@email email-address}', () => {
-      function getLinkByTypeName(typeName: string) {
-        return {
-          __type: 'link' as const,
-          title: typeName,
-          url: `mailto:${typeName}`,
-        };
-      }
-
-      const text = 'This is an email {@email example@example.com}';
-      const result = replaceInlineReferences(text, getFileLink, getLinkByTypeName);
-
-      const expected = [
-        'This is an email ',
-        {
-          __type: 'link',
-          title: 'example@example.com',
-          url: 'mailto:example@example.com',
-        },
-      ];
-
-      expect(result).toEqual(expected);
-    });
-  });
-
-  it('replaces both links and emails in the same string', () => {
-    const text = 'This is a test <<ClassName>>, and {@link AnotherClass}, and an email {@email testerson}';
-    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
-
-    const expected = [
-      'This is a test ',
-      {
-        __type: 'link',
-        title: 'ClassName',
-        url: '/api/ClassName.html',
-      },
-      ', and ',
-      {
-        __type: 'link',
-        title: 'AnotherClass',
-        url: '/api/AnotherClass.html',
-      },
-      ', and an email ',
-      {
-        __type: 'link',
-        title: 'testerson',
-        url: 'mailto:testerson',
-      },
-    ];
-
-    expect(result).toEqual(expected);
-  });
-});

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),
-  };
-}