@cparra/apexdocs 3.0.0 → 3.1.0

package/src/cli/generate.ts

@@ -1,32 +0,0 @@
-#!/usr/bin/env node
-import { Apexdocs } from '../application/Apexdocs';
-import { extractArgs } from './args';
-import { StdOutLogger } from '#utils/logger';
-import * as E from 'fp-ts/Either';
-
-const logger = new StdOutLogger();
-
-function main() {
-  function parseResult(result: E.Either<unknown, string>) {
-    E.match(
-      (error) => {
-        logger.error(`❌ An error occurred while generating the documentation: ${error}`);
-        process.exit(1);
-      },
-      (successMessage: string) => {
-        logger.logSingle(successMessage);
-      },
-    )(result);
-  }
-
-  function catchUnexpectedError(error: Error) {
-    logger.error(`❌ An unexpected error occurred: ${error.message}`);
-    process.exit(1);
-  }
-
-  extractArgs()
-    .then((config) => Apexdocs.generate(config, logger).then(parseResult))
-    .catch(catchUnexpectedError);
-}
-
-main();

package/src/core/__test__/manifest.spec.ts

@@ -1,16 +0,0 @@
-import Manifest from '../manifest';
-import { EnumMirror } from '@cparra/apex-reflection';
-
-const sampleEnum: EnumMirror = {
-  annotations: [],
-  name: 'SampleEnum',
-  type_name: 'enum',
-  access_modifier: 'public',
-  values: [],
-};
-
-it('holds a list of types', () => {
-  const types = [sampleEnum];
-  const manifest = new Manifest(types);
-  expect(manifest.types).toBe(types);
-});

package/src/core/manifest.ts

@@ -1,90 +0,0 @@
-import {
-  Annotation,
-  ClassMirror,
-  DocComment,
-  DocCommentAnnotation,
-  EnumMirror,
-  InterfaceMirror,
-  Type,
-} from '@cparra/apex-reflection';
-
-type AccessAndDocAware = { access_modifier: string; annotations: Annotation[]; docComment?: DocComment };
-
-/**
- * Represents the full library of Apex top-level types (classes, enums, and interface) for a Salesforce project.
- */
-export default class Manifest {
-  /**
-   * Constructs a new Manifest object.
-   * @param types List of types to be wrapped by this object.
-   * @param isForInnerTypes Whether this manifest represent an inner type or not.
-   */
-  constructor(
-    public types: Type[],
-    public isForInnerTypes: boolean = false,
-  ) {}
-
-  filteredByAccessModifierAndAnnotations(modifiers: string[]): Type[] {
-    const filteredTypes = Manifest.filterAccessibleModifier(this.types, modifiers);
-    const typesToReturn: Type[] = [];
-    for (const filteredType of filteredTypes) {
-      typesToReturn.push(Manifest.filterSingleType(filteredType, modifiers, this.isForInnerTypes));
-    }
-
-    return typesToReturn;
-  }
-
-  static filterSingleType(currentType: Type, modifiers: string[], isForInnerTypes: boolean): Type {
-    if (currentType.type_name === 'enum') {
-      // Ignoring enum values is not supported.
-      return currentType;
-    }
-
-    if (currentType.type_name === 'interface') {
-      const currentInterface = currentType as InterfaceMirror;
-      return {
-        ...currentType,
-        methods: this.filterAccessibleModifier(currentInterface.methods, modifiers),
-      } as InterfaceMirror;
-    }
-
-    const currentClass = currentType as ClassMirror;
-    const filteredClass = {
-      ...currentType,
-      methods: this.filterAccessibleModifier(currentClass.methods, modifiers),
-      properties: this.filterAccessibleModifier(currentClass.properties, modifiers),
-      fields: this.filterAccessibleModifier(currentClass.fields, modifiers),
-      constructors: this.filterAccessibleModifier(currentClass.constructors, modifiers),
-    } as ClassMirror;
-
-    if (!isForInnerTypes) {
-      return {
-        ...filteredClass,
-        enums: this.filterAccessibleModifier(currentClass.enums, modifiers) as EnumMirror[],
-        interfaces: this.filterAccessibleModifier(currentClass.interfaces, modifiers) as InterfaceMirror[],
-        classes: new Manifest(currentClass.classes, true).filteredByAccessModifierAndAnnotations(
-          modifiers,
-        ) as ClassMirror[],
-      };
-    }
-
-    return filteredClass;
-  }
-
-  static filterAccessibleModifier<T extends AccessAndDocAware>(accessAndDocAware: T[], modifiers: string[]): T[] {
-    return accessAndDocAware.filter((type) => this.shouldFilterType(type, modifiers));
-  }
-
-  static shouldFilterType(accessAndDocAware: AccessAndDocAware, modifiers: string[]) {
-    const hasIgnoreDocAnnotation = accessAndDocAware.docComment?.annotations.some(
-      (annotation: DocCommentAnnotation) => annotation.name.toLowerCase() === 'ignore',
-    );
-    if (hasIgnoreDocAnnotation) {
-      return false;
-    }
-    return (
-      modifiers.includes(accessAndDocAware.access_modifier) ||
-      accessAndDocAware.annotations.some((annotation: Annotation) => modifiers.includes(annotation.type.toLowerCase()))
-    );
-  }
-}

package/src/core/markdown/__test__/expect-extensions.ts

@@ -1,32 +0,0 @@
-import * as E from 'fp-ts/Either';
-import { DocumentationBundle } from '../../shared/types';
-
-export function extendExpect() {
-  expect.extend({
-    documentationBundleHasLength(received: E.Either<string[], DocumentationBundle>, length: number) {
-      return {
-        pass: E.isRight(received) && received.right.docs.length === length,
-        message: () => `Expected documentation bundle to have length ${length}`,
-      };
-    },
-    firstDocContains(doc: DocumentationBundle, content: string) {
-      return {
-        pass: doc.docs[0].content.includes(content),
-        message: () => `Expected documentation to contain ${content}. Got ${doc.docs[0].content}`,
-      };
-    },
-    firstDocContainsNot(doc: DocumentationBundle, content: string) {
-      return {
-        pass: !doc.docs[0].content.includes(content),
-        message: () => `Expected documentation to not contain ${content}. Got ${doc.docs[0].content}`,
-      };
-    },
-  });
-}
-
-export function assertEither<T, U>(result: E.Either<T, U>, assertion: (data: U) => void): void {
-  E.match<T, U, void>(
-    (error) => fail(error),
-    (data) => assertion(data),
-  )(result);
-}

package/src/core/markdown/__test__/generating-class-docs.spec.ts

@@ -1,362 +0,0 @@
-import { assertEither, extendExpect } from './expect-extensions';
-import { apexBundleFromRawString, generateDocs } from './test-helpers';
-
-describe('When generating documentation for a class', () => {
-  beforeAll(() => {
-    extendExpect();
-  });
-
-  describe('member information', () => {
-    it('displays the Method heading', async () => {
-      const input = `
-        public class MyClass {
-          public void myMethod() {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Methods'));
-    });
-
-    it('sorts methods when sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public void zMethod() {}
-          public void aMethod() {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aMethodIndex = data.docs[0].content.indexOf('aMethod');
-        const zMethodIndex = data.docs[0].content.indexOf('zMethod');
-        expect(aMethodIndex).toBeLessThan(zMethodIndex);
-      });
-    });
-
-    it('does not sort methods when not sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public void zMethod() {}
-          public void aMethod() {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aMethodIndex = data.docs[0].content.indexOf('aMethod');
-        const zMethodIndex = data.docs[0].content.indexOf('zMethod');
-        expect(aMethodIndex).toBeGreaterThan(zMethodIndex);
-      });
-    });
-
-    it('displays the Property heading', async () => {
-      const input = `
-        public class MyClass {
-          public String myProperty { get; set; }
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Properties'));
-    });
-
-    it('sorts properties when sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public String zProperty { get; set; }
-          public String aProperty { get; set; }
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aPropertyIndex = data.docs[0].content.indexOf('aProperty');
-        const zPropertyIndex = data.docs[0].content.indexOf('zProperty');
-        expect(aPropertyIndex).toBeLessThan(zPropertyIndex);
-      });
-    });
-
-    it('does not sort properties when not sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public String zProperty { get; set; }
-          public String aProperty { get; set; }
-        }  
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aPropertyIndex = data.docs[0].content.indexOf('aProperty');
-        const zPropertyIndex = data.docs[0].content.indexOf('zProperty');
-        expect(aPropertyIndex).toBeGreaterThan(zPropertyIndex);
-      });
-    });
-
-    it('displays the Field heading', async () => {
-      const input = `
-        public class MyClass {
-          public String myField;
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Fields'));
-    });
-
-    it('sort fields when sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public String zField;
-          public String aField;
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aFieldIndex = data.docs[0].content.indexOf('aField');
-        const zFieldIndex = data.docs[0].content.indexOf('zField');
-        expect(aFieldIndex).toBeLessThan(zFieldIndex);
-      });
-    });
-
-    it('does not sort fields when not sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public String zField;
-          public String aField;
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aFieldIndex = data.docs[0].content.indexOf('aField');
-        const zFieldIndex = data.docs[0].content.indexOf('zField');
-        expect(aFieldIndex).toBeGreaterThan(zFieldIndex);
-      });
-    });
-
-    it('displays the Constructor heading', async () => {
-      const input = `
-        public class MyClass {
-          public MyClass() {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Constructors'));
-    });
-
-    it('displays the Inner Class heading', async () => {
-      const input = `
-        public class MyClass {
-          public class InnerClass {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Classes'));
-    });
-
-    it('sorts inner classes when sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public class ZInnerClass {}
-          public class AInnerClass {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aInnerClassIndex = data.docs[0].content.indexOf('AInnerClass');
-        const zInnerClassIndex = data.docs[0].content.indexOf('ZInnerClass');
-        expect(aInnerClassIndex).toBeLessThan(zInnerClassIndex);
-      });
-    });
-
-    it('does not sort inner classes when not sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public class ZInnerClass {}
-          public class AInnerClass {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aInnerClassIndex = data.docs[0].content.indexOf('AInnerClass');
-        const zInnerClassIndex = data.docs[0].content.indexOf('ZInnerClass');
-        expect(aInnerClassIndex).toBeGreaterThan(zInnerClassIndex);
-      });
-    });
-
-    it('displays the Inner Interface heading', async () => {
-      const input = `
-        public class MyClass {
-          public interface InnerInterface {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Interfaces'));
-    });
-
-    it('sorts inner interfaces when sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public interface ZInnerInterface {}
-          public interface AInnerInterface {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aInnerInterfaceIndex = data.docs[0].content.indexOf('AInnerInterface');
-        const zInnerInterfaceIndex = data.docs[0].content.indexOf('ZInnerInterface');
-        expect(aInnerInterfaceIndex).toBeLessThan(zInnerInterfaceIndex);
-      });
-    });
-
-    it('does not sort inner interfaces when not sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public interface ZInnerInterface {}
-          public interface AInnerInterface {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aInnerInterfaceIndex = data.docs[0].content.indexOf('AInnerInterface');
-        const zInnerInterfaceIndex = data.docs[0].content.indexOf('ZInnerInterface');
-        expect(aInnerInterfaceIndex).toBeGreaterThan(zInnerInterfaceIndex);
-      });
-    });
-
-    it('displays the Inner Enum heading', async () => {
-      const input = `
-        public class MyClass {
-          public enum InnerEnum {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Enums'));
-    });
-
-    it('sort inner enums when sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public enum ZInnerEnum {}
-          public enum AInnerEnum {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aInnerEnumIndex = data.docs[0].content.indexOf('AInnerEnum');
-        const zInnerEnumIndex = data.docs[0].content.indexOf('ZInnerEnum');
-        expect(aInnerEnumIndex).toBeLessThan(zInnerEnumIndex);
-      });
-    });
-
-    it('does not sort inner enums when not sorting members alphabetically', async () => {
-      const input = `
-        public class MyClass {
-          public enum ZInnerEnum {}
-          public enum AInnerEnum {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => {
-        const aInnerEnumIndex = data.docs[0].content.indexOf('AInnerEnum');
-        const zInnerEnumIndex = data.docs[0].content.indexOf('ZInnerEnum');
-        expect(aInnerEnumIndex).toBeGreaterThan(zInnerEnumIndex);
-      });
-    });
-
-    it('supports having mermaid diagrams in descriptions', async () => {
-      const input = `
-        public class MyClass {
-          /**
-            * @mermaid
-            * \`\`\`mermaid
-            * graph TD
-            *   A[Square Rect] -- Link text --> B((Circle))
-            *   A --> C(Round Rect)
-            *   B --> D{Rhombus}
-            *   C --> D
-            * \`\`\`
-            */
-          public void myMethod() {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('```mermaid'));
-      assertEither(result, (data) => expect(data).firstDocContains('graph TD'));
-    });
-
-    it('supports having example code blocks in method descriptions', async () => {
-      const input = `
-        public class MyClass {
-          /**
-            * @example
-            * public class MyClass {
-            *   public void myMethod() {
-            *     System.debug('Hello, World!');
-            *   }
-            * }
-            */
-          public void myMethod() {}
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('```apex'));
-      assertEither(result, (data) => expect(data).firstDocContains('public class MyClass'));
-    });
-
-    it('displays an "inherited" tag if the method was inherited from a different interface', async () => {
-      const input1 = `
-        public virtual class MyClass {
-          public void myMethod() {}
-        }
-      `;
-
-      const input2 = `
-        public class AnotherClass extends MyClass {}
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-      expect(result).documentationBundleHasLength(2);
-      assertEither(result, (data) =>
-        expect(data.docs.find((doc) => doc.source.name === 'AnotherClass')?.content).toContain('Inherited'),
-      );
-    });
-  });
-});
-
-// TODO: Skips tags at the member level