@cparra/apexdocs 2.25.0-alpha.6 → 2.25.0-alpha.9

package/src/core/markdown/adapters/renderable-bundle.ts

@@ -1,144 +1,68 @@
-import { ParsedFile } from '../../shared/types';
-import { Link, RenderableBundle, StringOrLink } from './types';
+import { DocPageReference, ParsedFile } from '../../shared/types';
+import { Link, ReferenceGuideReference, Renderable, RenderableBundle, StringOrLink } from './types';
 import { typeToRenderable } from './apex-types';
 import { adaptDescribable } from './documentables';
-import { Type } from '@cparra/apex-reflection';
 import { MarkdownGeneratorConfig } from '../generate-docs';
+import { apply } from '#utils/fp';
+import { Type } from '@cparra/apex-reflection';
 
 export function parsedFilesToRenderableBundle(
   config: MarkdownGeneratorConfig,
   parsedFiles: ParsedFile[],
+  references: Record<string, DocPageReference>,
 ): RenderableBundle {
-  return parsedFiles.reduce<RenderableBundle>(
-    (acc, parsedFile) => {
-      const renderable = typeToRenderable(
-        parsedFile,
-        (referenceName) => {
-          return linkFromTypeNameGenerator(
-            parsedFile.type,
-            parsedFiles.map((file) => file.type),
-            referenceName,
-            config,
-          );
-        },
-        config,
-      );
-      acc.renderables.push(renderable);
+  const referenceFinder = apply(linkGenerator, references);
 
-      const descriptionLines = parsedFile.type.docComment?.descriptionLines;
-      const reference = {
-        typeName: parsedFile.type.name,
-        directory: getDirectoryFromRoot(config, parsedFile.type),
-        title: getLinkFromRoot(config, parsedFile.type),
-        description: adaptDescribable(descriptionLines, (referenceName) =>
-          getPossibleLinkFromRoot(
-            config,
-            referenceName,
-            findType(
-              parsedFiles.map((file) => file.type),
-              referenceName,
-            ),
-          ),
-        ).description,
-      };
-
-      const group = getTypeGroup(parsedFile.type, config);
-      if (!acc.references[group]) {
-        acc.references[group] = [];
-      }
-      acc.references[group].push(reference);
+  function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
+    return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
+      addToReferenceGuide(referenceFinder, config, references),
+      {},
+    );
+  }
 
+  function toRenderables(parsedFiles: ParsedFile[]): Renderable[] {
+    return parsedFiles.reduce<Renderable[]>((acc, parsedFile) => {
+      const renderable = typeToRenderable(parsedFile, referenceFinder, config);
+      acc.push(renderable);
       return acc;
-    },
-    {
-      references: {},
-      renderables: [],
-    },
-  );
-}
-
-function linkFromTypeNameGenerator(
-  typeBeingDocumented: Type,
-  repository: Type[],
-  referenceName: string,
-  config: MarkdownGeneratorConfig,
-): StringOrLink {
-  const type = findType(repository, referenceName);
-  if (!type) {
-    // If the type is not found, we return the type name as a string.
-    return referenceName;
+    }, []);
   }
 
-  const [fullClassName, fileLink] = getFileLinkTuple(typeBeingDocumented, type, config);
   return {
-    __type: 'link',
-    title: fullClassName,
-    url: fileLink,
+    referencesByGroup: toReferenceGuide(parsedFiles),
+    renderables: toRenderables(parsedFiles),
   };
 }
 
-function getPossibleLinkFromRoot(config: MarkdownGeneratorConfig, fallback: string, type?: Type): StringOrLink {
-  if (!type) {
-    return fallback;
-  }
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
-  const title = `${namespacePrefix}${type.name}`;
-  return {
-    __type: 'link',
-    title: title,
-    url: `${getDirectoryFromRoot(config, type)}/${title}.md`,
-  };
-}
-
-function getDirectoryFromRoot(config: MarkdownGeneratorConfig, type?: Type): string {
-  if (!type) {
-    return '';
-  }
-  return `./${getSanitizedGroup(type, config)}`;
-}
-
-function findType(repository: Type[], referenceName: string) {
-  return repository.find((currentType: Type) => currentType.name.toLowerCase() === referenceName.toLowerCase());
-}
-
-function getFileLinkTuple(
-  typeBeingDocumented: Type,
-  referencedType: Type,
+function addToReferenceGuide(
+  findLinkFromHome: (referenceName: string) => string | Link,
   config: MarkdownGeneratorConfig,
-): [string, string] {
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
-  const directoryRoot = `${getDirectoryRoot(typeBeingDocumented, referencedType, config)}`;
-  // TODO: Instead of adding a "." to the name when there is a namespace, maybe we want to create a folder for everything
-  // within that namespace and put the files in there.
-  const fullClassName = `${namespacePrefix}${referencedType.name}`;
-  return [fullClassName, `${directoryRoot}${fullClassName}.md`];
-}
+  references: Record<string, DocPageReference>,
+) {
+  return (acc: Record<string, ReferenceGuideReference[]>, parsedFile: ParsedFile) => {
+    const group: string = getTypeGroup(parsedFile.type, config);
+    if (!acc[group]) {
+      acc[group] = [];
+    }
+    acc[group].push({
+      reference: references[parsedFile.type.name],
+      title: findLinkFromHome(parsedFile.type.name) as Link,
+      description: adaptDescribable(parsedFile.type.docComment?.descriptionLines, findLinkFromHome).description ?? null,
+    });
 
-function getDirectoryRoot(typeBeingDocumented: Type, referencedType: Type, config: MarkdownGeneratorConfig) {
-  if (getTypeGroup(typeBeingDocumented, config) === getTypeGroup(referencedType, config)) {
-    // If the types the same groups then we simply link directly to that file
-    return './';
-  } else {
-    // If the types have different groups, then we have to go up a directory
-    return `../${getSanitizedGroup(referencedType, config)}/`;
-  }
+    return acc;
+  };
 }
 
+const linkGenerator = (references: Record<string, DocPageReference>, referenceName: string): StringOrLink => {
+  const reference: DocPageReference | undefined = references[referenceName];
+  return reference
+    ? // Starting the path with a "/" will ensure the link will always be relative to the root of the site.
+      { __type: 'link', title: reference.displayName, url: `/${reference.pathFromRoot}` }
+    : referenceName;
+};
+
 function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
   const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
   return groupAnnotation?.body ?? config.defaultGroupName;
 }
-
-function getSanitizedGroup(classModel: Type, config: MarkdownGeneratorConfig) {
-  return getTypeGroup(classModel, config).replace(/ /g, '-').replace('.', '');
-}
-
-function getLinkFromRoot(config: MarkdownGeneratorConfig, type: Type): Link {
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
-  const title = `${namespacePrefix}${type.name}`;
-  return {
-    __type: 'link',
-    title: title,
-    url: `${getDirectoryFromRoot(config, type)}/${title}.md`,
-  };
-}

package/src/core/markdown/adapters/renderable-to-page-data.ts

@@ -5,19 +5,20 @@ import { CompilationRequest, Template } from '../templates/template';
 import { enumMarkdownTemplate } from '../templates/enum-template';
 import { interfaceMarkdownTemplate } from '../templates/interface-template';
 import { classMarkdownTemplate } from '../templates/class-template';
+import { defaults } from '../../../defaults';
 
 export const convertToDocumentationBundle = (
   referenceGuideTemplate: string,
-  { references, renderables }: RenderableBundle,
+  { referencesByGroup, renderables }: RenderableBundle,
 ): DocumentationBundle => ({
   referenceGuide: {
-    directory: '',
     frontmatter: null,
-    content: referencesToReferenceGuideContent(references, referenceGuideTemplate),
-    fileExtension: 'md',
-    fileName: 'index',
+    content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
+    filePath: 'index.md',
   },
-  docs: renderables.map((renderable: Renderable) => renderableToPageData(Object.values(references).flat(), renderable)),
+  docs: renderables.map((renderable: Renderable) =>
+    renderableToPageData(Object.values(referencesByGroup).flat(), renderable),
+  ),
 });
 
 function referencesToReferenceGuideContent(
@@ -45,11 +46,9 @@ function referencesToReferenceGuideContent(
 
 function renderableToPageData(referenceGuideReference: ReferenceGuideReference[], renderable: Renderable): DocPageData {
   function buildDocOutput(renderable: Renderable, docContents: string): DocPageData {
-    const reference = referenceGuideReference.find(
-      (ref) => ref.typeName.toLowerCase() === renderable.name.toLowerCase(),
-    );
-
-    const namespacePrefix = renderable.namespace ? `${renderable.namespace}.` : '';
+    const reference: ReferenceGuideReference = referenceGuideReference.find(
+      (ref) => ref.reference.source.name.toLowerCase() === renderable.name.toLowerCase(),
+    )!;
 
     return {
       source: {
@@ -57,12 +56,10 @@ function renderableToPageData(referenceGuideReference: ReferenceGuideReference[]
         name: renderable.name,
         type: renderable.type,
       },
-      fileName: `${namespacePrefix}${renderable.name}`,
-      fileExtension: 'md',
-      directory: `${reference?.directory}`,
+      filePath: reference!.reference.pathFromRoot,
       frontmatter: null,
       content: docContents,
-      group: renderable.doc.group ?? 'Miscellaneous',
+      group: renderable.doc.group ?? defaults.defaultGroupName,
     };
   }
 

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

@@ -7,6 +7,7 @@ import {
   MethodMirror,
   PropertyMirror,
 } from '@cparra/apex-reflection';
+import { DocPageReference } from '../../shared/types';
 
 export type Describable = string[] | undefined;
 
@@ -24,17 +25,14 @@ export type MethodMirrorWithInheritance = MethodMirror & InheritanceSupport;
 // Renderable types
 
 export type ReferenceGuideReference = {
-  typeName: string;
-  directory: string;
+  reference: DocPageReference;
   title: Link;
-  description: RenderableContent[] | undefined;
+  description: RenderableContent[] | null;
 };
 
 export type RenderableBundle = {
   // References are grouped by their defined @group annotation
-  references: {
-    [key: string]: ReferenceGuideReference[];
-  };
+  referencesByGroup: Record<string, ReferenceGuideReference[]>;
   renderables: Renderable[];
 };
 
@@ -84,8 +82,7 @@ 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;

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

@@ -10,11 +10,14 @@ import {
   Frontmatter,
   PostHookDocumentationBundle,
   ReferenceGuidePageData,
-  SourceFile,
+  UnparsedSourceFile,
   TransformDocPage,
   TransformDocs,
   TransformReferenceGuide,
   UserDefinedMarkdownConfig,
+  DocPageReference,
+  TransformReference,
+  ParsedFile,
 } from '../shared/types';
 import { parsedFilesToRenderableBundle } from './adapters/renderable-bundle';
 import { reflectSourceCode } from './reflection/reflect-source';
@@ -27,6 +30,7 @@ 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,
@@ -37,6 +41,7 @@ export type MarkdownGeneratorConfig = Pick<
   | 'transformReferenceGuide'
   | 'transformDocs'
   | 'transformDocPage'
+  | 'transformReference'
 > & {
   referenceGuideTemplate: string;
   sortMembersAlphabetically: boolean;
@@ -48,8 +53,9 @@ export class HookError {
   constructor(public error: unknown) {}
 }
 
-export function generateDocs(apexBundles: SourceFile[], config: MarkdownGeneratorConfig) {
+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);
@@ -62,53 +68,45 @@ export function generateDocs(apexBundles: SourceFile[], config: MarkdownGenerato
     E.map(addInheritedMembersToTypes),
     E.map(addInheritanceChainToTypes),
     E.map(sortTypeMembers),
-    E.map(convertToRenderableBundle),
-    E.map(convertToDocumentationBundleForTemplate),
+    E.bindTo('parsedFiles'),
+    E.bind('references', ({ parsedFiles }) => E.right(convertToReferences(parsedFiles))),
     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,
-        }),
-      })),
-    })),
+    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 toFrontmatterString(frontmatter: Frontmatter): string {
-  if (typeof frontmatter === 'string') {
-    return frontmatter;
+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,
+    };
   }
 
-  if (!frontmatter) {
-    return '';
-  }
+  return ({ references, parsedFiles }: { references: Record<string, DocPageReference>; parsedFiles: ParsedFile[] }) =>
+    TE.tryCatch(
+      () => _execute(references, parsedFiles, config.transformReference),
+      (error) => new HookError(error),
+    );
+}
 
-  const yamlString = yaml.dump(frontmatter);
-  return `---\n${yamlString}---\n`;
+function transformDocumentationBundleHook(config: MarkdownGeneratorConfig) {
+  return (bundle: DocumentationBundle) =>
+    TE.tryCatch(
+      () => documentationBundleHook(bundle, config),
+      (error) => new HookError(error),
+    );
 }
 
 // Configurable hooks
@@ -116,6 +114,25 @@ 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,
@@ -156,3 +173,43 @@ const transformDocPage = async (doc: DocPageData, hook: TransformDocPage = passT
     ...(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/inheritance-chain-expanion.ts

@@ -3,7 +3,7 @@ import { createInheritanceChain } from './inheritance-chain';
 import { ParsedFile } from '../../shared/types';
 import { parsedFilesToTypes } from '../utils';
 
-export const addInheritanceChainToTypes = (parsedFiles: ParsedFile[]) =>
+export const addInheritanceChainToTypes = (parsedFiles: ParsedFile[]): ParsedFile[] =>
   parsedFiles.map((parsedFile) => ({
     ...parsedFile,
     type: addInheritanceChain(parsedFile.type, parsedFilesToTypes(parsedFiles)),

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

@@ -1,4 +1,4 @@
-import { ParsedFile, SourceFile } from '../../shared/types';
+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';
@@ -6,17 +6,21 @@ import * as O from 'fp-ts/Option';
 import { parseApexMetadata } from '../../parse-apex-metadata';
 import { ReflectionError } from './error-handling';
 
-export function reflectSourceCode(apexBundles: SourceFile[]) {
+export function reflectSourceCode(apexBundles: UnparsedSourceFile[]) {
   return apexBundles.map(reflectSourceBody);
 }
 
-function reflectSourceBody(apexBundle: SourceFile): E.Either<ReflectionError, ParsedFile> {
+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({
-        filePath,
+        source: {
+          filePath,
+          name: result.typeMirror!.name,
+          type: result.typeMirror!.type_name,
+        },
         type: addFileMetadataToTypeAnnotation(result.typeMirror!, metadata),
       });
 }

package/src/core/markdown/templates/documentable-partial-template.ts

@@ -21,6 +21,6 @@ export const documentablePartialTemplate = `
 
 {{#if doc.example.value}}
 {{ heading doc.example.headingLevel doc.example.heading }}
-{{code doc.example.value}}
+{{{renderContent doc.example.value}}}
 {{/if}}
 `.trim();

package/src/core/openapi/manifest-factory.ts

@@ -1,7 +1,7 @@
 import Manifest from '../manifest';
 import { TypeParser } from './parser';
 import { ReflectionResult } from '@cparra/apex-reflection';
-import { SourceFile } from '../shared/types';
+import { UnparsedSourceFile } from '../shared/types';
 
 /**
  * Builds a new Manifest object, sourcing its types from the received TypeParser.
@@ -10,7 +10,7 @@ import { SourceFile } from '../shared/types';
  */
 export function createManifest(
   typeParser: TypeParser,
-  reflect: (apexBundle: SourceFile) => ReflectionResult,
+  reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult,
 ): Manifest {
   return new Manifest(typeParser.parse(reflect));
 }

package/src/core/openapi/openapi-type-file.ts

@@ -4,9 +4,7 @@ import { OpenApiPageData } from '../shared/types';
 export function createOpenApiFile(fileName: string, openApiModel: OpenApi): OpenApiPageData {
   const content = JSON.stringify({ ...openApiModel, namespace: undefined }, null, 2);
   return {
-    fileExtension: 'json',
-    fileName,
-    directory: '',
+    filePath: '',
     content,
     frontmatter: null,
     group: null,

package/src/core/openapi/parser.ts

@@ -1,18 +1,18 @@
 import { ClassMirror, InterfaceMirror, ReflectionResult, Type } from '@cparra/apex-reflection';
 import { parseApexMetadata } from '../parse-apex-metadata';
 import { Logger } from '#utils/logger';
-import { SourceFile } from '../shared/types';
+import { UnparsedSourceFile } from '../shared/types';
 
 export interface TypeParser {
-  parse(reflect: (apexBundle: SourceFile) => ReflectionResult): Type[];
+  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[];
 }
 
 type NameAware = { name: string };
 
 export class RawBodyParser implements TypeParser {
-  constructor(public typeBundles: SourceFile[]) {}
+  constructor(public typeBundles: UnparsedSourceFile[]) {}
 
-  parse(reflect: (apexBundle: SourceFile) => ReflectionResult): Type[] {
+  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[] {
     const types = this.typeBundles
       .map((currentBundle) => {
         Logger.log(`Parsing file: ${currentBundle.filePath}`);