@cparra/apexdocs 3.0.0 → 3.1.0

package/src/core/openapi/parsers/__tests__/RequestBodyBuilder.spec.ts

@@ -1,64 +0,0 @@
-import { RequestBodyBuilder } from '../RequestBodyBuilder';
-import { Reference } from '../ReferenceBuilder';
-import { ReferenceObject } from '../../../../core/openapi/open-api-types';
-import { ApexDocHttpRequestBody } from '../../../../core/openapi/apex-doc-types';
-
-jest.mock('../ReferenceBuilder', () => {
-  return {
-    ReferenceBuilder: jest.fn().mockImplementation(() => {
-      return {
-        // eslint-disable-next-line @typescript-eslint/no-empty-function
-        build: (): Reference => {
-          return {
-            referenceComponents: [
-              {
-                referencedClass: 'MySampleClass',
-                schema: {
-                  type: 'string',
-                },
-              },
-            ],
-            entrypointReferenceObject: {
-              $ref: '/mySampleClass',
-            },
-          };
-        },
-      };
-    }),
-  };
-});
-
-it('should build a RequestBody based on the received schema', function () {
-  const apexRequestBody: ApexDocHttpRequestBody = {
-    description: 'Sample Request Body Description',
-    required: true,
-    schema: {
-      type: 'object',
-      properties: {
-        Prop1: {
-          type: 'string',
-          description: 'A Property',
-        },
-      },
-    },
-  };
-
-  const response = new RequestBodyBuilder().build(apexRequestBody);
-
-  expect(response.reference).toBeUndefined();
-  expect(response.body.description).toBe('Sample Request Body Description');
-  expect(response.body.required).toBe(true);
-  expect(response.body.content).toHaveProperty('application/json');
-  expect(response.body.content['application/json'].schema).toBe(apexRequestBody.schema);
-});
-
-it('should build a RequestBody with a reference when receiving a reference class name', function () {
-  const apexRequestBody: ApexDocHttpRequestBody = {
-    schema: 'MyClassName',
-  };
-
-  const response = new RequestBodyBuilder().build(apexRequestBody);
-
-  expect(response.reference).not.toBeUndefined();
-  expect((response.body.content['application/json']?.schema as ReferenceObject).$ref).toBe('/mySampleClass');
-});

package/src/core/openapi/parsers/__tests__/ResponsesBuilder.spec.ts

@@ -1,55 +0,0 @@
-import { ResponsesBuilder } from '../ResponsesBuilder';
-import { Reference } from '../ReferenceBuilder';
-import { ApexDocHttpResponse } from '../../../../core/openapi/apex-doc-types';
-
-jest.mock('../ReferenceBuilder', () => {
-  return {
-    ReferenceBuilder: jest.fn().mockImplementation(() => {
-      return {
-        // eslint-disable-next-line @typescript-eslint/no-empty-function
-        build: (): Reference => {
-          return {
-            referenceComponents: [
-              {
-                referencedClass: 'MySampleClass',
-                schema: {
-                  type: 'string',
-                },
-              },
-            ],
-            entrypointReferenceObject: {
-              $ref: '/mySampleClass',
-            },
-          };
-        },
-      };
-    }),
-  };
-});
-
-it('should build a ResponseObject based on the received schema', function () {
-  const apexDocResponse: ApexDocHttpResponse = {
-    statusCode: 200,
-    schema: {
-      type: 'string',
-    },
-  };
-
-  const response = new ResponsesBuilder().build(apexDocResponse);
-
-  expect(response.reference).toBeUndefined();
-  expect(response.body.description).toContain('200');
-  expect(response.body.content).toHaveProperty('application/json');
-  expect(response.body.content!['application/json'].schema).toBe(apexDocResponse.schema);
-});
-
-it('should build a ResponseObject with a reference', function () {
-  const apexDocResponse: ApexDocHttpResponse = {
-    statusCode: 200,
-    schema: 'SomeClass',
-  };
-
-  const response = new ResponsesBuilder().build(apexDocResponse);
-
-  expect(response.reference).not.toBeUndefined();
-});

package/src/core/openapi/transpiler.ts

@@ -1,17 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-import { OpenApiDocsProcessor } from './open-api-docs-processor';
-
-export default class Transpiler {
-  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;
-    });
-
-    sortedTypes.forEach((currentType) => {
-      processor.onProcess(currentType);
-    });
-    processor.onAfterProcess?.(sortedTypes);
-  }
-}

package/src/core/openapi/types-repository.ts

@@ -1,54 +0,0 @@
-import { ClassMirror, Type } from '@cparra/apex-reflection';
-
-export type TypeBundle = { type: Type; isChild: boolean; parentType?: Type };
-
-export class TypesRepository {
-  private static instance: TypesRepository;
-  private allTypes: Type[] = [];
-
-  public static getInstance(): TypesRepository {
-    if (!TypesRepository.instance) {
-      TypesRepository.instance = new TypesRepository();
-    }
-    return TypesRepository.instance;
-  }
-
-  public populateAll(types: Type[]) {
-    this.allTypes = types;
-  }
-
-  public getFromAllByName(typeName: string): TypeBundle | undefined {
-    if (typeName.includes('.')) {
-      // If it includes a dot we are assuming we are dealing with an inner class.
-      const [parentTypeName, childTypeName] = typeName.split('.');
-      const parentReference = this.allTypes.find(
-        (currentType: Type) => currentType.name.toLowerCase() === parentTypeName.toLowerCase(),
-      );
-      if (!parentReference || parentReference.type_name !== 'class') {
-        // If the parent is not found, no reason to keep searching, instead we return undefined.
-        // Similarly, if the parent is not a class, it means it cannot have children, so we return early.
-        return undefined;
-      }
-
-      const parentReferenceAsClass = parentReference as ClassMirror;
-      const childTypes = [
-        ...parentReferenceAsClass.classes,
-        ...parentReferenceAsClass.interfaces,
-        ...parentReferenceAsClass.enums,
-      ];
-      const foundType = childTypes.find((currentType: Type) => currentType.name.toLowerCase() === childTypeName);
-      if (!foundType) {
-        return undefined;
-      }
-      return { type: foundType, isChild: true, parentType: parentReference };
-    }
-
-    const foundType = this.allTypes.find(
-      (currentType: Type) => currentType.name.toLowerCase() === typeName.toLowerCase(),
-    );
-    if (!foundType) {
-      return undefined;
-    }
-    return { type: foundType, isChild: false };
-  }
-}

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

@@ -1,30 +0,0 @@
-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/shared/types.d.ts

@@ -1,150 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-
-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 = {
-  sourceDir: string;
-  targetGenerator: 'markdown';
-  targetDir: string;
-  scope: string[];
-  namespace?: string;
-  defaultGroupName: string;
-  sortAlphabetically: boolean;
-  includeMetadata: boolean;
-  linkingStrategy: LinkingStrategy;
-  excludeTags: string[];
-  referenceGuideTitle: string;
-} & Partial<ConfigurableHooks>;
-
-export type UserDefinedOpenApiConfig = {
-  targetGenerator: 'openapi';
-  sourceDir: string;
-  targetDir: string;
-  fileName: string;
-  namespace?: string;
-  title: string;
-  apiVersion: string;
-};
-
-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
-
-/**
- * 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 ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
-
-export 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

@@ -1,5 +0,0 @@
-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

@@ -1,21 +0,0 @@
-const commonDefaults = {
-  targetDir: './docs/',
-};
-
-export const markdownDefaults = {
-  ...commonDefaults,
-  scope: ['global'],
-  defaultGroupName: 'Miscellaneous',
-  includeMetadata: false,
-  sortAlphabetically: false,
-  linkingStrategy: 'relative' as const,
-  referenceGuideTitle: 'Apex Reference Guide',
-  excludeTags: [],
-};
-
-export const openApiDefaults = {
-  ...commonDefaults,
-  fileName: 'openapi',
-  title: 'Apex REST API',
-  apiVersion: '1.0.0',
-};

package/src/index.ts

@@ -1,110 +0,0 @@
-import type {
-  ConfigurableHooks,
-  Skip,
-  UserDefinedMarkdownConfig,
-  ReferenceGuidePageData,
-  DocPageData,
-  DocPageReference,
-  ConfigurableDocPageData,
-  TransformReferenceGuide,
-  TransformDocs,
-  TransformDocPage,
-  TransformReference,
-  ConfigurableDocPageReference,
-  UserDefinedOpenApiConfig,
-  UserDefinedConfig,
-} from './core/shared/types';
-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 {
-    ...markdownDefaults,
-    ...config,
-    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',
-  };
-}
-
-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,
-  TransformDocPage,
-  TransformReference,
-  ConfigurableHooks,
-  ReferenceGuidePageData,
-  DocPageData,
-  DocPageReference,
-  Skip,
-  ConfigurableDocPageData,
-  ConfigurableDocPageReference,
-  process,
-};

package/src/test-helpers/AnnotationBuilder.ts

@@ -1,29 +0,0 @@
-import { Annotation, AnnotationElementValue } from '@cparra/apex-reflection';
-
-/**
- * Builder class to create Annotation objects.
- * For testing purposes only.
- */
-export class AnnotationBuilder {
-  private name = 'restresource';
-  private elementValues: AnnotationElementValue[] = [];
-
-  withName(name: string): AnnotationBuilder {
-    this.name = name;
-    return this;
-  }
-
-  addElementValue(elementValue: AnnotationElementValue): AnnotationBuilder {
-    this.elementValues.push(elementValue);
-    return this;
-  }
-
-  build(): Annotation {
-    return {
-      rawDeclaration: '',
-      name: this.name,
-      type: this.name,
-      elementValues: this.elementValues,
-    };
-  }
-}

package/src/test-helpers/ClassMirrorBuilder.ts

@@ -1,69 +0,0 @@
-import { Annotation, ClassMirror, DocComment, FieldMirror, MethodMirror } from '@cparra/apex-reflection';
-
-/**
- * Builder class to create ClassMirror objects.
- * For testing purposes only.
- */
-export class ClassMirrorBuilder {
-  private name = 'SampleClass';
-  private annotations: Annotation[] = [];
-  private docComment?: DocComment;
-  private methods: MethodMirror[] = [];
-  private fields: FieldMirror[] = [];
-  private innerClasses: ClassMirror[] = [];
-  private extendedClass: string | undefined;
-
-  withName(name: string): ClassMirrorBuilder {
-    this.name = name;
-    return this;
-  }
-
-  addAnnotation(annotation: Annotation): ClassMirrorBuilder {
-    this.annotations.push(annotation);
-    return this;
-  }
-
-  withDocComment(docComment: DocComment): ClassMirrorBuilder {
-    this.docComment = docComment;
-    return this;
-  }
-
-  addMethod(method: MethodMirror): ClassMirrorBuilder {
-    this.methods.push(method);
-    return this;
-  }
-
-  addFiled(field: FieldMirror): ClassMirrorBuilder {
-    this.fields.push(field);
-    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,
-      name: this.name,
-      type_name: 'class',
-      methods: this.methods,
-      implemented_interfaces: [],
-      properties: [],
-      fields: this.fields,
-      constructors: [],
-      enums: [],
-      interfaces: [],
-      classes: this.innerClasses,
-      access_modifier: 'public',
-      docComment: this.docComment,
-      extended_class: this.extendedClass,
-    };
-  }
-}

package/src/test-helpers/DocCommentAnnotationBuilder.ts

@@ -1,24 +0,0 @@
-import { DocCommentAnnotation } from '@cparra/apex-reflection';
-
-export class DocCommentAnnotationBuilder {
-  private name = '';
-  private bodyLines: string[] = [];
-
-  withName(name: string): DocCommentAnnotationBuilder {
-    this.name = name;
-    return this;
-  }
-
-  withBodyLines(bodyLines: string[]): DocCommentAnnotationBuilder {
-    this.bodyLines = bodyLines;
-    return this;
-  }
-
-  build(): DocCommentAnnotation {
-    return {
-      name: this.name,
-      body: '',
-      bodyLines: this.bodyLines,
-    };
-  }
-}

package/src/test-helpers/DocCommentBuilder.ts

@@ -1,36 +0,0 @@
-import { DocComment, DocCommentAnnotation } from '@cparra/apex-reflection';
-
-/**
- * Builder class to create DocComment objects.
- * For testing purposes only.
- */
-export class DocCommentBuilder {
-  private description?: string;
-  private annotations: DocCommentAnnotation[] = [];
-
-  addAnnotation(annotation: DocCommentAnnotation): DocCommentBuilder {
-    this.annotations.push(annotation);
-    return this;
-  }
-
-  withDescription(description: string): DocCommentBuilder {
-    this.description = description;
-    return this;
-  }
-
-  build(): DocComment {
-    return {
-      paramAnnotations: [],
-      returnAnnotation: {
-        bodyLines: [],
-      },
-      exampleAnnotation: {
-        bodyLines: [],
-      },
-      throwsAnnotations: [],
-      annotations: this.annotations,
-      descriptionLines: [],
-      description: this.description ?? 'Sample Description',
-    };
-  }
-}