@cparra/apexdocs 3.0.0-rc.0 → 3.1.0

package/examples/vitepress/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "vitepress-example",
-  "scripts": {
-    "docs:clean": "rimraf --glob 'docs/!(.vitepress|index-frontmatter.md|api-examples.md|markdown-examples.md)'",
-    "apexdocs:build": "npm run docs:clean && ts-node ../../src/cli/generate.ts markdown",
-    "docs:build": "vitepress build docs",
-    "docs:gen": "npm run docs:clean && npm run docs:build",
-    "docs:dev": "vitepress dev docs",
-    "docs:preview": "vitepress preview docs"
-  },
-  "devDependencies": {
-    "ts-node": "^10.9.2",
-    "vitepress": "^1.3.1"
-  },
-  "dependencies": {
-    "rimraf": "^5.0.7"
-  }
-}

package/examples/vitepress/sfdx-project.json

@@ -1,12 +0,0 @@
-{
-  "packageDirectories": [
-    {
-      "path": "force-app",
-      "default": true
-    }
-  ],
-  "name": "vitepress",
-  "namespace": "",
-  "sfdcLoginUrl": "https://login.salesforce.com",
-  "sourceApiVersion": "61.0"
-}

package/jest.config.js

@@ -1,10 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  modulePathIgnorePatterns: ['<rootDir>/dist/'],
-  moduleNameMapper: {
-    '^chalk$': '<rootDir>/__mocks__/chalk.js',
-    '^log-update$': '<rootDir>/__mocks__/log-update.js',
-    '#utils/(.*)$': '<rootDir>/src/util/$1',
-  },
-};

package/jest.d.ts

@@ -1,7 +0,0 @@
-declare namespace jest {
-  interface Matchers<R> {
-    documentationBundleHasLength(length: number): R;
-    firstDocContains(content: string): R;
-    firstDocContainsNot(content: string): R;
-  }
-}

package/src/application/Apexdocs.ts

@@ -1,72 +0,0 @@
-import markdown from './generators/markdown';
-import openApi from './generators/openapi';
-
-import { ApexFileReader } from './apex-file-reader';
-import { DefaultFileSystem } from './file-system';
-import { Logger } from '#utils/logger';
-import { UnparsedSourceFile, UserDefinedConfig, UserDefinedMarkdownConfig } from '../core/shared/types';
-import { pipe } from 'fp-ts/function';
-import * as TE from 'fp-ts/TaskEither';
-import { ReflectionError } from '../core/markdown/reflection/reflect-source';
-
-/**
- * Application entry-point to generate documentation out of Apex source files.
- */
-export class Apexdocs {
-  /**
-   * Generates documentation out of Apex source files.
-   */
-  static async generate(config: UserDefinedConfig): Promise<void> {
-    Logger.logSingle(`Generating ${config.targetGenerator} documentation...`);
-
-    try {
-      const fileBodies = await ApexFileReader.processFiles(
-        new DefaultFileSystem(),
-        config.sourceDir,
-        config.targetGenerator === 'markdown' ? config.includeMetadata : false,
-      );
-
-      switch (config.targetGenerator) {
-        case 'markdown':
-          await generateMarkdownDocumentation(fileBodies, config)();
-          break;
-        case 'openapi':
-          await openApi(fileBodies, config);
-          break;
-      }
-    } catch (error) {
-      Logger.logSingle(`❌ An error occurred while generating the documentation: ${error}`, 'red');
-    }
-  }
-}
-
-function generateMarkdownDocumentation(fileBodies: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
-  return pipe(
-    markdown(fileBodies, config),
-    TE.map(() => Logger.logSingle('✔️ Documentation generated successfully!')),
-    TE.mapLeft((error) => {
-      if (error._tag === 'HookError') {
-        Logger.error('Error(s) occurred while processing hooks. Please review the following issues:');
-        Logger.error(error.error);
-        return;
-      }
-
-      if (error._tag === 'FileWritingError') {
-        Logger.error(error.message);
-        Logger.error(error.error);
-        return;
-      }
-
-      const errorMessages = [
-        'Error(s) occurred while parsing files. Please review the following issues:',
-        ...error.errors.map(formatReflectionError),
-      ].join('\n');
-
-      Logger.error(errorMessages);
-    }),
-  );
-}
-
-function formatReflectionError(error: ReflectionError) {
-  return `Source file: ${error.file}\n${error.message}\n`;
-}

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

@@ -1,87 +0,0 @@
-import { ApexFileReader } from '../apex-file-reader';
-
-describe('File Reader', () => {
-  it('returns an empty list when there are no files in the directory', async () => {
-    const result = await ApexFileReader.processFiles(
-      {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        isDirectory(_: string): Promise<boolean> {
-          return Promise.resolve(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): Promise<string[]> {
-          return Promise.resolve([]);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readFile(_: string): Promise<string> {
-          return Promise.resolve('');
-        },
-        exists(): boolean {
-          return true;
-        },
-      },
-      '',
-      false,
-    );
-    expect(result.length).toBe(0);
-  });
-
-  it('returns an empty list when there are no Apex files in the directory', async () => {
-    const result = await ApexFileReader.processFiles(
-      {
-        isDirectory(): Promise<boolean> {
-          return Promise.resolve(false);
-        },
-        joinPath(): string {
-          return '';
-        },
-        readDirectory(): Promise<string[]> {
-          return Promise.resolve(['SomeFile.md']);
-        },
-        readFile(): Promise<string> {
-          return Promise.resolve('');
-        },
-        exists(): boolean {
-          return true;
-        },
-      },
-      '',
-      false,
-    );
-    expect(result.length).toBe(0);
-  });
-
-  it('returns the file contents for an Apex file', async () => {
-    const result = await ApexFileReader.processFiles(
-      {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        isDirectory(_: string): Promise<boolean> {
-          return Promise.resolve(false);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        joinPath(_: string): string {
-          return 'SomeApexFile.cls';
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readDirectory(_: string): Promise<string[]> {
-          return Promise.resolve(['SomeApexFile.cls']);
-        },
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        readFile(_: string): Promise<string> {
-          return Promise.resolve('public class MyClass{}');
-        },
-        exists(): boolean {
-          return true;
-        },
-      },
-      '',
-      false,
-    );
-    expect(result.length).toBe(1);
-    expect(result[0].content).toBe('public class MyClass{}');
-  });
-});

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

@@ -1,55 +0,0 @@
-import { FileSystem } from './file-system';
-import { UnparsedSourceFile } from '../core/shared/types';
-
-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 async processFiles(
-    fileSystem: FileSystem,
-    rootPath: string,
-    includeMetadata: boolean,
-  ): Promise<UnparsedSourceFile[]> {
-    const filePaths = await this.getFilePaths(fileSystem, rootPath);
-    const apexFilePaths = filePaths.filter((filePath) => this.isApexFile(filePath));
-    const filePromises = apexFilePaths.map((filePath) => this.processFile(fileSystem, filePath, includeMetadata));
-    return Promise.all(filePromises);
-  }
-
-  private static async getFilePaths(fileSystem: FileSystem, rootPath: string): Promise<string[]> {
-    const directoryContents = await fileSystem.readDirectory(rootPath);
-    const paths: string[] = [];
-    for (const filePath of directoryContents) {
-      const currentPath = fileSystem.joinPath(rootPath, filePath);
-      if (await fileSystem.isDirectory(currentPath)) {
-        paths.push(...(await this.getFilePaths(fileSystem, currentPath)));
-      }
-      paths.push(currentPath);
-    }
-    return paths;
-  }
-
-  private static async processFile(
-    fileSystem: FileSystem,
-    filePath: string,
-    includeMetadata: boolean,
-  ): Promise<UnparsedSourceFile> {
-    const rawTypeContent = await fileSystem.readFile(filePath);
-    const metadataPath = `${filePath}-meta.xml`;
-    let rawMetadataContent = null;
-    if (includeMetadata) {
-      rawMetadataContent = fileSystem.exists(metadataPath) ? await fileSystem.readFile(metadataPath) : null;
-    }
-
-    return { filePath, content: rawTypeContent, metadataContent: rawMetadataContent };
-  }
-
-  private static isApexFile(currentFile: string): boolean {
-    return currentFile.endsWith(APEX_FILE_EXTENSION);
-  }
-}

package/src/application/file-system.ts

@@ -1,69 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-
-export interface FileSystem {
-  isDirectory: (path: string) => Promise<boolean>;
-  readDirectory: (sourceDirectory: string) => Promise<string[]>;
-  readFile: (path: string) => Promise<string>;
-  joinPath: (...paths: string[]) => string;
-  exists: (path: string) => boolean;
-}
-
-function stat(path: string): Promise<fs.Stats> {
-  return new Promise((resolve, reject) => {
-    fs.stat(path, (err, stats) => {
-      if (err) {
-        reject(err);
-      } else {
-        resolve(stats);
-      }
-    });
-  });
-}
-
-function readdir(path: string): Promise<string[]> {
-  return new Promise((resolve, reject) => {
-    fs.readdir(path, (err, files) => {
-      if (err) {
-        reject(err);
-      } else {
-        resolve(files);
-      }
-    });
-  });
-}
-
-function readFile(path: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    fs.readFile(path, (err, data) => {
-      if (err) {
-        reject(err);
-      } else {
-        resolve(data.toString());
-      }
-    });
-  });
-}
-
-export class DefaultFileSystem implements FileSystem {
-  async isDirectory(pathToRead: string): Promise<boolean> {
-    const stats = await stat(pathToRead);
-    return stats.isDirectory();
-  }
-
-  readDirectory(sourceDirectory: string): Promise<string[]> {
-    return readdir(sourceDirectory);
-  }
-
-  readFile(pathToRead: string): Promise<string> {
-    return readFile(pathToRead);
-  }
-
-  joinPath(...paths: string[]): string {
-    return path.join(...paths);
-  }
-
-  exists(path: string): boolean {
-    return fs.existsSync(path);
-  }
-}

package/src/application/file-writer.ts

@@ -1,43 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as TE from 'fp-ts/lib/TaskEither';
-import { PageData } from '../core/shared/types';
-import { pipe } from 'fp-ts/function';
-
-const mkdir: (path: fs.PathLike, options: fs.MakeDirectoryOptions) => TE.TaskEither<NodeJS.ErrnoException, void> =
-  TE.taskify(fs.mkdir);
-
-const writeFile: (
-  path: fs.PathOrFileDescriptor,
-  data: string,
-  options?: fs.WriteFileOptions,
-) => TE.TaskEither<NodeJS.ErrnoException, void> = TE.taskify(fs.writeFile);
-
-export function writeFiles(files: PageData[], outputDir: string, onWriteCallback?: (file: PageData) => void) {
-  return pipe(
-    files,
-    TE.traverseArray((file) => writeSingle(file, outputDir, onWriteCallback)),
-  );
-}
-
-function writeSingle(file: PageData, outputDir: string, onWriteCallback?: (file: PageData) => void) {
-  const ensureDirectoryExists = ({ outputDocPath }: PageData) =>
-    mkdir(path.dirname(outputDocPath), { recursive: true });
-
-  const writeContents = (file: PageData) => writeFile(file.outputDocPath, file.content, 'utf8');
-
-  return pipe(
-    resolveTargetLocation(file, outputDir),
-    (file) => TE.right(file),
-    TE.tapIO(ensureDirectoryExists),
-    TE.flatMap(writeContents),
-    TE.map(() => onWriteCallback?.(file)),
-  );
-}
-
-function resolveTargetLocation(file: PageData, outputDir: string): PageData {
-  return {
-    ...file,
-    outputDocPath: path.join(outputDir, file.outputDocPath),
-  };
-}

package/src/application/generators/markdown.ts

@@ -1,45 +0,0 @@
-import { generateDocs } from '../../core/markdown/generate-docs';
-import { pipe } from 'fp-ts/function';
-import {
-  PageData,
-  PostHookDocumentationBundle,
-  UnparsedSourceFile,
-  UserDefinedMarkdownConfig,
-} from '../../core/shared/types';
-import { referenceGuideTemplate } from '../../core/markdown/templates/reference-guide';
-import * as TE from 'fp-ts/TaskEither';
-import { isSkip } from '../../core/shared/utils';
-import { writeFiles } from '../file-writer';
-
-class FileWritingError {
-  readonly _tag = 'FileWritingError';
-
-  constructor(
-    public message: string,
-    public error: unknown,
-  ) {}
-}
-
-export default function generate(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
-  return pipe(
-    generateDocumentationBundle(bundles, config),
-    TE.flatMap((files) => writeFilesToSystem(files, config.targetDir)),
-  );
-}
-
-function generateDocumentationBundle(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
-  return generateDocs(bundles, {
-    ...config,
-    referenceGuideTemplate: referenceGuideTemplate,
-  });
-}
-
-function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: string) {
-  return pipe(
-    [files.referenceGuide, ...files.docs].filter((file) => !isSkip(file)),
-    (files) => writeFiles(files as PageData[], outputDir),
-    TE.mapLeft((error) => {
-      return new FileWritingError('An error occurred while writing files to the system.', error);
-    }),
-  );
-}

package/src/application/generators/openapi.ts

@@ -1,71 +0,0 @@
-import { createManifest } from '../../core/openapi/manifest-factory';
-import { RawBodyParser } from '../../core/openapi/parser';
-import { TypesRepository } from '../../core/openapi/types-repository';
-import Transpiler from '../../core/openapi/transpiler';
-import { Logger } from '#utils/logger';
-import ErrorLogger from '#utils/error-logger';
-import { reflect, ReflectionResult } from '@cparra/apex-reflection';
-import Manifest from '../../core/manifest';
-import { PageData, UnparsedSourceFile, UserDefinedOpenApiConfig } from '../../core/shared/types';
-import { OpenApiDocsProcessor } from '../../core/openapi/open-api-docs-processor';
-import { writeFiles } from '../file-writer';
-import { pipe } from 'fp-ts/function';
-import * as TE from 'fp-ts/TaskEither';
-import { OpenApiSettings } from '../../core/openApiSettings';
-
-export default async function openApi(fileBodies: UnparsedSourceFile[], config: UserDefinedOpenApiConfig) {
-  OpenApiSettings.build({
-    sourceDirectory: config.sourceDir,
-    outputDir: config.targetDir,
-    openApiFileName: config.fileName,
-    openApiTitle: config.title,
-    namespace: config.namespace,
-    version: config.apiVersion,
-  });
-
-  const manifest = createManifest(new RawBodyParser(fileBodies), reflectionWithLogger);
-  TypesRepository.getInstance().populateAll(manifest.types);
-  const filteredTypes = filterByScopes(manifest);
-  const processor = new OpenApiDocsProcessor();
-  Transpiler.generate(filteredTypes, processor);
-  const generatedFiles = processor.fileBuilder().files();
-
-  await pipe(
-    writeFiles(generatedFiles, config.targetDir, (file: PageData) => {
-      Logger.logSingle(`${file.outputDocPath} processed.`, 'green');
-    }),
-    TE.map(() => Logger.logSingle('✔️ Documentation generated successfully!')),
-    TE.mapError((error) => Logger.error(error)),
-  )();
-
-  // Logs any errors that the types might have in their doc comment's error field
-  ErrorLogger.logErrors(filteredTypes);
-}
-
-function reflectionWithLogger(apexBundle: UnparsedSourceFile): ReflectionResult {
-  const result = reflect(apexBundle.content);
-  if (result.error) {
-    Logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
-  }
-  return result;
-}
-
-function filterByScopes(manifest: Manifest) {
-  // If we are dealing with an OpenApi generator, we ignore the passed in access modifiers, and instead
-  // we only keep classes annotated as @RestResource
-  const filteredTypes = manifest.filteredByAccessModifierAndAnnotations([
-    'restresource',
-    'httpdelete',
-    'httpget',
-    'httppatch',
-    'httppost',
-    'httpput',
-  ]);
-  const filteredLogMessage = `Filtered ${
-    manifest.types.length - filteredTypes.length
-  } file(s), only keeping classes annotated as @RestResource.`;
-
-  Logger.logSingle(filteredLogMessage, 'green');
-  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, 'green');
-  return filteredTypes;
-}

package/src/cli/args.ts

@@ -1,46 +0,0 @@
-import { cosmiconfig, CosmiconfigResult } from 'cosmiconfig';
-import * as yargs from 'yargs';
-import { UserDefinedMarkdownConfig } from '../core/shared/types';
-import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
-import { markdownOptions } from './commands/markdown';
-import { openApiOptions } from './commands/openapi';
-
-/**
- * Extracts configuration from a configuration file or the package.json
- * through cosmiconfig.
- */
-function _extractConfig(): Promise<CosmiconfigResult> {
-  return cosmiconfig('apexdocs', {
-    loaders: {
-      '.ts': TypeScriptLoader(),
-    },
-  }).search();
-}
-
-/**
- * Extracts arguments from the command line.
- * @param config The configuration object from the configuration file, if any.
- */
-function _extractYargs(config?: CosmiconfigResult) {
-  return yargs
-    .config(config?.config)
-    .command('markdown', 'Generate documentation from Apex classes as a Markdown site.', (yargs) =>
-      yargs.options(markdownOptions),
-    )
-    .command('openapi', 'Generate an OpenApi REST specification from Apex classes.', () =>
-      yargs.options(openApiOptions),
-    )
-    .demandCommand()
-    .parseSync();
-}
-
-/**
- * Combines the extracted configuration and arguments.
- */
-export async function extractArgs(): Promise<UserDefinedMarkdownConfig> {
-  const config = await _extractConfig();
-  const cliArgs = _extractYargs(config);
-  const commandName = cliArgs._[0];
-
-  return { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
-}

package/src/cli/commands/markdown.ts

@@ -1,51 +0,0 @@
-import { Options } from 'yargs';
-import { defaults } from '../../defaults';
-
-export const markdownOptions: { [key: string]: Options } = {
-  sourceDir: {
-    type: 'string',
-    alias: 's',
-    demandOption: true,
-    describe: 'The directory location which contains your apex .cls classes.',
-  },
-  targetDir: {
-    type: 'string',
-    alias: 't',
-    default: defaults.targetDir,
-    describe: 'The directory location where documentation will be generated to.',
-  },
-  scope: {
-    type: 'string',
-    array: true,
-    alias: 'p',
-    default: defaults.scope,
-    describe:
-      'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
-      'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled.',
-  },
-  defaultGroupName: {
-    type: 'string',
-    default: defaults.defaultGroupName,
-    describe: 'Defines the @group name to be used when a file does not specify it.',
-  },
-  namespace: {
-    type: 'string',
-    describe: 'The package namespace, if any. If provided, it will be added to the generated files.',
-  },
-  sortMembersAlphabetically: {
-    type: 'boolean',
-    describe: 'Whether to sort members alphabetically.',
-    default: defaults.sortMembersAlphabetically,
-  },
-  includeMetadata: {
-    type: 'boolean',
-    describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
-    default: defaults.includeMetadata,
-  },
-  linkingStrategy: {
-    type: 'string',
-    describe: 'The strategy to use when linking to other documentation pages.',
-    choices: ['relative', 'no-link', 'none'],
-    default: defaults.linkingStrategy,
-  },
-};

package/src/cli/commands/openapi.ts

@@ -1,36 +0,0 @@
-import { Options } from 'yargs';
-import { defaults } from '../../defaults';
-
-export const openApiOptions: { [key: string]: Options } = {
-  sourceDir: {
-    type: 'string',
-    alias: 's',
-    demandOption: true,
-    describe: 'The directory location which contains your apex .cls classes.',
-  },
-  targetDir: {
-    type: 'string',
-    alias: 't',
-    default: defaults.targetDir,
-    describe: 'The directory location where the OpenApi file will be generated.',
-  },
-  fileName: {
-    type: 'string',
-    default: 'openapi',
-    describe: 'The name of the OpenApi file to be generated.',
-  },
-  namespace: {
-    type: 'string',
-    describe: 'The package namespace, if any. This will be added to the API file Server Url.',
-  },
-  title: {
-    type: 'string',
-    default: 'Apex REST API',
-    describe: 'The title of the OpenApi file.',
-  },
-  apiVersion: {
-    type: 'string',
-    default: '1.0.0',
-    describe: 'The version of the OpenApi file.',
-  },
-};

package/src/cli/generate.ts

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-import { Apexdocs } from '../application/Apexdocs';
-import { extractArgs } from './args';
-
-function main() {
-  function catchError(error: Error) {
-    console.error(error);
-    process.exit(1);
-  }
-
-  extractArgs()
-    .then((config) => Apexdocs.generate(config).catch(catchError))
-    .catch(catchError);
-}
-
-main();

package/src/core/__test__/manifest.spec.ts

@@ -1,16 +0,0 @@
-import Manifest from '../manifest';
-import { EnumMirror } from '@cparra/apex-reflection';
-
-const sampleEnum: EnumMirror = {
-  annotations: [],
-  name: 'SampleEnum',
-  type_name: 'enum',
-  access_modifier: 'public',
-  values: [],
-};
-
-it('holds a list of types', () => {
-  const types = [sampleEnum];
-  const manifest = new Manifest(types);
-  expect(manifest.types).toBe(types);
-});