test(docs): ensure defaults are consistent (#2177)

1 files changed, 76 insertions, 0 deletions

diff --git a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
index 47eca926..7e020335 100644
--- a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
+++ b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts
@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import type { ReflectionType, SomeType } from 'typedoc';
 import validator from 'validator';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { initMarkdownRenderer } from '../../../scripts/apidoc/markdown';
@@ -9,8 +10,10 @@ import {
   extractDescription,
   extractJoinedRawExamples,
   extractModuleFieldName,
+  extractRawDefault,
   extractSeeAlsos,
   extractSince,
+  extractSummaryDefault,
   extractTagContent,
   MISSING_DESCRIPTION,
 } from '../../../scripts/apidoc/typedoc';
@@ -89,6 +92,57 @@ describe('verify JSDoc tags', () => {
     }
   }
 
+  // keep in sync with analyzeParameterOptions
+  function assertNestedParameterDefault(
+    name: string,
+    parameterType?: SomeType
+  ): void {
+    if (!parameterType) {
+      return;
+    }
+
+    switch (parameterType.type) {
+      case 'array':
+        return assertNestedParameterDefault(
+          `${name}[]`,
+          parameterType.elementType
+        );
+
+      case 'union':
+        for (const type of parameterType.types) {
+          assertNestedParameterDefault(name, type);
+        }
+
+        return;
+
+      case 'reflection': {
+        for (const property of parameterType.declaration.children ?? []) {
+          const reflection = property.comment
+            ? property
+            : (property.type as ReflectionType)?.declaration?.signatures?.[0];
+          const comment = reflection?.comment;
+          const tagDefault = extractRawDefault({ comment }) || undefined;
+          const summaryDefault = extractSummaryDefault(comment, false);
+
+          if (summaryDefault) {
+            expect(
+              tagDefault,
+              `Expect jsdoc summary default and @default for ${name}.${property.name} to be the same`
+            ).toBe(summaryDefault);
+          }
+        }
+
+        return;
+      }
+
+      case 'typeOperator':
+        return assertNestedParameterDefault(name, parameterType.target);
+
+      default:
+        return;
+    }
+  }
+
   describe.each(Object.entries(modules))(
     '%s',
     (moduleName, [module, methodsByName]) => {
@@ -172,6 +226,28 @@ describe('verify JSDoc tags', () => {
           });
 
           it('verify @param tags', async () => {
+            // This must run before analyzeSignature
+            for (const param of signature.parameters ?? []) {
+              const type = param.type;
+              const paramDefault = param.defaultValue;
+              const commentDefault = extractSummaryDefault(
+                param.comment,
+                false
+              );
+              if (paramDefault) {
+                if (/^{.*}$/.test(paramDefault)) {
+                  expect(commentDefault).toBeUndefined();
+                } else {
+                  expect(
+                    commentDefault,
+                    `Expect '${param.name}'s js implementation default to be the same as the jsdoc summary default.`
+                  ).toBe(paramDefault);
+                }
+              }
+
+              assertNestedParameterDefault(param.name, type);
+            }
+
             for (const param of (
               await analyzeSignature(signature, '', methodName)
             ).parameters) {