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

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,3 +1,41 @@
-import * as reflection from '@cparra/apex-reflection';
+import { SetOptional } from 'type-fest';
+import type {
+  ConfigurableHooks,
+  Skip,
+  UserDefinedMarkdownConfig,
+  ReferenceGuidePageData,
+  DocPageData,
+  DocPageReference,
+} from './core/shared/types';
+import { defaults } from './defaults';
 
-export { reflection };
+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,13 +3,17 @@
     "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", "jest.d.ts"

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>