@cparra/apexdocs 3.0.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,69 +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 * as E from 'fp-ts/Either';
-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, logger: Logger): Promise<E.Either<unknown[], string>> {
-    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':
-          return await generateMarkdownDocumentation(fileBodies, config)();
-        case 'openapi':
-          await openApi(logger, fileBodies, config);
-          return E.right('✔️ Documentation generated successfully!');
-      }
-    } catch (error) {
-      return E.left([error]);
-    }
-  }
-}
-
-function generateMarkdownDocumentation(
-  fileBodies: UnparsedSourceFile[],
-  config: UserDefinedMarkdownConfig,
-): TE.TaskEither<unknown[], string> {
-  return pipe(
-    markdown(fileBodies, config),
-    TE.map(() => '✔️ Documentation generated successfully!'),
-    TE.mapLeft((error) => {
-      if (error._tag === 'HookError') {
-        return ['Error(s) occurred while processing hooks. Please review the following issues:', error.error];
-      }
-
-      if (error._tag === 'FileWritingError') {
-        return ['Error(s) occurred while writing files. Please review the following issues:', error.error];
-      }
-
-      return [
-        'Error(s) occurred while parsing files. Please review the following issues:',
-        ...error.errors.map(formatReflectionError),
-      ];
-    }),
-  );
-}
-
-function formatReflectionError(error: ReflectionError) {
-  return `Source file: ${error.file}\n${error.message}\n`;
-}

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

@@ -1,128 +0,0 @@
-import { ApexFileReader } from '../apex-file-reader';
-import { FileSystem } from '../file-system';
-
-type File = {
-  type: 'file';
-  path: string;
-  content: string;
-};
-
-type Directory = {
-  type: 'directory';
-  path: string;
-  files: (File | Directory)[];
-};
-
-type Path = File | Directory;
-
-class TestFileSystem implements FileSystem {
-  constructor(private readonly paths: Path[]) {}
-
-  async isDirectory(path: string): Promise<boolean> {
-    const directory = this.findPath(path);
-    return directory ? directory.type === 'directory' : false;
-  }
-
-  joinPath(...paths: string[]): string {
-    return paths.join('/');
-  }
-
-  async readDirectory(sourceDirectory: string): Promise<string[]> {
-    const directory = this.findPath(sourceDirectory);
-    if (!directory || directory.type !== 'directory') {
-      throw new Error('Directory not found');
-    }
-    return directory.files.map((f) => f.path);
-  }
-
-  async readFile(path: string): Promise<string> {
-    const file = this.findPath(path);
-    if (!file || file.type !== 'file') {
-      throw new Error('File not found');
-    }
-    return file.content;
-  }
-
-  exists(path: string): boolean {
-    return this.paths.some((p) => p.path === path);
-  }
-
-  findPath(path: string): Path | undefined {
-    const splitPath = path.split('/');
-    let currentPath = this.paths.find((p) => p.path === splitPath[0]);
-    for (let i = 1; i < splitPath.length; i++) {
-      if (!currentPath || currentPath.type !== 'directory') {
-        return undefined;
-      }
-      currentPath = currentPath.files.find((f) => f.path === splitPath[i]);
-    }
-    return currentPath;
-  }
-}
-
-describe('File Reader', () => {
-  it('returns an empty list when there are no files in the directory', async () => {
-    const fileSystem = new TestFileSystem([
-      {
-        type: 'directory',
-        path: '',
-        files: [],
-      },
-    ]);
-
-    const result = await ApexFileReader.processFiles(fileSystem, '', false);
-
-    expect(result.length).toBe(0);
-  });
-
-  it('returns an empty list when there are no Apex files in the directory', async () => {
-    const fileSystem = new TestFileSystem([
-      {
-        type: 'directory',
-        path: '',
-        files: [
-          {
-            type: 'file',
-            path: 'SomeFile.md',
-            content: '## Some Markdown',
-          },
-        ],
-      },
-    ]);
-
-    const result = await ApexFileReader.processFiles(fileSystem, '', false);
-    expect(result.length).toBe(0);
-  });
-
-  it('returns the file contents for all Apex files', async () => {
-    const fileSystem = new TestFileSystem([
-      {
-        type: 'directory',
-        path: '',
-        files: [
-          {
-            type: 'file',
-            path: 'SomeFile.cls',
-            content: 'public class MyClass{}',
-          },
-          {
-            type: 'directory',
-            path: 'subdir',
-            files: [
-              {
-                type: 'file',
-                path: 'AnotherFile.cls',
-                content: 'public class AnotherClass{}',
-              },
-            ],
-          },
-        ],
-      },
-    ]);
-
-    const result = await ApexFileReader.processFiles(fileSystem, '', false);
-    expect(result.length).toBe(2);
-    expect(result[0].content).toBe('public class MyClass{}');
-    expect(result[1].content).toBe('public class AnotherClass{}');
-  });
-});

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

@@ -1,56 +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)));
-        return paths;
-      }
-      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,75 +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';
-import { apply } from '#utils/fp';
-
-export default async function openApi(
-  logger: Logger,
-  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(logger, fileBodies), apply(reflectionWithLogger, logger));
-  TypesRepository.getInstance().populateAll(manifest.types);
-  const filteredTypes = filterByScopes(logger, manifest);
-  const processor = new OpenApiDocsProcessor(logger);
-  Transpiler.generate(filteredTypes, processor);
-  const generatedFiles = processor.fileBuilder().files();
-
-  await pipe(
-    writeFiles(generatedFiles, config.targetDir, (file: PageData) => {
-      logger.logSingle(`${file.outputDocPath} processed.`, 'green');
-    }),
-    TE.mapError((error) => logger.error(error)),
-  )();
-
-  // Logs any errors that the types might have in their doc comment's error field
-  ErrorLogger.logErrors(logger, filteredTypes);
-}
-
-function reflectionWithLogger(logger: Logger, apexBundle: UnparsedSourceFile): ReflectionResult {
-  const result = reflect(apexBundle.content);
-  if (result.error) {
-    logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);
-  }
-  return result;
-}
-
-function filterByScopes(logger: Logger, 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,55 +0,0 @@
-import { cosmiconfig, CosmiconfigResult } from 'cosmiconfig';
-import * as yargs from 'yargs';
-import { UserDefinedConfig, UserDefinedMarkdownConfig } from '../core/shared/types';
-import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
-import { markdownOptions } from './commands/markdown';
-import { openApiOptions } from './commands/openapi';
-
-const configOnlyDefaults: Partial<UserDefinedMarkdownConfig> = {
-  excludeTags: [],
-};
-
-/**
- * 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<UserDefinedConfig> {
-  const config = await _extractConfig();
-  const cliArgs = _extractYargs(config);
-  const commandName = cliArgs._[0];
-
-  const mergedConfig = { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
-  if (mergedConfig.targetGenerator === 'markdown') {
-    return { ...configOnlyDefaults, ...mergedConfig };
-  } else {
-    return mergedConfig;
-  }
-}

package/src/cli/commands/markdown.ts

@@ -1,56 +0,0 @@
-import { Options } from 'yargs';
-import { markdownDefaults } 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: markdownDefaults.targetDir,
-    describe: 'The directory location where documentation will be generated to.',
-  },
-  scope: {
-    type: 'string',
-    array: true,
-    alias: 'p',
-    default: markdownDefaults.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: markdownDefaults.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.',
-  },
-  sortAlphabetically: {
-    type: 'boolean',
-    describe: 'Whether to sort files and members alphabetically.',
-    default: markdownDefaults.sortAlphabetically,
-  },
-  includeMetadata: {
-    type: 'boolean',
-    describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
-    default: markdownDefaults.includeMetadata,
-  },
-  linkingStrategy: {
-    type: 'string',
-    describe: 'The strategy to use when linking to other documentation pages.',
-    choices: ['relative', 'no-link', 'none'],
-    default: markdownDefaults.linkingStrategy,
-  },
-  referenceGuideTitle: {
-    type: 'string',
-    describe: 'The title of the reference guide.',
-    default: markdownDefaults.referenceGuideTitle,
-  },
-};

package/src/cli/commands/openapi.ts

@@ -1,36 +0,0 @@
-import { Options } from 'yargs';
-import { markdownDefaults, openApiDefaults } 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: markdownDefaults.targetDir,
-    describe: 'The directory location where the OpenApi file will be generated.',
-  },
-  fileName: {
-    type: 'string',
-    default: openApiDefaults.fileName,
-    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: openApiDefaults.title,
-    describe: 'The title of the OpenApi file.',
-  },
-  apiVersion: {
-    type: 'string',
-    default: openApiDefaults.apiVersion,
-    describe: 'The version of the OpenApi file.',
-  },
-};