Consider the merged symbol when documenting global symbols

Resolves #2774

Author: Gerrit0

CHANGELOG.md

@@ -87,6 +87,8 @@ title: Changelog
 -   Fixed handling of `@enum` if the type was declared before the variable, #2719.
 -   Fixed empty top level modules page in packages mode, #2753.
 -   TypeDoc can now link to type alias properties, #2524.
+-   TypeDoc will now document the merged symbol type when considering globals
+    declared inside `declare global`, #2774
 -   Fixed an issue where properties were not properly marked optional in some
     cases. This primarily affected destructured parameters.
 -   Added `yaml` to the highlight languages supported by default.
@@ -103,10 +105,6 @@ title: Changelog
     one package were incorrectly reported as unused when running with
     entryPointStrategy set to packages.
 
-TODO:
-
--   Figure out automation for beta releases
-
 # Unreleased
 
 ## v0.26.11 (2024-11-01)

src/lib/converter/converter.ts

@@ -812,7 +812,8 @@ function getExports(
                             exp.declarations?.some(
                                 (d) => d.getSourceFile() === node,
                             ),
-                        );
+                        )
+                        .map((s) => context.checker.getMergedSymbol(s));
                 }
             }
         }

src/test/converter2/issues/gh2774/gh2774.ts

@@ -0,0 +1,3 @@
+namespace GH2774 {
+    export interface Extensions {}
+}

src/test/converter2/issues/gh2774/globalAugment.ts

@@ -0,0 +1,5 @@
+namespace GH2774 {
+    export interface Extensions {
+        globalAugment: string;
+    }
+}

src/test/converter2/issues/gh2774/moduleAugment.ts

@@ -0,0 +1,9 @@
+export {};
+
+declare global {
+    namespace GH2774 {
+        export interface Extensions {
+            moduleAugment: string;
+        }
+    }
+}

src/test/converter2/tsconfig.json

@@ -5,8 +5,9 @@
         "checkJs": true,
         "outDir": "dist",
         "target": "ESNext",
-
         "noImplicitAny": false,
+        // GH2774 test case needs global files
+        "moduleDetection": "legacy",
 
         "skipLibCheck": true
     },

src/test/issues.c2.test.ts

@@ -42,42 +42,51 @@ const base = getConverter2Base();
 const app = getConverter2App();
 const program = getConverter2Program();
 
-function doConvert(entry: string) {
-    const entryPoint = [
-        join(base, `issues/${entry}.ts`),
-        join(base, `issues/${entry}.d.ts`),
-        join(base, `issues/${entry}.tsx`),
-        join(base, `issues/${entry}.js`),
-        join(base, "issues", entry, "index.ts"),
-        join(base, "issues", entry, "index.js"),
-    ].find(existsSync);
-
-    ok(entryPoint, `No entry point found for ${entry}`);
-    const sourceFile = program.getSourceFile(entryPoint);
-    ok(sourceFile, `No source file found for ${entryPoint}`);
-
-    app.options.setValue("entryPoints", [entryPoint]);
+function doConvert(entries: string[]) {
+    const entryPoints = entries
+        .map((entry) =>
+            [
+                join(base, `issues/${entry}.ts`),
+                join(base, `issues/${entry}.d.ts`),
+                join(base, `issues/${entry}.tsx`),
+                join(base, `issues/${entry}.js`),
+                join(base, "issues", entry, "index.ts"),
+                join(base, "issues", entry, "index.js"),
+                join(base, "issues", entry),
+            ].find(existsSync),
+        )
+        .filter((x) => x !== undefined);
+
+    const files = entryPoints.map((e) => program.getSourceFile(e));
+    for (const [index, file] of files.entries()) {
+        ok(file, `No source file found for ${entryPoints[index]}`);
+    }
+
+    app.options.setValue("entryPoints", entryPoints);
     clearCommentCache();
-    return app.converter.convert([
-        {
-            displayName: entry,
-            program,
-            sourceFile,
-        },
-    ]);
+    return app.converter.convert(
+        files.map((file, index) => {
+            return {
+                displayName: entries[index].replace(/\.[tj]sx?$/, ""),
+                program,
+                sourceFile: file!,
+            };
+        }),
+    );
 }
 
 describe("Issue Tests", () => {
     let logger: TestLogger;
-    let convert: (name?: string) => ProjectReflection;
+    let convert: (...entries: string[]) => ProjectReflection;
     let optionsSnap: { __optionSnapshot: never };
 
     beforeEach(function () {
         app.logger = logger = new TestLogger();
         optionsSnap = app.options.snapshot();
         const issueNumber = this.currentTest?.title.match(/#(\d+)/)?.[1];
         ok(issueNumber, "Test name must contain an issue number.");
-        convert = (name = `gh${issueNumber}`) => doConvert(name);
+        convert = (...entries) =>
+            doConvert(entries.length ? entries : [`gh${issueNumber}`]);
     });
 
     afterEach(() => {
@@ -1885,4 +1894,18 @@ describe("Issue Tests", () => {
         equal(getSigComment(project, "Callable", 0), "A");
         equal(getSigComment(project, "Callable", 1), "B");
     });
+
+    it("#2774 gets global symbols in a consistent manner", () => {
+        const project = convert(
+            "gh2774/gh2774.ts",
+            "gh2774/globalAugment.ts",
+            "gh2774/moduleAugment.ts",
+        );
+
+        const decl = query(project, "gh2774/gh2774.GH2774");
+        equal(
+            decl.children?.map((c) => c.name),
+            ["Extensions"],
+        );
+    });
 });

src/test/utils.ts

@@ -45,7 +45,10 @@ export function query(
         refl = refl.getChildByName([parts[i]]) as SomeReflection | undefined;
     }
 
-    ok(refl instanceof DeclarationReflection, `Failed to find ${name}`);
+    ok(
+        refl instanceof DeclarationReflection,
+        `Failed to find ${name}\n${project.toStringHierarchy()}`,
+    );
     return refl;
 }