Merge branch 'typedoc-0.26-update'

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.0.0] - 2024-06-30
+### BREAKING CHANGES
+-   Support changed to TypeDoc version 0.26.x due to a breaking change in TypeDoc's API.
+
 ## [5.1.0] - 2023-08-30
 ### Added
 -   Added support for latest TypeDoc version 0.25.x.
@@ -17,7 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Categories and groups are incomplete when merging modules in a monorepo project.
 
 ## [5.0.0] - 2023-05-01
-### Breaking Changes
+### BREAKING CHANGES
 -   Support changed to TypeDoc versions 0.24.x due to a breaking change in TypeDoc's API.
 ### Fixed
 -   Monorepos were not merged correctly in version 4.1.0
@@ -31,7 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Plugin doesn't rename certain types of default exports.
 
 ## [4.0.0] - 2022-07-03
-### Breaking Changes
+### BREAKING CHANGES
 -   Support changed to TypeDoc versions 0.23.x due to a breaking change in TypeDoc's API.
 ### Added
 -   Option `mergeModulesMergeMode` now has a new value `module-category` to merge modules with the same name but only
@@ -53,7 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Plugin doesn't rename default exports of type interface.
 
 ## [3.0.0] - 2021-07-18
-### Breaking Changes
+### BREAKING CHANGES
 -   Support changed to TypeDoc versions >=0.21.0 due to a breaking change in TypeDoc's API.
 
 ## [2.1.1] - 2021-06-07
@@ -65,16 +69,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   New option `mergeModulesMergeMode` to merge by module names or to turn the plugin off.
 
 ## [2.0.0] - 2021-03-13
+### BREAKING CHANGES
+-   New option `mergeModulesRenameDefaults` is `true` by default.
 ### Added
 -   New option `mergeModulesRenameDefaults` to rename default exports.
-### Breaking Changes
--   New option `mergeModulesRenameDefaults` is `true` by default.
 
 ## [1.0.0] - 2021-01-30
 
 First release
 
-[unreleased]: https://github.com/krisztianb/typedoc-plugin-merge-modules/compare/v5.1.0...HEAD
+[unreleased]: https://github.com/krisztianb/typedoc-plugin-merge-modules/compare/v6.0.0...HEAD
+[6.0.0]: https://github.com/krisztianb/typedoc-plugin-merge-modules/releases/tag/v6.0.0
 [5.1.0]: https://github.com/krisztianb/typedoc-plugin-merge-modules/releases/tag/v5.1.0
 [5.0.1]: https://github.com/krisztianb/typedoc-plugin-merge-modules/releases/tag/v5.0.1
 [5.0.0]: https://github.com/krisztianb/typedoc-plugin-merge-modules/releases/tag/v5.0.0

README.md

@@ -23,7 +23,7 @@ This module can be installed using [npm](https://www.npmjs.com/package/typedoc-p
 $ npm install typedoc-plugin-merge-modules --save-dev
 ```
 
-The plugin requires TypeDoc version 0.24.x or 0.25.x to be installed. After installation you need to activate the plugin with a [typedoc command line argument](https://typedoc.org/options/configuration/#plugin) or inside your [typedoc config file](https://typedoc.org/options/configuration/#json-files).
+The plugin requires TypeDoc version 0.26.x to be installed. After installation you need to activate the plugin with a [typedoc command line argument](https://typedoc.org/options/configuration/#plugin) or inside your [typedoc config file](https://typedoc.org/options/configuration/#json-files).
 
 Here is an example using a JavaScript config file:
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "typedoc-plugin-merge-modules",
-    "version": "5.1.0",
+    "version": "6.0.0",
     "description": "Plugin for TypeDoc that merges the content of modules.",
     "author": {
         "name": "Krisztián Balla",
@@ -12,22 +12,22 @@
         "typedocplugin"
     ],
     "devDependencies": {
-        "@types/mocha": "10.0.1",
-        "@types/node": "18.16.20",
-        "@typescript-eslint/eslint-plugin": "6.5.0",
-        "@typescript-eslint/parser": "6.5.0",
+        "@types/mocha": "10.0.7",
+        "@types/node": "20.14.9",
+        "@typescript-eslint/eslint-plugin": "7.14.1",
+        "@typescript-eslint/parser": "7.14.1",
         "cypress": "12.13.0",
-        "eslint": "8.48.0",
-        "eslint-plugin-jsdoc": "46.5.1",
+        "eslint": "8.56.0",
+        "eslint-plugin-jsdoc": "48.5.0",
         "eslint-plugin-ordered-imports": "0.6.0",
-        "eslint-plugin-unicorn": "48.0.1",
-        "prettier": "3.0.3",
-        "rimraf": "5.0.1",
-        "typedoc": "0.25.0",
-        "typescript": "5.2.2"
+        "eslint-plugin-unicorn": "54.0.0",
+        "prettier": "3.3.2",
+        "rimraf": "5.0.7",
+        "typedoc": "0.26.3",
+        "typescript": "5.5.2"
     },
     "peerDependencies": {
-        "typedoc": "0.24.x || 0.25.x"
+        "typedoc": "0.26.x"
     },
     "repository": {
         "type": "git",
@@ -42,6 +42,6 @@
         "lint": "eslint ./src ./test",
         "format": "prettier --check ./src ./test",
         "build": "rimraf dist && tsc",
-        "test": "cd test && node test.js"
+        "test": "cd test && node prepare_test.js && node test.js"
     }
 }

src/merger/module_bundle.ts

@@ -1,6 +1,12 @@
 /** @module merger */
-import { DeclarationReflection, ProjectReflection } from "typedoc";
-import { removeTagFromCommentsOf } from "../utils";
+import { DeclarationReflection, DocumentReflection, ProjectReflection, ReflectionKind } from "typedoc";
+import {
+    addDeclarationReflectionToTarget,
+    addDocumentReflectionToTarget,
+    removeDeclarationReflectionFromModule,
+    removeDocumentReflectionFromModule,
+    removeTagFromCommentsOf,
+} from "../utils";
 
 /**
  * Name of the comment tag that can be used to mark a module as the target module within the bundle.
@@ -38,19 +44,11 @@ export class ModuleBundle {
      * Merges the modules of the bundle into one module.
      */
     public merge(): void {
-        const childrenOfAllModules = this.modules
-            .map((m) => m.children)
-            .filter((m): m is DeclarationReflection[] => m !== undefined)
-            .reduce((acc, val) => acc.concat(val), []);
-
         // get target module
         const targetModule = this.getTargetModule();
         removeTagFromCommentsOf(targetModule, targetModuleCommentTag);
 
-        // set target module for all children
-        childrenOfAllModules.forEach((child) => (child.parent = targetModule));
-        targetModule.children = childrenOfAllModules;
-
+        this.mergeChildrenAndDocumentsIntoTargetModule(targetModule);
         this.mergeCategoriesIntoTargetModule(targetModule);
         this.mergeGroupsIntoTargetModule(targetModule);
 
@@ -89,6 +87,48 @@ export class ModuleBundle {
         return this.modules[0];
     }
 
+    private mergeChildrenAndDocumentsIntoTargetModule(targetModule: DeclarationReflection): void {
+        for (const mod of this.modules) {
+            // Here we create a copy because the next loop modifies the collection
+            const reflections = [...(mod.childrenIncludingDocuments ?? [])];
+
+            for (const ref of reflections) {
+                // Drop aliases (= ReflectionKind.Reference)
+                if (ref instanceof DeclarationReflection && !ref.kindOf(ReflectionKind.Reference)) {
+                    this.moveDeclarationReflectionToTargetModule(ref, targetModule);
+                } else if (ref instanceof DocumentReflection) {
+                    this.moveDocumentReflectionToTargetModule(ref, targetModule);
+                }
+            }
+        }
+    }
+
+    /**
+     * Moves a declaration reflection to the given target module.
+     * @param ref The declaration reflection that should be moved.
+     * @param targetModule The target module into which the declaration reflection should be moved.
+     */
+    // eslint-disable-next-line class-methods-use-this
+    private moveDeclarationReflectionToTargetModule(
+        ref: DeclarationReflection,
+        targetModule: DeclarationReflection,
+    ): void {
+        removeDeclarationReflectionFromModule(ref);
+        addDeclarationReflectionToTarget(ref, targetModule);
+    }
+
+    /**
+     * Moves a document reflection to the given target module.
+     * @param ref The document reflection that should be moved.
+     * @param targetModule The target module into which the document reflection should be moved.
+     * @throws {Error} If the given reflection is not within a module.
+     */
+    // eslint-disable-next-line class-methods-use-this
+    private moveDocumentReflectionToTargetModule(ref: DocumentReflection, targetModule: DeclarationReflection): void {
+        removeDocumentReflectionFromModule(ref);
+        addDocumentReflectionToTarget(ref, targetModule);
+    }
+
     /**
      * Merges the children from all modules' categories into the corresponding category of the given target module.
      * @param targetModule The target module into whoes categories the children should be merged.

src/merger/project_merger.ts

@@ -1,5 +1,11 @@
 /** @module merger */
-import { ProjectReflection, ReflectionKind } from "typedoc";
+import { DeclarationReflection, DocumentReflection, ProjectReflection, ReflectionKind } from "typedoc";
+import {
+    addDeclarationReflectionToTarget,
+    addDocumentReflectionToTarget,
+    removeDeclarationReflectionFromModule,
+    removeDocumentReflectionFromModule,
+} from "../utils";
 
 /**
  * Merger that moves the content of all modules into the project root.
@@ -23,22 +29,50 @@ export class ProjectMerger {
         const modules = (this.project.children ?? []).filter((c) => c.kindOf(ReflectionKind.Module));
 
         if (modules.length > 0) {
-            this.project.children = [];
+            this.clearProject();
 
             for (const mod of modules) {
-                const reflections = mod.children ?? [];
+                // Here we create a copy because the next loop modifies the collection
+                const reflections = [...(mod.childrenIncludingDocuments ?? [])];
 
                 for (const ref of reflections) {
-                    // Drop aliases
-                    if (!ref.kindOf(ReflectionKind.Reference)) {
-                        ref.parent = this.project;
-                        this.project.children.push(ref);
+                    // Drop aliases (= ReflectionKind.Reference)
+                    if (ref instanceof DeclarationReflection && !ref.kindOf(ReflectionKind.Reference)) {
+                        this.moveDeclarationReflectionToProject(ref);
+                    } else if (ref instanceof DocumentReflection) {
+                        this.moveDocumentReflectionFromToProject(ref);
                     }
                 }
-
-                delete mod.children;
-                this.project.removeReflection(mod);
             }
         }
     }
+
+    /**
+     * Removes all children and documents from the project reflection.
+     */
+    private clearProject(): void {
+        this.project.children = [];
+        this.project.documents = [];
+        this.project.childrenIncludingDocuments = [];
+        this.project.children.forEach((child) => this.project.removeReflection(child));
+    }
+
+    /**
+     * Moves a declaration reflection to the project root.
+     * @param ref The declaration reflection that should be moved.
+     */
+    private moveDeclarationReflectionToProject(ref: DeclarationReflection): void {
+        removeDeclarationReflectionFromModule(ref);
+        addDeclarationReflectionToTarget(ref, this.project);
+    }
+
+    /**
+     * Moves a document reflection to the project root.
+     * @param ref The document reflection that should be moved.
+     * @throws {Error} If the given reflection is not within a module.
+     */
+    private moveDocumentReflectionFromToProject(ref: DocumentReflection): void {
+        removeDocumentReflectionFromModule(ref);
+        addDocumentReflectionToTarget(ref, this.project);
+    }
 }

src/plugin.ts

@@ -47,7 +47,7 @@ export class Plugin {
      * @param typedoc The TypeDoc application.
      */
     private subscribeToApplicationEvents(typedoc: Readonly<Application>): void {
-        typedoc.on(Application.EVENT_BOOTSTRAP_END, (c: Readonly<Context>) => this.onApplicationBootstrapEnd(c));
+        typedoc.on(Application.EVENT_BOOTSTRAP_END, (a: Readonly<Application>) => this.onApplicationBootstrapEnd(a));
         typedoc.converter.on(Converter.EVENT_CREATE_DECLARATION, (c: Readonly<Context>, r: DeclarationReflection) =>
             this.onConverterCreateDeclaration(c, r),
         );
@@ -60,18 +60,20 @@ export class Plugin {
             typedoc.entryPointStrategy === EntryPointStrategy.Packages;
 
         if (typeDocUsesMultipleConverters) {
-            typedoc.on(Application.EVENT_PROJECT_REVIVE, (c: Readonly<Context>) => this.onConvertersDone(c));
+            typedoc.on(Application.EVENT_PROJECT_REVIVE, (p: ProjectReflection) => this.onConvertersDone(p));
         } else {
-            typedoc.converter.on(Converter.EVENT_RESOLVE_BEGIN, (c: Readonly<Context>) => this.onConvertersDone(c));
+            typedoc.converter.on(Converter.EVENT_RESOLVE_BEGIN, (c: Readonly<Context>) =>
+                this.onConvertersDone(c.project),
+            );
         }
     }
 
     /**
      * Triggered after plugins have been loaded and options have been read.
-     * @param context Describes the current state the converter is in.
+     * @param typedoc The TypeDoc application.
      */
-    public onApplicationBootstrapEnd(context: Readonly<Context>): void {
-        this.options.readValuesFromApplication(context.converter.owner);
+    public onApplicationBootstrapEnd(typedoc: Readonly<Application>): void {
+        this.options.readValuesFromApplication(typedoc);
     }
 
     /**
@@ -103,11 +105,11 @@ export class Plugin {
 
     /**
      * Triggered after all converters are done.
-     * @param context Describes the current state the converter is in.
+     * @param project The project on which the event is triggered.
      */
-    public onConvertersDone(context: Readonly<Context>): void {
+    public onConvertersDone(project: ProjectReflection): void {
         if (this.isEnabled) {
-            this.createMerger(context.project)?.execute();
+            this.createMerger(project)?.execute();
         }
     }