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

package/src/cli/generate.ts

@@ -1,140 +1,16 @@
 #!/usr/bin/env node
-import * as yargs from 'yargs';
-
-import { Settings } from '../settings';
 import { Apexdocs } from '../application/Apexdocs';
-import { GeneratorChoices } from '../transpiler/generator-choices';
-import { cosmiconfig } from 'cosmiconfig';
+import { extractArgs } from './args';
 
-const result = cosmiconfig('apexdocs').search();
-result.then((config) => {
-  yargs.config(config?.config);
-  let argv = yargs
-    .options({
-      sourceDir: {
-        type: 'string',
-        alias: 's',
-        demandOption: true,
-        describe: 'The directory location which contains your apex .cls classes.',
-      },
-      targetDir: {
-        type: 'string',
-        alias: 't',
-        default: './docs/',
-        describe: 'The directory location where documentation will be generated to.',
-      },
-      recursive: {
-        type: 'boolean',
-        alias: 'r',
-        default: true,
-        describe: 'Whether .cls classes will be searched for recursively in the directory provided.',
-      },
-      scope: {
-        type: 'string',
-        array: true,
-        alias: 'p',
-        default: ['global'],
-        describe:
-          'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
-          'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled. ' +
-          'Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.',
-      },
-      targetGenerator: {
-        type: 'string',
-        alias: 'g',
-        default: 'jekyll',
-        choices: ['jekyll', 'docsify', 'plain-markdown', 'openapi'],
-        describe:
-          'Define the static file generator for which the documents will be created. ' +
-          'Currently supports jekyll, docsify, plain markdown, and OpenAPI v3.1.0.',
-      },
-      indexOnly: {
-        type: 'boolean',
-        default: false,
-        describe: 'Defines whether only the index file should be generated.',
-      },
-      defaultGroupName: {
-        type: 'string',
-        default: 'Miscellaneous',
-        describe: 'Defines the @group name to be used when a file does not specify it.',
-      },
-      sanitizeHtml: {
-        type: 'boolean',
-        default: true,
-        describe:
-          'When on, any special character within your ApexDocs is converted into its HTML code representation. ' +
-          'This is specially useful when generic objects are described within the docs, e.g. "List< Foo>", "Map<Foo, Bar>" ' +
-          'because otherwise the content within < and > would be treated as HTML tags and not shown in the output. ' +
-          'Content in @example blocks are never sanitized.',
-      },
-      openApiTitle: {
-        type: 'string',
-        default: 'Apex REST Api',
-        describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
-      },
-      title: {
-        type: 'string',
-        describe: "If this allows you to specify the title of the generated documentation's home file.",
-        default: 'Classes',
-      },
-      namespace: {
-        type: 'string',
-        describe:
-          'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
-          "If generating an OpenApi definition, it will be added to the file's Server Url.",
-      },
-      openApiFileName: {
-        type: 'string',
-        describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-        default: 'openapi',
-      },
-      sortMembersAlphabetically: {
-        type: 'boolean',
-        describe: 'Whether to sort members alphabetically.',
-        default: false,
-      },
-      includeMetadata: {
-        type: 'boolean',
-        describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
-        default: false,
-      },
-      documentationRootDir: {
-        type: 'string',
-        describe:
-          'Allows you to specify the root documentation directory where the files are being generated. This can be helpful when embedding the generated docs into an existing site so that the links are generated correctly.',
-      },
+function main() {
+  extractArgs()
+    .then((config) => {
+      Apexdocs.generate(config);
     })
-    .parseSync();
-
-  if (config) {
-    argv = { ...config.config, ...argv };
-  }
-
-  Settings.build({
-    sourceDirectory: argv.sourceDir,
-    recursive: argv.recursive,
-    scope: argv.scope,
-    outputDir: argv.targetDir,
-    targetGenerator: argv.targetGenerator as GeneratorChoices,
-    indexOnly: argv.indexOnly,
-    defaultGroupName: argv.defaultGroupName,
-    sanitizeHtml: argv.sanitizeHtml,
-    openApiTitle: argv.openApiTitle,
-    title: argv.title,
-    namespace: argv.namespace,
-    openApiFileName: argv.openApiFileName,
-    sortMembersAlphabetically: argv.sortMembersAlphabetically,
-    includeMetadata: argv.includeMetadata,
-    rootDir: argv.documentationRootDir,
-    onAfterProcess: config?.config?.onAfterProcess,
-    onBeforeFileWrite: config?.config?.onBeforeFileWrite,
-    frontMatterHeader: config?.config?.frontMatterHeader,
-  });
+    .catch((error) => {
+      console.error(error);
+      process.exit(1);
+    });
+}
 
-  try {
-    Apexdocs.generate();
-  } catch (error) {
-    console.error(error);
-    process.exit(1);
-  }
-});
+main();

package/src/core/__test__/inheritance-chain.test.ts

@@ -0,0 +1,54 @@
+import { ClassMirrorBuilder } from '../../test-helpers/ClassMirrorBuilder';
+import { createInheritanceChain } from '../inheritance-chain';
+
+describe('inheritance chain for classes', () => {
+  test('returns an empty list of the class does not extend any other class', () => {
+    const classMirror = new ClassMirrorBuilder().build();
+    const repository = [classMirror];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual([]);
+  });
+
+  test('returns the name of the extended class if it is not found in the repository', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const repository = [classMirror];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass']);
+  });
+
+  test('returns the extended class when it is present in the repository', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').build();
+    const repository = [classMirror, extendedClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass']);
+  });
+
+  test('returns the full inheritance chain when the extended class is also extended', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').withExtendedClass('SuperClass').build();
+    const superClass = new ClassMirrorBuilder().withName('SuperClass').build();
+    const repository = [classMirror, extendedClass, superClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass', 'SuperClass']);
+  });
+
+  test('returns the inheritance for a class that extends an inner class', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('OuterClass.InnerClass').build();
+    const innerClass = new ClassMirrorBuilder().withName('InnerClass').build();
+    const outerClass = new ClassMirrorBuilder().withName('OuterClass').addInnerClass(innerClass).build();
+    const repository = [classMirror, outerClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['OuterClass.InnerClass']);
+  });
+});

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

@@ -1,7 +1,7 @@
-import { InterfaceMirrorBuilder } from '../../test-helpers/InterfaceMirrorBuilder';
-import { AnnotationBuilder } from '../../test-helpers/AnnotationBuilder';
-import { MethodMirrorBuilder, ParameterBuilder } from '../../test-helpers/MethodMirrorBuilder';
-import { interfaceTypeToInterfaceSource } from '../apex-types';
+import { typeToRenderable } from '../apex-types';
+import { InterfaceMirrorBuilder } from '../../../test-helpers/InterfaceMirrorBuilder';
+import { AnnotationBuilder } from '../../../test-helpers/AnnotationBuilder';
+import { MethodMirrorBuilder, ParameterBuilder } from '../../../test-helpers/MethodMirrorBuilder';
 
 function linkGenerator(type: string): string {
   return type;
@@ -10,14 +10,14 @@ function linkGenerator(type: string): string {
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {
   it('converts the name', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().withName('SampleInterface').build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.name).toBe('SampleInterface');
   });
 
   it('converts the access modifier', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.meta.accessModifier).toBe('public');
   });
@@ -26,7 +26,7 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
     const interfaceMirror = new InterfaceMirrorBuilder()
       .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
       .build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.doc.annotations).toEqual(['MYANNOTATION']);
   });
@@ -44,10 +44,10 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.methods.value).toHaveLength(1);
-    expect(interfaceSource.methods.value[0].signature.value[0]).toBe('public String sampleMethod()');
+    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe('public String sampleMethod()');
   });
 
   it('converts method declarations. Method with parameters', () => {
@@ -72,9 +72,11 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.methods.value).toHaveLength(1);
-    expect(interfaceSource.methods.value[0].signature.value[0]).toBe('public String sampleMethod(String param1)');
+    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe(
+      'public String sampleMethod(String param1)',
+    );
   });
 });

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

@@ -1,8 +1,9 @@
 import { replaceInlineReferences } from '../references';
-import { Link } from '../../core/renderable/types';
+import { Link } from '../types';
 
 function getFileLink(typeName: string): Link {
   return {
+    __type: 'link' as const,
     title: typeName,
     url: `/api/${typeName}.html`,
   };
@@ -10,6 +11,7 @@ function getFileLink(typeName: string): Link {
 
 function getEmailLink(typeName: string) {
   return {
+    __type: 'link' as const,
     title: typeName,
     url: `mailto:${typeName}`,
   };
@@ -33,6 +35,7 @@ describe('reference utilities', () => {
       const expected = [
         'This is a test ',
         {
+          __type: 'link',
           title: 'ClassName',
           url: '/api/ClassName.html',
         },
@@ -44,6 +47,7 @@ describe('reference utilities', () => {
     it('replaces links in the format of {@link ClassName}', () => {
       function getFileLinkByTypeName(typeName: string): Link {
         return {
+          __type: 'link' as const,
           title: typeName,
           url: `/api/${typeName}.html`,
         };
@@ -55,6 +59,7 @@ describe('reference utilities', () => {
       const expected = [
         'This is a test ',
         {
+          __type: 'link',
           title: 'ClassName',
           url: '/api/ClassName.html',
         },
@@ -68,6 +73,7 @@ describe('reference utilities', () => {
     it('replaces emails in the format of {@email email-address}', () => {
       function getLinkByTypeName(typeName: string) {
         return {
+          __type: 'link' as const,
           title: typeName,
           url: `mailto:${typeName}`,
         };
@@ -79,6 +85,7 @@ describe('reference utilities', () => {
       const expected = [
         'This is an email ',
         {
+          __type: 'link',
           title: 'example@example.com',
           url: 'mailto:example@example.com',
         },
@@ -95,16 +102,19 @@ describe('reference utilities', () => {
     const expected = [
       'This is a test ',
       {
+        __type: 'link',
         title: 'ClassName',
         url: '/api/ClassName.html',
       },
       ', and ',
       {
+        __type: 'link',
         title: 'AnotherClass',
         url: '/api/AnotherClass.html',
       },
       ', and an email ',
       {
+        __type: 'link',
         title: 'testerson',
         url: 'mailto:testerson',
       },

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

@@ -4,16 +4,45 @@ import {
   RenderableClass,
   RenderableEnum,
   RenderableInterface,
-  Renderable,
   RenderableSection,
   GroupedMember,
-} from '../core/renderable/types';
+  ClassMirrorWithInheritanceChain,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+} from './types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
-import { FieldMirrorWithInheritance, PropertyMirrorWithInheritance } from '../model/inheritance';
+import { GetRenderableContentByTypeName } from './references';
 import { adaptConstructor, adaptMethod } from './methods-and-constructors';
 import { adaptFieldOrProperty } from './fields-and-properties';
 
+type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
+  ? RenderableInterface
+  : T extends ClassMirror
+    ? RenderableClass
+    : RenderableEnum;
+
+export function typeToRenderable<T extends Type>(
+  type: T,
+  linkGenerator: GetRenderableContentByTypeName,
+  namespace?: string,
+): GetReturnRenderable<T> {
+  function getRenderable(): RenderableInterface | RenderableClass | RenderableEnum {
+    switch (type.type_name) {
+      case 'enum':
+        return enumTypeToEnumSource(type as EnumMirror, linkGenerator) as RenderableEnum;
+      case 'interface':
+        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator) as RenderableInterface;
+      case 'class':
+        return classTypeToClassSource(type as ClassMirrorWithInheritanceChain, linkGenerator) as RenderableClass;
+    }
+  }
+
+  return {
+    ...(getRenderable() as GetReturnRenderable<T>),
+    namespace,
+  };
+}
+
 function baseTypeAdapter(
   type: EnumMirror | InterfaceMirror | ClassMirror,
   linkGenerator: GetRenderableContentByTypeName,
@@ -40,29 +69,7 @@ function baseTypeAdapter(
   };
 }
 
-export function typeToRenderableType(
-  type: Type,
-  linkGenerator: GetRenderableContentByTypeName,
-  namespace?: string,
-): Renderable {
-  function getRenderable() {
-    switch (type.type_name) {
-      case 'enum':
-        return enumTypeToEnumSource(type as EnumMirror, linkGenerator);
-      case 'interface':
-        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator);
-      case 'class':
-        return classTypeToClassSource(type as ClassMirror, linkGenerator);
-    }
-  }
-
-  return {
-    ...getRenderable(),
-    namespace,
-  };
-}
-
-export function enumTypeToEnumSource(
+function enumTypeToEnumSource(
   enumType: EnumMirror,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number = 1,
@@ -81,7 +88,7 @@ export function enumTypeToEnumSource(
   };
 }
 
-export function interfaceTypeToInterfaceSource(
+function interfaceTypeToInterfaceSource(
   interfaceType: InterfaceMirror,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number = 1,
@@ -89,7 +96,7 @@ export function interfaceTypeToInterfaceSource(
   return {
     type: 'interface',
     ...baseTypeAdapter(interfaceType, linkGenerator, baseHeadingLevel),
-    extends: interfaceType.extended_interfaces.map(linkFromTypeNameGenerator),
+    extends: interfaceType.extended_interfaces.map(linkGenerator),
     methods: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Methods',
@@ -98,8 +105,8 @@ export function interfaceTypeToInterfaceSource(
   };
 }
 
-export function classTypeToClassSource(
-  classType: ClassMirror,
+function classTypeToClassSource(
+  classType: ClassMirrorWithInheritanceChain,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number = 1,
 ): RenderableClass {
@@ -108,36 +115,36 @@ export function classTypeToClassSource(
     ...baseTypeAdapter(classType, linkGenerator, baseHeadingLevel),
     classModifier: classType.classModifier,
     sharingModifier: classType.sharingModifier,
-    implements: classType.implemented_interfaces.map(linkFromTypeNameGenerator),
-    extends: classType.extended_class ? linkFromTypeNameGenerator(classType.extended_class) : undefined,
-    methods: adaptMembers('Methods', classType.methods, adaptMethod, linkFromTypeNameGenerator, baseHeadingLevel + 1),
+    implements: classType.implemented_interfaces.map(linkGenerator),
+    extends: classType.inheritanceChain.map(linkGenerator),
+    methods: adaptMembers('Methods', classType.methods, adaptMethod, linkGenerator, baseHeadingLevel + 1),
     constructors: adaptMembers(
       'Constructors',
       classType.constructors,
       (constructor, linkGenerator, baseHeadingLevel) =>
         adaptConstructor(classType.name, constructor, linkGenerator, baseHeadingLevel),
-      linkFromTypeNameGenerator,
+      linkGenerator,
       baseHeadingLevel + 1,
     ),
     fields: adaptMembers(
       'Fields',
       classType.fields as FieldMirrorWithInheritance[],
       adaptFieldOrProperty,
-      linkFromTypeNameGenerator,
+      linkGenerator,
       baseHeadingLevel + 1,
     ),
     properties: adaptMembers(
       'Properties',
       classType.properties as PropertyMirrorWithInheritance[],
       adaptFieldOrProperty,
-      linkFromTypeNameGenerator,
+      linkGenerator,
       baseHeadingLevel + 1,
     ),
     innerClasses: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Classes',
       value: classType.classes.map((innerClass) =>
-        classTypeToClassSource(innerClass, linkGenerator, baseHeadingLevel + 2),
+        classTypeToClassSource({ ...innerClass, inheritanceChain: [] }, linkGenerator, baseHeadingLevel + 2),
       ),
     },
     innerEnums: {
@@ -200,12 +207,15 @@ function toGroupedMembers<T extends Groupable, K>(
 }
 
 function groupByGroupName<T extends Groupable>(members: T[]): Record<string, T[]> {
-  return members.reduce((acc, member) => {
-    const groupName = member.group ?? 'Other';
-    acc[groupName] = acc[groupName] ?? [];
-    acc[groupName].push(member);
-    return acc;
-  }, {} as Record<string, T[]>);
+  return members.reduce(
+    (acc, member) => {
+      const groupName = member.group ?? 'Other';
+      acc[groupName] = acc[groupName] ?? [];
+      acc[groupName].push(member);
+      return acc;
+    },
+    {} as Record<string, T[]>,
+  );
 }
 
 function singleGroup<T extends Groupable, K>(