@cparra/apexdocs 3.0.0 → 3.1.0

package/src/core/markdown/__test__/generating-reference-guide.spec.ts

@@ -1,196 +0,0 @@
-import { assertEither, extendExpect } from './expect-extensions';
-import { pipe } from 'fp-ts/function';
-import * as E from 'fp-ts/Either';
-import { apexBundleFromRawString, generateDocs } from './test-helpers';
-import { ReferenceGuidePageData } from '../../shared/types';
-
-describe('When generating the Reference Guide', () => {
-  beforeAll(() => {
-    extendExpect();
-  });
-
-  it('contains the correct default title by default', async () => {
-    const result = await generateDocs([])();
-
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('# Apex Reference Guide'),
-    );
-  });
-
-  it('allows for the reference guide title to be configured', async () => {
-    const result = await generateDocs([], { referenceGuideTitle: 'Custom Title' })();
-
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('# Custom Title'),
-    );
-  });
-
-  it('returns a reference guide with links to all other files', async () => {
-    const input1 = `
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](miscellaneous/MyEnum.md)'),
-    );
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](miscellaneous/MyClass.md)'),
-    );
-  });
-
-  it('groups things under Miscellaneous if no group is provided', async () => {
-    const input = `
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input)])();
-    expect(result).documentationBundleHasLength(1);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('## Miscellaneous'),
-    );
-  });
-
-  it('group things under the provided group', async () => {
-    const input = `
-      /**
-        * @group MyGroup
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input)])();
-    expect(result).documentationBundleHasLength(1);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('## MyGroup'),
-    );
-  });
-
-  it('displays groups in alphabetical order', async () => {
-    const input1 = `
-      /**
-        * @group ZGroup
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @group AGroup
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    pipe(
-      result,
-      E.map((data) => ({
-        aGroupIndex: (data.referenceGuide as ReferenceGuidePageData).content.indexOf('## AGroup'),
-        zGroupIndex: (data.referenceGuide as ReferenceGuidePageData).content.indexOf('## ZGroup'),
-      })),
-      E.match(
-        () => fail('Expected data'),
-        (data) => expect(data.aGroupIndex).toBeLessThan(data.zGroupIndex),
-      ),
-    );
-  });
-
-  it('displays references within groups in alphabetical order', async () => {
-    const input1 = `
-      /**
-        * @group Group1
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @group Group1
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('## Group1'),
-    );
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('MyClass'),
-    );
-    assertEither(result, (data) => expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('MyEnum'));
-  });
-
-  it('returns a reference guide with descriptions', async () => {
-    const input1 = `
-      /**
-        * @description This is a description
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @description This is a description
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('This is a description'),
-    );
-  });
-
-  it('returns a reference guide with descriptions with links to all other files', async () => {
-    const input1 = `
-      /**
-        * @description This is a description with a {@link MyClass}
-        * @group Group1
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @group Group2
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](group2/MyClass.md)'),
-    );
-  });
-});

package/src/core/markdown/__test__/inheritance-chain.test.ts

@@ -1,54 +0,0 @@
-import { ClassMirrorBuilder } from '../../../test-helpers/ClassMirrorBuilder';
-import { createInheritanceChain } from '../reflection/inheritance-chain';
-
-describe('inheritance chain for classes', () => {
-  test('returns an empty list of the class does not extend any other class', () => {
-    const classMirror = new ClassMirrorBuilder().build();
-    const repository = [classMirror];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual([]);
-  });
-
-  test('returns the name of the extended class if it is not found in the repository', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
-    const repository = [classMirror];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['ExtendedClass']);
-  });
-
-  test('returns the extended class when it is present in the repository', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
-    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').build();
-    const repository = [classMirror, extendedClass];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['ExtendedClass']);
-  });
-
-  test('returns the full inheritance chain when the extended class is also extended', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
-    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').withExtendedClass('SuperClass').build();
-    const superClass = new ClassMirrorBuilder().withName('SuperClass').build();
-    const repository = [classMirror, extendedClass, superClass];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['ExtendedClass', 'SuperClass']);
-  });
-
-  test('returns the inheritance for a class that extends an inner class', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('OuterClass.InnerClass').build();
-    const innerClass = new ClassMirrorBuilder().withName('InnerClass').build();
-    const outerClass = new ClassMirrorBuilder().withName('OuterClass').addInnerClass(innerClass).build();
-    const repository = [classMirror, outerClass];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['OuterClass.InnerClass']);
-  });
-});

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

@@ -1,25 +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',
-    sortAlphabetically: false,
-    referenceGuideTemplate: referenceGuideTemplate,
-    linkingStrategy: 'relative',
-    excludeTags: [],
-    referenceGuideTitle: 'Apex Reference Guide',
-    ...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,150 +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: '',
-  sortAlphabetically: false,
-  linkingStrategy: 'relative',
-  referenceGuideTitle: 'Apex Reference Guide',
-  excludeTags: [],
-};
-
-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__/link-generator.spec.ts

@@ -1,130 +0,0 @@
-import { generateLink } from '../generate-link';
-
-describe('Generates links', () => {
-  describe('relative', () => {
-    it('generates relative links from the base when found', () => {
-      const references = {
-        referenceName: {
-          referencePath: 'referencePath',
-          displayName: 'displayName',
-        },
-      };
-      const from = '__base__';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('relative')(references, from, referenceName);
-
-      expect(result).toEqual({
-        __type: 'link',
-        title: 'displayName',
-        url: 'referencePath',
-      });
-    });
-
-    it('returns the name of the reference when not found', () => {
-      const references = {};
-      const from = '__base__';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('relative')(references, from, referenceName);
-
-      expect(result).toEqual('referenceName');
-    });
-
-    it('returns a relative path when linking from a file', () => {
-      const references = {
-        referenceName: {
-          referencePath: 'a/referencePath',
-          displayName: 'displayName',
-        },
-        from: {
-          referencePath: 'b/fromPath',
-          displayName: 'fromName',
-        },
-      };
-      const from = 'from';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('relative')(references, from, referenceName);
-
-      expect(result).toEqual({
-        __type: 'link',
-        title: 'displayName',
-        url: '../a/referencePath',
-      });
-    });
-
-    it('returns the display name when the from reference is not found', () => {
-      const references = {
-        referenceName: {
-          referencePath: 'a/referencePath',
-          displayName: 'displayName',
-        },
-      };
-      const from = 'from';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('relative')(references, from, referenceName);
-
-      expect(result).toEqual('displayName');
-    });
-  });
-
-  describe('no-link', () => {
-    it('returns the name of the reference when the reference is not found', () => {
-      const references = {};
-      const from = '__base__';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('no-link')(references, from, referenceName);
-
-      expect(result).toEqual('referenceName');
-    });
-
-    it('returns the display name of the reference when the reference is found', () => {
-      const references = {
-        referenceName: {
-          referencePath: 'referencePath',
-          displayName: 'displayName',
-        },
-      };
-      const from = '__base__';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('no-link')(references, from, referenceName);
-
-      expect(result).toEqual('displayName');
-    });
-  });
-
-  describe('none', () => {
-    it('returns the path as is when the reference is found', () => {
-      const references = {
-        referenceName: {
-          referencePath: 'referencePath',
-          displayName: 'displayName',
-        },
-      };
-      const from = '__base__';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('none')(references, from, referenceName);
-
-      expect(result).toEqual({
-        __type: 'link',
-        title: 'displayName',
-        url: 'referencePath',
-      });
-    });
-
-    it('returns the name of the reference when the reference is not found', () => {
-      const references = {};
-      const from = '__base__';
-      const referenceName = 'referenceName';
-
-      const result = generateLink('none')(references, from, referenceName);
-
-      expect(result).toEqual('referenceName');
-    });
-  });
-});