@cparra/apexdocs 3.0.0-rc.0 → 3.1.0

package/src/core/markdown/reflection/reflect-source.ts

@@ -1,123 +0,0 @@
-import { ParsedFile, UnparsedSourceFile } from '../../shared/types';
-import * as TE from 'fp-ts/TaskEither';
-import * as E from 'fp-ts/Either';
-import * as T from 'fp-ts/Task';
-import * as A from 'fp-ts/lib/Array';
-import { Annotation, reflect as mirrorReflection, Type } from '@cparra/apex-reflection';
-import { pipe } from 'fp-ts/function';
-import * as O from 'fp-ts/Option';
-import { parseApexMetadata } from '../../parse-apex-metadata';
-import { ParsingError } from '@cparra/apex-reflection';
-import { apply } from '#utils/fp';
-import { Semigroup } from 'fp-ts/Semigroup';
-
-export class ReflectionErrors {
-  readonly _tag = 'ReflectionErrors';
-
-  constructor(public errors: ReflectionError[]) {}
-}
-
-export class ReflectionError {
-  constructor(
-    public file: string,
-    public message: string,
-  ) {}
-}
-
-async function reflectAsync(rawSource: string): Promise<Type> {
-  return new Promise((resolve, reject) => {
-    const result = mirrorReflection(rawSource);
-    if (result.typeMirror) {
-      return resolve(result.typeMirror);
-    } else if (result.error) {
-      return reject(result.error);
-    } else {
-      return reject(new Error('Unknown error'));
-    }
-  });
-}
-
-export function reflectBundles(apexBundles: UnparsedSourceFile[]) {
-  const semiGroupReflectionError: Semigroup<ReflectionErrors> = {
-    concat: (x, y) => new ReflectionErrors([...x.errors, ...y.errors]),
-  };
-  const Ap = TE.getApplicativeTaskValidation(T.ApplyPar, semiGroupReflectionError);
-
-  return pipe(apexBundles, A.traverse(Ap)(reflectBundle));
-}
-
-function reflectBundle(apexBundle: UnparsedSourceFile): TE.TaskEither<ReflectionErrors, ParsedFile> {
-  const convertToParsedFile: (typeMirror: Type) => ParsedFile = apply(toParsedFile, apexBundle.filePath);
-  const withMetadata = apply(addMetadata, apexBundle.metadataContent);
-
-  return pipe(apexBundle, reflectAsTask, TE.map(convertToParsedFile), TE.flatMap(withMetadata));
-}
-
-function reflectAsTask(apexBundle: UnparsedSourceFile): TE.TaskEither<ReflectionErrors, Type> {
-  return TE.tryCatch(
-    () => reflectAsync(apexBundle.content),
-    (error) =>
-      new ReflectionErrors([new ReflectionError(apexBundle.filePath, (error as ParsingError | Error).message)]),
-  );
-}
-
-function toParsedFile(filePath: string, typeMirror: Type): ParsedFile {
-  return {
-    source: {
-      filePath: filePath,
-      name: typeMirror.name,
-      type: typeMirror.type_name,
-    },
-    type: typeMirror,
-  };
-}
-
-function addMetadata(
-  rawMetadataContent: string | null,
-  parsedFile: ParsedFile,
-): TE.TaskEither<ReflectionErrors, ParsedFile> {
-  return TE.fromEither(
-    pipe(
-      parsedFile.type,
-      (type) => addFileMetadataToTypeAnnotation(type, rawMetadataContent),
-      E.map((type) => ({ ...parsedFile, type })),
-      E.mapLeft((error) => errorToReflectionErrors(error, parsedFile.source.filePath)),
-    ),
-  );
-}
-
-function errorToReflectionErrors(error: Error, filePath: string): ReflectionErrors {
-  return new ReflectionErrors([new ReflectionError(filePath, error.message)]);
-}
-
-function addFileMetadataToTypeAnnotation(type: Type, metadata: string | null): E.Either<Error, Type> {
-  const concatAnnotationToType = apply(concatAnnotations, type);
-
-  return pipe(
-    O.fromNullable(metadata),
-    O.map(concatAnnotationToType),
-    O.getOrElse(() => E.right(type)),
-  );
-}
-
-function concatAnnotations(type: Type, metadataInput: string): E.Either<Error, Type> {
-  return pipe(
-    metadataInput,
-    parseApexMetadata,
-    E.map((metadataMap) => ({
-      ...type,
-      annotations: [...type.annotations, ...mapToAnnotations(metadataMap)],
-    })),
-  );
-}
-
-function mapToAnnotations(metadata: Map<string, string>): Annotation[] {
-  return Array.from(metadata.entries()).map(([key, value]) => {
-    const declaration = `${key}: ${value}`;
-    return {
-      name: declaration,
-      type: declaration,
-      rawDeclaration: declaration,
-    };
-  });
-}

package/src/core/markdown/reflection/sort-members.ts

@@ -1,59 +0,0 @@
-import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
-import { ParsedFile } from '../../shared/types';
-
-type Named = { name: string };
-
-export function sortMembers(shouldSortMembers: boolean, parsedFiles: ParsedFile[]): ParsedFile[] {
-  return parsedFiles.map((parsedFile) => ({
-    ...parsedFile,
-    type: sortTypeMember(parsedFile.type, shouldSortMembers),
-  }));
-}
-
-function sortByNames<T extends Named>(shouldSort: boolean, a: T, b: T): number {
-  if (shouldSort) {
-    return a.name.localeCompare(b.name);
-  }
-  return 0;
-}
-
-function sortNamed<T extends Named>(shouldSort: boolean, items: T[]): T[] {
-  return items.sort((a, b) => sortByNames(shouldSort, a, b));
-}
-
-function sortTypeMember(type: Type, shouldSort: boolean): Type {
-  switch (type.type_name) {
-    case 'enum':
-      return sortEnumValues(shouldSort, type as EnumMirror);
-    case 'interface':
-      return sortInterfaceMethods(shouldSort, type as InterfaceMirror);
-    case 'class':
-      return sortClassMembers(shouldSort, type as ClassMirror);
-  }
-}
-
-function sortEnumValues(shouldSort: boolean, enumType: EnumMirror): EnumMirror {
-  return {
-    ...enumType,
-    values: sortNamed(shouldSort, enumType.values),
-  };
-}
-
-function sortInterfaceMethods(shouldSort: boolean, interfaceType: InterfaceMirror): InterfaceMirror {
-  return {
-    ...interfaceType,
-    methods: sortNamed(shouldSort, interfaceType.methods),
-  };
-}
-
-function sortClassMembers(shouldSort: boolean, classType: ClassMirror): ClassMirror {
-  return {
-    ...classType,
-    fields: sortNamed(shouldSort, classType.fields),
-    classes: sortNamed(shouldSort, classType.classes),
-    enums: sortNamed(shouldSort, classType.enums),
-    interfaces: sortNamed(shouldSort, classType.interfaces),
-    methods: sortNamed(shouldSort, classType.methods),
-    properties: sortNamed(shouldSort, classType.properties),
-  };
-}

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

@@ -1,75 +0,0 @@
-export const classMarkdownTemplate = `
-{{ heading headingLevel heading }}
-{{#if classModifier}}
-\`{{classModifier}}\`
-{{/if}}
-
-{{> typeDocumentation}}
-
-{{#if extends.length}}
-**Inheritance**
-
-{{#each extends}}{{link this}}{{#unless @last}} < {{/unless}}{{/each}}
-{{/if}}
-
-{{#if implements}}
-**Implements**
-
-{{#each implements}}
-{{link this}}{{#unless @last}}, {{/unless}}
-{{/each}}
-{{/if}}
-
-{{#if fields.value}}
-{{#if fields.isGrouped}}
-{{> groupedMembersPartialTemplate fields subTemplate="fieldsPartialTemplate"}}
-{{else}}
-{{> fieldsPartialTemplate fields}}
-{{/if}}
-{{/if}}
-
-{{#if properties.value}}
-{{#if properties.isGrouped}}
-{{> groupedMembersPartialTemplate properties subTemplate="fieldsPartialTemplate"}}
-{{else}}
-{{> fieldsPartialTemplate properties}}
-{{/if}}
-{{/if}}
-
-{{#if constructors.value}}
-{{#if constructors.isGrouped}}
-{{> groupedMembersPartialTemplate constructors subTemplate="constructorsPartialTemplate"}}
-{{else}}
-{{> constructorsPartialTemplate constructors}}
-{{/if}}
-{{/if}}
-
-{{#if methods.value}}
-{{#if methods.isGrouped}}
-{{> groupedMembersPartialTemplate methods subTemplate="methodsPartialTemplate"}}
-{{else}}
-{{> methodsPartialTemplate methods}}
-{{/if}}
-{{/if}}
-
-{{#if innerClasses.value}}
-{{ heading innerClasses.headingLevel innerClasses.heading }}
-{{#each innerClasses.value}}
-{{> classTemplate this}}
-{{/each}}
-{{/if}}
-
-{{#if innerEnums.value}}
-{{ heading innerEnums.headingLevel innerEnums.heading }}
-{{#each innerEnums.value}}
-{{> enumTemplate this}}
-{{/each}}
-{{/if}}
-
-{{#if innerInterfaces.value}}
-{{ heading innerInterfaces.headingLevel innerInterfaces.heading }}
-{{#each innerInterfaces.value}}
-{{> interfaceTemplate this}}
-{{/each}}
-{{/if}}
-`.trim();

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

@@ -1,32 +0,0 @@
-export const constructorsPartialTemplate = `
-{{ heading headingLevel heading }}
-{{#each value}}
-{{{ heading headingLevel (inlineCode heading) }}}
-
-{{#> 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}} | {{description}} |
-{{/each}}
-{{/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/documentable-partial-template.ts

@@ -1,26 +0,0 @@
-export const documentablePartialTemplate = `
-{{#each doc.annotations}}
-\`{{this}}\`
-{{/each}}
-
-{{{renderContent doc.description}}}
-
-{{#each doc.customTags}}
-**{{splitAndCapitalize name}}** 
-
-{{{renderContent description}}}
-
-{{/each}}
-
-{{> @partial-block}}
-
-{{#if doc.mermaid.value}}
-{{ heading doc.mermaid.headingLevel doc.mermaid.heading }}
-{{code doc.mermaid.value}}
-{{/if}}
-
-{{#if doc.example.value}}
-{{ heading doc.example.headingLevel doc.example.heading }}
-{{{renderContent doc.example.value}}}
-{{/if}}
-`.trim();

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

@@ -1,12 +0,0 @@
-export const enumMarkdownTemplate = `
-{{ heading headingLevel heading }}
-
-{{> typeDocumentation }}
-
-{{ heading values.headingLevel values.heading }}
-| Value | Description |
-|-------|-------------|
-{{#each values.value}}
-| {{value}} | {{description}} |
-{{/each}}
-`.trim();

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

@@ -1,23 +0,0 @@
-export const fieldsPartialTemplate = `
-{{ heading headingLevel heading }}
-{{#each value}}
-{{{ heading headingLevel (inlineCode heading) }}}
-
-{{#if inherited}}
-*Inherited*
-{{/if}}
-
-{{#> documentablePartialTemplate }}
-
-{{ heading signature.headingLevel signature.heading }}
-{{ code signature.value }}
-
-{{ heading type.headingLevel type.heading }}
-{{link type.value}}
-
-{{/documentablePartialTemplate}}
-
-{{#unless @last}}---{{/unless}}
-
-{{/each}}
-`.trim();

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 = `
-# Apex Reference Guide
-
-{{#each this}}
-## {{@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);
-});