@cparra/apexdocs 3.0.0 → 3.1.0

package/src/core/markdown/generate-docs.ts

@@ -1,210 +0,0 @@
-import { pipe } from 'fp-ts/function';
-import * as TE from 'fp-ts/TaskEither';
-import yaml from 'js-yaml';
-
-import { apply } from '#utils/fp';
-import {
-  DocPageData,
-  DocumentationBundle,
-  Frontmatter,
-  PostHookDocumentationBundle,
-  ReferenceGuidePageData,
-  UnparsedSourceFile,
-  TransformDocPage,
-  TransformDocs,
-  TransformReferenceGuide,
-  UserDefinedMarkdownConfig,
-  DocPageReference,
-  TransformReference,
-  ParsedFile,
-} from '../shared/types';
-import { parsedFilesToRenderableBundle } from './adapters/renderable-bundle';
-import { reflectBundles } from './reflection/reflect-source';
-import { addInheritanceChainToTypes } from './reflection/inheritance-chain-expanion';
-import { addInheritedMembersToTypes } from './reflection/inherited-member-expansion';
-import { convertToDocumentationBundle } from './adapters/renderable-to-page-data';
-import { filterScope } from './reflection/filter-scope';
-import { Template } from './templates/template';
-import { hookableTemplate } from './templates/hookable';
-import { sortTypesAndMembers } from './reflection/sort-types-and-members';
-import { isSkip } from '../shared/utils';
-import { parsedFilesToReferenceGuide } from './adapters/reference-guide';
-import { removeExcludedTags } from './reflection/remove-excluded-tags';
-
-export type MarkdownGeneratorConfig = Omit<
-  UserDefinedMarkdownConfig,
-  'sourceDir' | 'targetGenerator' | 'includeMetadata'
-> & {
-  referenceGuideTemplate: string;
-};
-
-export class HookError {
-  readonly _tag = 'HookError';
-
-  constructor(public error: unknown) {}
-}
-
-export function generateDocs(apexBundles: UnparsedSourceFile[], config: MarkdownGeneratorConfig) {
-  const filterOutOfScope = apply(filterScope, config.scope);
-  const convertToReferences = apply(parsedFilesToReferenceGuide, config);
-  const convertToRenderableBundle = apply(parsedFilesToRenderableBundle, config);
-  const convertToDocumentationBundleForTemplate = apply(
-    convertToDocumentationBundle,
-    config.referenceGuideTitle,
-    config.referenceGuideTemplate,
-  );
-  const sort = apply(sortTypesAndMembers, config.sortAlphabetically);
-  const removeExcluded = apply(removeExcludedTags, config.excludeTags);
-
-  return pipe(
-    apexBundles,
-    reflectBundles,
-    TE.map(filterOutOfScope),
-    TE.map(addInheritedMembersToTypes),
-    TE.map(addInheritanceChainToTypes),
-    TE.map(sort),
-    TE.map(removeExcluded),
-    TE.bindTo('parsedFiles'),
-    TE.bind('references', ({ parsedFiles }) => TE.right(convertToReferences(parsedFiles))),
-    TE.flatMap(({ parsedFiles, references }) => transformReferenceHook(config)({ references, parsedFiles })),
-    TE.map(({ parsedFiles, references }) => convertToRenderableBundle(parsedFiles, references)),
-    TE.map(convertToDocumentationBundleForTemplate),
-    TE.flatMap(transformDocumentationBundleHook(config)),
-    TE.map(postHookCompile),
-  );
-}
-
-function transformReferenceHook(config: MarkdownGeneratorConfig) {
-  async function _execute(
-    references: Record<string, DocPageReference>,
-    parsedFiles: ParsedFile[],
-    transformReference?: TransformReference | undefined,
-  ): Promise<{
-    references: Record<string, DocPageReference>;
-    parsedFiles: ParsedFile[];
-  }> {
-    return {
-      references: await execTransformReferenceHook(Object.values(references), transformReference),
-      parsedFiles,
-    };
-  }
-
-  return ({ references, parsedFiles }: { references: Record<string, DocPageReference>; parsedFiles: ParsedFile[] }) =>
-    TE.tryCatch(
-      () => _execute(references, parsedFiles, config.transformReference),
-      (error) => new HookError(error),
-    );
-}
-
-function transformDocumentationBundleHook(config: MarkdownGeneratorConfig) {
-  return (bundle: DocumentationBundle) =>
-    TE.tryCatch(
-      () => documentationBundleHook(bundle, config),
-      (error) => new HookError(error),
-    );
-}
-
-// Configurable hooks
-function passThroughHook<T>(value: T): T {
-  return value;
-}
-
-const execTransformReferenceHook = async (
-  references: DocPageReference[],
-  hook: TransformReference = passThroughHook,
-): Promise<Record<string, DocPageReference>> => {
-  const hooked = references.map<Promise<DocPageReference>>(async (reference) => {
-    const hookedResult = await hook(reference);
-    return {
-      ...reference,
-      ...hookedResult,
-    };
-  });
-  const awaited = await Promise.all(hooked);
-
-  return awaited.reduce<Record<string, DocPageReference>>((acc, reference) => {
-    acc[reference.source.name] = reference;
-    return acc;
-  }, {});
-};
-
-const documentationBundleHook = async (
-  bundle: DocumentationBundle,
-  config: MarkdownGeneratorConfig,
-): Promise<PostHookDocumentationBundle> => {
-  return {
-    referenceGuide: await transformReferenceGuide(bundle.referenceGuide, config.transformReferenceGuide),
-    docs: await transformDocs(bundle.docs, config.transformDocs, config.transformDocPage),
-  };
-};
-
-const transformReferenceGuide = async (
-  referenceGuide: ReferenceGuidePageData,
-  hook: TransformReferenceGuide = passThroughHook,
-) => {
-  const result = await hook(referenceGuide);
-  if (isSkip(result)) {
-    return result;
-  }
-
-  return {
-    ...referenceGuide,
-    ...(await hook(referenceGuide)),
-  };
-};
-
-const transformDocs = async (
-  docs: DocPageData[],
-  transformDocsHook: TransformDocs = passThroughHook,
-  transformDocPageHook: TransformDocPage = passThroughHook,
-): Promise<Awaited<DocPageData[]>> => {
-  const transformed = await transformDocsHook(docs);
-  return Promise.all(transformed.map((doc) => transformDocPage(doc, transformDocPageHook)));
-};
-
-const transformDocPage = async (doc: DocPageData, hook: TransformDocPage = passThroughHook) => {
-  return {
-    ...doc,
-    ...(await hook(doc)),
-  };
-};
-
-function postHookCompile(bundle: PostHookDocumentationBundle) {
-  return {
-    referenceGuide: isSkip(bundle.referenceGuide)
-      ? bundle.referenceGuide
-      : {
-          ...bundle.referenceGuide,
-          content: Template.getInstance().compile({
-            source: {
-              frontmatter: toFrontmatterString(bundle.referenceGuide.frontmatter),
-              content: bundle.referenceGuide.content,
-            },
-            template: hookableTemplate,
-          }),
-        },
-    docs: bundle.docs.map((doc) => ({
-      ...doc,
-      content: Template.getInstance().compile({
-        source: {
-          frontmatter: toFrontmatterString(doc.frontmatter),
-          content: doc.content,
-        },
-        template: hookableTemplate,
-      }),
-    })),
-  };
-}
-
-function toFrontmatterString(frontmatter: Frontmatter): string {
-  if (typeof frontmatter === 'string') {
-    return frontmatter;
-  }
-
-  if (!frontmatter) {
-    return '';
-  }
-
-  const yamlString = yaml.dump(frontmatter);
-  return `---\n${yamlString}---\n`;
-}

package/src/core/markdown/reflection/__test__/filter-scope.spec.ts

@@ -1,290 +0,0 @@
-import { ClassMirror, EnumMirror, InterfaceMirror } from '@cparra/apex-reflection';
-import { filterScope } from '../filter-scope';
-import { parsedFileFromRawString } from './helpers';
-
-describe('When filtering scope', () => {
-  it('filters out files with the @ignore annotation', () => {
-    const properties: [string, number][] = [
-      [
-        `
-        /**
-         * @ignore
-         */
-        global class MyClass {}
-        `,
-        0,
-      ],
-      ['global class MyClass {}', 1],
-    ];
-
-    for (const [input, expected] of properties) {
-      const parsedFile = parsedFileFromRawString(input);
-
-      const result = filterScope(['global'], [parsedFile]);
-
-      expect(result).toHaveLength(expected);
-    }
-  });
-
-  describe('when scoping a class', () => {
-    it('filters out methods tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global class MyClass {
-            /**
-             * @ignore
-             */
-            global void myMethod() {}
-          }
-          `,
-          0,
-        ],
-        [
-          `
-          global class MyClass {
-            global void myMethod() {}
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as ClassMirror).methods).toHaveLength(expected);
-      }
-    });
-
-    it('filters out properties tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global class MyClass {
-            /**
-             * @ignore
-             */
-            global Integer myProperty { get; set; }
-          }
-          `,
-          0,
-        ],
-        [
-          `
-          global class MyClass {
-            global Integer myProperty { get; set; }
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as ClassMirror).properties).toHaveLength(expected);
-      }
-    });
-
-    it('filters out fields tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global class MyClass {
-            /**
-             * @ignore
-             */
-            global Integer myField;
-          }
-          `,
-          0,
-        ],
-        [
-          `
-          global class MyClass {
-            global Integer myField;
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as ClassMirror).fields).toHaveLength(expected);
-      }
-    });
-
-    it('filters out inner classes tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global class MyClass {
-            /**
-             * @ignore
-             */
-            global class InnerClass {}
-          }
-          `,
-          0,
-        ],
-        [
-          `
-          global class MyClass {
-            global class InnerClass {}
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as ClassMirror).classes).toHaveLength(expected);
-      }
-    });
-
-    it('filters out inner interfaces tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global class MyClass {
-            /**
-             * @ignore
-             */
-            global interface InnerInterface {}
-          }
-          `,
-          0,
-        ],
-        [
-          `
-          global class MyClass {
-            global interface InnerInterface {}
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as ClassMirror).interfaces).toHaveLength(expected);
-      }
-    });
-
-    it('filters out inner enums tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global class MyClass {
-            /**
-             * @ignore
-             */
-            global enum InnerEnum {}
-          }
-          `,
-          0,
-        ],
-        [
-          `
-          global class MyClass {
-            global enum InnerEnum {}
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as ClassMirror).enums).toHaveLength(expected);
-      }
-    });
-  });
-
-  describe('when scoping an interface', () => {
-    it('filters out methods tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global interface MyInterface {
-            /**
-             * @ignore
-             */
-            void myMethod();
-          }
-          `,
-          0,
-        ],
-        [
-          `
-          global interface MyInterface {
-            void myMethod();
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as InterfaceMirror).methods).toHaveLength(expected);
-      }
-    });
-  });
-
-  describe('when scoping an enum', () => {
-    it('never filters out enum values, even if tagged with @ignore', () => {
-      const properties: [string, number][] = [
-        [
-          `
-          global enum MyEnum {
-            /**
-             * @ignore
-             */
-            VALUE
-          }
-          `,
-          1,
-        ],
-        [
-          `
-          global enum MyEnum {
-            VALUE
-          }
-          `,
-          1,
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const parsedFile = parsedFileFromRawString(input);
-
-        const result = filterScope(['global'], [parsedFile]);
-
-        expect((result[0].type as EnumMirror).values).toHaveLength(expected);
-      }
-    });
-  });
-});

package/src/core/markdown/reflection/__test__/helpers.ts

@@ -1,18 +0,0 @@
-import { ParsedFile } from '../../../shared/types';
-import { reflect } from '@cparra/apex-reflection';
-
-export function parsedFileFromRawString(raw: string): ParsedFile {
-  const { error, typeMirror } = reflect(raw);
-  if (error) {
-    throw new Error(error.message);
-  }
-
-  return {
-    source: {
-      filePath: 'test.cls',
-      name: typeMirror!.name,
-      type: typeMirror!.type_name,
-    },
-    type: typeMirror!,
-  };
-}

package/src/core/markdown/reflection/__test__/remove-excluded-tags.spec.ts

@@ -1,200 +0,0 @@
-import { parsedFileFromRawString } from './helpers';
-import { removeExcludedTags } from '../remove-excluded-tags';
-import { ClassMirror, InterfaceMirror } from '@cparra/apex-reflection';
-
-describe('when removing excluded tags', () => {
-  describe('from any type', () => {
-    it('removes annotations', () => {
-      const tagsToExclude = ['group'];
-      const content = `
-        /**
-         * @group MyGroup
-         * @custom myCustomTag
-         */
-        global class MyClass {}
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect(result[0].type.docComment?.annotations).toHaveLength(1);
-      expect(result[0].type.docComment?.annotations[0].name).toBe('custom');
-    });
-
-    it('removes example annotations', () => {
-      const tagsToExclude = ['example'];
-      const content = `
-        /**
-         * @example
-         * This is my example
-         * public void myMethod() {}
-         */
-        global class MyClass {}
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect(result[0].type.docComment?.exampleAnnotation).toBeNull();
-    });
-
-    it('removes params annotations', () => {
-      const tagsToExclude = ['param'];
-      const content = `
-        /**
-         * @param myParam
-         * public void myMethod() {}
-         */
-        global class MyClass {}
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect(result[0].type.docComment?.paramAnnotations).toHaveLength(0);
-    });
-
-    it('removes the return annotation', () => {
-      const tagsToExclude = ['return'];
-      const content = `
-        /**
-         * @return myReturn
-         * public void myMethod() {}
-         */
-        global class MyClass {}
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect(result[0].type.docComment?.returnAnnotation).toBeNull();
-    });
-
-    it('removes the throws annotations', () => {
-      const tagsToExclude = ['throws'];
-      const content = `
-        /**
-         * @throws MyException
-         * public void myMethod() {}
-         */
-        global class MyClass {}
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect(result[0].type.docComment?.throwsAnnotations).toHaveLength(0);
-    });
-
-    it('removes the exception annotations', () => {
-      const tagsToExclude = ['exception'];
-      const content = `
-        /**
-         * @exception MyException
-         * public void myMethod() {}
-         */
-        global class MyClass {}
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect(result[0].type.docComment?.throwsAnnotations).toHaveLength(0);
-    });
-
-    it('removes descriptions', () => {
-      const tagsToExclude = ['description'];
-      const content = `
-        /**
-         * @description This is my description
-         * public void myMethod() {}
-         */
-        global class MyClass {}
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect(result[0].type.docComment?.description).toBe('');
-      expect(result[0].type.docComment?.descriptionLines).toHaveLength(0);
-    });
-  });
-
-  describe('from an interface', () => {
-    it('removes annotations from methods', () => {
-      const tagsToExclude = ['throws'];
-      const content = `
-        global interface MyInterface {
-          /**
-           * @throws MyException
-           */
-          void myMethod();
-        }
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      expect((result[0].type as InterfaceMirror).methods[0].docComment?.throwsAnnotations).toHaveLength(0);
-    });
-  });
-
-  describe('from a class', () => {
-    it('removes annotations from members', () => {
-      const tagsToExclude = ['throws'];
-      const content = `
-        global class MyClass {
-          /**
-           * @throws MyException
-           */
-          String myProperty {get; set;}
-          
-          /**
-           * @throws MyException
-           */
-          String myField;
-          /**
-           * @throws MyException
-           */
-          void myMethod() {}
-          
-          /**
-           * @throws MyException
-           */
-          MyClass() {}
-          
-          /**
-           * @throws MyException
-           */
-           public enum MyEnum {}
-           
-          /**
-            * @throws MyException
-            */
-          interface MyInnerInterface {}
-          
-          /**
-            * @throws MyException
-            */
-          class MyInnerClass {}
-        }
-        `;
-      const parsedFile = parsedFileFromRawString(content);
-
-      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
-
-      const classMirror = result[0].type as ClassMirror;
-      expect(classMirror.methods[0].docComment?.throwsAnnotations).toHaveLength(0);
-      expect(classMirror.properties[0].docComment?.throwsAnnotations).toHaveLength(0);
-      expect(classMirror.fields[0].docComment?.throwsAnnotations).toHaveLength(0);
-      expect(classMirror.constructors[0].docComment?.throwsAnnotations).toHaveLength(0);
-      expect(classMirror.enums[0].docComment?.throwsAnnotations).toHaveLength(0);
-      expect(classMirror.interfaces[0].docComment?.throwsAnnotations).toHaveLength(0);
-      expect(classMirror.classes[0].docComment?.throwsAnnotations).toHaveLength(0);
-    });
-  });
-});
-
-// fields
-// inner interfaces
-// inner classes