@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

package/src/{transpiler → core}/openapi/parsers/__tests__/RequestBodyBuilder.spec.ts

@@ -1,7 +1,7 @@
 import { RequestBodyBuilder } from '../RequestBodyBuilder';
 import { Reference } from '../ReferenceBuilder';
-import { ReferenceObject } from '../../../../model/openapi/open-api-types';
-import { ApexDocHttpRequestBody } from '../../../../model/openapi/apex-doc-types';
+import { ReferenceObject } from '../../../../core/openapi/open-api-types';
+import { ApexDocHttpRequestBody } from '../../../../core/openapi/apex-doc-types';
 
 jest.mock('../ReferenceBuilder', () => {
   return {

package/src/{transpiler → core}/openapi/parsers/__tests__/ResponsesBuilder.spec.ts

@@ -1,6 +1,6 @@
 import { ResponsesBuilder } from '../ResponsesBuilder';
 import { Reference } from '../ReferenceBuilder';
-import { ApexDocHttpResponse } from '../../../../model/openapi/apex-doc-types';
+import { ApexDocHttpResponse } from '../../../../core/openapi/apex-doc-types';
 
 jest.mock('../ReferenceBuilder', () => {
   return {

package/src/{transpiler → core/openapi}/transpiler.ts

@@ -1,24 +1,20 @@
 import { Type } from '@cparra/apex-reflection';
-import ProcessorTypeTranspiler from './processor-type-transpiler';
 import { Settings } from '../settings';
-import State from '../service/state';
+import { OpenApiDocsProcessor } from './open-api-docs-processor';
 
 export default class Transpiler {
-  static generate(types: Type[], processor: ProcessorTypeTranspiler): void {
+  static generate(types: Type[], processor: OpenApiDocsProcessor): void {
     const sortedTypes = types.sort((apexTypeA, apexTypeB) => {
       if (apexTypeA.name < apexTypeB.name) return -1;
       if (apexTypeA.name > apexTypeB.name) return 1;
       return 0;
     });
 
-    processor.onBeforeProcess?.(sortedTypes);
-
     if (Settings.getInstance().indexOnly) {
       return;
     }
 
     sortedTypes.forEach((currentType) => {
-      State.getInstance().setTypeBeingProcessed(currentType);
       processor.onProcess(currentType);
     });
     processor.onAfterProcess?.(sortedTypes);

package/src/{model → core/openapi}/types-repository.ts

@@ -4,7 +4,6 @@ export type TypeBundle = { type: Type; isChild: boolean; parentType?: Type };
 
 export class TypesRepository {
   private static instance: TypesRepository;
-  private scopedTypes: Type[] = [];
   private allTypes: Type[] = [];
 
   public static getInstance(): TypesRepository {
@@ -52,12 +51,4 @@ export class TypesRepository {
     }
     return { type: foundType, isChild: false };
   }
-
-  public populateScoped(types: Type[]) {
-    this.scopedTypes = types;
-  }
-
-  public getFromScopedByName(typeName: string): Type | undefined {
-    return this.scopedTypes.find((currentType: Type) => currentType.name === typeName);
-  }
 }

package/src/core/parse-apex-metadata.ts

@@ -0,0 +1,30 @@
+import { XMLParser } from 'fast-xml-parser';
+import * as E from 'fp-ts/Either';
+import { pipe } from 'fp-ts/function';
+
+type ApexMetadata = {
+  ApexClass: ApexClassMetadata;
+};
+
+type ApexClassMetadata = {
+  apiVersion: string;
+  status?: string;
+};
+
+export function parseApexMetadata(input: string) {
+  return pipe(input, parse, E.map(toMap));
+}
+
+function parse(input: string): E.Either<Error, ApexMetadata> {
+  return E.tryCatch(() => new XMLParser().parse(input), E.toError);
+}
+
+function toMap(metadata: ApexMetadata): Map<string, string> {
+  const map = new Map<string, string>();
+  map.set('apiVersion', String(metadata.ApexClass.apiVersion));
+  if (metadata.ApexClass.status) {
+    map.set('status', String(metadata.ApexClass.status));
+  }
+
+  return map;
+}

package/src/core/settings.ts

@@ -0,0 +1,56 @@
+import { Generator } from './shared/types';
+
+export interface SettingsConfig {
+  sourceDirectory: string;
+  scope: string[];
+  outputDir: string;
+  targetGenerator: Generator;
+  indexOnly: boolean;
+  defaultGroupName: string;
+  openApiTitle?: string;
+  namespace?: string;
+  openApiFileName: string;
+  includeMetadata: boolean;
+  sortMembersAlphabetically?: boolean;
+}
+
+export class Settings {
+  private static instance: Settings;
+
+  private constructor(public config: SettingsConfig) {}
+
+  public static build(config: SettingsConfig) {
+    Settings.instance = new Settings(config);
+  }
+
+  public static getInstance(): Settings {
+    if (!Settings.instance) {
+      throw new Error('Settings has not been initialized');
+    }
+    return Settings.instance;
+  }
+
+  get scope(): string[] {
+    return this.config.scope;
+  }
+
+  get targetGenerator(): Generator {
+    return this.config.targetGenerator;
+  }
+
+  get indexOnly(): boolean {
+    return this.config.indexOnly;
+  }
+
+  public getOpenApiTitle(): string | undefined {
+    return this.config.openApiTitle;
+  }
+
+  public getNamespace(): string | undefined {
+    return this.config.namespace;
+  }
+
+  public openApiFileName(): string {
+    return this.config.openApiFileName;
+  }
+}

package/src/core/shared/types.d.ts

@@ -0,0 +1,147 @@
+import { Type } from '@cparra/apex-reflection';
+
+export type Generator = 'markdown' | 'openapi';
+
+/**
+ * The configurable hooks that can be used to modify the output of the generator.
+ */
+export type ConfigurableHooks = {
+  transformReferenceGuide: TransformReferenceGuide;
+  transformDocs: TransformDocs;
+  transformDocPage: TransformDocPage;
+  transformReference: TransformReference;
+};
+
+type LinkingStrategy =
+  // Links will be generated using relative paths.
+  | 'relative'
+  // No links will be generated.
+  // If the reference is found, the display name will be used.
+  // Otherwise, the name
+  // of the reference itself will be used.
+  | 'no-link'
+  // No logic will be applied, the reference path will be used as is.
+  | 'none';
+
+export type UserDefinedMarkdownConfig = {
+  targetGenerator: 'markdown';
+  sourceDir: string;
+  targetDir: string;
+  scope: string[];
+  defaultGroupName: string;
+  namespace?: string;
+  sortMembersAlphabetically: boolean;
+  includeMetadata: boolean;
+  linkingStrategy: LinkingStrategy;
+} & Partial<ConfigurableHooks>;
+
+export type UserDefinedOpenApiConfig = {
+  targetGenerator: 'openapi';
+  sourceDir: string;
+  targetDir: string;
+  includeMetadata: boolean;
+};
+
+export type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig;
+
+export type UnparsedSourceFile = {
+  filePath: string;
+  content: string;
+  metadataContent: string | null;
+};
+
+export type SourceFileMetadata = {
+  filePath: string;
+  name: string;
+  type: 'interface' | 'class' | 'enum';
+};
+
+export type ParsedFile = {
+  source: SourceFileMetadata;
+  type: Type;
+};
+
+export type DocPageReference = {
+  source: SourceFileMetadata;
+  // The name under which the type should be displayed in the documentation.
+  // By default, this will match the source.name, but it can be configured by the user.
+  displayName: string;
+  // The location where the file will be written.
+  outputDocPath: string;
+  // The path to the file relative to the documentation root directory. This is used when linking to the file.
+  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
+  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
+  // the path where the file is written.
+  referencePath: string;
+};
+
+type Frontmatter = string | Record<string, unknown> | null;
+
+export type ReferenceGuidePageData = {
+  frontmatter: Frontmatter;
+  content: string;
+  outputDocPath: string;
+};
+
+export type DocPageData = {
+  source: SourceFileMetadata;
+  group: string | null;
+  outputDocPath: string;
+  frontmatter: Frontmatter;
+  content: string;
+};
+
+export type OpenApiPageData = Omit<DocPageData, 'source'>;
+
+export type PageData = DocPageData | OpenApiPageData | ReferenceGuidePageData;
+
+export type DocumentationBundle = {
+  referenceGuide: ReferenceGuidePageData;
+  docs: DocPageData[];
+};
+
+/**
+ * Represents a file to be skipped.
+ */
+export type Skip = {
+  readonly _tag: 'Skip';
+};
+
+export type PostHookDocumentationBundle = {
+  referenceGuide: ReferenceGuidePageData | Skip;
+  docs: DocPageData[];
+};
+
+// Configurable Hooks
+
+type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
+
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
+
+/**
+ * Allows changing where the files are written to.
+ */
+export type TransformReference = (
+  reference: DocPageReference,
+) => Partial<ConfigurableDocPageReference> | Promise<ConfigurableDocPageReference>;
+
+/**
+ * Allows changing the frontmatter and content of the reference guide, or even if creating a reference
+ * guide will be skipped altogether.
+ */
+export type TransformReferenceGuide = (
+  referenceGuide: ReferenceGuidePageData,
+) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;
+
+/**
+ * The main purpose if for allowing for doc pages to be skipped, but it can also be used to change the frontmatter
+ * and content of the doc pages.
+ */
+export type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>;
+
+/**
+ * Allows changing the frontmatter and content of the doc pages.
+ */
+export type TransformDocPage = (
+  doc: DocPageData,
+) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;

package/src/core/shared/utils.ts

@@ -0,0 +1,5 @@
+import { Skip } from './types';
+
+export function isSkip(value: unknown): value is Skip {
+  return Object.prototype.hasOwnProperty.call(value, '_tag') && (value as Skip)._tag === 'Skip';
+}

package/src/defaults.ts

@@ -0,0 +1,9 @@
+export const defaults = {
+  targetGenerator: 'markdown' as const,
+  targetDir: './docs/',
+  scope: ['global'],
+  defaultGroupName: 'Miscellaneous',
+  includeMetadata: false,
+  sortMembersAlphabetically: false,
+  linkingStrategy: 'relative' as const,
+};

package/src/index.ts

@@ -1 +1,36 @@
-export * from './service/manifest-factory';
+import { SetOptional } from 'type-fest';
+import type {
+  ConfigurableHooks,
+  Skip,
+  UserDefinedMarkdownConfig,
+  ReferenceGuidePageData,
+  DocPageData,
+  DocPageReference,
+} from './core/shared/types';
+import { defaults } from './defaults';
+
+type ConfigurableMarkdownConfig = Omit<
+  SetOptional<
+    UserDefinedMarkdownConfig,
+    'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'
+  >,
+  'targetGenerator'
+>;
+
+function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig {
+  return {
+    ...defaults,
+    ...config,
+    targetGenerator: 'markdown',
+  };
+}
+
+function skip(): Skip {
+  return {
+    _tag: 'Skip',
+  };
+}
+
+// Exports
+
+export { defineMarkdownConfig, skip, ConfigurableHooks, ReferenceGuidePageData, DocPageData, DocPageReference };

package/src/test-helpers/ClassMirrorBuilder.ts

@@ -10,6 +10,8 @@ export class ClassMirrorBuilder {
   private docComment?: DocComment;
   private methods: MethodMirror[] = [];
   private fields: FieldMirror[] = [];
+  private innerClasses: ClassMirror[] = [];
+  private extendedClass: string | undefined;
 
   withName(name: string): ClassMirrorBuilder {
     this.name = name;
@@ -36,6 +38,16 @@ export class ClassMirrorBuilder {
     return this;
   }
 
+  addInnerClass(innerClass: ClassMirror): ClassMirrorBuilder {
+    this.innerClasses.push(innerClass);
+    return this;
+  }
+
+  withExtendedClass(extendedClass: string): ClassMirrorBuilder {
+    this.extendedClass = extendedClass;
+    return this;
+  }
+
   build(): ClassMirror {
     return {
       annotations: this.annotations,
@@ -48,9 +60,10 @@ export class ClassMirrorBuilder {
       constructors: [],
       enums: [],
       interfaces: [],
-      classes: [],
+      classes: this.innerClasses,
       access_modifier: 'public',
       docComment: this.docComment,
+      extended_class: this.extendedClass,
     };
   }
 }

package/src/test-helpers/FieldMirrorBuilder.ts

@@ -1,5 +1,5 @@
 import { DocComment, FieldMirror } from '@cparra/apex-reflection';
-import { ReferencedType } from '@cparra/apex-reflection/index';
+import { ReferencedType } from '@cparra/apex-reflection';
 
 type MemberModifier = 'static' | 'webservice' | 'final' | 'override' | 'testmethod' | 'transient';
 

package/src/test-helpers/InterfaceMirrorBuilder.ts

@@ -0,0 +1,39 @@
+import { Annotation, DocComment, InterfaceMirror, MethodMirror } from '@cparra/apex-reflection';
+
+/**
+ * Builder class to create Interface objects.
+ * For testing purposes only.
+ */
+export class InterfaceMirrorBuilder {
+  private name = 'SampleClass';
+  private annotations: Annotation[] = [];
+  private docComment?: DocComment;
+  private methods: MethodMirror[] = [];
+
+  withName(name: string): InterfaceMirrorBuilder {
+    this.name = name;
+    return this;
+  }
+
+  addAnnotation(annotation: Annotation): InterfaceMirrorBuilder {
+    this.annotations.push(annotation);
+    return this;
+  }
+
+  addMethod(method: MethodMirror): InterfaceMirrorBuilder {
+    this.methods.push(method);
+    return this;
+  }
+
+  build(): InterfaceMirror {
+    return {
+      annotations: this.annotations,
+      name: this.name,
+      type_name: 'interface',
+      methods: this.methods,
+      access_modifier: 'public',
+      docComment: this.docComment,
+      extended_interfaces: [],
+    };
+  }
+}

package/src/test-helpers/MethodMirrorBuilder.ts

@@ -1,9 +1,16 @@
-import { Annotation, DocComment, MethodMirror } from '@cparra/apex-reflection';
+import { Annotation, DocComment, MethodMirror, ParameterMirror } from '@cparra/apex-reflection';
+
+type Parameter = ParameterMirror;
 
 export class MethodMirrorBuilder {
   private name = 'sampleMethod';
   private annotations: Annotation[] = [];
   private docComment?: DocComment;
+  private typeReference: { type: string; rawDeclaration: string } = {
+    type: 'void',
+    rawDeclaration: 'void',
+  };
+  private parameters: Parameter[] = [];
 
   withName(name: string): MethodMirrorBuilder {
     this.name = name;
@@ -20,18 +27,51 @@ export class MethodMirrorBuilder {
     return this;
   }
 
+  withTypeReference(param: { type: string; rawDeclaration: string }) {
+    this.typeReference = param;
+    return this;
+  }
+
+  addParameter(parameter: Parameter): MethodMirrorBuilder {
+    this.parameters.push(parameter);
+    return this;
+  }
+
   build(): MethodMirror {
     return {
       access_modifier: 'public',
       annotations: this.annotations,
       name: this.name,
       memberModifiers: [],
-      typeReference: {
-        type: 'void',
-        rawDeclaration: 'void',
-      },
-      parameters: [],
+      typeReference: this.typeReference,
+      parameters: this.parameters,
       docComment: this.docComment,
     };
   }
 }
+
+export class ParameterBuilder {
+  private name = 'param';
+  private typeReference: { type: string; rawDeclaration: string } = {
+    type: 'String',
+    rawDeclaration: 'String',
+  };
+
+  withName(name: string): ParameterBuilder {
+    this.name = name;
+    return this;
+  }
+
+  withTypeReference(param: { type: string; rawDeclaration: string }) {
+    this.typeReference = param;
+    return this;
+  }
+
+  build(): Parameter {
+    return {
+      memberModifiers: [],
+      name: this.name,
+      typeReference: this.typeReference,
+    };
+  }
+}

package/src/test-helpers/SettingsBuilder.ts

@@ -1,4 +1,4 @@
-import { SettingsConfig } from '../settings';
+import { SettingsConfig } from '../core/settings';
 
 /**
  * Builder class to create SettingsConfig objects.
@@ -8,16 +8,13 @@ export class SettingsBuilder {
   build(): SettingsConfig {
     return {
       sourceDirectory: './',
-      recursive: true,
       scope: [],
       outputDir: './',
       targetGenerator: 'openapi',
       indexOnly: false,
       defaultGroupName: 'Misc',
-      sanitizeHtml: true,
       openApiTitle: 'Apex API',
       openApiFileName: 'openapi',
-      title: 'Classes',
       includeMetadata: false,
     };
   }

package/src/util/error-logger.ts

@@ -8,7 +8,7 @@ export default class ErrorLogger {
     });
   }
 
-  private static logErrorsForSingleType(currentType: Type, parentType?: Type): void {
+  private static logErrorsForSingleType(currentType: Type): void {
     this.logTypeErrors(currentType);
 
     if (currentType.type_name === 'class') {
@@ -67,15 +67,15 @@ export default class ErrorLogger {
     });
 
     classMirror.enums.forEach((currentEnum) => {
-      this.logErrorsForSingleType(currentEnum, classMirror);
+      this.logErrorsForSingleType(currentEnum);
     });
 
     classMirror.interfaces.forEach((currentInterface) => {
-      this.logErrorsForSingleType(currentInterface, classMirror);
+      this.logErrorsForSingleType(currentInterface);
     });
 
     classMirror.classes.forEach((currentClass) => {
-      this.logErrorsForSingleType(currentClass, classMirror);
+      this.logErrorsForSingleType(currentClass);
     });
   }
 

package/src/util/fp.ts

@@ -0,0 +1,3 @@
+export function apply<T extends unknown[], U extends unknown[], R>(fn: (...args: [...T, ...U]) => R, ...front: T) {
+  return (...tailArgs: U) => fn(...front, ...tailArgs);
+}

package/src/util/logger.ts

@@ -1,13 +1,9 @@
-import * as chalk from 'chalk';
-import * as logUpdate from 'log-update';
-
+import chalk from 'chalk';
 /**
  * Logs messages to the console.
  */
 export class Logger {
-  static currentFrame = -1;
-
-  static frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  static currentFrame = 0;
 
   /**
    * Logs a message with optional arguments.
@@ -26,32 +22,23 @@ export class Logger {
    * @param message The error message to log.
    * @param args Optional arguments.
    */
-  public static error(message: string, ...args: string[]) {
-    this.logSingle(message, false, 'red', false);
-    args.forEach((arg) => {
-      this.logSingle(message, false, 'red', false);
+  public static error(message: unknown, ...args: string[]) {
+    this.logSingle(message, 'red');
+    args.forEach(() => {
+      this.logSingle(message, 'red');
     });
   }
 
-  public static logSingle(text: string, showSpinner = true, color: 'green' | 'red' = 'green', overrideConsole = true) {
+  public static logSingle(text: unknown, color: 'green' | 'red' = 'green') {
     if (this.currentFrame > 9) {
       this.currentFrame = 0;
     }
-    const spinner = showSpinner ? `${this.frames[this.currentFrame++]}` : '';
-    let logMessage;
-    if (color === 'green') {
-      logMessage = `${chalk.green(new Date().toLocaleString() + ': ')}${text}\n`;
-    } else {
-      logMessage = `${chalk.red(new Date().toLocaleString() + ': ')}${text}\n`;
-    }
-    if (overrideConsole) {
-      logUpdate(`${spinner} ${logMessage}`);
-    } else {
-      process.stdout.write(`${spinner} ${logMessage}`);
-    }
+
+    const logMessage = `${this.getChalkFn(color)(new Date().toLocaleString() + ': ')}${text}\n`;
+    process.stdout.write(logMessage);
   }
 
-  public static clear() {
-    logUpdate.clear();
+  private static getChalkFn(color: 'green' | 'red') {
+    return color === 'green' ? chalk.green : chalk.red;
   }
 }

package/src/util/string-utils.ts

@@ -1,7 +1,3 @@
-export function truncate(str: string, n: number) {
-  return str.length > n ? str.substr(0, n - 1) + '…' : str;
-}
-
 export const camel2title = (camelCase: string) =>
   camelCase
     .replace(/\//g, ' ')

package/tsconfig.json

@@ -3,15 +3,20 @@
     "target": "es6",
     "module": "commonjs",
     "declaration": true,
-    "outDir": "./lib",
+    "outDir": "./dist",
     "strict": true,
     "sourceMap": true,
+    "esModuleInterop": true,
     "lib": [
       "ES2021"
-    ]
+    ],
+    "baseUrl": "./",
+    "paths": {
+      "#utils/*": ["src/util/*"],
+    }
   },
   "include": [
-    "src"
+    "src", "jest.d.ts"
   ],
   "exclude": [
     "node_modules",

package/.eslintrc.js

@@ -1,12 +0,0 @@
-module.exports = {
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    ecmaVersion: 2020,
-    sourceType: 'module',
-  },
-  extends: [
-    'plugin:@typescript-eslint/recommended',
-    'plugin:prettier/recommended',
-  ],
-  rules: {},
-};