3 files changed, 54 insertions, 32 deletions

diff --git a/scripts/apidocs/processing/error.ts b/scripts/apidocs/processing/error.ts
index f171d6b4..e4117301 100644
--- a/scripts/apidocs/processing/error.ts
+++ b/scripts/apidocs/processing/error.ts
@@ -1,4 +1,5 @@
 import { FakerError } from '../../../src/errors/faker-error';
+import { CI_PREFLIGHT } from '../../env';
 import type { SourceableNode } from './source';
 import { getSourcePath } from './source';
 
@@ -6,14 +7,22 @@ export class FakerApiDocsProcessingError extends FakerError {
   constructor(options: {
     type: string;
     name: string;
-    source: string | SourceableNode;
+    source: SourceableNode;
     cause: unknown;
   }) {
     const { type, name, source, cause } = options;
-    const sourceText =
-      typeof source === 'string' ? source : getSourcePathText(source);
+
+    const mainText = `Failed to process ${type} '${name}'`;
     const causeText = cause instanceof Error ? cause.message : '';
-    super(`Failed to process ${type} ${name} at ${sourceText} : ${causeText}`, {
+    const { filePath, line, column } = getSourcePath(source);
+    const sourceText = `${filePath}:${line}:${column}`;
+
+    if (CI_PREFLIGHT) {
+      const sourceArgs = `file=${filePath},line=${line},col=${column}`;
+      console.log(`::error ${sourceArgs}::${mainText}: ${causeText}`);
+    }
+
+    super(`${mainText} at ${sourceText} : ${causeText}`, {
       cause,
     });
   }
@@ -22,7 +31,7 @@ export class FakerApiDocsProcessingError extends FakerError {
 export function newProcessingError(options: {
   type: string;
   name: string;
-  source: string | SourceableNode;
+  source: SourceableNode;
   cause: unknown;
 }): FakerApiDocsProcessingError {
   const { cause } = options;
@@ -33,8 +42,3 @@ export function newProcessingError(options: {
 
   return new FakerApiDocsProcessingError(options);
 }
-
-function getSourcePathText(source: SourceableNode): string {
-  const { filePath, line, column } = getSourcePath(source);
-  return `${filePath}:${line}:${column}`;
-}
diff --git a/scripts/apidocs/processing/jsdocs.ts b/scripts/apidocs/processing/jsdocs.ts
index 4135e5e6..0999abca 100644
--- a/scripts/apidocs/processing/jsdocs.ts
+++ b/scripts/apidocs/processing/jsdocs.ts
@@ -10,7 +10,11 @@ import {
 export type JSDocableLikeNode = Pick<JSDocableNode, 'getJsDocs'>;
 
 export function getJsDocs(node: JSDocableLikeNode): JSDoc {
-  return exactlyOne(node.getJsDocs(), 'jsdocs');
+  return exactlyOne(
+    node.getJsDocs(),
+    'jsdocs',
+    'Please ensure that each method signature has JSDocs, and that all properties of option/object parameters are documented with both @param tags and inline JSDocs.'
+  );
 }
 
 export function getDeprecated(jsdocs: JSDoc): string | undefined {
diff --git a/scripts/apidocs/processing/parameter.ts b/scripts/apidocs/processing/parameter.ts
index 7a6b67da..05f2f1f3 100644
--- a/scripts/apidocs/processing/parameter.ts
+++ b/scripts/apidocs/processing/parameter.ts
@@ -1,5 +1,6 @@
 import type {
   PropertySignature,
+  Symbol,
   Type,
   TypeParameterDeclaration,
 } from 'ts-morph';
@@ -174,30 +175,43 @@ function processComplexParameter(
     return type
       .getApparentProperties()
       .flatMap((parameter) => {
-        const declaration = exactlyOne(
-          parameter.getDeclarations(),
-          'property declaration'
-        ) as PropertySignature;
-        const propertyType = declaration.getType();
-        const jsdocs = getJsDocs(declaration);
-        const deprecated = getDeprecated(jsdocs);
-
-        return [
-          {
-            name: `${name}.${parameter.getName()}${getNameSuffix(propertyType)}`,
-            type: getTypeText(propertyType, {
-              abbreviate: false,
-              stripUndefined: true,
-            }),
-            default: getDefault(jsdocs),
-            description:
-              getDescription(jsdocs) +
-              (deprecated ? `\n\n**DEPRECATED:** ${deprecated}` : ''),
-          },
-        ];
+        try {
+          return processComplexParameterProperty(name, parameter);
+        } catch (error) {
+          throw newProcessingError({
+            type: 'property',
+            name: `${name}.${parameter.getName()}`,
+            source: parameter.getDeclarations()[0],
+            cause: error,
+          });
+        }
       })
       .sort((a, b) => a.name.localeCompare(b.name));
   }
 
   return [];
 }
+
+function processComplexParameterProperty(name: string, parameter: Symbol) {
+  const declaration = exactlyOne(
+    parameter.getDeclarations(),
+    'property declaration'
+  ) as PropertySignature;
+  const propertyType = declaration.getType();
+  const jsdocs = getJsDocs(declaration);
+  const deprecated = getDeprecated(jsdocs);
+
+  return [
+    {
+      name: `${name}.${parameter.getName()}${getNameSuffix(propertyType)}`,
+      type: getTypeText(propertyType, {
+        abbreviate: false,
+        stripUndefined: true,
+      }),
+      default: getDefault(jsdocs),
+      description:
+        getDescription(jsdocs) +
+        (deprecated ? `\n\n**DEPRECATED:** ${deprecated}` : ''),
+    },
+  ];
+}