@cparra/apexdocs 3.0.0-beta.1 → 3.0.0-rc.0

package/examples/markdown-jsconfig/sfdx-project.json

@@ -0,0 +1,12 @@
+{
+  "packageDirectories": [
+    {
+      "path": "force-app",
+      "default": true
+    }
+  ],
+  "name": "plain-markdown",
+  "namespace": "",
+  "sfdcLoginUrl": "https://login.salesforce.com",
+  "sourceApiVersion": "59.0"
+}

package/examples/vitepress/apexdocs.config.ts

@@ -29,10 +29,15 @@ export default defineMarkdownConfig({
   sourceDir: 'force-app',
   scope: ['global', 'public', 'protected', 'private', 'namespaceaccessible'],
   namespace: 'apexdocs',
-  transformReferenceGuide: async (referenceGuide) => {
+  transformReference: (reference) => {
+    return {
+      // remove the trailing .md
+      referencePath: reference.referencePath.replace(/\.md$/, ''),
+    };
+  },
+  transformReferenceGuide: async () => {
     const frontMatter = await loadFileAsync('./docs/index-frontmatter.md');
     return {
-      ...referenceGuide,
       frontmatter: frontMatter,
     };
   },

package/examples/vitepress/docs/index.md

@@ -19,38 +19,38 @@ hero:
 
 ## Miscellaneous
 
-### [BaseClass](miscellaneous/BaseClass.md)
+### [BaseClass](miscellaneous/BaseClass)
 
-### [MultiInheritanceClass](miscellaneous/MultiInheritanceClass.md)
+### [MultiInheritanceClass](miscellaneous/MultiInheritanceClass)
 
-### [ParentInterface](miscellaneous/ParentInterface.md)
+### [ParentInterface](miscellaneous/ParentInterface)
 
-### [ReferencedEnum](miscellaneous/ReferencedEnum.md)
+### [ReferencedEnum](miscellaneous/ReferencedEnum)
 
-### [SampleException](miscellaneous/SampleException.md)
+### [SampleException](miscellaneous/SampleException)
 
 This is a sample exception.
 
-### [SampleInterface](miscellaneous/SampleInterface.md)
+### [SampleInterface](miscellaneous/SampleInterface)
 
 This is a sample interface
 
-### [Url](miscellaneous/Url.md)
+### [Url](miscellaneous/Url)
 
 Represents a uniform resource locator (URL) and provides access to parts of the URL. 
 Enables access to the base URL used to access your Salesforce org.
 
 ## Sample Enums
 
-### [SampleEnum](sample-enums/SampleEnum.md)
+### [SampleEnum](sample-enums/SampleEnum)
 
-This is a sample enum. This references [ReferencedEnum](miscellaneous/ReferencedEnum.md) . 
+This is a sample enum. This references [ReferencedEnum](miscellaneous/ReferencedEnum) . 
  
 This description has several lines
 
 ## SampleGroup
 
-### [SampleClass](samplegroup/SampleClass.md)
+### [SampleClass](samplegroup/SampleClass)
 
 aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
-deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+**deserunt** ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.

package/examples/vitepress/docs/miscellaneous/BaseClass.md

@@ -17,4 +17,4 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](../sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum)

package/examples/vitepress/docs/miscellaneous/MultiInheritanceClass.md

@@ -9,7 +9,7 @@ apexdocs
 
 **Inheritance**
 
-[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
+[SampleClass](../samplegroup/SampleClass) < [BaseClass](BaseClass)
 
 ## Fields
 ### `sampleEnumFromBase`
@@ -22,7 +22,7 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](../sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum)
 
 ## Properties
 ### Group Name

package/examples/vitepress/docs/miscellaneous/SampleException.md

@@ -9,7 +9,7 @@ This is a sample exception.
 **Usage** 
 
 You can use the exception the following way. 
-You can also take a look at [SampleClass](../samplegroup/SampleClass.md) to see how it is used. 
+You can also take a look at [SampleClass](../samplegroup/SampleClass) to see how it is used. 
 This is a dangerous HTML tag: <script>alert('Hello');</script> 
  
 ```apex

package/examples/vitepress/docs/miscellaneous/SampleInterface.md

@@ -19,9 +19,9 @@ C -->|extends| D[GreatGrandParentInterface]
 
 **Date** 2020-01-01
 
-**See** [SampleEnum](../sample-enums/SampleEnum.md)
+**See** [SampleEnum](../sample-enums/SampleEnum)
 
-**See** [ReferencedEnum](ReferencedEnum.md)
+**See** [ReferencedEnum](ReferencedEnum)
 
 ## Namespace
 apexdocs
@@ -31,7 +31,7 @@ SampleInterface sampleInterface = new SampleInterface();
 sampleInterface.sampleMethod();
 
 **Extends**
-[ParentInterface](ParentInterface.md)
+[ParentInterface](ParentInterface)
 
 ## Methods
 ### `sampleMethod()`
@@ -66,7 +66,7 @@ public String sampleMethod()
 Some return value
 
 #### Throws
-[SampleException](SampleException.md): This is a sample exception
+[SampleException](SampleException): This is a sample exception
 
 AnotherSampleException: This is another sample exception
 
@@ -94,10 +94,10 @@ public SampleEnum sampleMethodWithParams(String param1, Integer param2, SampleEn
 |------|------|-------------|
 | param1 | String | This is the first parameter |
 | param2 | Integer | This is the second parameter |
-| theEnum | [SampleEnum](../sample-enums/SampleEnum.md) | This is an enum parameter |
+| theEnum | [SampleEnum](../sample-enums/SampleEnum) | This is an enum parameter |
 
 #### Return Type
-**[SampleEnum](../sample-enums/SampleEnum.md)**
+**[SampleEnum](../sample-enums/SampleEnum)**
 
 Some return value
 

package/examples/vitepress/docs/miscellaneous/Url.md

@@ -120,7 +120,7 @@ global Url(Url context, String spec)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| context | [Url](Url.md) | The context in which to parse the specification. |
+| context | [Url](Url) | The context in which to parse the specification. |
 | spec | String | The string to parse as a URL. |
 
 ---
@@ -191,7 +191,7 @@ global static Url getCurrentRequestUrl()
 ```
 
 #### Return Type
-**[Url](Url.md)**
+**[Url](Url)**
 
 The URL of the entire request.
 
@@ -299,7 +299,7 @@ global static Url getOrgDomainUrl()
 ```
 
 #### Return Type
-**[Url](Url.md)**
+**[Url](Url)**
 
 getOrgDomainUrl() always returns the login URL for your org, regardless of context. Use that URL when making API calls to your org.
 

package/examples/vitepress/docs/sample-enums/SampleEnum.md

@@ -6,13 +6,13 @@ title: SampleEnum
 
 `NAMESPACEACCESSIBLE`
 
-This is a sample enum. This references [ReferencedEnum](../miscellaneous/ReferencedEnum.md) . 
+This is a sample enum. This references [ReferencedEnum](../miscellaneous/ReferencedEnum) . 
  
 This description has several lines
 
 **Some Custom** 
 
-Test. I can also have a [ReferencedEnum](../miscellaneous/ReferencedEnum.md) here. 
+Test. I can also have a [ReferencedEnum](../miscellaneous/ReferencedEnum) here. 
 And it can be multiline.
 
 **Mermaid** 
@@ -27,7 +27,7 @@ B -->|referenced by| A
 
 **Date** 2022-01-01
 
-**See** [ReferencedEnum](../miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](../miscellaneous/ReferencedEnum)
 
 ## Namespace
 apexdocs

package/examples/vitepress/docs/samplegroup/SampleClass.md

@@ -6,7 +6,7 @@ title: SampleClass
 `virtual`
 
 aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
-deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+**deserunt** ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
 
 **Group** SampleGroup
 
@@ -19,12 +19,12 @@ sample.doSomething();
 
 **Inheritance**
 
-[BaseClass](../miscellaneous/BaseClass.md)
+[BaseClass](../miscellaneous/BaseClass)
 
 **Implements**
 
-[SampleInterface](../miscellaneous/SampleInterface.md), 
-[ParentInterface](../miscellaneous/ParentInterface.md)
+[SampleInterface](../miscellaneous/SampleInterface), 
+[ParentInterface](../miscellaneous/ParentInterface)
 
 ## Fields
 ### Group Name
@@ -51,7 +51,7 @@ public sampleEnumFromBase
 ```
 
 ##### Type
-[SampleEnum](../sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum)
 
 ## Properties
 ### Group Name

package/examples/vitepress/force-app/main/default/classes/SampleClass.cls

@@ -1,6 +1,6 @@
 /**
  * @description aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex
- *              deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+ *              **deserunt** ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
  * @group SampleGroup
  * @example
  * SampleClass sample = new SampleClass();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-rc.0",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -17,6 +17,7 @@
   },
   "scripts": {
     "test": "npm run build && jest",
+    "test:cov": "npm run build && jest --coverage",
     "build": "rimraf ./lib && npm run lint && tsc --noEmit && pkgroll",
     "lint": "eslint \"./src/**/*.{js,ts}\" --quiet --fix",
     "prepare": "npm run build",
@@ -68,7 +69,6 @@
     "fp-ts": "^2.16.8",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
-    "type-fest": "^4.23.0",
     "yargs": "^17.7.2"
   },
   "imports": {

package/src/cli/commands/markdown.ts

@@ -30,9 +30,7 @@ export const markdownOptions: { [key: string]: Options } = {
   },
   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.",
+    describe: 'The package namespace, if any. If provided, it will be added to the generated files.',
   },
   sortMembersAlphabetically: {
     type: 'boolean',

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

@@ -1,139 +1,11 @@
 import { assertEither, extendExpect } from './expect-extensions';
 import { apexBundleFromRawString, generateDocs } from './test-helpers';
 
-describe('Generates interface documentation', () => {
+describe('When generating documentation for a class', () => {
   beforeAll(() => {
     extendExpect();
   });
 
-  describe('documentation output', () => {
-    it('returns the name of the class', async () => {
-      const input = 'public class MyClass {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyClass'));
-    });
-
-    it('returns the type as class', async () => {
-      const input = 'public class MyClass {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].source.type).toBe('class'));
-    });
-
-    it('does not return classes out of scope', async () => {
-      const input1 = `
-        global class MyClass {}
-      `;
-
-      const input2 = `
-        public class AnotherClass {}
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)], {
-        scope: ['global'],
-      })();
-      expect(result).documentationBundleHasLength(1);
-    });
-
-    it('does not return classes that have an @ignore in the docs', async () => {
-      const input = `
-      /**
-        * @ignore
-        */
-      public class MyClass {}`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(0);
-    });
-
-    it('does not return class methods that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public void myMethod() {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('myMethod'));
-    });
-
-    it('does not return class properties that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public String myProperty { get; set; }
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('myProperty'));
-    });
-
-    it('does not return class fields that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public String myField;
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('myField'));
-    });
-
-    it('does not return class inner classes that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public class InnerClass {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('InnerClass'));
-    });
-
-    it('does not return class inner interfaces that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public interface InnerInterface {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('InnerInterface'));
-    });
-
-    it('does not return class inner enums that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public enum InnerEnum {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('InnerEnum'));
-    });
-  });
-
   describe('documentation content', () => {
     describe('type level information', () => {
       it('generates a heading with the class name', async () => {

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

@@ -0,0 +1,111 @@
+import { DocPageData, PostHookDocumentationBundle } from '../../shared/types';
+import { assertEither, extendExpect } from './expect-extensions';
+import { apexBundleFromRawString, generateDocs } from './test-helpers';
+
+function aSingleDoc(result: PostHookDocumentationBundle): DocPageData {
+  expect(result.docs).toHaveLength(1);
+  return result.docs[0];
+}
+
+describe('When generating documentation', () => {
+  beforeAll(() => {
+    extendExpect();
+  });
+
+  describe('the resulting files', () => {
+    it('are named after the type', async () => {
+      const properties: [string, string][] = [
+        ['public class MyClass {}', 'MyClass.md'],
+        ['public interface MyInterface {}', 'MyInterface.md'],
+        ['public enum MyEnum {}', 'MyEnum.md'],
+      ];
+
+      for (const [input, expected] of properties) {
+        const result = await generateDocs([apexBundleFromRawString(input)])();
+        assertEither(result, (data) => expect(aSingleDoc(data).outputDocPath).toContain(expected));
+      }
+    });
+
+    it('are placed in the miscellaneous folder if no group is provided', async () => {
+      const properties: [string, string][] = [
+        ['public class MyClass {}', 'miscellaneous'],
+        ['public interface MyInterface {}', 'miscellaneous'],
+        ['public enum MyEnum {}', 'miscellaneous'],
+      ];
+
+      for (const [input, expected] of properties) {
+        const result = await generateDocs([apexBundleFromRawString(input)])();
+        assertEither(result, (data) => expect(aSingleDoc(data).outputDocPath).toContain(expected));
+      }
+    });
+
+    it('are placed in the slugified group folder if a group is provided', async () => {
+      const properties: [string, string][] = [
+        [
+          `/**
+           * @group MyGroup
+           */
+           public class MyClass {}`,
+          'mygroup',
+        ],
+        [
+          `/**
+           * @group MyGroup
+           */
+           public interface MyInterface {}`,
+          'mygroup',
+        ],
+        [
+          `/**
+           * @group MyGroup
+           */
+           public enum MyEnum {}`,
+          'mygroup',
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const result = await generateDocs([apexBundleFromRawString(input)])();
+        assertEither(result, (data) => expect(aSingleDoc(data).outputDocPath).toContain(expected));
+      }
+    });
+  });
+
+  describe('the generated bundles', () => {
+    it('return the type', async () => {
+      const properties: [string, string][] = [
+        ['public class MyClass {}', 'class'],
+        ['public interface MyInterface {}', 'interface'],
+        ['public enum MyEnum {}', 'enum'],
+      ];
+
+      for (const [input, expected] of properties) {
+        const result = await generateDocs([apexBundleFromRawString(input)])();
+        assertEither(result, (data) => expect(aSingleDoc(data).source.type).toBe(expected));
+      }
+    });
+  });
+
+  describe('the generated bundle', () => {
+    it('does not return files out of scope', async () => {
+      const input1 = 'global class MyClass {}';
+      const input2 = 'public class AnotherClass {}';
+
+      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)], {
+        scope: ['global'],
+      })();
+      expect(result).documentationBundleHasLength(1);
+    });
+
+    it('does not return files that have an @ignore in the docs', async () => {
+      const input = `
+      /**
+        * @ignore
+        */
+      public class MyClass {}`;
+
+      const result = await generateDocs([apexBundleFromRawString(input)])();
+      expect(result).documentationBundleHasLength(0);
+    });
+  });
+});

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

@@ -6,70 +6,6 @@ describe('Generates enum documentation', () => {
     extendExpect();
   });
 
-  describe('documentation output', () => {
-    it('returns the name of the enum', async () => {
-      const input = `
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyEnum'));
-    });
-
-    it('returns the type as enum', async () => {
-      const input = `
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].source.type).toBe('enum'));
-    });
-
-    it('does not return enums out of scope', async () => {
-      const input1 = `
-     global enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const input2 = `
-      public enum MyEnum {
-          VALUE1,
-          VALUE2
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)], {
-        scope: ['global'],
-      })();
-      expect(result).documentationBundleHasLength(1);
-    });
-
-    it('does not return enums that have an @ignore in the docs', async () => {
-      const input = `
-      /**
-        * @ignore
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(0);
-    });
-  });
-
   describe('documentation content', () => {
     it('generates a heading with the enum name', async () => {
       const input = `