@cparra/apexdocs 2.25.0-alpha.9 → 2.25.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.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/__tests__/apex-file-reader.spec.ts

@@ -1,104 +0,0 @@
-import { Settings, SettingsConfig } from '../../core/settings';
-import { ApexFileReader } from '../apex-file-reader';
-
-describe('File Reader', () => {
-  beforeEach(() => {
-    Settings.build({
-      sourceDirectory: '',
-      recursive: true,
-      scope: [],
-      outputDir: '',
-      targetGenerator: 'markdown',
-      indexOnly: false,
-      defaultGroupName: 'Misc',
-      sanitizeHtml: true,
-      openApiFileName: 'openapi',
-      title: 'Classes',
-      includeMetadata: false,
-    } 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 '';
-        },
-        exists(): boolean {
-          return true;
-        },
-      },
-      '',
-      false,
-    );
-    expect(result.length).toBe(0);
-  });
-
-  it('returns an empty list when there are no Apex files in the directory', () => {
-    const result = ApexFileReader.processFiles(
-      {
-        isDirectory(): boolean {
-          return false;
-        },
-        joinPath(): string {
-          return '';
-        },
-        readDirectory(): string[] {
-          return ['SomeFile.md'];
-        },
-        readFile(): string {
-          return '';
-        },
-        exists(): boolean {
-          return true;
-        },
-      },
-      '',
-      false,
-    );
-    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{}';
-        },
-        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,42 +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 processFiles(fileSystem: FileSystem, rootPath: string, includeMetadata: boolean): UnparsedSourceFile[] {
-    let bundles: UnparsedSourceFile[] = [];
-
-    const directoryContents = fileSystem.readDirectory(rootPath);
-    directoryContents.forEach((filePath) => {
-      const currentPath = fileSystem.joinPath(rootPath, filePath);
-      if (fileSystem.isDirectory(currentPath)) {
-        bundles = bundles.concat(this.processFiles(fileSystem, currentPath, includeMetadata));
-      }
-
-      if (!this.isApexFile(filePath)) {
-        return;
-      }
-
-      const rawTypeContent = fileSystem.readFile(currentPath);
-      const metadataPath = fileSystem.joinPath(rootPath, `${filePath}-meta.xml`);
-      let rawMetadataContent = null;
-      if (includeMetadata) {
-        rawMetadataContent = fileSystem.exists(metadataPath) ? fileSystem.readFile(metadataPath) : null;
-      }
-
-      bundles.push({ filePath: currentPath, content: rawTypeContent, metadataContent: rawMetadataContent });
-    });
-    return bundles;
-  }
-
-  private static isApexFile(currentFile: string): boolean {
-    return currentFile.endsWith(APEX_FILE_EXTENSION);
-  }
-}

package/src/application/file-writer.ts

@@ -1,21 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { PageData } from '../core/shared/types';
-
-export class FileWriter {
-  static write(files: PageData[], outputDir: string, onWriteCallback: (file: PageData) => void) {
-    files.forEach((file) => {
-      const { filePath, content } = this.getTargetLocation(file, outputDir);
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, content, 'utf8');
-      onWriteCallback(file);
-    });
-  }
-
-  private static getTargetLocation(file: PageData, outputDir: string): PageData {
-    return {
-      ...file,
-      filePath: path.join(outputDir, file.filePath),
-    };
-  }
-}

package/src/application/generators/markdown.ts

@@ -1,58 +0,0 @@
-import { generateDocs } from '../../core/markdown/generate-docs';
-import { FileWriter } from '../file-writer';
-import { Logger } from '#utils/logger';
-import { pipe } from 'fp-ts/function';
-import {
-  PageData,
-  PostHookDocumentationBundle,
-  UnparsedSourceFile,
-  UserDefinedMarkdownConfig,
-} from '../../core/shared/types';
-import { ReflectionError } from '../../core/markdown/reflection/error-handling';
-import { referenceGuideTemplate } from '../../core/markdown/templates/reference-guide';
-import * as TE from 'fp-ts/TaskEither';
-import { isSkip } from '../../core/shared/utils';
-
-export default function generate(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
-  return pipe(
-    generateDocumentationBundle(bundles, config),
-    TE.map((files) => writeFilesToSystem(files, config.targetDir)),
-    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;
-      }
-
-      const errorMessages = [
-        'Error(s) occurred while parsing files. Please review the following issues:',
-        ...error.errors.map(formatReflectionError),
-      ].join('\n');
-
-      Logger.error(errorMessages);
-    }),
-  )();
-}
-
-function generateDocumentationBundle(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
-  return generateDocs(bundles, {
-    ...config,
-    referenceGuideTemplate: referenceGuideTemplate,
-  });
-}
-
-function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: string) {
-  FileWriter.write(
-    [files.referenceGuide, ...files.docs]
-      // Filter out any files that should be skipped
-      .filter((file) => !isSkip(file)) as PageData[],
-    outputDir,
-    (file: PageData) => {
-      Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
-    },
-  );
-}
-
-function formatReflectionError(error: ReflectionError) {
-  return `Source file: ${error.file}\n${error.message}\n`;
-}

package/src/application/generators/openapi.ts

@@ -1,56 +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 { FileWriter } from '../file-writer';
-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';
-
-export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDefinedOpenApiConfig) {
-  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();
-
-  FileWriter.write(generatedFiles, config.targetDir, (file: PageData) => {
-    Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
-  });
-
-  // Error logging
-  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.clear();
-
-  Logger.logSingle(filteredLogMessage, false, 'green', false);
-  Logger.logSingle(`Creating documentation for ${filteredTypes.length} file(s)`, false, 'green', false);
-  return filteredTypes;
-}

package/src/cli/args.ts

@@ -1,43 +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';
-
-/**
- * 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.')
-    .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,58 +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. ' +
-      'Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.',
-  },
-  defaultGroupName: {
-    type: 'string',
-    default: defaults.defaultGroupName,
-    describe: 'Defines the @group name to be used when a file does not specify it.',
-  },
-  openApiTitle: {
-    type: 'string',
-    default: 'Apex REST Api',
-    describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
-  },
-  namespace: {
-    type: 'string',
-    describe:
-      'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
-      "If generating an OpenApi definition, it will be added to the file's Server Url.",
-  },
-  openApiFileName: {
-    type: 'string',
-    describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-    default: 'openapi',
-  },
-  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,
-  },
-};

package/src/core/manifest.ts

@@ -1,90 +0,0 @@
-import {
-  Annotation,
-  ClassMirror,
-  DocComment,
-  DocCommentAnnotation,
-  EnumMirror,
-  InterfaceMirror,
-  Type,
-} from '@cparra/apex-reflection';
-
-type AccessAndDocAware = { access_modifier: string; annotations: Annotation[]; docComment?: DocComment };
-
-/**
- * Represents the full library of Apex top-level types (classes, enums, and interface) for a Salesforce project.
- */
-export default class Manifest {
-  /**
-   * Constructs a new Manifest object.
-   * @param types List of types to be wrapped by this object.
-   * @param isForInnerTypes Whether this manifest represent an inner type or not.
-   */
-  constructor(
-    public types: Type[],
-    public isForInnerTypes: boolean = false,
-  ) {}
-
-  filteredByAccessModifierAndAnnotations(modifiers: string[]): Type[] {
-    const filteredTypes = Manifest.filterAccessibleModifier(this.types, modifiers);
-    const typesToReturn: Type[] = [];
-    for (const filteredType of filteredTypes) {
-      typesToReturn.push(Manifest.filterSingleType(filteredType, modifiers, this.isForInnerTypes));
-    }
-
-    return typesToReturn;
-  }
-
-  static filterSingleType(currentType: Type, modifiers: string[], isForInnerTypes: boolean): Type {
-    if (currentType.type_name === 'enum') {
-      // Ignoring enum values is not supported.
-      return currentType;
-    }
-
-    if (currentType.type_name === 'interface') {
-      const currentInterface = currentType as InterfaceMirror;
-      return {
-        ...currentType,
-        methods: this.filterAccessibleModifier(currentInterface.methods, modifiers),
-      } as InterfaceMirror;
-    }
-
-    const currentClass = currentType as ClassMirror;
-    const filteredClass = {
-      ...currentType,
-      methods: this.filterAccessibleModifier(currentClass.methods, modifiers),
-      properties: this.filterAccessibleModifier(currentClass.properties, modifiers),
-      fields: this.filterAccessibleModifier(currentClass.fields, modifiers),
-      constructors: this.filterAccessibleModifier(currentClass.constructors, modifiers),
-    } as ClassMirror;
-
-    if (!isForInnerTypes) {
-      return {
-        ...filteredClass,
-        enums: this.filterAccessibleModifier(currentClass.enums, modifiers) as EnumMirror[],
-        interfaces: this.filterAccessibleModifier(currentClass.interfaces, modifiers) as InterfaceMirror[],
-        classes: new Manifest(currentClass.classes, true).filteredByAccessModifierAndAnnotations(
-          modifiers,
-        ) as ClassMirror[],
-      };
-    }
-
-    return filteredClass;
-  }
-
-  static filterAccessibleModifier<T extends AccessAndDocAware>(accessAndDocAware: T[], modifiers: string[]): T[] {
-    return accessAndDocAware.filter((type) => this.shouldFilterType(type, modifiers));
-  }
-
-  static shouldFilterType(accessAndDocAware: AccessAndDocAware, modifiers: string[]) {
-    const hasIgnoreDocAnnotation = accessAndDocAware.docComment?.annotations.some(
-      (annotation: DocCommentAnnotation) => annotation.name.toLowerCase() === 'ignore',
-    );
-    if (hasIgnoreDocAnnotation) {
-      return false;
-    }
-    return (
-      modifiers.includes(accessAndDocAware.access_modifier) ||
-      accessAndDocAware.annotations.some((annotation: Annotation) => modifiers.includes(annotation.type.toLowerCase()))
-    );
-  }
-}

package/src/core/markdown/__test__/expect-extensions.ts

@@ -1,32 +0,0 @@
-import * as E from 'fp-ts/Either';
-import { DocumentationBundle } from '../../shared/types';
-
-export function extendExpect() {
-  expect.extend({
-    documentationBundleHasLength(received: E.Either<string[], DocumentationBundle>, length: number) {
-      return {
-        pass: E.isRight(received) && received.right.docs.length === length,
-        message: () => `Expected documentation bundle to have length ${length}`,
-      };
-    },
-    firstDocContains(doc: DocumentationBundle, content: string) {
-      return {
-        pass: doc.docs[0].content.includes(content),
-        message: () => `Expected documentation to contain ${content}. Got ${doc.docs[0].content}`,
-      };
-    },
-    firstDocContainsNot(doc: DocumentationBundle, content: string) {
-      return {
-        pass: !doc.docs[0].content.includes(content),
-        message: () => `Expected documentation to not contain ${content}. Got ${doc.docs[0].content}`,
-      };
-    },
-  });
-}
-
-export function assertEither<T, U>(result: E.Either<T, U>, assertion: (data: U) => void): void {
-  E.match<T, U, void>(
-    (error) => fail(error),
-    (data) => assertion(data),
-  )(result);
-}