@cparra/apexdocs 2.25.0-alpha.1 → 2.25.0-alpha.10

package/src/core/{renderable → markdown/adapters}/types.d.ts

@@ -1,15 +1,56 @@
+// Apex Reflection-based types
+import {
+  Annotation as MirrorAnnotation,
+  ClassMirror,
+  DocComment,
+  FieldMirror,
+  MethodMirror,
+  PropertyMirror,
+} from '@cparra/apex-reflection';
+import { DocPageReference } from '../../shared/types';
+
+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 = {
+  reference: DocPageReference;
+  title: Link;
+  description: RenderableContent[] | null;
+};
+
+export type RenderableBundle = {
+  // References are grouped by their defined @group annotation
+  referencesByGroup: Record<string, ReferenceGuideReference[]>;
+  renderables: Renderable[];
+};
+
 export type Link = {
+  readonly __type: 'link';
   title: string;
   url: string;
 };
 
 export type EmptyLine = {
-  type: 'empty-line';
+  __type: 'empty-line';
 };
 
 export type StringOrLink = string | Link;
 
-export type RenderableContent = StringOrLink | EmptyLine;
+export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+
+export type RenderableContent = StringOrLink | EmptyLine | CodeBlock | InlineCode;
 
 type EnumValue = {
   value: string;
@@ -22,18 +63,26 @@ type CustomTag = {
 };
 
 /**
- * Represents an annotation to a top-level type. For example @NamespaceAccessible.
+ * Represents an annotation to a top-level type. For example, @NamespaceAccessible.
  */
 type Annotation = string;
 
-type CodeBlock = 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[];
-  mermaid: RenderableSection<CodeBlock | undefined>;
-  example: RenderableSection<CodeBlock | undefined>;
+  example: RenderableSection<RenderableContent[] | undefined>;
   group?: string;
   author?: string;
   date?: string;
@@ -102,7 +151,7 @@ export type GroupedMember<T> = RenderableSection<T[]> & { groupDescription: stri
 
 export type RenderableClass = RenderableType & {
   type: 'class';
-  extends?: StringOrLink;
+  extends?: StringOrLink[];
   implements?: StringOrLink[];
   classModifier?: string;
   sharingModifier?: string;
@@ -128,4 +177,4 @@ export type RenderableEnum = RenderableType & {
   values: RenderableSection<EnumValue[]>;
 };
 
-export type Renderable = RenderableClass | RenderableInterface | RenderableEnum;
+export type Renderable = (RenderableClass | RenderableInterface | RenderableEnum) & { filePath: string };

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

@@ -0,0 +1,216 @@
+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,
+  UnparsedSourceFile,
+  TransformDocPage,
+  TransformDocs,
+  TransformReferenceGuide,
+  UserDefinedMarkdownConfig,
+  DocPageReference,
+  TransformReference,
+  ParsedFile,
+} 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';
+import { parsedFilesToReferenceGuide } from './adapters/reference-guide';
+
+export type MarkdownGeneratorConfig = Pick<
+  UserDefinedMarkdownConfig,
+  | 'targetDir'
+  | 'scope'
+  | 'namespace'
+  | 'defaultGroupName'
+  | 'transformReferenceGuide'
+  | 'transformDocs'
+  | 'transformDocPage'
+  | 'transformReference'
+  | 'documentationRootDir'
+> & {
+  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,
+    reflectSourceCode,
+    checkForReflectionErrors,
+    E.map(filterOutOfScope),
+    E.map(addInheritedMembersToTypes),
+    E.map(addInheritanceChainToTypes),
+    E.map(sortTypeMembers),
+    E.bindTo('parsedFiles'),
+    E.bind('references', ({ parsedFiles }) => E.right(convertToReferences(parsedFiles))),
+    TE.fromEither,
+    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/error-handling.ts

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,23 @@
+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

@@ -0,0 +1,105 @@
+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

@@ -0,0 +1,45 @@
+import { ParsedFile, UnparsedSourceFile } 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: UnparsedSourceFile[]) {
+  return apexBundles.map(reflectSourceBody);
+}
+
+function reflectSourceBody(apexBundle: UnparsedSourceFile): 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({
+        source: {
+          filePath,
+          name: result.typeMirror!.name,
+          type: result.typeMirror!.type_name,
+        },
+        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

@@ -0,0 +1,59 @@
+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),
+  };
+}

package/src/{transpiler/markdown/plain-markdown → core/markdown/templates}/class-template.ts

@@ -6,13 +6,15 @@ export const classMarkdownTemplate = `
 
 {{> typeDocumentation}}
 
-{{#if extends}}
-**Extends**
-{{link extends}}
+{{#if extends.length}}
+**Inheritance**
+
+{{#each extends}}{{link this}}{{#unless @last}} < {{/unless}}{{/each}}
 {{/if}}
 
 {{#if implements}}
 **Implements**
+
 {{#each implements}}
 {{link this}}{{#unless @last}}, {{/unless}}
 {{/each}}

package/src/{transpiler/markdown/plain-markdown → core/markdown/templates}/constructors-partial-template.ts

@@ -6,14 +6,14 @@ export const constructorsPartialTemplate = `
 {{#> documentablePartialTemplate}}
 
 {{ heading signature.headingLevel signature.heading }}
-{{ code "apex" signature.value }}
+{{ code signature.value }}
 
 {{#if parameters.value}}
 {{ heading parameters.headingLevel parameters.heading }}
 | Name | Type | Description |
 |------|------|-------------|
 {{#each parameters.value}}
-| {{name}} | {{type}} | {{description}} |
+| {{name}} | {{link type}} | {{description}} |
 {{/each}}
 {{/if}}