@cparra/apexdocs 2.24.0 → 2.25.0-alpha.0

package/package.json

@@ -1,78 +1,79 @@
-{
-  "name": "@cparra/apexdocs",
-  "version": "2.24.0",
-  "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
-  "keywords": [
-    "apex",
-    "salesforce",
-    "documentation",
-    "cli",
-    "apex-docs",
-    "docs"
-  ],
-  "main": "lib/index.js",
-  "bin": {
-    "apexdocs-generate": "lib/cli/generate.js"
-  },
-  "types": "lib/index.d.ts",
-  "scripts": {
-    "test": "jest --coverage",
-    "build": "rimraf ./lib && npm run lint && tsc --declaration",
-    "lint": "eslint \"./src/**/*.{js,ts}\" --quiet --fix",
-    "prepare": "npm run build",
-    "version": "npm run format && git add -A src",
-    "postversion": "git push && git push --tags",
-    "docs:init": "docsify init docs",
-    "docs:serve": "docsify serve docs",
-    "execute:example": "rimraf ./docs/types && node lib/cli/generate.js -s examples/force-app -t docs/types --scope global public private protected -g docsify --defaultGroupName \"Misc Group\" --namespace nspc --title \"Sample Documentation\" --documentationRootDir types",
-    "execute:example:index:only": "node lib/cli/generate.js -s examples/force-app -t docs --scope global public private -g docsify --indexOnly",
-    "execute:example:openapi": "node lib/cli/generate.js -s examples/force-app -t docs -g openapi --openApiTitle \"Sample REST Api\" --namespace nspc --openApiFileName restapi"
-  },
-  "author": "Cesar Parra",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/cesarParra/apexdocs"
-  },
-  "devDependencies": {
-    "@types/html-entities": "^1.3.4",
-    "@types/jest": "^27.4.1",
-    "@types/js-yaml": "^4.0.5",
-    "@types/node": "^13.7.4",
-    "@types/shelljs": "^0.8.6",
-    "@types/yargs": "^15.0.3",
-    "@typescript-eslint/eslint-plugin": "^5.41.0",
-    "@typescript-eslint/parser": "^5.41.0",
-    "docsify": "^4.13.0",
-    "eslint": "^8.0.1",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "husky": "^8.0.3",
-    "jest": "^27.5.1",
-    "lint-staged": "^13.2.1",
-    "prettier": "^2.4.1",
-    "rimraf": "^3.0.2",
-    "ts-jest": "^27.1.3",
-    "typescript": "^4.8.4"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
-    }
-  },
-  "lint-staged": {
-    "*.{js,ts,tsx}": [
-      "eslint --fix"
-    ]
-  },
-  "dependencies": {
-    "@cparra/apex-reflection": "2.8.0",
-    "chalk": "^4.1.2",
-    "cosmiconfig": "^9.0.0",
-    "fast-xml-parser": "^4.0.1",
-    "js-yaml": "^4.1.0",
-    "log-update": "4.0.0",
-    "xss": "^1.0.11",
-    "yargs": "^16.0.3"
-  }
-}
+{
+  "name": "@cparra/apexdocs",
+  "version": "2.25.0-alpha.0",
+  "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
+  "keywords": [
+    "apex",
+    "salesforce",
+    "documentation",
+    "cli",
+    "apex-docs",
+    "docs"
+  ],
+  "main": "lib/index.js",
+  "bin": {
+    "apexdocs-generate": "lib/cli/generate.js"
+  },
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "test": "jest --coverage",
+    "build": "rimraf ./lib && npm run lint && tsc --declaration",
+    "lint": "eslint \"./src/**/*.{js,ts}\" --quiet --fix",
+    "prepare": "npm run build",
+    "version": "npm run format && git add -A src",
+    "postversion": "git push && git push --tags",
+    "docs:init": "docsify init docs",
+    "docs:serve": "docsify serve docs",
+    "execute:example": "rimraf ./docs/types && node lib/cli/generate.js -s examples/force-app -t docs/types --scope global public private protected -g docsify --defaultGroupName \"Misc Group\" --namespace nspc --title \"Sample Documentation\" --documentationRootDir types",
+    "execute:example:index:only": "node lib/cli/generate.js -s examples/force-app -t docs --scope global public private -g docsify --indexOnly",
+    "execute:example:openapi": "node lib/cli/generate.js -s examples/force-app -t docs -g openapi --openApiTitle \"Sample REST Api\" --namespace nspc --openApiFileName restapi"
+  },
+  "author": "Cesar Parra",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cesarParra/apexdocs"
+  },
+  "devDependencies": {
+    "@types/html-entities": "^1.3.4",
+    "@types/jest": "^29.5.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.2",
+    "@types/shelljs": "^0.8.15",
+    "@types/yargs": "^15.0.3",
+    "@typescript-eslint/eslint-plugin": "^7.12.0",
+    "@typescript-eslint/parser": "^7.12.0",
+    "docsify": "^4.13.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "husky": "^8.0.3",
+    "jest": "^29.7.0",
+    "lint-staged": "^13.2.1",
+    "prettier": "^2.8.8",
+    "rimraf": "^3.0.2",
+    "ts-jest": "^29.1.4",
+    "typescript": "^4.8.4"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.{js,ts,tsx}": [
+      "eslint --fix"
+    ]
+  },
+  "dependencies": {
+    "@cparra/apex-reflection": "2.9.2",
+    "chalk": "^4.1.2",
+    "cosmiconfig": "^9.0.0",
+    "fast-xml-parser": "^4.4.0",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "log-update": "4.0.0",
+    "xss": "^1.0.11",
+    "yargs": "^16.0.3"
+  }
+}

package/src/adapters/__tests__/interface-adapter.spec.ts

@@ -0,0 +1,76 @@
+import { InterfaceMirrorBuilder } from '../../test-helpers/InterfaceMirrorBuilder';
+import { AnnotationBuilder } from '../../test-helpers/AnnotationBuilder';
+import { MethodMirrorBuilder, ParameterBuilder } from '../../test-helpers/MethodMirrorBuilder';
+import { interfaceTypeToInterfaceSource } from '../apex-types';
+
+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);
+
+    expect(interfaceSource.name).toBe('SampleInterface');
+  });
+
+  it('converts the access modifier', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder().build();
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+
+    expect(interfaceSource.accessModifier).toBe('public');
+  });
+
+  it('converts annotations', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder()
+      .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
+      .build();
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+
+    expect(interfaceSource.annotations).toEqual(['MYANNOTATION']);
+  });
+
+  it('converts method declarations. Method with no parameters', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder()
+      .addMethod(
+        new MethodMirrorBuilder()
+          .withName('sampleMethod')
+          .withTypeReference({
+            type: 'String',
+            rawDeclaration: 'String',
+          })
+          .build(),
+      )
+      .build();
+
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+
+    expect(interfaceSource.methods).toHaveLength(1);
+    expect(interfaceSource.methods![0].signature).toBe('public String sampleMethod()');
+  });
+
+  it('converts method declarations. Method with parameters', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder()
+      .addMethod(
+        new MethodMirrorBuilder()
+          .withName('sampleMethod')
+          .withTypeReference({
+            type: 'String',
+            rawDeclaration: 'String',
+          })
+          .addParameter(
+            new ParameterBuilder()
+              .withName('param1')
+              .withTypeReference({
+                type: 'String',
+                rawDeclaration: 'String',
+              })
+              .build(),
+          )
+          .build(),
+      )
+      .build();
+
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+
+    expect(interfaceSource.methods).toHaveLength(1);
+    expect(interfaceSource.methods![0].signature).toBe('public String sampleMethod(String param1)');
+  });
+});

package/src/adapters/__tests__/references.spec.ts

@@ -0,0 +1,115 @@
+import { replaceInlineReferences } from '../references';
+import { Link } from '../../templating/types';
+
+function getFileLink(typeName: string): Link {
+  return {
+    title: typeName,
+    url: `/api/${typeName}.html`,
+  };
+}
+
+function getEmailLink(typeName: string) {
+  return {
+    title: typeName,
+    url: `mailto:${typeName}`,
+  };
+}
+
+describe('reference utilities', () => {
+  it('returns a RenderableContent array with the full string when there are no links', () => {
+    const text = 'This is a test';
+    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+    const expected = ['This is a test'];
+
+    expect(result).toEqual(expected);
+  });
+
+  describe('replace inline links', () => {
+    it('replaces links in the format of <<ClassName>>', () => {
+      const text = 'This is a test <<ClassName>>.';
+      const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+      const expected = [
+        'This is a test ',
+        {
+          title: 'ClassName',
+          url: '/api/ClassName.html',
+        },
+        '.',
+      ];
+
+      expect(result).toEqual(expected);
+    });
+    it('replaces links in the format of {@link ClassName}', () => {
+      function getFileLinkByTypeName(typeName: string): Link {
+        return {
+          title: typeName,
+          url: `/api/${typeName}.html`,
+        };
+      }
+
+      const text = 'This is a test {@link ClassName}';
+      const result = replaceInlineReferences(text, getFileLinkByTypeName, getEmailLink);
+
+      const expected = [
+        'This is a test ',
+        {
+          title: 'ClassName',
+          url: '/api/ClassName.html',
+        },
+      ];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
+  describe('replace inline emails', () => {
+    it('replaces emails in the format of {@email email-address}', () => {
+      function getLinkByTypeName(typeName: string) {
+        return {
+          title: typeName,
+          url: `mailto:${typeName}`,
+        };
+      }
+
+      const text = 'This is an email {@email example@example.com}';
+      const result = replaceInlineReferences(text, getFileLink, getLinkByTypeName);
+
+      const expected = [
+        'This is an email ',
+        {
+          title: 'example@example.com',
+          url: 'mailto:example@example.com',
+        },
+      ];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
+  it('replaces both links and emails in the same string', () => {
+    const text = 'This is a test <<ClassName>>, and {@link AnotherClass}, and an email {@email testerson}';
+    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+    const expected = [
+      'This is a test ',
+      {
+        title: 'ClassName',
+        url: '/api/ClassName.html',
+      },
+      ', and ',
+      {
+        title: 'AnotherClass',
+        url: '/api/AnotherClass.html',
+      },
+      ', and an email ',
+      {
+        title: 'testerson',
+        url: 'mailto:testerson',
+      },
+    ];
+
+    expect(result).toEqual(expected);
+  });
+});

package/src/adapters/apex-types.ts

@@ -0,0 +1,67 @@
+import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
+import { BaseTypeSource, ClassSource, EnumSource, InterfaceSource } from '../templating/types';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { linkFromTypeNameGenerator } from './references';
+import { FieldMirrorWithInheritance } from '../model/inheritance';
+import { adaptConstructor, adaptMethod } from './methods-and-constructors';
+import { adaptField } from './fields-and-properties';
+
+function baseTypeAdapter(type: EnumMirror | InterfaceMirror | ClassMirror): BaseTypeSource {
+  function extractAnnotationBody(type: Type, annotationName: string): string | undefined {
+    return type.docComment?.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
+    )?.body;
+  }
+
+  function extractSeeAnnotations(type: Type): string[] {
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === 'see')
+        .map((currentAnnotation) => currentAnnotation.body) ?? []
+    );
+  }
+
+  return {
+    ...adaptDocumentable(type),
+    accessModifier: type.access_modifier,
+    name: type.name,
+    group: extractAnnotationBody(type, 'group'),
+    author: extractAnnotationBody(type, 'author'),
+    date: extractAnnotationBody(type, 'date'),
+    sees: extractSeeAnnotations(type).map(linkFromTypeNameGenerator),
+  };
+}
+
+export function enumTypeToEnumSource(enumType: EnumMirror): EnumSource {
+  return {
+    __type: 'enum',
+    ...baseTypeAdapter(enumType),
+    values: enumType.values.map((value) => ({
+      ...adaptDescribable(value.docComment?.descriptionLines),
+      value: value.name,
+    })),
+  };
+}
+
+export function interfaceTypeToInterfaceSource(interfaceType: InterfaceMirror): InterfaceSource {
+  return {
+    __type: 'interface',
+    ...baseTypeAdapter(interfaceType),
+    extends: interfaceType.extended_interfaces.map(linkFromTypeNameGenerator),
+    methods: interfaceType.methods.map(adaptMethod),
+  };
+}
+
+export function classTypeToClassSource(classType: ClassMirror): ClassSource {
+  return {
+    __type: 'class',
+    ...baseTypeAdapter(classType),
+    classModifier: classType.classModifier,
+    sharingModifier: classType.sharingModifier,
+    implements: classType.implemented_interfaces.map(linkFromTypeNameGenerator),
+    extends: classType.extended_class ? linkFromTypeNameGenerator(classType.extended_class) : undefined,
+    methods: classType.methods.map(adaptMethod),
+    constructors: classType.constructors.map((constructor) => adaptConstructor(classType.name, constructor)),
+    fields: classType.fields.map((field) => adaptField(field as FieldMirrorWithInheritance)),
+  };
+}

package/src/adapters/documentables.ts

@@ -0,0 +1,58 @@
+import { CustomTag, DocumentableSource, RenderableContent } from '../templating/types';
+import { Describable, Documentable } from './types';
+import { replaceInlineReferences } from './references';
+import { isEmptyLine } from './type-utils';
+
+export function adaptDescribable(describable: Describable): { description?: RenderableContent[] } {
+  function describableToRenderableContent(describable: Describable): RenderableContent[] | undefined {
+    if (!describable) {
+      return;
+    }
+
+    return (
+      describable
+        .map<RenderableContent[]>((line) => [
+          ...replaceInlineReferences(line),
+          {
+            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 {
+    description: describableToRenderableContent(describable),
+  };
+}
+
+export function adaptDocumentable(documentable: Documentable): DocumentableSource {
+  function extractCustomTags(type: Documentable): CustomTag[] {
+    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'mermaid', 'throws', 'exception'];
+
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase()))
+        .map<CustomTag>((currentAnnotation) => ({
+          ...adaptDescribable(currentAnnotation.bodyLines),
+          name: currentAnnotation.name,
+        })) ?? []
+    );
+  }
+
+  function extractAnnotationBodyLines(type: Documentable, annotationName: string): string[] | undefined {
+    return type.docComment?.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
+    )?.bodyLines;
+  }
+
+  return {
+    ...adaptDescribable(documentable.docComment?.descriptionLines),
+    annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
+    customTags: extractCustomTags(documentable),
+    mermaid: extractAnnotationBodyLines(documentable, 'mermaid'),
+    example: documentable.docComment?.exampleAnnotation?.bodyLines,
+  };
+}

package/src/adapters/fields-and-properties.ts

@@ -0,0 +1,14 @@
+import { FieldMirrorWithInheritance } from '../model/inheritance';
+import { FieldSource } from '../templating/types';
+import { adaptDocumentable } from './documentables';
+import { linkFromTypeNameGenerator } from './references';
+
+export function adaptField(field: FieldMirrorWithInheritance): FieldSource {
+  return {
+    ...adaptDocumentable(field),
+    name: field.name,
+    type: linkFromTypeNameGenerator(field.typeReference.rawDeclaration),
+    inherited: field.inherited,
+    accessModifier: field.access_modifier,
+  };
+}

package/src/adapters/methods-and-constructors.ts

@@ -0,0 +1,78 @@
+import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
+import { ConstructorSource, MethodSource } from '../templating/types';
+import { MethodMirrorWithInheritance } from '../model/inheritance';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { linkFromTypeNameGenerator } from './references';
+import { Documentable } from './types';
+
+export function adaptMethod(method: MethodMirror): MethodSource {
+  function buildTitle(method: MethodMirrorWithInheritance): string {
+    const { name, parameters } = method;
+    const parametersString = parameters.map((param) => param.name).join(', ');
+    return `${name}(${parametersString})`;
+  }
+
+  function buildSignature(method: MethodMirrorWithInheritance): string {
+    const { access_modifier, typeReference, name, memberModifiers } = method;
+    const parameters = method.parameters
+      .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
+      .join(', ');
+    const members = memberModifiers.length > 0 ? `${memberModifiers.join(' ')} ` : '';
+    return `${access_modifier} ${members}${typeReference.rawDeclaration} ${name}(${parameters})`;
+  }
+
+  return {
+    ...adaptDocumentable(method),
+    title: buildTitle(method as MethodMirrorWithInheritance),
+    signature: buildSignature(method as MethodMirrorWithInheritance),
+    returnType: {
+      ...adaptDescribable(method.docComment?.returnAnnotation?.bodyLines),
+      type: linkFromTypeNameGenerator(method.typeReference.rawDeclaration),
+    },
+    throws: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+    parameters: method.parameters.map((param) => mapParameters(method, param)),
+    inherited: (method as MethodMirrorWithInheritance).inherited,
+  };
+}
+
+export function adaptConstructor(typeName: string, constructor: ConstructorMirror): ConstructorSource {
+  function buildTitle(name: string, constructor: ConstructorMirror): string {
+    const { parameters } = constructor;
+    const parametersString = parameters.map((param) => param.name).join(', ');
+    return `${name}(${parametersString})`;
+  }
+
+  function buildSignature(name: string, constructor: ConstructorMirror): string {
+    const { access_modifier } = constructor;
+    const parameters = constructor.parameters
+      .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
+      .join(', ');
+    return `${access_modifier} ${name}(${parameters})`;
+  }
+
+  return {
+    ...adaptDocumentable(constructor),
+    title: buildTitle(typeName, constructor),
+    signature: buildSignature(typeName, constructor),
+    parameters: constructor.parameters.map((param) => mapParameters(constructor, param)),
+    throws: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+  };
+}
+
+function mapParameters(documentable: Documentable, param: ParameterMirror) {
+  const paramAnnotation = documentable.docComment?.paramAnnotations.find(
+    (pa) => pa.paramName.toLowerCase() === param.name.toLowerCase(),
+  );
+  return {
+    ...adaptDescribable(paramAnnotation?.bodyLines),
+    name: param.name,
+    type: linkFromTypeNameGenerator(param.typeReference.rawDeclaration),
+  };
+}
+
+function mapThrows(thrown: ThrowsAnnotation) {
+  return {
+    ...adaptDescribable(thrown.bodyLines),
+    type: linkFromTypeNameGenerator(thrown.exceptionName),
+  };
+}