@cparra/apexdocs 1.13.4 → 2.0.0-alpha.14

package/src/service/__tests__/apex-file-reader.spec.ts

@@ -0,0 +1,79 @@
+import { Settings, SettingsConfig } from '../../settings';
+import { ApexFileReader } from '../apex-file-reader';
+
+describe('File Reader', () => {
+  beforeEach(() => {
+    Settings.build({
+      sourceDirectory: '',
+      recursive: true,
+      configPath: '',
+      targetGenerator: 'jekyll',
+      group: true,
+      outputDir: '',
+      scope: [],
+    } as SettingsConfig);
+  });
+
+  it('returns an empty list when there are no files in the directory', () => {
+    const result = ApexFileReader.processFiles({
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      isDirectory(_: string): boolean {
+        return false;
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      joinPath(_: string): string {
+        return '';
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      readDirectory(_: string): string[] {
+        return [];
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      readFile(_: string): string {
+        return '';
+      },
+    });
+    expect(result.length).toBe(0);
+  });
+
+  it('returns an empty list when there are no Apex files in the directory', () => {
+    const result = ApexFileReader.processFiles({
+      isDirectory(_: string): boolean {
+        return false;
+      },
+      joinPath(_: string): string {
+        return '';
+      },
+      readDirectory(_: string): string[] {
+        return ['SomeFile.md'];
+      },
+      readFile(_: string): string {
+        return '';
+      },
+    });
+    expect(result.length).toBe(0);
+  });
+
+  it('returns the file contents for an Apex file', () => {
+    const result = ApexFileReader.processFiles({
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      isDirectory(_: string): boolean {
+        return false;
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      joinPath(_: string): string {
+        return '';
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      readDirectory(_: string): string[] {
+        return ['SomeApexFile.cls'];
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      readFile(_: string): string {
+        return 'public class MyClass{}';
+      },
+    });
+    expect(result.length).toBe(1);
+    expect(result[0]).toBe('public class MyClass{}');
+  });
+});

package/src/service/__tests__/manifest-factory.spec.ts

@@ -0,0 +1,16 @@
+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(), (typeBody: string) => {
+    return {};
+  });
+  expect(manifest.types.length).toBe(0);
+});

package/src/service/apex-file-reader.ts

@@ -0,0 +1,45 @@
+import { Settings } from '../settings';
+import { FileSystem } from './file-system';
+
+const APEX_FILE_EXTENSION = '.cls';
+
+/**
+ * Reads from .cls files and returns their raw body.
+ */
+export class ApexFileReader {
+  /**
+   * Reads from .cls files and returns their raw body.
+   */
+  static processFiles(fileSystem: FileSystem): string[] {
+    let bodies: string[] = [];
+
+    const directoryContents = fileSystem.readDirectory(this.sourceDirectory);
+
+    directoryContents.forEach((currentFilePath) => {
+      const currentPath = fileSystem.joinPath(this.sourceDirectory, currentFilePath);
+      if (this.readRecursively && fileSystem.isDirectory(currentPath)) {
+        bodies = bodies.concat(this.processFiles(fileSystem));
+      }
+
+      if (!this.isApexFile(currentFilePath)) {
+        return;
+      }
+
+      const rawFile = fileSystem.readFile(currentPath);
+      bodies.push(rawFile);
+    });
+    return bodies;
+  }
+
+  private static isApexFile(currentFile: string): boolean {
+    return currentFile.endsWith(APEX_FILE_EXTENSION);
+  }
+
+  private static get sourceDirectory() {
+    return Settings.getInstance().sourceDirectory;
+  }
+
+  private static get readRecursively() {
+    return Settings.getInstance().recursive;
+  }
+}

package/src/service/file-system.ts

@@ -0,0 +1,28 @@
+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;
+}
+
+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);
+  }
+}

package/src/service/file-writer.ts

@@ -0,0 +1,25 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { File } from '../model/file';
+import { Settings } from '../settings';
+
+export class FileWriter {
+  static write(files: File[], onWriteCallback: (fileName: string) => void) {
+    const outputDir = Settings.getInstance().outputDir;
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir);
+    }
+
+    files.forEach((file) => {
+      const dirPath = path.join(outputDir, file.dir);
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath);
+      }
+
+      const filePath = path.join(dirPath, `${file.fileName}${file.fileExtension()}`);
+      fs.writeFile(filePath, file.body, 'utf8', () => {
+        onWriteCallback(file.fileName);
+      });
+    });
+  }
+}

package/src/service/manifest-factory.ts

@@ -0,0 +1,12 @@
+import Manifest from '../model/manifest';
+import { TypeParser } from './parser';
+import { ReflectionResult } from '@cparra/apex-reflection';
+
+/**
+ * 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: (typeBody: string) => ReflectionResult): Manifest {
+  return new Manifest(typeParser.parse(reflect));
+}

package/src/service/parser.ts

@@ -0,0 +1,18 @@
+import { Type, ReflectionResult } from '@cparra/apex-reflection';
+
+export interface TypeParser {
+  parse(reflect: (typeBody: string) => ReflectionResult): Type[];
+}
+
+export class RawBodyParser implements TypeParser {
+  constructor(public typeBodies: string[]) {}
+
+  parse(reflect: (typeBody: string) => ReflectionResult): Type[] {
+    return this.typeBodies
+      .map((rawBody) => reflect(rawBody))
+      .filter((reflectionResult) => {
+        return reflectionResult.typeMirror;
+      })
+      .map((reflectionResult) => reflectionResult.typeMirror!);
+  }
+}

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

@@ -0,0 +1,31 @@
+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(classMirror.fields);
+    }
+    if (classMirror.properties.length) {
+      listener.onPropertiesDeclaration(classMirror.properties);
+    }
+    if (classMirror.methods.length) {
+      listener.onMethodsDeclaration(classMirror.methods);
+    }
+    if (classMirror.enums.length) {
+      listener.onInnerEnumsDeclaration(classMirror.enums);
+    }
+    if (classMirror.classes.length) {
+      listener.onInnerClassesDeclaration(classMirror.classes);
+    }
+    if (classMirror.interfaces.length) {
+      listener.onInnerInterfacesDeclaration(classMirror.interfaces);
+    }
+  }
+}

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

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

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

@@ -0,0 +1,12 @@
+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(interfaceMirror.methods);
+    }
+  }
+}

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

@@ -0,0 +1,18 @@
+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);
+    }
+  }
+}

package/src/service/walkers/walker.ts

@@ -0,0 +1,35 @@
+import {
+  ClassMirror,
+  ConstructorMirror,
+  EnumMirror,
+  FieldMirror,
+  InterfaceMirror,
+  MethodMirror,
+  PropertyMirror,
+  Type,
+} from '@cparra/apex-reflection';
+import { Annotation } from '@cparra/apex-reflection/index';
+
+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;
+}

package/src/settings.ts

@@ -0,0 +1,57 @@
+import ProcessorTypeTranspiler from './transpiler/processor-type-transpiler';
+import { JekyllDocsProcessor } from './transpiler/markdown/jekyll/jekyll-docsProcessor';
+import DocsifyDocsProcessor from './transpiler/markdown/docsify/docsify-docs-processor';
+
+export type GeneratorChoices = 'jekyll' | 'docsify';
+
+export interface SettingsConfig {
+  sourceDirectory: string;
+  recursive: boolean;
+  scope: string[];
+  outputDir: string;
+  targetGenerator: GeneratorChoices;
+}
+
+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 typeTranspiler(): ProcessorTypeTranspiler {
+    switch (this.config.targetGenerator) {
+      case 'jekyll':
+        return new JekyllDocsProcessor();
+      case 'docsify':
+        return new DocsifyDocsProcessor();
+      default:
+        throw Error('Invalid target generator');
+    }
+  }
+}

package/src/transpiler/file-container.ts

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

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

@@ -0,0 +1,16 @@
+import { Type } from '@cparra/apex-reflection';
+
+export default class ClassFileGeneratorHelper {
+  public static getSanitizedGroup(classModel: Type) {
+    return this.getClassGroup(classModel).replace(/ /g, '-').replace('.', '');
+  }
+
+  public static getFileLink(classModel: Type) {
+    return `[${classModel.name}](/${this.getSanitizedGroup(classModel)}/${classModel.name}.md)`;
+  }
+
+  private static getClassGroup(classModel: Type): string {
+    const groupAnnotation = classModel.docComment?.annotations.find((annotation) => annotation.name === 'group');
+    return groupAnnotation?.body ?? 'Misc';
+  }
+}

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

@@ -0,0 +1,7 @@
+import { MarkdownTranspilerBase } from '../markdown-transpiler-base';
+
+export default class DocsifyDocsProcessor extends MarkdownTranspilerBase {
+  homeFileName(): string {
+    return 'README';
+  }
+}

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

@@ -0,0 +1,22 @@
+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';
+
+export class JekyllDocsProcessor extends MarkdownTranspilerBase {
+  homeFileName(): string {
+    return 'index';
+  }
+
+  onBeforeProcess = (types: Type[]) => {
+    this._fileContainer.pushFile(new MarkdownHomeFile(this.homeFileName(), types, this.frontMatterHeader));
+  };
+
+  onProcess(type: Type): void {
+    this._fileContainer.pushFile(new MarkdownTypeFile(type, 1, this.frontMatterHeader));
+  }
+
+  get frontMatterHeader(): string {
+    return '---\nlayout: default\n---';
+  }
+}

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

@@ -0,0 +1,28 @@
+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/processor-type-transpiler.ts

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

package/src/transpiler/transpiler.ts

@@ -0,0 +1,18 @@
+import { Type } from '@cparra/apex-reflection';
+import ProcessorTypeTranspiler from './processor-type-transpiler';
+
+export default class Transpiler {
+  static generate(types: Type[], processor: ProcessorTypeTranspiler): void {
+    const sortedTypes = types.sort((apexTypeA, apexTypeB) => {
+      if (apexTypeA.name < apexTypeB.name) return -1;
+      if (apexTypeA.name > apexTypeB.name) return 1;
+      return 0;
+    });
+
+    processor.onBeforeProcess?.(sortedTypes);
+    sortedTypes.forEach((currentType) => {
+      processor.onProcess(currentType);
+    });
+    processor.onAfterProcess?.(sortedTypes);
+  }
+}

package/src/util/logger.ts

@@ -0,0 +1,31 @@
+import * as chalk from 'chalk';
+
+/**
+ * Logs messages to the console.
+ */
+export class Logger {
+  /**
+   * Logs a message with optional arguments.
+   * @param message The message to log.
+   * @param args Optional arguments.
+   */
+  public static log(message: string, ...args: string[]) {
+    this.logSingle(message);
+    args.forEach((arg) => {
+      this.logSingle(arg);
+    });
+  }
+
+  /**
+   * Logs an error message with optional arguments.
+   * @param message The error message to log.
+   * @param args Optional arguments.
+   */
+  public static error(message: string, ...args: string[]) {
+    this.log(`${chalk.red(message)}`, ...args);
+  }
+
+  private static logSingle(message: string) {
+    process.stdout.write(`${chalk.green(new Date().toLocaleString() + ': ')}${message}\n`);
+  }
+}

package/tsconfig.json

@@ -4,8 +4,14 @@
     "module": "commonjs",
     "declaration": true,
     "outDir": "./lib",
-    "strict": true
+    "strict": true,
+    "sourceMap": true
   },
-  "include": ["src"],
-  "exclude": ["node_modules", "**/__tests__/*"]
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/__tests__/*"
+  ]
 }

package/.prettierrc

@@ -1,5 +0,0 @@
-{
-  "printWidth": 120,
-  "trailingComma": "all",
-  "singleQuote": true
-}

package/examples/config/config.json

@@ -1,5 +0,0 @@
-{
-  "home": {
-    "header": "./examples/includes/header.md"
-  }
-}

package/lib/AsJsDocsProcessor.d.ts

@@ -1,9 +0,0 @@
-import DocsProcessor from './DocsProcessor';
-import JsHelper from './JsHelper';
-import ClassModel from './model/ClassModel';
-export default class AsJsDocsProcessor extends DocsProcessor {
-    process(classModel: ClassModel, outputDir: string): void;
-    generateDocsForClass(generator: JsHelper, classModel: ClassModel): void;
-    private addProperties;
-    private addInnerClasses;
-}

package/lib/AsJsDocsProcessor.js

@@ -1,61 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const fs = require("fs");
-const path = require("path");
-const DocsProcessor_1 = require("./DocsProcessor");
-const JsHelper_1 = require("./JsHelper");
-class AsJsDocsProcessor extends DocsProcessor_1.default {
-    process(classModel, outputDir) {
-        const jsHelper = new JsHelper_1.default();
-        this.generateDocsForClass(jsHelper, classModel);
-        if (!fs.existsSync(outputDir)) {
-            fs.mkdirSync(outputDir);
-        }
-        const filePath = path.join(outputDir, `${classModel.getClassName()}.doc.js`);
-        fs.writeFile(filePath, jsHelper.contents, 'utf8', () => {
-            // tslint:disable-next-line:no-console
-            console.log(`${classModel.getClassName()} processed.`);
-        });
-    }
-    generateDocsForClass(generator, classModel) {
-        generator.initializeBlock();
-        generator.declareType(classModel.getClassName(false), classModel.getDescription());
-        this.addProperties(generator, classModel);
-        generator.finalizeBlock();
-        this.addInnerClasses(classModel, generator);
-    }
-    addProperties(generator, classModel) {
-        if (classModel.getProperties().length === 0) {
-            return;
-        }
-        classModel
-            .getProperties()
-            .sort((propA, propB) => {
-            if (propA.getPropertyName() < propB.getPropertyName())
-                return -1;
-            if (propA.getPropertyName() > propB.getPropertyName())
-                return 1;
-            return 0;
-        })
-            .forEach(propertyModel => {
-            generator.declareProperty(propertyModel.getReturnType(), propertyModel.getPropertyName(), propertyModel.getDescription());
-        });
-    }
-    addInnerClasses(classModel, generator) {
-        if (classModel.getChildClasses().length > 0) {
-            classModel
-                .getChildClasses()
-                .sort((classA, classB) => {
-                if (classA.getClassName() < classB.getClassName())
-                    return -1;
-                if (classA.getClassName() > classB.getClassName())
-                    return 1;
-                return 0;
-            })
-                .forEach(innerClass => {
-                this.generateDocsForClass(generator, innerClass);
-            });
-        }
-    }
-}
-exports.default = AsJsDocsProcessor;

package/lib/ClassFileGeneratorHelper.d.ts

@@ -1,5 +0,0 @@
-import ClassModel from './model/ClassModel';
-export default class ClassFileGeneratorHelper {
-    static getSanitizedGroup(classModel: ClassModel): string;
-    static getFileLink(classModel: ClassModel): string;
-}