@cparra/apexdocs 2.25.0-alpha.8 → 2.25.0

package/src/core/markdown/adapters/types.d.ts

@@ -1,182 +0,0 @@
-// Apex Reflection-based types
-import {
-  Annotation as MirrorAnnotation,
-  ClassMirror,
-  DocComment,
-  FieldMirror,
-  MethodMirror,
-  PropertyMirror,
-} from '@cparra/apex-reflection';
-
-export type Describable = string[] | undefined;
-
-export type Documentable = {
-  annotations: MirrorAnnotation[];
-  docComment?: DocComment;
-};
-
-export type InheritanceSupport = { inherited: boolean };
-export type ClassMirrorWithInheritanceChain = ClassMirror & { inheritanceChain: string[] };
-export type FieldMirrorWithInheritance = FieldMirror & InheritanceSupport;
-export type PropertyMirrorWithInheritance = PropertyMirror & InheritanceSupport;
-export type MethodMirrorWithInheritance = MethodMirror & InheritanceSupport;
-
-// Renderable types
-
-export type ReferenceGuideReference = {
-  typeName: string;
-  directory: string;
-  title: Link;
-  description: RenderableContent[] | undefined;
-};
-
-export type RenderableBundle = {
-  // References are grouped by their defined @group annotation
-  references: {
-    [key: string]: ReferenceGuideReference[];
-  };
-  renderables: Renderable[];
-};
-
-export type Link = {
-  readonly __type: 'link';
-  title: string;
-  url: string;
-};
-
-export type EmptyLine = {
-  __type: 'empty-line';
-};
-
-export type StringOrLink = string | Link;
-
-export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
-
-export type RenderableContent = StringOrLink | EmptyLine | CodeBlock | InlineCode;
-
-type EnumValue = {
-  value: string;
-  description?: RenderableContent[];
-};
-
-type CustomTag = {
-  name: string;
-  description?: RenderableContent[];
-};
-
-/**
- * Represents an annotation to a top-level type. For example, @NamespaceAccessible.
- */
-type Annotation = string;
-
-type CodeBlock = {
-  readonly __type: 'code-block';
-  language: string;
-  content: string[];
-};
-
-type InlineCode = {
-  readonly __type: 'inline-code';
-  content: string;
-};
-
-type RenderableDocumentation = {
-  annotations?: Annotation[];
-  description?: RenderableContent[];
-  customTags?: CustomTag[];
-  example: RenderableSection<RenderableContent[] | undefined>;
-  group?: string;
-  author?: string;
-  date?: string;
-  sees?: StringOrLink[];
-};
-
-type RenderableType = {
-  namespace?: string;
-  headingLevel: number;
-  heading: string;
-  name: string;
-  meta: {
-    accessModifier: string;
-  };
-  doc: RenderableDocumentation;
-};
-
-type RenderableMethodParameter = {
-  name: string;
-  type: StringOrLink;
-  description?: RenderableContent[];
-};
-
-type TypeSource = {
-  type: StringOrLink;
-  description?: RenderableContent[];
-};
-
-type RenderableConstructor = {
-  headingLevel: number;
-  heading: string;
-  signature: RenderableSection<CodeBlock>;
-  parameters?: RenderableSection<RenderableMethodParameter[] | undefined>;
-  throws?: RenderableSection<TypeSource[] | undefined>;
-  doc: RenderableDocumentation;
-};
-
-type RenderableMethod = {
-  doc: RenderableDocumentation;
-  headingLevel: number;
-  heading: string;
-  signature: RenderableSection<CodeBlock>;
-  parameters: RenderableSection<RenderableMethodParameter[] | undefined>;
-  returnType: RenderableSection<TypeSource>;
-  throws: RenderableSection<TypeSource[] | undefined>;
-  inherited?: boolean;
-};
-
-type RenderableField = {
-  headingLevel: number;
-  heading: string;
-  type: RenderableSection<StringOrLink>;
-  accessModifier: string;
-  inherited?: boolean;
-  signature: RenderableSection<CodeBlock>;
-  doc: RenderableDocumentation;
-};
-
-export type RenderableSection<T> = {
-  headingLevel: number;
-  heading: string;
-  value: T;
-};
-
-export type GroupedMember<T> = RenderableSection<T[]> & { groupDescription: string | undefined };
-
-export type RenderableClass = RenderableType & {
-  type: 'class';
-  extends?: StringOrLink[];
-  implements?: StringOrLink[];
-  classModifier?: string;
-  sharingModifier?: string;
-  constructors: RenderableSection<RenderableConstructor[] | GroupedMember<RenderableConstructor>[]> & {
-    isGrouped: boolean;
-  };
-  methods: RenderableSection<RenderableMethod[] | GroupedMember<RenderableMethod>[]> & { isGrouped: boolean };
-  fields: RenderableSection<RenderableField[] | GroupedMember<RenderableField>[]> & { isGrouped: boolean };
-  properties: RenderableSection<RenderableField[] | GroupedMember<RenderableField>[]> & { isGrouped: boolean };
-  innerClasses: RenderableSection<RenderableClass[]>;
-  innerEnums: RenderableSection<RenderableEnum[]>;
-  innerInterfaces: RenderableSection<RenderableInterface[]>;
-};
-
-export type RenderableInterface = RenderableType & {
-  type: 'interface';
-  extends?: StringOrLink[];
-  methods: RenderableSection<RenderableMethod[]>;
-};
-
-export type RenderableEnum = RenderableType & {
-  type: 'enum';
-  values: RenderableSection<EnumValue[]>;
-};
-
-export type Renderable = (RenderableClass | RenderableInterface | RenderableEnum) & { filePath: string };

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

@@ -1,158 +0,0 @@
-import { pipe } from 'fp-ts/function';
-import * as E from 'fp-ts/Either';
-import * as TE from 'fp-ts/TaskEither';
-import yaml from 'js-yaml';
-
-import { apply } from '#utils/fp';
-import {
-  DocPageData,
-  DocumentationBundle,
-  Frontmatter,
-  PostHookDocumentationBundle,
-  ReferenceGuidePageData,
-  SourceFile,
-  TransformDocPage,
-  TransformDocs,
-  TransformReferenceGuide,
-  UserDefinedMarkdownConfig,
-} from '../shared/types';
-import { parsedFilesToRenderableBundle } from './adapters/renderable-bundle';
-import { reflectSourceCode } from './reflection/reflect-source';
-import { checkForReflectionErrors } from './reflection/error-handling';
-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';
-
-export type MarkdownGeneratorConfig = Pick<
-  UserDefinedMarkdownConfig,
-  | 'targetDir'
-  | 'scope'
-  | 'namespace'
-  | 'defaultGroupName'
-  | 'transformReferenceGuide'
-  | 'transformDocs'
-  | 'transformDocPage'
-> & {
-  referenceGuideTemplate: string;
-  sortMembersAlphabetically: boolean;
-};
-
-export class HookError {
-  readonly _tag = 'HookError';
-
-  constructor(public error: unknown) {}
-}
-
-export function generateDocs(apexBundles: SourceFile[], config: MarkdownGeneratorConfig) {
-  const filterOutOfScope = apply(filterScope, config.scope);
-  const convertToRenderableBundle = apply(parsedFilesToRenderableBundle, config);
-  const convertToDocumentationBundleForTemplate = apply(convertToDocumentationBundle, config.referenceGuideTemplate);
-  const sortTypeMembers = apply(sortMembers, config.sortMembersAlphabetically);
-
-  return pipe(
-    apexBundles,
-    reflectSourceCode,
-    checkForReflectionErrors,
-    E.map(filterOutOfScope),
-    E.map(addInheritedMembersToTypes),
-    E.map(addInheritanceChainToTypes),
-    E.map(sortTypeMembers),
-    E.map(convertToRenderableBundle),
-    E.map(convertToDocumentationBundleForTemplate),
-    TE.fromEither,
-    TE.flatMap((bundle) =>
-      TE.tryCatch(
-        () => documentationBundleHook(bundle, config),
-        (error) => new HookError(error),
-      ),
-    ),
-    TE.map((bundle: PostHookDocumentationBundle) => ({
-      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`;
-}
-
-// Configurable hooks
-function passThroughHook<T>(value: T): T {
-  return value;
-}
-
-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)),
-  };
-};

package/src/core/markdown/reflection/error-handling.ts

@@ -1,37 +0,0 @@
-import * as E from 'fp-ts/Either';
-import { ParsedFile } from '../../shared/types';
-import { pipe } from 'fp-ts/function';
-
-export class ReflectionErrors {
-  readonly _tag = 'ReflectionErrors';
-  constructor(public errors: ReflectionError[]) {}
-}
-
-export class ReflectionError {
-  constructor(
-    public file: string,
-    public message: string,
-  ) {}
-}
-
-export function checkForReflectionErrors(reflectionResult: E.Either<ReflectionError, ParsedFile>[]) {
-  function reduceReflectionResultIntoSingleEither(results: E.Either<ReflectionError, ParsedFile>[]): {
-    errors: ReflectionError[];
-    parsedFiles: ParsedFile[];
-  } {
-    return results.reduce<{ errors: ReflectionError[]; parsedFiles: ParsedFile[] }>(
-      (acc, result) => {
-        E.isLeft(result) ? acc.errors.push(result.left) : acc.parsedFiles.push(result.right);
-        return acc;
-      },
-      {
-        errors: [],
-        parsedFiles: [],
-      },
-    );
-  }
-
-  return pipe(reflectionResult, reduceReflectionResultIntoSingleEither, ({ errors, parsedFiles }) =>
-    errors.length ? E.left(new ReflectionErrors(errors)) : E.right(parsedFiles),
-  );
-}

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

package/src/core/markdown/reflection/reflect-source.ts

@@ -1,41 +0,0 @@
-import { ParsedFile, SourceFile } from '../../shared/types';
-import * as E from 'fp-ts/Either';
-import { reflect as mirrorReflection, Type } from '@cparra/apex-reflection';
-import { pipe } from 'fp-ts/function';
-import * as O from 'fp-ts/Option';
-import { parseApexMetadata } from '../../parse-apex-metadata';
-import { ReflectionError } from './error-handling';
-
-export function reflectSourceCode(apexBundles: SourceFile[]) {
-  return apexBundles.map(reflectSourceBody);
-}
-
-function reflectSourceBody(apexBundle: SourceFile): E.Either<ReflectionError, ParsedFile> {
-  const { filePath, content: input, metadataContent: metadata } = apexBundle;
-  const result = mirrorReflection(input);
-  return result.error
-    ? E.left(new ReflectionError(filePath, result.error.message))
-    : E.right({
-        filePath,
-        type: addFileMetadataToTypeAnnotation(result.typeMirror!, metadata),
-      });
-}
-
-function addFileMetadataToTypeAnnotation(type: Type, metadata: string | null): Type {
-  return pipe(
-    O.fromNullable(metadata),
-    O.map((metadata) => {
-      const metadataParams = parseApexMetadata(metadata);
-      metadataParams.forEach((value, key) => {
-        const declaration = `${key}: ${value}`;
-        type.annotations.push({
-          rawDeclaration: declaration,
-          name: declaration,
-          type: declaration,
-        });
-      });
-      return type;
-    }),
-    O.getOrElse(() => type),
-  );
-}

package/src/core/markdown/reflection/sort-members.ts

@@ -1,59 +0,0 @@
-import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
-import { ParsedFile } from '../../shared/types';
-
-type Named = { name: string };
-
-export function sortMembers(shouldSortMembers: boolean, parsedFiles: ParsedFile[]): ParsedFile[] {
-  return parsedFiles.map((parsedFile) => ({
-    ...parsedFile,
-    type: sortTypeMember(parsedFile.type, shouldSortMembers),
-  }));
-}
-
-function sortByNames<T extends Named>(shouldSort: boolean, a: T, b: T): number {
-  if (shouldSort) {
-    return a.name.localeCompare(b.name);
-  }
-  return 0;
-}
-
-function sortNamed<T extends Named>(shouldSort: boolean, items: T[]): T[] {
-  return items.sort((a, b) => sortByNames(shouldSort, a, b));
-}
-
-function sortTypeMember(type: Type, shouldSort: boolean): Type {
-  switch (type.type_name) {
-    case 'enum':
-      return sortEnumValues(shouldSort, type as EnumMirror);
-    case 'interface':
-      return sortInterfaceMethods(shouldSort, type as InterfaceMirror);
-    case 'class':
-      return sortClassMembers(shouldSort, type as ClassMirror);
-  }
-}
-
-function sortEnumValues(shouldSort: boolean, enumType: EnumMirror): EnumMirror {
-  return {
-    ...enumType,
-    values: sortNamed(shouldSort, enumType.values),
-  };
-}
-
-function sortInterfaceMethods(shouldSort: boolean, interfaceType: InterfaceMirror): InterfaceMirror {
-  return {
-    ...interfaceType,
-    methods: sortNamed(shouldSort, interfaceType.methods),
-  };
-}
-
-function sortClassMembers(shouldSort: boolean, classType: ClassMirror): ClassMirror {
-  return {
-    ...classType,
-    fields: sortNamed(shouldSort, classType.fields),
-    classes: sortNamed(shouldSort, classType.classes),
-    enums: sortNamed(shouldSort, classType.enums),
-    interfaces: sortNamed(shouldSort, classType.interfaces),
-    methods: sortNamed(shouldSort, classType.methods),
-    properties: sortNamed(shouldSort, classType.properties),
-  };
-}