@cparra/apexdocs 3.0.0 → 3.1.0

package/src/core/markdown/templates/grouped-members-partial-template.ts

@@ -1,6 +0,0 @@
-export const groupedMembersPartialTemplate = `
-{{ heading headingLevel heading }}
-{{#each value}}
-{{> (lookup .. "subTemplate") this}}
-{{/each}}
-`.trim();

package/src/core/markdown/templates/hookable.ts

@@ -1,7 +0,0 @@
-export const hookableTemplate = `
-{{#if frontmatter}}
-{{{frontmatter}}}
-{{/if}}
-
-{{{content}}}
-`.trim();

package/src/core/markdown/templates/interface-template.ts

@@ -1,16 +0,0 @@
-export const interfaceMarkdownTemplate = `
-{{ heading headingLevel heading }}
-
-{{> typeDocumentation }}
-
-{{#if extends}}
-**Extends**
-{{#each extends}}
-{{link this}}{{#unless @last}}, {{/unless}}
-{{/each}}
-{{/if}}
-
-{{#if methods}}
-{{> methodsPartialTemplate methods}}
-{{/if}}
-`.trim();

package/src/core/markdown/templates/methods-partial-template.ts

@@ -1,43 +0,0 @@
-export const methodsPartialTemplate = `
-{{ heading headingLevel heading }}
-{{#each value}}
-{{{ heading headingLevel (inlineCode heading) }}}
-
-{{#if inherited}}
-*Inherited*
-{{/if}}
-
-{{#> documentablePartialTemplate}}
-
-{{ heading signature.headingLevel signature.heading }}
-{{ code signature.value }}
-
-{{#if parameters.value}}
-{{ heading parameters.headingLevel parameters.heading }}
-| Name | Type | Description |
-|------|------|-------------|
-{{#each parameters.value}}
-| {{name}} | {{link type}} | {{{renderContent description}}} |
-{{/each}}
-{{/if}}
-
-{{ heading returnType.headingLevel returnType.heading }}
-**{{link returnType.value.type}}**
-
-{{#if returnType.value.description}}
-{{returnType.value.description}}
-{{/if}}
-
-{{#if throws.value}}
-{{ heading throws.headingLevel throws.heading }}
-{{#each throws.value}}
-{{link this.type}}: {{this.description}}
-
-{{/each}}
-{{/if}}
-{{/documentablePartialTemplate}}
-
-{{#unless @last}}---{{/unless}}
-
-{{/each}}
-`.trim();

package/src/core/markdown/templates/reference-guide.ts

@@ -1,14 +0,0 @@
-export const referenceGuideTemplate = `
-# {{referenceGuideTitle}}
-
-{{#each references}}
-## {{@key}}
-
-{{#each this}}
-### {{link title}}
-
-{{{renderContent description}}}
-
-{{/each}}
-{{/each}}
-`.trim();

package/src/core/markdown/templates/template.ts

@@ -1,114 +0,0 @@
-import Handlebars from 'handlebars';
-import { CodeBlock, RenderableContent, StringOrLink } from '../adapters/types';
-import { isCodeBlock, isEmptyLine, isInlineCode } from '../adapters/type-utils';
-import { typeDocPartial } from './type-doc-partial';
-import { documentablePartialTemplate } from './documentable-partial-template';
-import { methodsPartialTemplate } from './methods-partial-template';
-import { groupedMembersPartialTemplate } from './grouped-members-partial-template';
-import { constructorsPartialTemplate } from './constructors-partial-template';
-import { fieldsPartialTemplate } from './fieldsPartialTemplate';
-import { classMarkdownTemplate } from './class-template';
-import { enumMarkdownTemplate } from './enum-template';
-import { interfaceMarkdownTemplate } from './interface-template';
-
-export type CompilationRequest = {
-  template: string;
-  source: unknown;
-};
-
-export class Template {
-  private static instance: Template;
-
-  private constructor() {
-    Handlebars.registerPartial('typeDocumentation', typeDocPartial);
-    Handlebars.registerPartial('documentablePartialTemplate', documentablePartialTemplate);
-    Handlebars.registerPartial('methodsPartialTemplate', methodsPartialTemplate);
-    Handlebars.registerPartial('constructorsPartialTemplate', constructorsPartialTemplate);
-    Handlebars.registerPartial('groupedMembersPartialTemplate', groupedMembersPartialTemplate);
-    Handlebars.registerPartial('fieldsPartialTemplate', fieldsPartialTemplate);
-    Handlebars.registerPartial('classTemplate', classMarkdownTemplate);
-    Handlebars.registerPartial('enumTemplate', enumMarkdownTemplate);
-    Handlebars.registerPartial('interfaceTemplate', interfaceMarkdownTemplate);
-
-    Handlebars.registerHelper('link', link);
-    Handlebars.registerHelper('code', convertCodeBlock);
-    Handlebars.registerHelper('renderContent', resolveRenderableContent);
-    Handlebars.registerHelper('heading', heading);
-    Handlebars.registerHelper('inlineCode', inlineCode);
-    Handlebars.registerHelper('splitAndCapitalize', splitAndCapitalize);
-  }
-
-  public static getInstance(): Template {
-    if (!Template.instance) {
-      Template.instance = new Template();
-    }
-    return Template.instance;
-  }
-
-  compile(request: CompilationRequest): string {
-    const compiled = Handlebars.compile(request.template);
-    return (
-      compiled(request.source)
-        .trim()
-        // clean up extra newlines
-        .replace(/\n{3,}/g, '\n\n')
-    );
-  }
-}
-
-const splitAndCapitalize = (text: string) => {
-  const words = text.split(/[-_]+/);
-  const capitalizedWords = [];
-  for (const word of words) {
-    capitalizedWords.push(word.charAt(0).toUpperCase() + word.slice(1));
-  }
-  return capitalizedWords.join(' ');
-};
-
-const heading = (level: number, text: string) => {
-  return `${'#'.repeat(level)} ${text}`;
-};
-
-const inlineCode = (text: string) => {
-  return new Handlebars.SafeString(`\`${text}\``);
-};
-
-const convertCodeBlock = (codeBlock: CodeBlock): Handlebars.SafeString => {
-  return new Handlebars.SafeString(
-    `
-\`\`\`${codeBlock.language}
-${codeBlock.content.join('\n')}
-\`\`\`
-  `.trim(),
-  );
-};
-
-const resolveRenderableContent = (description?: RenderableContent[]): string => {
-  if (!description) {
-    return '';
-  }
-
-  function reduceDescription(acc: string, curr: RenderableContent) {
-    if (isEmptyLine(curr)) {
-      return acc + '\n';
-    }
-    if (isCodeBlock(curr)) {
-      return acc + convertCodeBlock(curr) + '\n';
-    }
-    if (isInlineCode(curr)) {
-      return acc + inlineCode(curr.content).toString() + ' ';
-    } else {
-      return acc + Handlebars.escapeExpression(link(curr)).trim() + ' ';
-    }
-  }
-
-  return description.reduce(reduceDescription, '').trim();
-};
-
-const link = (source: StringOrLink): string => {
-  if (typeof source === 'string') {
-    return source;
-  } else {
-    return `[${source.title}](${source.url})`;
-  }
-};

package/src/core/markdown/templates/type-doc-partial.ts

@@ -1,27 +0,0 @@
-export const typeDocPartial = `
-{{#> documentablePartialTemplate}}
-
-{{#if doc.group}}
-**Group** {{doc.group}}
-{{/if}}
-
-{{#if doc.author}}
-**Author** {{doc.author}}
-{{/if}}
-
-{{#if doc.date}}
-**Date** {{doc.date}}
-{{/if}}
-
-{{#each doc.sees}}
-**See** {{link this}}
-
-{{/each}}
-
-{{#if namespace}}
-## Namespace
-{{namespace}}
-{{/if}}
-
-{{/documentablePartialTemplate}}
-`.trim();

package/src/core/markdown/utils.ts

@@ -1,3 +0,0 @@
-import { ParsedFile } from '../shared/types';
-
-export const parsedFilesToTypes = (parsedFiles: ParsedFile[]) => parsedFiles.map((parsedFile) => parsedFile.type);

package/src/core/openApiSettings.ts

@@ -1,41 +0,0 @@
-export interface SettingsConfig {
-  sourceDirectory: string;
-  outputDir: string;
-  openApiFileName: string;
-  namespace?: string;
-  openApiTitle?: string;
-  version: string;
-}
-
-export class OpenApiSettings {
-  private static instance: OpenApiSettings;
-
-  private constructor(public config: SettingsConfig) {}
-
-  public static build(config: SettingsConfig) {
-    OpenApiSettings.instance = new OpenApiSettings(config);
-  }
-
-  public static getInstance(): OpenApiSettings {
-    if (!OpenApiSettings.instance) {
-      throw new Error('Settings has not been initialized');
-    }
-    return OpenApiSettings.instance;
-  }
-
-  public getOpenApiTitle(): string | undefined {
-    return this.config.openApiTitle;
-  }
-
-  public getNamespace(): string | undefined {
-    return this.config.namespace;
-  }
-
-  public openApiFileName(): string {
-    return this.config.openApiFileName;
-  }
-
-  public getVersion(): string {
-    return this.config.version;
-  }
-}

package/src/core/openapi/__tests__/manifest-factory.spec.ts

@@ -1,16 +0,0 @@
-import { createManifest } from '../manifest-factory';
-import { Type } from '@cparra/apex-reflection';
-import { TypeParser } from '../parser';
-
-class TestParser implements TypeParser {
-  parse(): Type[] {
-    return [];
-  }
-}
-
-it('creates a manifest from the result of a type parser', () => {
-  const manifest = createManifest(new TestParser(), () => {
-    return {};
-  });
-  expect(manifest.types.length).toBe(0);
-});

package/src/core/openapi/__tests__/open-api-docs-processor.spec.ts

@@ -1,59 +0,0 @@
-import { OpenApiDocsProcessor } from '../open-api-docs-processor';
-import { OpenApiSettings } from '../../openApiSettings';
-import { SettingsBuilder } from '../../../test-helpers/SettingsBuilder';
-import { DocCommentBuilder } from '../../../test-helpers/DocCommentBuilder';
-import { AnnotationBuilder } from '../../../test-helpers/AnnotationBuilder';
-import { ClassMirrorBuilder } from '../../../test-helpers/ClassMirrorBuilder';
-import { NoLogger } from '../../../util/logger';
-
-const noLogger = new NoLogger();
-
-beforeEach(() => {
-  OpenApiSettings.build(new SettingsBuilder().build());
-});
-
-it('should add a path based on the @UrlResource annotation on the class', function () {
-  const annotationElementValue = {
-    key: 'urlMapping',
-    value: "'/Account/*'",
-  };
-  const classMirror = new ClassMirrorBuilder()
-    .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
-    .build();
-
-  const processor = new OpenApiDocsProcessor(noLogger);
-  processor.onProcess(classMirror);
-
-  expect(processor.openApiModel.paths).toHaveProperty('Account/');
-});
-
-it('should respect slashes', function () {
-  const annotationElementValue = {
-    key: 'urlMapping',
-    value: "'v1/Account/*'",
-  };
-  const classMirror = new ClassMirrorBuilder()
-    .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
-    .build();
-
-  const processor = new OpenApiDocsProcessor(noLogger);
-  processor.onProcess(classMirror);
-
-  expect(processor.openApiModel.paths).toHaveProperty('v1/Account/');
-});
-
-it('should contain a path with a description when the class has an ApexDoc comment', function () {
-  const annotationElementValue = {
-    key: 'urlMapping',
-    value: "'/Account/*'",
-  };
-  const classMirror = new ClassMirrorBuilder()
-    .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
-    .withDocComment(new DocCommentBuilder().withDescription('My Description').build())
-    .build();
-
-  const processor = new OpenApiDocsProcessor(noLogger);
-  processor.onProcess(classMirror);
-
-  expect(processor.openApiModel.paths['Account/'].description).toBe('My Description');
-});

package/src/core/openapi/__tests__/open-api.spec.ts

@@ -1,22 +0,0 @@
-import { OpenApi } from '../open-api';
-
-it('should get created with a title and a version', function () {
-  const openApi = new OpenApi('Test Spec', '1.0.0');
-
-  expect(openApi.info.title).toBe('Test Spec');
-  expect(openApi.info.version).toBe('1.0.0');
-});
-
-it('should contain a single server, which points to the correct server URL', function () {
-  const openApi = new OpenApi('Test Spec', '1.0.0');
-
-  expect(openApi.servers.length).toBe(1);
-  expect(openApi.servers[0].url).toBe('/services/apexrest/');
-});
-
-it('should optionally allow for a namespace to be passed in as part of the server', function () {
-  const openApi = new OpenApi('Test Spec', '1.0.0', 'Namespace');
-
-  expect(openApi.servers.length).toBe(1);
-  expect(openApi.servers[0].url).toBe('/services/apexrest/Namespace/');
-});

package/src/core/openapi/apex-doc-types.ts

@@ -1,26 +0,0 @@
-// These are types that represent how the data is expected to be created in the ApexDoc (as YAML), which
-// in some cases might be different from the official OpenApi spec for simplicity when writing the ApexDoc.
-
-import { SchemaObjectArray, SchemaObjectObject } from './open-api-types';
-
-export type ApexDocHttpResponse = {
-  statusCode: number;
-  description?: string;
-  schema: ApexDocSchemaObject;
-};
-
-export type ApexDocHttpRequestBody = {
-  description?: string;
-  schema: ApexDocSchemaObject;
-  required?: boolean;
-};
-
-export type ApexDocParameterObject = {
-  name: string;
-  in: 'query' | 'header' | 'path' | 'cookie';
-  description?: string;
-  required?: boolean;
-  schema: ApexDocSchemaObject;
-};
-
-export type ApexDocSchemaObject = SchemaObjectObject | SchemaObjectArray | string;

package/src/core/openapi/apex-type-wrappers/ClassMirrorWrapper.ts

@@ -1,12 +0,0 @@
-import { ClassMirror, MethodMirror } from '@cparra/apex-reflection';
-
-export class ClassMirrorWrapper {
-  constructor(public classMirror: ClassMirror) {}
-
-  getMethodsByAnnotation(annotation: string): MethodMirror[] {
-    return this.classMirror.methods.filter((method) => this.hasAnnotation(method, annotation));
-  }
-
-  private hasAnnotation = (method: MethodMirror, annotationName: string) =>
-    method.annotations.some((annotation) => annotation.name.toLowerCase() === annotationName);
-}

package/src/core/openapi/apex-type-wrappers/MethodMirrorWrapper.ts

@@ -1,11 +0,0 @@
-import { DocCommentAnnotation, MethodMirror } from '@cparra/apex-reflection';
-
-export class MethodMirrorWrapper {
-  constructor(public methodMirror: MethodMirror) {}
-
-  public hasDocCommentAnnotation = (annotationName: string) =>
-    this.methodMirror.docComment?.annotations.some((annotation) => annotation.name.toLowerCase() === annotationName);
-
-  public getDocCommentAnnotation = (annotationName: string): DocCommentAnnotation | undefined =>
-    this.methodMirror.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === annotationName);
-}

package/src/core/openapi/apex-type-wrappers/__tests__/ClassMirrorWrapper.spec.ts

@@ -1,15 +0,0 @@
-import { ClassMirrorWrapper } from '../ClassMirrorWrapper';
-import { ClassMirrorBuilder } from '../../../../test-helpers/ClassMirrorBuilder';
-import { MethodMirrorBuilder } from '../../../../test-helpers/MethodMirrorBuilder';
-import { AnnotationBuilder } from '../../../../test-helpers/AnnotationBuilder';
-
-it('should return methods by annotation when they exist', function () {
-  const classMirror = new ClassMirrorBuilder()
-    .addMethod(new MethodMirrorBuilder().addAnnotation(new AnnotationBuilder().withName('httpget').build()).build())
-    .build();
-
-  const classMirrorWrapper = new ClassMirrorWrapper(classMirror);
-  const foundMethods = classMirrorWrapper.getMethodsByAnnotation('httpget');
-
-  expect(foundMethods.length).toBe(1);
-});

package/src/core/openapi/file-container.ts

@@ -1,13 +0,0 @@
-import { PageData } from '../shared/types';
-
-export class FileContainer {
-  _files: PageData[] = [];
-
-  files(): PageData[] {
-    return this._files;
-  }
-
-  pushFile(file: PageData): void {
-    this._files.push(file);
-  }
-}

package/src/core/openapi/manifest-factory.ts

@@ -1,16 +0,0 @@
-import Manifest from '../manifest';
-import { TypeParser } from './parser';
-import { ReflectionResult } from '@cparra/apex-reflection';
-import { UnparsedSourceFile } from '../shared/types';
-
-/**
- * Builds a new Manifest object, sourcing its types from the received TypeParser.
- * @param typeParser In charge of returning the list of reflected types.
- * @param reflect Reflection function.
- */
-export function createManifest(
-  typeParser: TypeParser,
-  reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult,
-): Manifest {
-  return new Manifest(typeParser.parse(reflect));
-}

package/src/core/openapi/open-api-docs-processor.ts

@@ -1,93 +0,0 @@
-import { FileContainer } from './file-container';
-import { ClassMirror, Type } from '@cparra/apex-reflection';
-import { Logger } from '#utils/logger';
-import { OpenApi } from './open-api';
-import { OpenApiSettings } from '../openApiSettings';
-import { MethodParser } from './parsers/MethodParser';
-import { camel2title } from '#utils/string-utils';
-import { createOpenApiFile } from './openapi-type-file';
-
-export class OpenApiDocsProcessor {
-  protected readonly _fileContainer: FileContainer;
-  openApiModel: OpenApi;
-
-  constructor(private logger: Logger) {
-    this._fileContainer = new FileContainer();
-    const title = OpenApiSettings.getInstance().getOpenApiTitle();
-    if (!title) {
-      throw Error('No OpenApi title was provided.');
-    }
-    this.openApiModel = new OpenApi(
-      title,
-      OpenApiSettings.getInstance().getVersion(),
-      OpenApiSettings.getInstance().getNamespace(),
-    );
-  }
-
-  fileBuilder(): FileContainer {
-    return this._fileContainer;
-  }
-
-  onProcess(type: Type): void {
-    this.logger.logSingle(`Processing ${type.name}`, 'green');
-
-    const endpointPath = this.getEndpointPath(type);
-    if (!endpointPath) {
-      return;
-    }
-
-    this.openApiModel.paths[endpointPath] = {};
-    if (type.docComment?.description) {
-      this.openApiModel.paths[endpointPath].description = type.docComment.description;
-    }
-
-    // We can safely cast to a ClassMirror, since only these support the @RestResource annotation
-    const typeAsClass = type as ClassMirror;
-
-    // Add tags for this Apex class to the OpenApi model
-    const tagName = camel2title(endpointPath);
-    this.openApiModel.tags.push({
-      name: tagName,
-      description: type.docComment?.description,
-    });
-
-    const parser = new MethodParser(this.openApiModel);
-
-    // GET
-    parser.parseMethod(typeAsClass, endpointPath, 'get', tagName);
-
-    // PATCH
-    parser.parseMethod(typeAsClass, endpointPath, 'patch', tagName);
-
-    // POST
-    parser.parseMethod(typeAsClass, endpointPath, 'post', tagName);
-
-    // PUT
-    parser.parseMethod(typeAsClass, endpointPath, 'put', tagName);
-
-    // DELETE
-    parser.parseMethod(typeAsClass, endpointPath, 'delete', tagName);
-  }
-
-  onAfterProcess: ((types: Type[]) => void) | undefined = () => {
-    const page = createOpenApiFile(OpenApiSettings.getInstance().openApiFileName(), this.openApiModel);
-    this._fileContainer.pushFile(page);
-  };
-
-  private getEndpointPath(type: Type): string | null {
-    const restResourceAnnotation = type.annotations.find((element) => element.name.toLowerCase() === 'restresource');
-    const urlMapping = restResourceAnnotation?.elementValues?.find(
-      (element) => element.key.toLowerCase() === 'urlmapping',
-    );
-    if (!urlMapping) {
-      this.logger.error(`Type does not contain urlMapping annotation ${type.name}`);
-      return null;
-    }
-
-    let endpointPath = urlMapping.value.replaceAll('"', '').replaceAll("'", '').replaceAll('/*', '/');
-    if (endpointPath.startsWith('/')) {
-      endpointPath = endpointPath.substring(1);
-    }
-    return endpointPath;
-  }
-}