Merge pull request #305 from cesarParra/best-effort

Best effort and debug flag support.

Author: cesarParra

README.md

@@ -159,6 +159,7 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 | `--includeInlineHelpTextMetadata` | N/A   | Whether to include the inline help text for fields in the generated files.                                                                                                                               | `false`                    | No       |
 | `--parallelReflection`            | N/A   | Parallelize CPU-heavy reflection via worker threads.                                                                                                                                                     | `true`                     | No       |
 | `--parallelReflectionMaxWorkers`  | N/A   | Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value based on CPU count.                                                                                      | N/A                        | No       |
+| `--debug`                         | N/A   | Enable debug logging. Prints file-by-file parsing progress and success/failure.                                                                                                                          | `false`                    | No       |
 
 > **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
 > - `--sourceDir` (single directory or array of directories)
@@ -216,6 +217,7 @@ apexdocs markdown -s force-app -t docs -p global public namespaceaccessible -n M
 | `--apiVersion`                   | N/A   | The version of the API.                                                                          | `1.0.0`         | No       |
 | `--parallelReflection`           | N/A   | Parallelize CPU-heavy reflection via worker threads.                                             | `true`          | No       |
 | `--parallelReflectionMaxWorkers` | N/A   | Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value. | N/A             | No       |
+| `--debug`                        | N/A   | Enable debug logging. Prints file-by-file parsing progress and success/failure.                   | `false`         | No       |
 
 #### Sample Usage
 
@@ -240,6 +242,7 @@ apexdocs openapi -s force-app -t docs -n MyNamespace --title "My Custom OpenApi
 | `--skipIfNoChanges`              | N/A   | Whether to skip generating the changelog if there are no changes.                                | `true`      | No       |
 | `--parallelReflection`           | N/A   | Parallelize CPU-heavy reflection via worker threads.                                             | `true`      | No       |
 | `--parallelReflectionMaxWorkers` | N/A   | Maximum number of worker threads to use for parallel reflection. Defaults to a reasonable value. | N/A         | No       |
+| `--debug`                        | N/A   | Enable debug logging. Prints file-by-file parsing progress and success/failure.                   | `false`     | No       |
 
 #### Sample Usage
 

examples/vitepress/package.json

@@ -2,7 +2,7 @@
   "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",
+    "apexdocs:build": "npm run docs:clean && ts-node ../../src/cli/generate.ts --parallelReflection=false --debug",
     "docs:dev": "vitepress dev docs"
   },
   "devDependencies": {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.17.0",
+  "version": "3.17.1-beta.5",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "engines": {
     "node": ">=18"

package.json

@@ -9,6 +9,7 @@ import changelog from './generators/changelog';
 import { allComponentTypes, processFiles } from './source-code-file-reader';
 import { DefaultFileSystem } from './file-system';
 import { Logger } from '#utils/logger';
+import type { ReflectionDebugLogger } from '../core/reflection/apex/reflect-apex-source';
 import {
   UnparsedApexBundle,
   UserDefinedChangelogConfig,
@@ -28,18 +29,34 @@ export class Apexdocs {
   /**
    * Generates documentation out of Apex source files.
    */
-  static async generate(config: UserDefinedConfig, logger: Logger): Promise<E.Either<unknown[], string>> {
+  static async generate(
+    config: UserDefinedConfig,
+    deps: {
+      logger: Logger;
+      reflectionDebugLogger: ReflectionDebugLogger;
+    },
+  ): Promise<E.Either<unknown[], string>> {
+    const { logger, reflectionDebugLogger } = deps;
     logger.logSingle(`Generating ${config.targetGenerator} documentation...`);
 
     try {
       switch (config.targetGenerator) {
-        case 'markdown':
-          return (await processMarkdown(config))();
-        case 'openapi':
-          await processOpenApi(config, logger);
+        case 'markdown': {
+          return (await processMarkdown(config, logger, reflectionDebugLogger))();
+        }
+        case 'openapi': {
+          const task = await processOpenApi(config, logger);
+          const openApiResult = await task();
+
+          if (E.isLeft(openApiResult)) {
+            return E.left([openApiResult.left]);
+          }
+
           return E.right('✔️ Documentation generated successfully!');
-        case 'changelog':
-          return (await processChangeLog(config))();
+        }
+        case 'changelog': {
+          return (await processChangeLog(config, logger, reflectionDebugLogger))();
+        }
       }
     } catch (error) {
       return E.left([error]);
@@ -49,7 +66,13 @@ export class Apexdocs {
 
 const readFiles = apply(processFiles, new DefaultFileSystem());
 
-async function processMarkdown(config: UserDefinedMarkdownConfig) {
+async function processMarkdown(
+  config: UserDefinedMarkdownConfig,
+  logger: Logger,
+  reflectionDebugLogger: ReflectionDebugLogger,
+) {
+  const debugLogger = reflectionDebugLogger;
+
   return pipe(
     resolveAndValidateSourceDirectories(config),
     E.mapLeft((error) => new FileReadingError(`Failed to resolve source directories: ${error.message}`, error)),
@@ -63,9 +86,15 @@ async function processMarkdown(config: UserDefinedMarkdownConfig) {
       ),
     ),
     TE.fromEither,
-    TE.flatMap((fileBodies) => markdown(fileBodies, config)),
+    TE.flatMap((fileBodies) => markdown(fileBodies, config, debugLogger)),
     TE.map(() => '✔️ Documentation generated successfully!'),
-    TE.mapLeft(toErrors),
+    TE.mapLeft((err) => {
+      const errors = toErrors(err);
+      if (logger.isDebugEnabled()) {
+        logger.debug(`markdown generator finished with ${Array.isArray(errors) ? errors.length : 1} error item(s)`);
+      }
+      return errors;
+    }),
   );
 }
 
@@ -89,7 +118,11 @@ async function processOpenApi(config: UserDefinedOpenApiConfig, logger: Logger)
   );
 }
 
-async function processChangeLog(config: UserDefinedChangelogConfig) {
+async function processChangeLog(
+  config: UserDefinedChangelogConfig,
+  logger: Logger,
+  reflectionDebugLogger: ReflectionDebugLogger,
+) {
   function loadFiles() {
     const previousVersionConfig = {
       sourceDir: config.previousVersionDir,
@@ -129,8 +162,14 @@ async function processChangeLog(config: UserDefinedChangelogConfig) {
   return pipe(
     loadFiles(),
     TE.fromEither,
-    TE.flatMap(([previous, current]) => changelog(previous, current, config)),
-    TE.mapLeft(toErrors),
+    TE.flatMap(([previous, current]) => changelog(previous, current, config, reflectionDebugLogger)),
+    TE.mapLeft((err) => {
+      const errors = toErrors(err);
+      if (logger.isDebugEnabled()) {
+        logger.debug(`changelog generator finished with ${Array.isArray(errors) ? errors.length : 1} error item(s)`);
+      }
+      return errors;
+    }),
   );
 }
 

src/application/Apexdocs.ts

@@ -11,11 +11,13 @@ import { writeFiles } from '../file-writer';
 import { generateChangeLog } from '../../core/changelog/generate-change-log';
 import { FileWritingError } from '../errors';
 import { isSkip } from '../../core/shared/utils';
+import type { ReflectionDebugLogger } from '../../core/reflection/apex/reflect-apex-source';
 
 export default function generate(
   oldBundles: UnparsedSourceBundle[],
   newBundles: UnparsedSourceBundle[],
   config: UserDefinedChangelogConfig,
+  debugLogger: ReflectionDebugLogger,
 ) {
   function handleFile(file: ChangeLogPageData | Skip) {
     if (isSkip(file)) {
@@ -25,7 +27,7 @@ export default function generate(
     return writeFilesToSystem(file, config.targetDir);
   }
 
-  return pipe(generateChangeLog(oldBundles, newBundles, config), TE.flatMap(handleFile));
+  return pipe(generateChangeLog(oldBundles, newBundles, config, debugLogger), TE.flatMap(handleFile));
 }
 
 function writeFilesToSystem(pageData: ChangeLogPageData, outputDir: string) {

src/application/generators/changelog.ts

@@ -11,19 +11,32 @@ import * as TE from 'fp-ts/TaskEither';
 import { isSkip } from '../../core/shared/utils';
 import { writeFiles } from '../file-writer';
 import { FileWritingError } from '../errors';
+import type { ReflectionDebugLogger } from '../../core/reflection/apex/reflect-apex-source';
 
-export default function generate(bundles: UnparsedSourceBundle[], config: UserDefinedMarkdownConfig) {
+export default function generate(
+  bundles: UnparsedSourceBundle[],
+  config: UserDefinedMarkdownConfig,
+  debugLogger: ReflectionDebugLogger,
+) {
   return pipe(
-    generateDocumentationBundle(bundles, config),
+    generateDocumentationBundle(bundles, config, debugLogger),
     TE.flatMap((files) => writeFilesToSystem(files, config.targetDir)),
   );
 }
 
-function generateDocumentationBundle(bundles: UnparsedSourceBundle[], config: UserDefinedMarkdownConfig) {
-  return generateDocs(bundles, {
-    ...config,
-    referenceGuideTemplate: referenceGuideTemplate,
-  });
+function generateDocumentationBundle(
+  bundles: UnparsedSourceBundle[],
+  config: UserDefinedMarkdownConfig,
+  debugLogger: ReflectionDebugLogger,
+) {
+  return generateDocs(
+    bundles,
+    {
+      ...config,
+      referenceGuideTemplate: referenceGuideTemplate,
+    },
+    debugLogger,
+  );
 }
 
 function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: string) {

src/application/generators/markdown.ts

@@ -12,8 +12,11 @@ import { writeFiles } from '../file-writer';
 import { pipe } from 'fp-ts/function';
 import * as TE from 'fp-ts/TaskEither';
 import { OpenApiSettings } from '../../core/openapi/openApiSettings';
-import { reflectApexSource } from '../../core/reflection/apex/reflect-apex-source';
+import { reflectApexSourceBestEffort } from '../../core/reflection/apex/reflect-apex-source';
+import { ReflectionErrors } from '../../core/errors/errors';
 import * as E from 'fp-ts/Either';
+import { FileWritingError } from '../errors';
+import { createReflectionDebugLogger } from '#utils/reflection-debug-logger';
 
 export default async function openApi(
   logger: Logger,
@@ -35,18 +38,40 @@ export default async function openApi(
     version: config.apiVersion,
   });
 
-  const parsedFilesEither = await reflectApexSource(fileBodies, {
-    parallelReflection: config.parallelReflection,
-    parallelReflectionMaxWorkers: config.parallelReflectionMaxWorkers,
-  })();
+  const debugLogger = createReflectionDebugLogger(logger);
 
-  if (E.isLeft(parsedFilesEither)) {
-    const errors = parsedFilesEither.left;
-    logger.error(errors);
-    return;
+  const reflectedEither = await reflectApexSourceBestEffort(
+    fileBodies,
+    {
+      parallelReflection: config.parallelReflection,
+      parallelReflectionMaxWorkers: config.parallelReflectionMaxWorkers,
+    },
+    debugLogger,
+  )();
+
+  if (E.isLeft(reflectedEither)) {
+    // Propagate the failure to the caller instead of swallowing it.
+    // The CLI/application layer is responsible for end-of-run aggregation.
+    return E.left(reflectedEither.left);
+  }
+
+  const { successes: parsedFiles, errors: recoverableErrors } = reflectedEither.right;
+
+  if (recoverableErrors.errors.length > 0) {
+    logger.logSingle(
+      `⚠️ ${recoverableErrors.errors.length} file(s) failed to parse/reflect. Continuing with successfully reflected files.`,
+      'red',
+    );
+
+    logger.error(
+      new ReflectionErrors(
+        recoverableErrors.errors.map((e) => ({
+          ...e,
+        })),
+      ),
+    );
   }
 
-  const parsedFiles = parsedFilesEither.right;
   const reflectionByPath = new Map<string, ReflectionResult>();
 
   for (const parsed of parsedFiles) {
@@ -74,15 +99,32 @@ export default async function openApi(
   Transpiler.generate(filteredTypes, processor);
   const generatedFiles = processor.fileBuilder().files();
 
-  await pipe(
+  const writeResult = await pipe(
     writeFiles(generatedFiles, config.targetDir, (file: PageData) => {
       logger.logSingle(`${file.outputDocPath} processed.`, 'green');
     }),
-    TE.mapError((error) => logger.error(error)),
+    TE.mapLeft((error) => new FileWritingError('An error occurred while writing files to the system.', error)),
   )();
 
+  if (E.isLeft(writeResult)) {
+    return E.left(writeResult.left);
+  }
+
   // Logs any errors that the types might have in their doc comment's error field
   ErrorLogger.logErrors(logger, filteredTypes);
+
+  // If there were recoverable reflection failures, propagate them to the caller for aggregation.
+  if (recoverableErrors.errors.length > 0) {
+    return E.left(
+      new ReflectionErrors(
+        recoverableErrors.errors.map((e) => ({
+          ...e,
+        })),
+      ),
+    );
+  }
+
+  return E.right(undefined);
 }
 
 function filterByScopes(logger: Logger, manifest: Manifest) {

src/application/generators/openapi.ts

@@ -15,6 +15,15 @@ import { changeLogOptions, validateChangelogArgs } from './commands/changelog';
 import { pipe } from 'fp-ts/function';
 import { validateSourceDirectoryConfig } from '#utils/source-directory-resolver';
 
+const globalOptions = {
+  debug: {
+    type: 'boolean',
+    demandOption: false,
+    default: false,
+    describe: 'Enable debug logging.',
+  },
+} as const;
+
 const configOnlyMarkdownDefaults: Partial<UserDefinedMarkdownConfig> = {
   targetGenerator: 'markdown',
   excludeTags: [],
@@ -226,6 +235,7 @@ function getConfigType(config: ConfigResult): E.Either<Error, NoConfig | SingleC
 function extractYargsDemandingCommand(extractFromProcessFn: ExtractArgsFromProcess, config: ConfigResult) {
   return yargs
     .config(config.config as Record<string, unknown>)
+    .options(globalOptions)
     .command('markdown', 'Generate documentation from Apex classes as a Markdown site.', (yargs) =>
       yargs.options(markdownOptions).check(validateMarkdownArgs),
     )
@@ -271,6 +281,7 @@ function extractMultiCommandConfig(
   return E.tryCatch(() => {
     return yargs(extractFromProcessFn())
       .config(config)
+      .options(globalOptions)
       .options(options)
       .check(validator)
       .fail((msg) => {