@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

package/src/service/file-system.ts

@@ -1,33 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-
-export interface FileSystem {
-  readDirectory: (sourceDirectory: string) => string[];
-  isDirectory: (path: string) => boolean;
-  readFile: (path: string) => string;
-  joinPath: (...paths: string[]) => string;
-  exists: (path: string) => boolean;
-}
-
-export class DefaultFileSystem implements FileSystem {
-  isDirectory(pathToRead: string): boolean {
-    return fs.statSync(pathToRead).isDirectory();
-  }
-
-  readDirectory(sourceDirectory: string): string[] {
-    return fs.readdirSync(sourceDirectory);
-  }
-
-  readFile(pathToRead: string): string {
-    const rawFile = fs.readFileSync(pathToRead);
-    return rawFile.toString();
-  }
-
-  joinPath(...paths: string[]): string {
-    return path.join(...paths);
-  }
-
-  exists(path: string): boolean {
-    return fs.existsSync(path);
-  }
-}

package/src/service/file-writer.ts

@@ -1,34 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { OutputFile } from '../model/outputFile';
-import { OnBeforeFileWrite, Settings, TargetFile } from '../settings';
-
-export class FileWriter {
-  static write(files: OutputFile[], onWriteCallback: (file: TargetFile) => void) {
-    const onBeforeFileWrite: OnBeforeFileWrite = (file: TargetFile) => Settings.getInstance().onBeforeFileWrite(file);
-    files.forEach((file) => {
-      const resolvedFile = this.getTargetLocation(file, onBeforeFileWrite);
-      const fullDir = path.join(resolvedFile.dir.baseDir, resolvedFile.dir.fileDir);
-      if (!fs.existsSync(fullDir)) {
-        fs.mkdirSync(fullDir, { recursive: true });
-      }
-
-      const filePath = path.join(fullDir, `${resolvedFile.name}${resolvedFile.extension}`);
-      fs.writeFileSync(filePath, file.body, 'utf8');
-      onWriteCallback(resolvedFile);
-    });
-  }
-
-  private static getTargetLocation(file: OutputFile, onBeforeFileWrite: OnBeforeFileWrite): TargetFile {
-    const targetFile: TargetFile = {
-      name: file.fileName,
-      extension: file.fileExtension(),
-      dir: {
-        baseDir: Settings.getInstance().outputDir,
-        fileDir: file.dir,
-      },
-    };
-
-    return onBeforeFileWrite(targetFile);
-  }
-}

package/src/service/metadata-processor.ts

@@ -1,16 +0,0 @@
-import { XMLParser } from 'fast-xml-parser';
-
-export default class MetadataProcessor {
-  public static process(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/service/state.ts

@@ -1,24 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-
-export default class State {
-  private static instance: State;
-  private typeBeingProcessed?: Type;
-
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  private constructor() {}
-
-  public static getInstance(): State {
-    if (!State.instance) {
-      State.instance = new State();
-    }
-    return State.instance;
-  }
-
-  public setTypeBeingProcessed(typeToSet: Type): void {
-    this.typeBeingProcessed = typeToSet;
-  }
-
-  public getTypeBeingProcessed(): Type | undefined {
-    return this.typeBeingProcessed;
-  }
-}

package/src/service/walkers/class-walker.ts

@@ -1,30 +0,0 @@
-import { Walker, WalkerListener } from './walker';
-import { ClassMirror } from '@cparra/apex-reflection';
-
-export class ClassWalker extends Walker {
-  walk(listener: WalkerListener): void {
-    listener.onTypeDeclaration(this.type);
-    const classMirror = this.type as ClassMirror;
-    if (classMirror.constructors.length) {
-      listener.onConstructorDeclaration(this.type.name, classMirror.constructors);
-    }
-    if (classMirror.fields.length) {
-      listener.onFieldsDeclaration(this.sortType(classMirror.fields));
-    }
-    if (classMirror.properties.length) {
-      listener.onPropertiesDeclaration(this.sortType(classMirror.properties));
-    }
-    if (classMirror.methods.length) {
-      listener.onMethodsDeclaration(this.sortType(classMirror.methods));
-    }
-    if (classMirror.enums.length) {
-      listener.onInnerEnumsDeclaration(this.sortType(classMirror.enums));
-    }
-    if (classMirror.classes.length) {
-      listener.onInnerClassesDeclaration(this.sortType(classMirror.classes));
-    }
-    if (classMirror.interfaces.length) {
-      listener.onInnerInterfacesDeclaration(this.sortType(classMirror.interfaces));
-    }
-  }
-}

package/src/service/walkers/enum-walker.ts

@@ -1,7 +0,0 @@
-import { Walker, WalkerListener } from './walker';
-
-export class EnumWalker extends Walker {
-  walk(listener: WalkerListener): void {
-    listener.onTypeDeclaration(this.type);
-  }
-}

package/src/service/walkers/interface-walker.ts

@@ -1,12 +0,0 @@
-import { Walker, WalkerListener } from './walker';
-import { InterfaceMirror } from '@cparra/apex-reflection';
-
-export class InterfaceWalker extends Walker {
-  walk(listener: WalkerListener): void {
-    listener.onTypeDeclaration(this.type);
-    const interfaceMirror = this.type as InterfaceMirror;
-    if (interfaceMirror.methods.length) {
-      listener.onMethodsDeclaration(this.sortType(interfaceMirror.methods));
-    }
-  }
-}

package/src/service/walkers/walker-factory.ts

@@ -1,19 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-import { Walker } from './walker';
-import { ClassWalker } from './class-walker';
-import { EnumWalker } from './enum-walker';
-import { InterfaceWalker } from './interface-walker';
-
-export class WalkerFactory {
-  static get(type: Type): Walker {
-    switch (type.type_name) {
-      case 'class':
-        return new ClassWalker(type);
-      case 'enum':
-        return new EnumWalker(type);
-      case 'interface':
-        return new InterfaceWalker(type);
-    }
-    throw Error('Walker not found for type.');
-  }
-}

package/src/service/walkers/walker.ts

@@ -1,42 +0,0 @@
-import {
-  ClassMirror,
-  ConstructorMirror,
-  EnumMirror,
-  FieldMirror,
-  InterfaceMirror,
-  MethodMirror,
-  PropertyMirror,
-  Type,
-} from '@cparra/apex-reflection';
-import { Settings } from '../../settings';
-
-export interface WalkerListener {
-  onTypeDeclaration(typeMirror: Type): void;
-
-  onConstructorDeclaration(className: string, constructors: ConstructorMirror[]): void;
-
-  onFieldsDeclaration(fields: FieldMirror[]): void;
-
-  onPropertiesDeclaration(properties: PropertyMirror[]): void;
-
-  onMethodsDeclaration(methods: MethodMirror[]): void;
-
-  onInnerEnumsDeclaration(enums: EnumMirror[]): void;
-
-  onInnerClassesDeclaration(classes: ClassMirror[]): void;
-
-  onInnerInterfacesDeclaration(interfaces: InterfaceMirror[]): void;
-}
-
-export abstract class Walker {
-  constructor(public type: Type) {}
-
-  abstract walk(listener: WalkerListener): void;
-
-  protected sortType<T extends { name: string }>(types: T[]): T[] {
-    if (Settings.getInstance().sortMembersAlphabetically()) {
-      return types.sort((a, b) => a.name.localeCompare(b.name));
-    }
-    return types;
-  }
-}

package/src/settings.ts

@@ -1,147 +0,0 @@
-import { GeneratorChoices } from './transpiler/generator-choices';
-
-export type OnBeforeFileWrite = (file: TargetFile) => TargetFile;
-
-export type TargetFile = {
-  name: string;
-  extension: string;
-  dir: OutputDir;
-};
-
-export type OutputDir = {
-  baseDir: string;
-  fileDir: string;
-};
-
-export type TargetType = {
-  name: string;
-  typeName: 'class' | 'interface' | 'enum';
-  accessModifier: string;
-  description?: string;
-  group?: string;
-};
-
-export interface SettingsConfig {
-  sourceDirectory: string;
-  recursive: boolean;
-  scope: string[];
-  outputDir: string;
-  targetGenerator: GeneratorChoices;
-  indexOnly: boolean;
-  defaultGroupName: string;
-  sanitizeHtml: boolean;
-  openApiTitle?: string;
-  title: string;
-  namespace?: string;
-  openApiFileName: string;
-  includeMetadata: boolean;
-  rootDir?: string;
-  sortMembersAlphabetically?: boolean;
-  onAfterProcess?: (files: TargetFile[]) => void;
-  onBeforeFileWrite?: (file: TargetFile) => TargetFile;
-  frontMatterHeader?: (file: TargetType) => string[];
-}
-
-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 sourceDirectory(): string {
-    return this.config.sourceDirectory;
-  }
-
-  get recursive(): boolean {
-    return this.config.recursive;
-  }
-
-  get scope(): string[] {
-    return this.config.scope;
-  }
-
-  get outputDir(): string {
-    return this.config.outputDir;
-  }
-
-  get targetGenerator(): GeneratorChoices {
-    return this.config.targetGenerator;
-  }
-
-  get indexOnly(): boolean {
-    return this.config.indexOnly;
-  }
-
-  get sanitizeHtml(): boolean {
-    return this.config.sanitizeHtml;
-  }
-
-  public getDefaultGroupName(): string {
-    return this.config.defaultGroupName;
-  }
-
-  public getOpenApiTitle(): string | undefined {
-    return this.config.openApiTitle ?? this.config.title;
-  }
-
-  public getTitle(): string {
-    return this.config.title;
-  }
-
-  public getNamespace(): string | undefined {
-    return this.config.namespace;
-  }
-
-  public getNamespacePrefix(): string {
-    if (!this.config.namespace) {
-      return '';
-    }
-    return `${this.config.namespace}.`;
-  }
-
-  public openApiFileName(): string {
-    return this.config.openApiFileName;
-  }
-
-  public includeMetadata(): boolean {
-    return this.config.includeMetadata;
-  }
-
-  public sortMembersAlphabetically(): boolean {
-    return this.config.sortMembersAlphabetically ?? false;
-  }
-
-  public getRootDir(): string | undefined {
-    return this.config.rootDir;
-  }
-
-  public onAfterProcess(files: TargetFile[]): void {
-    if (this.config.onAfterProcess) {
-      this.config.onAfterProcess(files);
-    }
-  }
-
-  public onBeforeFileWrite(file: TargetFile): TargetFile {
-    if (this.config.onBeforeFileWrite) {
-      return this.config.onBeforeFileWrite(file);
-    }
-    return file;
-  }
-
-  public frontMatterHeader(file: TargetType): string[] {
-    if (this.config.frontMatterHeader) {
-      return this.config.frontMatterHeader(file);
-    }
-    return [];
-  }
-}

package/src/transpiler/factory.ts

@@ -1,33 +0,0 @@
-import ProcessorTypeTranspiler from './processor-type-transpiler';
-import { GeneratorChoices } from './generator-choices';
-import { JekyllDocsProcessor } from './markdown/jekyll/jekyll-docsProcessor';
-import DocsifyDocsProcessor from './markdown/docsify/docsify-docs-processor';
-import { PlainMarkdownDocsProcessor } from './markdown/plain-markdown/plain-docsProcessor';
-import { OpenApiDocsProcessor } from './openapi/open-api-docs-processor';
-
-export class TypeTranspilerFactory {
-  private static typeTranspilerCache?: ProcessorTypeTranspiler;
-
-  public static get(generator: GeneratorChoices): ProcessorTypeTranspiler {
-    if (this.typeTranspilerCache) {
-      return this.typeTranspilerCache;
-    }
-
-    switch (generator) {
-      case 'jekyll':
-        this.typeTranspilerCache = new JekyllDocsProcessor();
-        return this.typeTranspilerCache;
-      case 'docsify':
-        this.typeTranspilerCache = new DocsifyDocsProcessor();
-        return this.typeTranspilerCache;
-      case 'plain-markdown':
-        this.typeTranspilerCache = new PlainMarkdownDocsProcessor();
-        return this.typeTranspilerCache;
-      case 'openapi':
-        this.typeTranspilerCache = new OpenApiDocsProcessor();
-        return this.typeTranspilerCache;
-      default:
-        throw Error('Invalid target generator');
-    }
-  }
-}

package/src/transpiler/file-container.ts

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

package/src/transpiler/generator-choices.ts

@@ -1 +0,0 @@
-export type GeneratorChoices = 'jekyll' | 'docsify' | 'plain-markdown' | 'openapi';

package/src/transpiler/markdown/class-file-generatorHelper.ts

@@ -1,58 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-import { TypesRepository } from '../../model/types-repository';
-import { Settings } from '../../settings';
-import State from '../../service/state';
-import { TypeTranspilerFactory } from '../factory';
-
-export default class ClassFileGeneratorHelper {
-  public static getSanitizedGroup(classModel: Type) {
-    return this.getClassGroup(classModel).replace(/ /g, '-').replace('.', '');
-  }
-
-  public static getFileLink(classModel: Type) {
-    const documentationRoot = Settings.getInstance().getRootDir() ?? '';
-    const directoryRoot = `${documentationRoot}${this.getDirectoryRoot(classModel)}`;
-    const fullClassName = `${Settings.getInstance().getNamespacePrefix()}${classModel.name}`;
-    return `[${fullClassName}](${directoryRoot}${fullClassName}.md)`;
-  }
-
-  public static getFileLinkByTypeName(typeName: string) {
-    const type = TypesRepository.getInstance().getFromScopedByName(typeName);
-    if (!type) {
-      // If the type is not found, we return a Markdown hyperlink with whatever we received.
-      return `[${typeName}](${typeName})`;
-    }
-
-    return this.getFileLink(type);
-  }
-
-  private static getDirectoryRoot(classModel: Type) {
-    // root-relative links start from the root by using a leading '/'
-    const generator = Settings.getInstance().targetGenerator;
-    if (TypeTranspilerFactory.get(generator).getLinkingStrategy() === 'root-relative') {
-      return `/${this.getSanitizedGroup(classModel)}/`;
-    }
-
-    // path-relative links traverse the directory structure
-    const typeBeingProcessed = State.getInstance().getTypeBeingProcessed();
-    if (typeBeingProcessed) {
-      if (this.getClassGroup(typeBeingProcessed) === this.getClassGroup(classModel)) {
-        // If the types the same groups then we simply link directly to that file
-        return './';
-      } else {
-        // If the types have different groups, then we have to go up a directory
-        return `../${this.getSanitizedGroup(classModel)}/`;
-      }
-    } else {
-      // If nothing is being processed, then we assume we are at the root and links should include the groups
-      return `./${this.getSanitizedGroup(classModel)}/`;
-    }
-  }
-
-  private static getClassGroup(classModel: Type): string {
-    const groupAnnotation = classModel.docComment?.annotations.find(
-      (annotation) => annotation.name.toLowerCase() === 'group',
-    );
-    return groupAnnotation?.body ?? Settings.getInstance().getDefaultGroupName();
-  }
-}

package/src/transpiler/markdown/docsify/docsify-docs-processor.ts

@@ -1,12 +0,0 @@
-import { MarkdownTranspilerBase } from '../markdown-transpiler-base';
-import { LinkingStrategy } from '../../processor-type-transpiler';
-
-export default class DocsifyDocsProcessor extends MarkdownTranspilerBase {
-  homeFileName(): string {
-    return 'README';
-  }
-
-  getLinkingStrategy(): LinkingStrategy {
-    return 'root-relative';
-  }
-}

package/src/transpiler/markdown/jekyll/jekyll-docsProcessor.ts

@@ -1,50 +0,0 @@
-import { MarkdownTranspilerBase } from '../markdown-transpiler-base';
-import { Type } from '@cparra/apex-reflection';
-import { MarkdownHomeFile } from '../../../model/markdown-home-file';
-import { MarkdownTypeFile } from '../../../model/markdown-type-file';
-import { LinkingStrategy } from '../../processor-type-transpiler';
-import { Settings } from '../../../settings';
-
-export class JekyllDocsProcessor extends MarkdownTranspilerBase {
-  homeFileName(): string {
-    return 'index';
-  }
-
-  onBeforeProcess = (types: Type[]) => {
-    this._fileContainer.pushFile(new MarkdownHomeFile(this.homeFileName(), types, this.frontMatterForHomeFile));
-  };
-
-  onProcess(type: Type): void {
-    this._fileContainer.pushFile(new MarkdownTypeFile(type, 1, this.getFrontMatterHeader(type)));
-  }
-
-  get frontMatterForHomeFile(): string {
-    return '---\nlayout: default\n---';
-  }
-
-  getFrontMatterHeader(type: Type): string {
-    const headerLines = ['---'];
-    // "layout: default" is a required front matter header for Jekyll
-    headerLines.push('layout: default');
-    // Add any additional front matter headers that might have been configured in the settings
-    const targetType = {
-      name: type.name,
-      typeName: type.type_name,
-      accessModifier: type.access_modifier,
-      group: type.group,
-      description: type.docComment?.description,
-    };
-    const configuredHeaders = Settings.getInstance().frontMatterHeader(targetType);
-    if (configuredHeaders) {
-      configuredHeaders.forEach((header) => {
-        headerLines.push(header);
-      });
-    }
-    headerLines.push('---');
-    return headerLines.join('\n');
-  }
-
-  getLinkingStrategy(): LinkingStrategy {
-    return 'path-relative';
-  }
-}

package/src/transpiler/markdown/markdown-transpiler-base.ts

@@ -1,28 +0,0 @@
-import ProcessorTypeTranspiler from '../processor-type-transpiler';
-import { Type } from '@cparra/apex-reflection';
-import { FileContainer } from '../file-container';
-import { MarkdownHomeFile } from '../../model/markdown-home-file';
-import { MarkdownTypeFile } from '../../model/markdown-type-file';
-
-export abstract class MarkdownTranspilerBase extends ProcessorTypeTranspiler {
-  protected readonly _fileContainer: FileContainer;
-
-  constructor() {
-    super();
-    this._fileContainer = new FileContainer();
-  }
-
-  abstract homeFileName(): string;
-
-  fileBuilder(): FileContainer {
-    return this._fileContainer;
-  }
-
-  onBeforeProcess = (types: Type[]) => {
-    this._fileContainer.pushFile(new MarkdownHomeFile(this.homeFileName(), types));
-  };
-
-  onProcess(type: Type): void {
-    this._fileContainer.pushFile(new MarkdownTypeFile(type));
-  }
-}

package/src/transpiler/markdown/plain-markdown/plain-docsProcessor.ts

@@ -1,12 +0,0 @@
-import { MarkdownTranspilerBase } from '../markdown-transpiler-base';
-import { LinkingStrategy } from '../../processor-type-transpiler';
-
-export class PlainMarkdownDocsProcessor extends MarkdownTranspilerBase {
-  homeFileName(): string {
-    return 'index';
-  }
-
-  getLinkingStrategy(): LinkingStrategy {
-    return 'path-relative';
-  }
-}

package/src/transpiler/processor-type-transpiler.ts

@@ -1,18 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-import { FileContainer } from './file-container';
-
-export type LinkingStrategy = 'root-relative' | 'path-relative';
-
-export default abstract class ProcessorTypeTranspiler {
-  onBeforeProcess: ((types: Type[]) => void) | undefined;
-
-  abstract onProcess(type: Type): void;
-
-  onAfterProcess: ((types: Type[]) => void) | undefined;
-
-  abstract fileBuilder(): FileContainer;
-
-  getLinkingStrategy(): LinkingStrategy {
-    return 'root-relative';
-  }
-}