@cparra/apexdocs 2.25.0-alpha.3 → 2.25.0-alpha.5

package/src/core/markdown/__test__/test-helpers.ts

@@ -0,0 +1,22 @@
+import { SourceFile } from '../../shared/types';
+import { generateDocs as gen, MarkdownGeneratorConfig } from '../generate-docs';
+import { referenceGuideTemplate } from '../templates/reference-guide';
+
+export function apexBundleFromRawString(raw: string, rawMetadata?: string): SourceFile {
+  return {
+    filePath: 'test.cls',
+    content: raw,
+    metadataContent: rawMetadata ?? null,
+  };
+}
+
+export function generateDocs(apexBundles: SourceFile[], config?: Partial<MarkdownGeneratorConfig>) {
+  return gen(apexBundles, {
+    targetDir: 'target',
+    scope: ['global', 'public'],
+    defaultGroupName: 'Miscellaneous',
+    sortMembersAlphabetically: true,
+    referenceGuideTemplate: referenceGuideTemplate,
+    ...config,
+  });
+}

package/src/core/markdown/adapters/__tests__/documentables.spec.ts

@@ -0,0 +1,109 @@
+import { adaptDescribable } from '../documentables';
+
+function linkGenerator(typeName: string) {
+  return typeName;
+}
+
+describe('describable', () => {
+  it('returns undefined if describable is undefined', () => {
+    const result = adaptDescribable(undefined, linkGenerator);
+
+    expect(result).toEqual({
+      description: undefined,
+    });
+  });
+
+  it('returns an empty array if describable is an empty array', () => {
+    const result = adaptDescribable([], linkGenerator);
+
+    expect(result).toEqual({
+      description: [],
+    });
+  });
+
+  it('returns a string if describable contains a string', () => {
+    const describable = ['This is a test'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: ['This is a test'],
+    });
+  });
+
+  it('separates strings with an empty line', () => {
+    const describable = ['This is a test', 'This is another test'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: ['This is a test', { __type: 'empty-line' }, 'This is another test'],
+    });
+  });
+
+  it('returns a code block if describable contains code', () => {
+    const describable = ['```typescript', 'const a = 1;', '```'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'typescript',
+          content: ['const a = 1;'],
+        },
+      ],
+    });
+  });
+
+  it('sets the code blocks language to apex if one is not provided', () => {
+    const describable = ['```', 'const a = 1;', '```'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'apex',
+          content: ['const a = 1;'],
+        },
+      ],
+    });
+  });
+
+  it('returns a code block followed by an empty line and then whatever content is in the describable', () => {
+    const describable = ['```typescript', 'const a = 1;', '```', 'This is a test'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'typescript',
+          content: ['const a = 1;'],
+        },
+        { __type: 'empty-line' },
+        'This is a test',
+      ],
+    });
+  });
+
+  it('returns a code block even when there is no closing tag', () => {
+    const describable = ['```typescript', 'const a = 1;'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'typescript',
+          content: ['const a = 1;'],
+        },
+      ],
+    });
+  });
+});

package/src/core/{adapters → markdown/adapters}/__tests__/interface-adapter.spec.ts

@@ -1,23 +1,41 @@
 import { typeToRenderable } from '../apex-types';
-import { InterfaceMirrorBuilder } from '../../../test-helpers/InterfaceMirrorBuilder';
-import { AnnotationBuilder } from '../../../test-helpers/AnnotationBuilder';
-import { MethodMirrorBuilder, ParameterBuilder } from '../../../test-helpers/MethodMirrorBuilder';
+import { InterfaceMirrorBuilder } from '../../../../test-helpers/InterfaceMirrorBuilder';
+import { AnnotationBuilder } from '../../../../test-helpers/AnnotationBuilder';
+import { MethodMirrorBuilder, ParameterBuilder } from '../../../../test-helpers/MethodMirrorBuilder';
+import { MarkdownGeneratorConfig } from '../../generate-docs';
 
 function linkGenerator(type: string): string {
   return type;
 }
 
+const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
+  targetDir: '',
+  scope: ['global', 'public'],
+  namespace: '',
+  defaultGroupName: 'Miscellaneous',
+  referenceGuideTemplate: '',
+  sortMembersAlphabetically: false,
+};
+
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {
   it('converts the name', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().withName('SampleInterface').build();
-    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(
+      { filePath: '', type: interfaceMirror },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
 
     expect(interfaceSource.name).toBe('SampleInterface');
   });
 
   it('converts the access modifier', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().build();
-    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(
+      { filePath: '', type: interfaceMirror },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
 
     expect(interfaceSource.meta.accessModifier).toBe('public');
   });
@@ -26,7 +44,11 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
     const interfaceMirror = new InterfaceMirrorBuilder()
       .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
       .build();
-    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(
+      { filePath: '', type: interfaceMirror },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
 
     expect(interfaceSource.doc.annotations).toEqual(['MYANNOTATION']);
   });
@@ -44,7 +66,11 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(
+      { filePath: '', type: interfaceMirror },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
 
     expect(interfaceSource.methods.value).toHaveLength(1);
     expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe('public String sampleMethod()');
@@ -72,7 +98,11 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(
+      { filePath: '', type: interfaceMirror },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
 
     expect(interfaceSource.methods.value).toHaveLength(1);
     expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe(

package/src/core/{adapters → markdown/adapters}/__tests__/references.spec.ts

@@ -1,4 +1,4 @@
-import { replaceInlineReferences } from '../references';
+import { replaceInlineReferences } from '../inline';
 import { Link } from '../types';
 
 function getFileLink(typeName: string): Link {
@@ -27,6 +27,17 @@ describe('reference utilities', () => {
     expect(result).toEqual(expected);
   });
 
+  describe('replace inline code', () => {
+    it('replaces inline code with InlineCode', () => {
+      const text = 'This is a test `ClassName`.';
+      const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+      const expected = ['This is a test ', { __type: 'inline-code', content: 'ClassName' }, '.'];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
   describe('replace inline links', () => {
     it('replaces links in the format of <<ClassName>>', () => {
       const text = 'This is a test <<ClassName>>.';

package/src/core/{adapters → markdown/adapters}/apex-types.ts

@@ -9,11 +9,12 @@ import {
   ClassMirrorWithInheritanceChain,
   FieldMirrorWithInheritance,
   PropertyMirrorWithInheritance,
+  GetRenderableContentByTypeName,
 } from './types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
 import { adaptConstructor, adaptMethod } from './methods-and-constructors';
 import { adaptFieldOrProperty } from './fields-and-properties';
+import { MarkdownGeneratorConfig } from '../generate-docs';
 
 type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
   ? RenderableInterface
@@ -22,11 +23,12 @@ type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
     : RenderableEnum;
 
 export function typeToRenderable<T extends Type>(
-  type: T,
+  parsedFile: { filePath: string; type: T },
   linkGenerator: GetRenderableContentByTypeName,
-  namespace?: string,
-): GetReturnRenderable<T> {
+  config: MarkdownGeneratorConfig,
+): GetReturnRenderable<T> & { filePath: string; namespace?: string } {
   function getRenderable(): RenderableInterface | RenderableClass | RenderableEnum {
+    const { type } = parsedFile;
     switch (type.type_name) {
       case 'enum':
         return enumTypeToEnumSource(type as EnumMirror, linkGenerator) as RenderableEnum;
@@ -39,7 +41,8 @@ export function typeToRenderable<T extends Type>(
 
   return {
     ...(getRenderable() as GetReturnRenderable<T>),
-    namespace,
+    filePath: parsedFile.filePath,
+    namespace: config.namespace,
   };
 }
 

package/src/core/{adapters → markdown/adapters}/documentables.ts

@@ -1,6 +1,6 @@
 import { CustomTag, RenderableDocumentation, RenderableContent, CodeBlock } from './types';
-import { Describable, Documentable } from './types';
-import { GetRenderableContentByTypeName, replaceInlineReferences } from './references';
+import { Describable, Documentable, GetRenderableContentByTypeName } from './types';
+import { replaceInlineReferences } from './inline';
 import { isEmptyLine } from './type-utils';
 
 export function adaptDescribable(
@@ -32,7 +32,6 @@ export function adaptDescribable(
           codeBlockLines.push(currentLine);
           i++;
         }
-        console.log('codeBlockLines', codeBlockLines);
         content = [
           ...content,
           {
@@ -55,68 +54,9 @@ export function adaptDescribable(
     }
     return (
       content
-        .flatMap((line) => line)
         // If the last element is an empty line, remove it
         .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
     );
-
-    // TODO: Now we want to also extract code blocks if we encounter any line that starts with "```"
-
-    // return describable.reduce<RenderableContent[]>(
-    //   (acc, line) => {
-    //     if (line.trim() === '') {
-    //       return [...acc, { __type: 'empty-line' }];
-    //     }
-    //
-    //     // The language might or might not be present after ```
-    //     const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
-    //     if (codeBlockMatch) {
-    //       console.log('codeBlockMatch', codeBlockMatch);
-    //       // Check if the language is present, if not, fallback to "apex"
-    //       const language = codeBlockMatch[1] || 'apex';
-    //       const codeBlockLines: string[] = [];
-    //       let index = acc.length + 1;
-    //       while (index < describable.length) {
-    //         const currentLine = describable[index];
-    //         if (currentLine.trim() === '```') {
-    //           break;
-    //         }
-    //         codeBlockLines.push(currentLine);
-    //         index++;
-    //       }
-    //       return [
-    //         ...acc,
-    //         {
-    //           __type: 'code-block',
-    //           language,
-    //           content: codeBlockLines,
-    //         },
-    //       ];
-    //     }
-    //
-    //     return [
-    //       ...acc,
-    //       ...replaceInlineReferences(line, linkGenerator),
-    //       {
-    //         __type: 'empty-line',
-    //       },
-    //     ];
-    //   },
-    //   <RenderableContent[]>[],
-    // );
-
-    // return (
-    //   describable
-    //     .map<RenderableContent[]>((line) => [
-    //       ...replaceInlineReferences(line, linkGenerator),
-    //       {
-    //         __type: 'empty-line',
-    //       },
-    //     ])
-    //     .flatMap((line) => line)
-    //     // If the last element is an empty line, remove it
-    //     .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
-    // );
   }
 
   return {

package/src/core/{adapters → markdown/adapters}/fields-and-properties.ts

@@ -1,6 +1,11 @@
-import { CodeBlock, FieldMirrorWithInheritance, PropertyMirrorWithInheritance, RenderableField } from './types';
+import {
+  CodeBlock,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  RenderableField,
+  GetRenderableContentByTypeName,
+} from './types';
 import { adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
 
 export function adaptFieldOrProperty(
   field: FieldMirrorWithInheritance | PropertyMirrorWithInheritance,

package/src/core/{adapters/references.ts → markdown/adapters/inline.ts}

@@ -1,6 +1,10 @@
-import { Link, RenderableContent, StringOrLink } from './types';
+import { InlineCode, Link, RenderableContent } from './types';
+import { pipe } from 'fp-ts/function';
+import { apply } from '#utils/fp';
 
-export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+type InlineRenderableContent = InlineCode | Link | string;
+
+type ToInlineRenderableContent = (typeName: string) => InlineRenderableContent;
 
 function defaultGetEmailByReference(email: string): Link {
   return {
@@ -12,22 +16,51 @@ function defaultGetEmailByReference(email: string): Link {
 
 export function replaceInlineReferences(
   text: string,
-  linkReplacer: GetRenderableContentByTypeName,
-  emailReplacer: GetRenderableContentByTypeName = defaultGetEmailByReference,
+  linkReplacer: ToInlineRenderableContent,
+  emailReplacer: ToInlineRenderableContent = defaultGetEmailByReference,
 ): RenderableContent[] {
-  return replaceInlineEmails(replaceInlineLinks([text], linkReplacer), emailReplacer);
+  const inlineLinks = apply(replaceInlineLinks, linkReplacer);
+  const inlineEmails = apply(replaceInlineEmails, emailReplacer);
+
+  return pipe(inlineCode([text]), inlineLinks, inlineEmails);
+}
+
+function inlineCode(renderableContents: RenderableContent[]): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineCodeContent(renderableContent));
+}
+
+// Replace string that is inline code with InlineCode
+// Inline code is any text that backticks surround
+function inlineCodeContent(renderableContent: RenderableContent): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  function inlineCodeLink(text: string): InlineCode {
+    return {
+      __type: 'inline-code',
+      content: text,
+    };
+  }
+
+  const text = renderableContent;
+
+  // Matches any text surrounded by backticks
+  const codeFormatRegEx = '`([^`]*)`';
+  const matches = match(codeFormatRegEx, text);
+  return createRenderableContents(matches, text, inlineCodeLink);
 }
 
 function replaceInlineLinks(
+  getLinkByTypeName: ToInlineRenderableContent,
   renderableContents: RenderableContent[],
-  getLinkByTypeName: GetRenderableContentByTypeName,
 ): RenderableContent[] {
   return renderableContents.flatMap((renderableContent) => inlineLinkContent(renderableContent, getLinkByTypeName));
 }
 
 function inlineLinkContent(
   renderableContent: RenderableContent,
-  getLinkByTypeName: GetRenderableContentByTypeName,
+  getLinkByTypeName: ToInlineRenderableContent,
 ): RenderableContent[] {
   if (typeof renderableContent !== 'string') {
     return [renderableContent];
@@ -42,15 +75,15 @@ function inlineLinkContent(
 }
 
 export function replaceInlineEmails(
+  getLinkByTypeName: ToInlineRenderableContent,
   renderableContents: RenderableContent[],
-  getLinkByTypeName: GetRenderableContentByTypeName,
 ): RenderableContent[] {
   return renderableContents.flatMap((renderableContent) => inlineEmailContent(renderableContent, getLinkByTypeName));
 }
 
 function inlineEmailContent(
   renderableContent: RenderableContent,
-  getLinkByTypeName: GetRenderableContentByTypeName,
+  getLinkByTypeName: ToInlineRenderableContent,
 ): RenderableContent[] {
   if (typeof renderableContent !== 'string') {
     return [renderableContent];
@@ -79,7 +112,7 @@ function match(regex: string, text: string) {
   return matches;
 }
 
-function createRenderableContents(matches: RegExpExecArray[], text: string, linker: GetRenderableContentByTypeName) {
+function createRenderableContents(matches: RegExpExecArray[], text: string, linker: ToInlineRenderableContent) {
   if (matches.length === 0) {
     return [text];
   }

package/src/core/{adapters → markdown/adapters}/methods-and-constructors.ts

@@ -1,7 +1,12 @@
 import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
-import { RenderableConstructor, RenderableMethod, MethodMirrorWithInheritance, CodeBlock } from './types';
+import {
+  RenderableConstructor,
+  RenderableMethod,
+  MethodMirrorWithInheritance,
+  CodeBlock,
+  GetRenderableContentByTypeName,
+} from './types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
 import { Documentable } from './types';
 
 export function adaptMethod(

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

@@ -0,0 +1,144 @@
+import { ParsedFile } from '../../shared/types';
+import { Link, RenderableBundle, StringOrLink } from './types';
+import { typeToRenderable } from './apex-types';
+import { adaptDescribable } from './documentables';
+import { Type } from '@cparra/apex-reflection';
+import { MarkdownGeneratorConfig } from '../generate-docs';
+
+export function parsedFilesToRenderableBundle(
+  config: MarkdownGeneratorConfig,
+  parsedFiles: ParsedFile[],
+): 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 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);
+
+      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,
+  };
+}
+
+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,
+  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`];
+}
+
+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)}/`;
+  }
+}
+
+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`,
+  };
+}