@cparra/apexdocs 2.25.0-alpha.0 → 2.25.0-alpha.10

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

@@ -1,6 +1,6 @@
-import { ParameterObject } from '../../../model/openapi/open-api-types';
+import { ParameterObject } from '../../../core/openapi/open-api-types';
 import { Reference } from './ReferenceBuilder';
-import { ApexDocParameterObject } from '../../../model/openapi/apex-doc-types';
+import { ApexDocParameterObject } from '../../../core/openapi/apex-doc-types';
 import { Builder } from './Builder';
 
 export class ParameterObjectBuilder extends Builder<ParameterObject, ApexDocParameterObject> {

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

@@ -5,11 +5,11 @@ import {
   SchemaObject,
   SchemaObjectArray,
   SchemaObjectObject,
-} from '../../../model/openapi/open-api-types';
-import { TypeBundle, TypesRepository } from '../../../model/types-repository';
+} from '../../../core/openapi/open-api-types';
+import { TypeBundle, TypesRepository } from '../../../core/openapi/types-repository';
 import { ClassMirror, DocCommentAnnotation, FieldMirror, PropertyMirror } from '@cparra/apex-reflection';
 import { ListObjectType, ReferencedType } from '@cparra/apex-reflection';
-import { ApexDocSchemaObject } from '../../../model/openapi/apex-doc-types';
+import { ApexDocSchemaObject } from '../../../core/openapi/apex-doc-types';
 
 type TypeBundleWithIsCollectionAndReferenceOverrides = TypeBundle & {
   originalTypeName: string;
@@ -227,7 +227,7 @@ export class ReferenceBuilder {
         return { schema: { type: 'object' }, referenceComponents: [] };
       case 'object':
         return { schema: { type: 'object' }, referenceComponents: [] };
-      default:
+      default: {
         // If we got here we are dealing with a non-primitive (most likely a custom class or an SObject).
         const referencedType = TypesRepository.getInstance().getFromAllByName(typeName);
         if (!referencedType) {
@@ -243,6 +243,7 @@ export class ReferenceBuilder {
           schema: reference.entrypointReferenceObject,
           referenceComponents: [...reference.referenceComponents],
         };
+      }
     }
   }
 
@@ -266,7 +267,7 @@ type SchemaObjectReferencePair = {
 
 class ReferenceOverrides {
   static build(referenceAsString: string): ReferenceOverride[] {
-    const cleanedUpReference = referenceAsString.replace(/[\[\]]/g, '');
+    const cleanedUpReference = referenceAsString.replace(/[[\]]/g, '');
     const referenceStrings = cleanedUpReference.split(',').map((item) => item.replace(/\s/g, ''));
     return referenceStrings.map((item) => {
       const [propertyName, referenceName] = item.split(':');

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

@@ -1,6 +1,6 @@
-import { RequestBody } from '../../../model/openapi/open-api-types';
+import { RequestBody } from '../../../core/openapi/open-api-types';
 import { Reference } from './ReferenceBuilder';
-import { ApexDocHttpRequestBody } from '../../../model/openapi/apex-doc-types';
+import { ApexDocHttpRequestBody } from '../../../core/openapi/apex-doc-types';
 import { Builder } from './Builder';
 
 /**

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

@@ -1,6 +1,6 @@
-import { ResponseObject } from '../../../model/openapi/open-api-types';
+import { ResponseObject } from '../../../core/openapi/open-api-types';
 import { Reference } from './ReferenceBuilder';
-import { ApexDocHttpResponse } from '../../../model/openapi/apex-doc-types';
+import { ApexDocHttpResponse } from '../../../core/openapi/apex-doc-types';
 import { Builder } from './Builder';
 
 export class ResponsesBuilder extends Builder<ResponseObject, ApexDocHttpResponse> {

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

@@ -1,7 +1,7 @@
 import { ClassMirrorBuilder } from '../../../../test-helpers/ClassMirrorBuilder';
 import { MethodMirrorBuilder } from '../../../../test-helpers/MethodMirrorBuilder';
 import { AnnotationBuilder } from '../../../../test-helpers/AnnotationBuilder';
-import { OpenApi } from '../../../../model/openapi/open-api';
+import { OpenApi } from '../../../../core/openapi/open-api';
 import { MethodParser } from '../MethodParser';
 import { DocCommentBuilder } from '../../../../test-helpers/DocCommentBuilder';
 

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

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

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

@@ -1,8 +1,8 @@
-import { TypesRepository } from '../../../../model/types-repository';
+import { TypesRepository } from '../../../../core/openapi/types-repository';
 import { ReferenceBuilder } from '../ReferenceBuilder';
 import { ClassMirrorBuilder } from '../../../../test-helpers/ClassMirrorBuilder';
 import { FieldMirrorBuilder } from '../../../../test-helpers/FieldMirrorBuilder';
-import { SchemaObjectArray, SchemaObjectObject } from '../../../../model/openapi/open-api-types';
+import { SchemaObjectArray, SchemaObjectObject } from '../../../../core/openapi/open-api-types';
 import { DocCommentBuilder } from '../../../../test-helpers/DocCommentBuilder';
 import { DocCommentAnnotationBuilder } from '../../../../test-helpers/DocCommentAnnotationBuilder';
 

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,14 @@
+import { XMLParser } from 'fast-xml-parser';
+
+export function parseApexMetadata(input: string) {
+  const map = new Map<string, string>();
+  const xml = new XMLParser().parse(input);
+
+  map.set('apiVersion', xml.ApexClass.apiVersion ?? '');
+
+  if (xml.ApexClass.status) {
+    map.set('status', xml.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,131 @@
+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;
+};
+
+export type UserDefinedMarkdownConfig = {
+  targetGenerator: 'markdown';
+  sourceDir: string;
+  targetDir: string;
+  scope: string[];
+  defaultGroupName: string;
+  namespace?: string;
+  sortMembersAlphabetically: boolean;
+  includeMetadata: boolean;
+  documentationRootDir: string;
+} & 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 of the file relative to the root of the documentation.
+  pathFromRoot: string;
+};
+
+type Frontmatter = string | Record<string, unknown> | null;
+
+export type ReferenceGuidePageData = {
+  frontmatter: Frontmatter;
+  content: string;
+  filePath: string;
+};
+
+export type DocPageData = {
+  source: SourceFileMetadata;
+  group: string | null;
+  filePath: 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' | 'filePath'>;
+
+/**
+ * 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,
+  documentationRootDir: '',
+};

package/src/index.ts

@@ -1 +1,41 @@
-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'
+    | 'documentationRootDir'
+  >,
+  '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/InterfaceMirrorBuilder.ts

@@ -20,11 +20,6 @@ export class InterfaceMirrorBuilder {
     return this;
   }
 
-  withDocComment(docComment: DocComment): InterfaceMirrorBuilder {
-    this.docComment = docComment;
-    return this;
-  }
-
   addMethod(method: MethodMirror): InterfaceMirrorBuilder {
     this.methods.push(method);
     return this;

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/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

@@ -5,7 +5,7 @@ import logUpdate from 'log-update';
  * Logs messages to the console.
  */
 export class Logger {
-  static currentFrame = -1;
+  static currentFrame = 0;
 
   static frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
@@ -26,14 +26,14 @@ export class Logger {
    * @param message The error message to log.
    * @param args Optional arguments.
    */
-  public static error(message: string, ...args: string[]) {
+  public static error(message: unknown, ...args: string[]) {
     this.logSingle(message, false, 'red', false);
     args.forEach(() => {
       this.logSingle(message, false, 'red', false);
     });
   }
 
-  public static logSingle(text: string, showSpinner = true, color: 'green' | 'red' = 'green', overrideConsole = true) {
+  public static logSingle(text: unknown, showSpinner = true, color: 'green' | 'red' = 'green', overrideConsole = true) {
     if (this.currentFrame > 9) {
       this.currentFrame = 0;
     }

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,16 +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: {},
-};

package/apexdocs.config.ts

@@ -1,13 +0,0 @@
-import { TargetFile, TargetType } from './src/settings';
-
-export default {
-  onBeforeFileWrite: (file: TargetFile): TargetFile => {
-    console.log('onBefore writing', file);
-    return file;
-  },
-  onAfterProcess: (files: TargetFile[]) => {
-    console.log('onAfterProcess files', files);
-  },
-  frontMatterHeader: (file: TargetType) => [`title: ${file.name}.cls`, `description: ${file.description}`],
-  sortMembersAlphabetically: true,
-};

package/docs/__old/README.md

@@ -1 +0,0 @@
-Go to [docs](/types/README.md) for more information.

package/docs/__old/index.html

@@ -1,22 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Document</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="description" content="Description">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
-  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: '',
-      repo: ''
-    }
-  </script>
-  <!-- Docsify v4 -->
-  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
-</body>
-</html>