@cparra/apexdocs 3.0.0-rc.0 → 3.0.0

package/src/index.ts

@@ -11,29 +11,89 @@ import type {
   TransformDocPage,
   TransformReference,
   ConfigurableDocPageReference,
+  UserDefinedOpenApiConfig,
+  UserDefinedConfig,
 } from './core/shared/types';
-import { defaults } from './defaults';
+import { markdownDefaults, openApiDefaults } from './defaults';
+import { NoLogger } from '#utils/logger';
+import { Apexdocs } from './application/Apexdocs';
+import * as E from 'fp-ts/Either';
 
 type ConfigurableMarkdownConfig = Omit<Partial<UserDefinedMarkdownConfig>, 'targetGenerator'>;
 
+/**
+ * Helper function to define a configuration to generate Markdown documentation.
+ * @param config The configuration to use.
+ */
 function defineMarkdownConfig(config: ConfigurableMarkdownConfig): Partial<UserDefinedMarkdownConfig> {
   return {
-    ...defaults,
+    ...markdownDefaults,
     ...config,
-    targetGenerator: 'markdown',
+    targetGenerator: 'markdown' as const,
   };
 }
 
+type ConfigurableOpenApiConfig = Omit<Partial<UserDefinedOpenApiConfig>, 'targetGenerator'>;
+
+/**
+ * Helper function to define a configuration to generate OpenAPI documentation.
+ * @param config The configuration to use.
+ */
+function defineOpenApiConfig(config: ConfigurableOpenApiConfig): Partial<UserDefinedOpenApiConfig> {
+  return {
+    ...openApiDefaults,
+    ...config,
+    targetGenerator: 'openapi' as const,
+  };
+}
+
+/**
+ * Represents a file to be skipped.
+ */
 function skip(): Skip {
   return {
     _tag: 'Skip',
   };
 }
 
-// Exports
+type CallableConfig = Partial<UserDefinedConfig> & { sourceDir: string; targetGenerator: 'markdown' | 'openapi' };
+
+async function process(config: CallableConfig): Promise<void> {
+  const logger = new NoLogger();
+  const configWithDefaults = {
+    ...getDefault(config),
+    ...config,
+  };
+
+  if (!configWithDefaults.sourceDir) {
+    throw new Error('sourceDir is required');
+  }
+
+  const result = await Apexdocs.generate(configWithDefaults as UserDefinedConfig, logger);
+  E.match(
+    (errors) => {
+      throw errors;
+    },
+    () => {},
+  )(result);
+}
+
+function getDefault(config: CallableConfig) {
+  switch (config.targetGenerator) {
+    case 'markdown':
+      return markdownDefaults;
+    case 'openapi':
+      return openApiDefaults;
+    default:
+      throw new Error('Unknown target generator');
+  }
+}
 
 export {
   defineMarkdownConfig,
+  ConfigurableMarkdownConfig,
+  defineOpenApiConfig,
+  ConfigurableOpenApiConfig,
   skip,
   TransformReferenceGuide,
   TransformDocs,
@@ -46,4 +106,5 @@ export {
   Skip,
   ConfigurableDocPageData,
   ConfigurableDocPageReference,
+  process,
 };

package/src/util/error-logger.ts

@@ -2,90 +2,90 @@ import { ClassMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
 import { Logger } from './logger';
 
 export default class ErrorLogger {
-  public static logErrors(types: Type[]): void {
+  public static logErrors(logger: Logger, types: Type[]): void {
     types.forEach((currentType) => {
-      this.logErrorsForSingleType(currentType);
+      this.logErrorsForSingleType(logger, currentType);
     });
   }
 
-  private static logErrorsForSingleType(currentType: Type): void {
-    this.logTypeErrors(currentType);
+  private static logErrorsForSingleType(logger: Logger, currentType: Type): void {
+    this.logTypeErrors(logger, currentType);
 
     if (currentType.type_name === 'class') {
-      this.logErrorsForClass(currentType as ClassMirror);
+      this.logErrorsForClass(logger, currentType as ClassMirror);
     } else if (currentType.type_name === 'interface') {
-      this.logErrorsForInterface(currentType as InterfaceMirror);
+      this.logErrorsForInterface(logger, currentType as InterfaceMirror);
     }
   }
 
-  private static logTypeErrors(currentType: Type, parentType?: Type) {
+  private static logTypeErrors(logger: Logger, currentType: Type, parentType?: Type) {
     if (currentType.docComment?.error) {
       const typeName = parentType ? `${parentType!.name}.${currentType.name}` : currentType.name;
-      Logger.error(`${typeName} - Doc comment parsing error. Level: Type`);
-      Logger.error(`Comment:\n ${currentType.docComment.rawDeclaration}`);
-      Logger.error(currentType.docComment.error);
-      Logger.error('=================================');
+      logger.error(`${typeName} - Doc comment parsing error. Level: Type`);
+      logger.error(`Comment:\n ${currentType.docComment.rawDeclaration}`);
+      logger.error(currentType.docComment.error);
+      logger.error('=================================');
     }
   }
 
-  private static logErrorsForClass(classMirror: ClassMirror, parentType?: Type): void {
+  private static logErrorsForClass(logger: Logger, classMirror: ClassMirror, parentType?: Type): void {
     const typeName = parentType ? `${parentType!.name}.${classMirror.name}` : classMirror.name;
     classMirror.constructors.forEach((currentConstructor) => {
       if (currentConstructor.docComment?.error) {
-        Logger.error(`${typeName} - Doc comment parsing error. Level: Constructor`);
-        Logger.error(`Comment:\n ${currentConstructor.docComment.rawDeclaration}`);
-        Logger.error(currentConstructor.docComment.error);
-        Logger.error('=================================');
+        logger.error(`${typeName} - Doc comment parsing error. Level: Constructor`);
+        logger.error(`Comment:\n ${currentConstructor.docComment.rawDeclaration}`);
+        logger.error(currentConstructor.docComment.error);
+        logger.error('=================================');
       }
     });
 
     classMirror.fields.forEach((currentField) => {
       if (currentField.docComment?.error) {
-        Logger.error(`${typeName} - Doc comment parsing error. Level: Field`);
-        Logger.error(`Comment:\n ${currentField.docComment.rawDeclaration}`);
-        Logger.error(currentField.docComment.error);
-        Logger.error('=================================');
+        logger.error(`${typeName} - Doc comment parsing error. Level: Field`);
+        logger.error(`Comment:\n ${currentField.docComment.rawDeclaration}`);
+        logger.error(currentField.docComment.error);
+        logger.error('=================================');
       }
     });
 
     classMirror.properties.forEach((currentProperty) => {
       if (currentProperty.docComment?.error) {
-        Logger.error(`${typeName} - Doc comment parsing error. Level: Property`);
-        Logger.error(`Comment:\n ${currentProperty.docComment.rawDeclaration}`);
-        Logger.error(currentProperty.docComment.error);
-        Logger.error('=================================');
+        logger.error(`${typeName} - Doc comment parsing error. Level: Property`);
+        logger.error(`Comment:\n ${currentProperty.docComment.rawDeclaration}`);
+        logger.error(currentProperty.docComment.error);
+        logger.error('=================================');
       }
     });
 
     classMirror.methods.forEach((currentMethod) => {
       if (currentMethod.docComment?.error) {
-        Logger.error(`${typeName} - Doc comment parsing error. Level: Method`);
-        Logger.error(`Comment:\n ${currentMethod.docComment.rawDeclaration}`);
-        Logger.error(currentMethod.docComment.error);
-        Logger.error('=================================');
+        logger.error(`${typeName} - Doc comment parsing error. Level: Method`);
+        logger.error(`Comment:\n ${currentMethod.docComment.rawDeclaration}`);
+        logger.error(currentMethod.docComment.error);
+        logger.error('=================================');
       }
     });
 
     classMirror.enums.forEach((currentEnum) => {
-      this.logErrorsForSingleType(currentEnum);
+      this.logErrorsForSingleType(logger, currentEnum);
     });
 
     classMirror.interfaces.forEach((currentInterface) => {
-      this.logErrorsForSingleType(currentInterface);
+      this.logErrorsForSingleType(logger, currentInterface);
     });
 
     classMirror.classes.forEach((currentClass) => {
-      this.logErrorsForSingleType(currentClass);
+      this.logErrorsForSingleType(logger, currentClass);
     });
   }
 
-  private static logErrorsForInterface(interfaceMirror: InterfaceMirror): void {
+  private static logErrorsForInterface(logger: Logger, interfaceMirror: InterfaceMirror): void {
     interfaceMirror.methods.forEach((currentMethod) => {
       if (currentMethod.docComment?.error) {
-        Logger.error(`${interfaceMirror.name} - Doc comment parsing error. Level: Method`);
-        Logger.error(`Comment: ${currentMethod.docComment.rawDeclaration}`);
-        Logger.error(currentMethod.docComment.error);
-        Logger.error('=================================');
+        logger.error(`${interfaceMirror.name} - Doc comment parsing error. Level: Method`);
+        logger.error(`Comment: ${currentMethod.docComment.rawDeclaration}`);
+        logger.error(currentMethod.docComment.error);
+        logger.error('=================================');
       }
     });
   }

package/src/util/logger.ts

@@ -1,16 +1,21 @@
 import chalk from 'chalk';
+
+export interface Logger {
+  log(message: string, ...args: string[]): void;
+  error(message: unknown, ...args: string[]): void;
+  logSingle(text: unknown, color?: 'green' | 'red'): void;
+}
+
 /**
  * Logs messages to the console.
  */
-export class Logger {
-  static currentFrame = 0;
-
+export class StdOutLogger {
   /**
    * Logs a message with optional arguments.
    * @param message The message to log.
    * @param args Optional arguments.
    */
-  public static log(message: string, ...args: string[]) {
+  public log(message: string, ...args: string[]) {
     this.logSingle(message);
     args.forEach((arg) => {
       this.logSingle(arg);
@@ -22,23 +27,25 @@ export class Logger {
    * @param message The error message to log.
    * @param args Optional arguments.
    */
-  public static error(message: unknown, ...args: string[]) {
+  public error(message: unknown, ...args: string[]) {
     this.logSingle(message, 'red');
     args.forEach(() => {
       this.logSingle(message, 'red');
     });
   }
 
-  public static logSingle(text: unknown, color: 'green' | 'red' = 'green') {
-    if (this.currentFrame > 9) {
-      this.currentFrame = 0;
-    }
-
+  public logSingle(text: unknown, color: 'green' | 'red' = 'green') {
     const logMessage = `${this.getChalkFn(color)(new Date().toLocaleString() + ': ')}${text}\n`;
     process.stdout.write(logMessage);
   }
 
-  private static getChalkFn(color: 'green' | 'red') {
+  private getChalkFn(color: 'green' | 'red') {
     return color === 'green' ? chalk.green : chalk.red;
   }
 }
+
+export class NoLogger implements Logger {
+  public log() {}
+  public error() {}
+  public logSingle() {}
+}