@cparra/apexdocs 3.0.0-rc.0 → 3.1.0

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

@@ -1,212 +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 { sortMembers } from './reflection/sort-members';
-import { isSkip } from '../shared/utils';
-import { parsedFilesToReferenceGuide } from './adapters/reference-guide';
-
-export type MarkdownGeneratorConfig = Pick<
-  UserDefinedMarkdownConfig,
-  | 'targetDir'
-  | 'scope'
-  | 'namespace'
-  | 'defaultGroupName'
-  | 'transformReferenceGuide'
-  | 'transformDocs'
-  | 'transformDocPage'
-  | 'transformReference'
-  | 'linkingStrategy'
-> & {
-  referenceGuideTemplate: string;
-  sortMembersAlphabetically: boolean;
-};
-
-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.referenceGuideTemplate);
-  const sortTypeMembers = apply(sortMembers, config.sortMembersAlphabetically);
-
-  return pipe(
-    apexBundles,
-    reflectBundles,
-    TE.map(filterOutOfScope),
-    TE.map(addInheritedMembersToTypes),
-    TE.map(addInheritanceChainToTypes),
-    TE.map(sortTypeMembers),
-    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,306 +0,0 @@
-import { ParsedFile } from '../../../shared/types';
-import { ClassMirror, EnumMirror, InterfaceMirror, reflect } from '@cparra/apex-reflection';
-import { filterScope } from '../filter-scope';
-
-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!,
-  };
-}
-
-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/filter-scope.ts

@@ -1,13 +0,0 @@
-import { ParsedFile } from '../../shared/types';
-import Manifest from '../../manifest';
-
-export function filterScope(scopes: string[], parsedFiles: ParsedFile[]): ParsedFile[] {
-  return parsedFiles
-    .filter(({ type }) => Manifest.shouldFilterType(type, scopes))
-    .map((parsedFile) => {
-      return {
-        ...parsedFile,
-        type: Manifest.filterSingleType(parsedFile.type, scopes, false),
-      };
-    });
-}

package/src/core/markdown/reflection/inheritance-chain-expanion.ts

@@ -1,22 +0,0 @@
-import { ClassMirror, Type } from '@cparra/apex-reflection';
-import { createInheritanceChain } from './inheritance-chain';
-import { ParsedFile } from '../../shared/types';
-import { parsedFilesToTypes } from '../utils';
-
-export const addInheritanceChainToTypes = (parsedFiles: ParsedFile[]): ParsedFile[] =>
-  parsedFiles.map((parsedFile) => ({
-    ...parsedFile,
-    type: addInheritanceChain(parsedFile.type, parsedFilesToTypes(parsedFiles)),
-  }));
-
-function addInheritanceChain<T extends Type>(current: T, repository: Type[]): T {
-  if (current.type_name === 'enum' || current.type_name === 'interface') {
-    return current;
-  } else {
-    const inheritanceChain = createInheritanceChain(repository, current as ClassMirror);
-    return {
-      ...current,
-      inheritanceChain,
-    };
-  }
-}

package/src/core/markdown/reflection/inheritance-chain.ts

@@ -1,23 +0,0 @@
-import { ClassMirror, Type } from '@cparra/apex-reflection';
-import { pipe } from 'fp-ts/function';
-import * as O from 'fp-ts/Option';
-
-export function createInheritanceChain(repository: Type[], classMirror: ClassMirror): string[] {
-  return pipe(
-    O.fromNullable(classMirror.extended_class),
-    O.match(
-      () => [],
-      (extendedClassName) => inheritanceChainFromParentClassName(repository, extendedClassName),
-    ),
-  );
-}
-
-function inheritanceChainFromParentClassName(repository: Type[], className: string): string[] {
-  return pipe(
-    O.fromNullable(repository.find((type) => type.name.toLowerCase() === className.toLowerCase())),
-    O.match(
-      () => [className],
-      (extendedClass: Type) => [className, ...createInheritanceChain(repository, extendedClass as ClassMirror)],
-    ),
-  );
-}

package/src/core/markdown/reflection/inherited-member-expansion.ts

@@ -1,105 +0,0 @@
-import { ClassMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
-import { ParsedFile } from '../../shared/types';
-import { pipe } from 'fp-ts/function';
-import { parsedFilesToTypes } from '../utils';
-
-export const addInheritedMembersToTypes = (parsedFiles: ParsedFile[]) =>
-  parsedFiles.map((parsedFile) => addInheritedMembers(parsedFilesToTypes(parsedFiles), parsedFile));
-
-export function addInheritedMembers(repository: Type[], parsedFile: ParsedFile): ParsedFile {
-  function addInheritedMembersToType<T extends Type>(repository: Type[], current: T): T {
-    if (current.type_name === 'enum') {
-      return current;
-    } else if (current.type_name === 'interface') {
-      return addInheritedInterfaceMethods(current as InterfaceMirror, repository) as T;
-    } else {
-      return addInheritedClassMembers(current as ClassMirror, repository) as T;
-    }
-  }
-
-  return {
-    ...parsedFile,
-    type: addInheritedMembersToType(repository, parsedFile.type),
-  };
-}
-
-function addInheritedInterfaceMethods(interfaceMirror: InterfaceMirror, repository: Type[]): InterfaceMirror {
-  function methodAlreadyExists(memberName: string, members: { name: string }[]) {
-    return members.some((member) => member.name.toLowerCase() === memberName.toLowerCase());
-  }
-
-  function parentExtractor(interfaceMirror: InterfaceMirror): string[] {
-    return interfaceMirror.extended_interfaces;
-  }
-
-  const parents = getParents(parentExtractor, interfaceMirror, repository);
-  return {
-    ...interfaceMirror,
-    methods: parents.reduce(
-      (acc, currentValue) => [
-        ...acc,
-        ...currentValue.methods
-          .filter((method) => !methodAlreadyExists(method.name, acc))
-          .map((method) => ({
-            ...method,
-            inherited: true,
-          })),
-      ],
-      interfaceMirror.methods,
-    ),
-  };
-}
-
-function addInheritedClassMembers(classMirror: ClassMirror, repository: Type[]): ClassMirror {
-  function memberAlreadyExists(memberName: string, members: { name: string }[]) {
-    return members.some((member) => member.name.toLowerCase() === memberName.toLowerCase());
-  }
-
-  function parentExtractor(classMirror: ClassMirror): string[] {
-    return classMirror.extended_class ? [classMirror.extended_class] : [];
-  }
-
-  function filterMember<T extends { name: string; access_modifier: string }>(members: T[], existing: T[]): T[] {
-    return members
-      .filter((member) => member.access_modifier.toLowerCase() !== 'private')
-      .filter((member) => !memberAlreadyExists(member.name, existing))
-      .map((member) => ({
-        ...member,
-        inherited: true,
-      }));
-  }
-
-  const parents = getParents(parentExtractor, classMirror, repository);
-  return {
-    ...classMirror,
-    fields: parents.reduce(
-      (acc, currentValue) => [...acc, ...filterMember(currentValue.fields, acc)],
-      classMirror.fields,
-    ),
-    properties: parents.reduce(
-      (acc, currentValue) => [...acc, ...filterMember(currentValue.properties, acc)],
-      classMirror.properties,
-    ),
-    methods: parents.reduce(
-      (acc, currentValue) => [...acc, ...filterMember(currentValue.methods, acc)],
-      classMirror.methods,
-    ),
-  };
-}
-
-function getParents<T extends Type>(
-  extendedNamesExtractor: (current: T) => string[],
-  current: T,
-  repository: Type[],
-): T[] {
-  return pipe(
-    extendedNamesExtractor(current),
-    (interfaces: string[]) => interfaces.map((interfaceName) => repository.find((type) => type.name === interfaceName)),
-    (interfaces = []) => interfaces.filter((type) => type !== undefined) as T[],
-    (interfaces) =>
-      interfaces.reduce<T[]>(
-        (acc, current) => [...acc, ...getParents(extendedNamesExtractor, current, repository)],
-        interfaces,
-      ),
-  );
-}