typedoc 0.26.10 → 0.27.0-beta.0

package/dist/lib/converter/plugins/IncludePlugin.d.ts

@@ -0,0 +1,11 @@
+import { ConverterComponent } from "../components.js";
+import type { Converter } from "../converter.js";
+/**
+ * Handles `@include` and `@includeCode` within comments/documents.
+ */
+export declare class IncludePlugin extends ConverterComponent {
+    get logger(): import("../../utils/loggers.js").Logger;
+    constructor(owner: Converter);
+    private onCreate;
+    private checkIncludeTagsParts;
+}

package/dist/lib/converter/plugins/IncludePlugin.js

@@ -0,0 +1,72 @@
+import path from "path";
+import fs from "fs";
+import { ConverterComponent } from "../components.js";
+import { ConverterEvents } from "../converter-events.js";
+import { MinimalSourceFile } from "../../utils/minimalSourceFile.js";
+import { isFile } from "../../utils/fs.js";
+/**
+ * Handles `@include` and `@includeCode` within comments/documents.
+ */
+export class IncludePlugin extends ConverterComponent {
+    get logger() {
+        return this.application.logger;
+    }
+    constructor(owner) {
+        super(owner);
+        const onCreate = this.onCreate.bind(this);
+        owner.on(ConverterEvents.CREATE_DOCUMENT, onCreate);
+        owner.on(ConverterEvents.CREATE_DECLARATION, onCreate);
+        owner.on(ConverterEvents.CREATE_PARAMETER, onCreate);
+        owner.on(ConverterEvents.CREATE_SIGNATURE, onCreate);
+        owner.on(ConverterEvents.CREATE_TYPE_PARAMETER, onCreate);
+    }
+    onCreate(_context, refl) {
+        if (refl.isDocument()) {
+            // We know it must be present as documents are always associated with a file.
+            const relative = this.application.files.getReflectionPath(refl);
+            this.checkIncludeTagsParts(refl, path.dirname(relative), refl.content);
+        }
+        if (!refl.comment?.sourcePath)
+            return;
+        const relative = path.dirname(refl.comment.sourcePath);
+        this.checkIncludeTagsParts(refl, relative, refl.comment.summary);
+        for (const tag of refl.comment.blockTags) {
+            this.checkIncludeTagsParts(refl, relative, tag.content);
+        }
+    }
+    checkIncludeTagsParts(refl, relative, parts, included = []) {
+        for (let i = 0; i < parts.length; ++i) {
+            const part = parts[i];
+            if (part.kind !== "inline-tag" ||
+                !["@include", "@includeCode"].includes(part.tag)) {
+                continue;
+            }
+            const file = path.resolve(relative, part.text.trim());
+            if (included.includes(file) && part.tag === "@include") {
+                this.logger.error(this.logger.i18n.include_0_in_1_specified_2_circular_include_3(part.tag, refl.getFriendlyFullName(), part.text, included.join("\n\t")));
+            }
+            else if (isFile(file)) {
+                const text = fs.readFileSync(file, "utf-8");
+                if (part.tag === "@include") {
+                    const sf = new MinimalSourceFile(text, file);
+                    const { content } = this.owner.parseRawComment(sf, refl.project.files);
+                    this.checkIncludeTagsParts(refl, path.dirname(file), content, [...included, file]);
+                    parts.splice(i, 1, ...content);
+                }
+                else {
+                    parts[i] = {
+                        kind: "code",
+                        text: makeCodeBlock(path.extname(file).substring(1), text),
+                    };
+                }
+            }
+            else {
+                this.logger.warn(this.logger.i18n.include_0_in_1_specified_2_resolved_to_3_does_not_exist(part.tag, refl.getFriendlyFullName(), part.text, file));
+            }
+        }
+    }
+}
+function makeCodeBlock(lang, code) {
+    const escaped = code.replace(/`(?=`)/g, "`\u200B");
+    return "\n\n```" + lang + "\n" + escaped.trimEnd() + "\n```";
+}

package/dist/lib/converter/plugins/InheritDocPlugin.d.ts

@@ -1,5 +1,6 @@
-import { ConverterComponent } from "../components";
-import { type ValidationOptions } from "../../utils";
+import { ConverterComponent } from "../components.js";
+import { type ValidationOptions } from "../../utils/index.js";
+import type { Converter } from "../converter.js";
 /**
  * A plugin that handles `@inheritDoc` tags by copying documentation from another API item.
  * It is NOT responsible for handling bare JSDoc style `@inheritDoc` tags which do not specify
@@ -19,7 +20,7 @@ export declare class InheritDocPlugin extends ConverterComponent {
     /**
      * Create a new InheritDocPlugin instance.
      */
-    initialize(): void;
+    constructor(owner: Converter);
     /**
      * Traverse through reflection descendant to check for `inheritDoc` tag.
      * If encountered, the parameter of the tag is used to determine a source reflection

package/dist/lib/converter/plugins/InheritDocPlugin.js

@@ -1,4 +1,3 @@
-"use strict";
 var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
     function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
     var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
@@ -33,31 +32,14 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     }
     return useValue ? value : void 0;
 };
-var __setFunctionName = (this && this.__setFunctionName) || function (f, name, prefix) {
-    if (typeof name === "symbol") name = name.description ? "[".concat(name.description, "]") : "";
-    return Object.defineProperty(f, "name", { configurable: true, value: prefix ? "".concat(prefix, " ", name) : name });
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InheritDocPlugin = void 0;
-const models_1 = require("../../models");
-const components_1 = require("../components");
-const converter_1 = require("../converter");
-const utils_1 = require("../../utils");
-const array_1 = require("../../utils/array");
-const declarationReference_1 = require("../comments/declarationReference");
-const declarationReferenceResolver_1 = require("../comments/declarationReferenceResolver");
-const application_events_1 = require("../../application-events");
+import { Comment, DeclarationReflection, ReflectionKind, ReflectionType, SignatureReflection, } from "../../models/index.js";
+import { ConverterComponent } from "../components.js";
+import { Option, DefaultMap, } from "../../utils/index.js";
+import { zip } from "../../utils/array.js";
+import { parseDeclarationReference } from "../comments/declarationReference.js";
+import { resolveDeclarationReference } from "../comments/declarationReferenceResolver.js";
+import { ApplicationEvents } from "../../application-events.js";
+import { ConverterEvents } from "../converter-events.js";
 /**
  * A plugin that handles `@inheritDoc` tags by copying documentation from another API item.
  * It is NOT responsible for handling bare JSDoc style `@inheritDoc` tags which do not specify
@@ -72,30 +54,29 @@ const application_events_1 = require("../../application-events");
  * - `@return` block
  */
 let InheritDocPlugin = (() => {
-    var _InheritDocPlugin_validation_accessor_storage;
-    let _classDecorators = [(0, components_1.Component)({ name: "inheritDoc" })];
-    let _classDescriptor;
-    let _classExtraInitializers = [];
-    let _classThis;
-    let _classSuper = components_1.ConverterComponent;
+    let _classSuper = ConverterComponent;
     let _validation_decorators;
     let _validation_initializers = [];
     let _validation_extraInitializers = [];
-    var InheritDocPlugin = _classThis = class extends _classSuper {
-        constructor() {
-            super(...arguments);
-            _InheritDocPlugin_validation_accessor_storage.set(this, __runInitializers(this, _validation_initializers, void 0));
-            // Key is depended on by Values
-            this.dependencies = (__runInitializers(this, _validation_extraInitializers), new utils_1.DefaultMap(() => []));
+    return class InheritDocPlugin extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _validation_decorators = [Option("validation")];
+            __esDecorate(this, null, _validation_decorators, { kind: "accessor", name: "validation", static: false, private: false, access: { has: obj => "validation" in obj, get: obj => obj.validation, set: (obj, value) => { obj.validation = value; } }, metadata: _metadata }, _validation_initializers, _validation_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        get validation() { return __classPrivateFieldGet(this, _InheritDocPlugin_validation_accessor_storage, "f"); }
-        set validation(value) { __classPrivateFieldSet(this, _InheritDocPlugin_validation_accessor_storage, value, "f"); }
+        #validation_accessor_storage = __runInitializers(this, _validation_initializers, void 0);
+        get validation() { return this.#validation_accessor_storage; }
+        set validation(value) { this.#validation_accessor_storage = value; }
+        // Key is depended on by Values
+        dependencies = (__runInitializers(this, _validation_extraInitializers), new DefaultMap(() => []));
         /**
          * Create a new InheritDocPlugin instance.
          */
-        initialize() {
-            this.owner.on(converter_1.Converter.EVENT_RESOLVE_END, (context) => this.processInheritDoc(context.project));
-            this.application.on(application_events_1.ApplicationEvents.REVIVE, this.processInheritDoc.bind(this));
+        constructor(owner) {
+            super(owner);
+            this.owner.on(ConverterEvents.RESOLVE_END, (context) => this.processInheritDoc(context.project));
+            this.application.on(ApplicationEvents.REVIVE, this.processInheritDoc.bind(this));
         }
         /**
          * Traverse through reflection descendant to check for `inheritDoc` tag.
@@ -108,18 +89,18 @@ let InheritDocPlugin = (() => {
                 const source = extractInheritDocTagReference(reflection);
                 if (!source)
                     continue;
-                const declRef = (0, declarationReference_1.parseDeclarationReference)(source, 0, source.length);
+                const declRef = parseDeclarationReference(source, 0, source.length);
                 if (!declRef || /\S/.test(source.substring(declRef[1]))) {
                     this.application.logger.warn(this.application.i18n.declaration_reference_in_inheritdoc_for_0_not_fully_parsed(reflection.getFriendlyFullName()));
                 }
-                let sourceRefl = declRef && (0, declarationReferenceResolver_1.resolveDeclarationReference)(reflection, declRef[0]);
-                if (reflection instanceof models_1.SignatureReflection) {
+                let sourceRefl = declRef && resolveDeclarationReference(reflection, declRef[0]);
+                if (reflection instanceof SignatureReflection) {
                     // Assumes that if there are overloads, they are declared in the same order as the parent.
                     // TS doesn't check this, but if a user messes this up then they are almost
                     // guaranteed to run into bugs where they can't call a method on a child class
                     // but if they assign (without a type assertion) that child to a variable of the parent class
                     // then they can call the method.
-                    if (sourceRefl instanceof models_1.DeclarationReflection) {
+                    if (sourceRefl instanceof DeclarationReflection) {
                         const index = reflection.parent
                             .getAllSignatures()
                             .indexOf(reflection);
@@ -127,8 +108,8 @@ let InheritDocPlugin = (() => {
                             sourceRefl.getAllSignatures()[index] || sourceRefl;
                     }
                 }
-                if (sourceRefl instanceof models_1.DeclarationReflection &&
-                    sourceRefl.kindOf(models_1.ReflectionKind.Accessor)) {
+                if (sourceRefl instanceof DeclarationReflection &&
+                    sourceRefl.kindOf(ReflectionKind.Accessor)) {
                     // Accessors, like functions, never have comments on their actual root reflection.
                     // If the user didn't specify whether to inherit from the getter or setter, then implicitly
                     // try to inherit from the getter, #1968.
@@ -149,13 +130,13 @@ let InheritDocPlugin = (() => {
             if (!target.comment)
                 return;
             if (!source.comment &&
-                source instanceof models_1.DeclarationReflection &&
+                source instanceof DeclarationReflection &&
                 source.signatures) {
                 source = source.signatures[0];
             }
             if (!source.comment &&
-                source instanceof models_1.DeclarationReflection &&
-                source.type instanceof models_1.ReflectionType &&
+                source instanceof DeclarationReflection &&
+                source.type instanceof ReflectionType &&
                 source.type.declaration.signatures) {
                 source = source.type.declaration.signatures[0];
             }
@@ -170,7 +151,7 @@ let InheritDocPlugin = (() => {
                 return;
             }
             target.comment.removeTags("@inheritDoc");
-            target.comment.summary = models_1.Comment.cloneDisplayParts(source.comment.summary);
+            target.comment.summary = Comment.cloneDisplayParts(source.comment.summary);
             const remarks = source.comment.getTag("@remarks");
             if (remarks) {
                 target.comment.blockTags.unshift(remarks.clone());
@@ -179,13 +160,13 @@ let InheritDocPlugin = (() => {
             if (returns) {
                 target.comment.blockTags.push(returns.clone());
             }
-            if (source instanceof models_1.SignatureReflection &&
-                target instanceof models_1.SignatureReflection) {
+            if (source instanceof SignatureReflection &&
+                target instanceof SignatureReflection) {
                 copySummaries(source.parameters, target.parameters);
                 copySummaries(source.typeParameters, target.typeParameters);
             }
-            else if (source instanceof models_1.DeclarationReflection &&
-                target instanceof models_1.DeclarationReflection) {
+            else if (source instanceof DeclarationReflection &&
+                target instanceof DeclarationReflection) {
                 copySummaries(source.typeParameters, target.typeParameters);
             }
             // Now copy the comment for anyone who depends on me.
@@ -216,23 +197,11 @@ let InheritDocPlugin = (() => {
             }
         }
     };
-    _InheritDocPlugin_validation_accessor_storage = new WeakMap();
-    __setFunctionName(_classThis, "InheritDocPlugin");
-    (() => {
-        const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-        _validation_decorators = [(0, utils_1.Option)("validation")];
-        __esDecorate(_classThis, null, _validation_decorators, { kind: "accessor", name: "validation", static: false, private: false, access: { has: obj => "validation" in obj, get: obj => obj.validation, set: (obj, value) => { obj.validation = value; } }, metadata: _metadata }, _validation_initializers, _validation_extraInitializers);
-        __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
-        InheritDocPlugin = _classThis = _classDescriptor.value;
-        if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-        __runInitializers(_classThis, _classExtraInitializers);
-    })();
-    return InheritDocPlugin = _classThis;
 })();
-exports.InheritDocPlugin = InheritDocPlugin;
+export { InheritDocPlugin };
 function copySummaries(source, target) {
-    for (const [s, t] of (0, array_1.zip)(source || [], target || [])) {
-        t.comment = new models_1.Comment(s.comment?.summary);
+    for (const [s, t] of zip(source || [], target || [])) {
+        t.comment = new Comment(s.comment?.summary);
         t.comment.sourcePath = s.comment?.sourcePath;
     }
 }

package/dist/lib/converter/plugins/LinkResolverPlugin.d.ts

@@ -1,13 +1,13 @@
-import { ConverterComponent } from "../components";
-import type { Context } from "../../converter";
-import { type ValidationOptions } from "../../utils";
-import { type ProjectReflection } from "../../models";
+import { ConverterComponent } from "../components.js";
+import type { Context, Converter } from "../../converter/index.js";
+import { type ValidationOptions } from "../../utils/index.js";
+import { type ProjectReflection } from "../../models/index.js";
 /**
  * A plugin that resolves `{@link Foo}` tags.
  */
 export declare class LinkResolverPlugin extends ConverterComponent {
     accessor validation: ValidationOptions;
-    initialize(): void;
+    constructor(owner: Converter);
     onResolve(context: Context): void;
     resolveLinks(project: ProjectReflection): void;
     private resolveCategoryLinks;

package/dist/lib/converter/plugins/LinkResolverPlugin.js

@@ -1,4 +1,3 @@
-"use strict";
 var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
     function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
     var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
@@ -33,49 +32,35 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     }
     return useValue ? value : void 0;
 };
-var __setFunctionName = (this && this.__setFunctionName) || function (f, name, prefix) {
-    if (typeof name === "symbol") name = name.description ? "[".concat(name.description, "]") : "";
-    return Object.defineProperty(f, "name", { configurable: true, value: prefix ? "".concat(prefix, " ", name) : name });
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LinkResolverPlugin = void 0;
-const components_1 = require("../components");
-const converter_events_1 = require("../converter-events");
-const utils_1 = require("../../utils");
-const models_1 = require("../../models");
-const reflections_1 = require("../../utils/reflections");
-const application_events_1 = require("../../application-events");
+import { ConverterComponent } from "../components.js";
+import { ConverterEvents } from "../converter-events.js";
+import { Option } from "../../utils/index.js";
+import { ContainerReflection, makeRecursiveVisitor, } from "../../models/index.js";
+import { discoverAllReferenceTypes } from "../../utils/reflections.js";
+import { ApplicationEvents } from "../../application-events.js";
 /**
  * A plugin that resolves `{@link Foo}` tags.
  */
 let LinkResolverPlugin = (() => {
-    var _LinkResolverPlugin_validation_accessor_storage;
-    let _classDecorators = [(0, components_1.Component)({ name: "link-resolver" })];
-    let _classDescriptor;
-    let _classExtraInitializers = [];
-    let _classThis;
-    let _classSuper = components_1.ConverterComponent;
+    let _classSuper = ConverterComponent;
     let _validation_decorators;
     let _validation_initializers = [];
     let _validation_extraInitializers = [];
-    var LinkResolverPlugin = _classThis = class extends _classSuper {
-        get validation() { return __classPrivateFieldGet(this, _LinkResolverPlugin_validation_accessor_storage, "f"); }
-        set validation(value) { __classPrivateFieldSet(this, _LinkResolverPlugin_validation_accessor_storage, value, "f"); }
-        initialize() {
-            super.initialize();
-            this.owner.on(converter_events_1.ConverterEvents.RESOLVE_END, this.onResolve.bind(this), -300);
-            this.application.on(application_events_1.ApplicationEvents.REVIVE, this.resolveLinks.bind(this), -300);
+    return class LinkResolverPlugin extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _validation_decorators = [Option("validation")];
+            __esDecorate(this, null, _validation_decorators, { kind: "accessor", name: "validation", static: false, private: false, access: { has: obj => "validation" in obj, get: obj => obj.validation, set: (obj, value) => { obj.validation = value; } }, metadata: _metadata }, _validation_initializers, _validation_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        #validation_accessor_storage = __runInitializers(this, _validation_initializers, void 0);
+        get validation() { return this.#validation_accessor_storage; }
+        set validation(value) { this.#validation_accessor_storage = value; }
+        constructor(owner) {
+            super(owner);
+            __runInitializers(this, _validation_extraInitializers);
+            this.owner.on(ConverterEvents.RESOLVE_END, this.onResolve.bind(this), -300);
+            this.application.on(ApplicationEvents.REVIVE, this.resolveLinks.bind(this), -300);
         }
         onResolve(context) {
             this.resolveLinks(context.project);
@@ -87,7 +72,7 @@ let LinkResolverPlugin = (() => {
                     this.owner.resolveLinks(reflection.comment, reflection);
                 }
                 if (reflection.isDeclaration()) {
-                    reflection.type?.visit((0, models_1.makeRecursiveVisitor)({
+                    reflection.type?.visit(makeRecursiveVisitor({
                         union: (type) => {
                             type.elementSummaries = type.elementSummaries?.map((parts) => this.owner.resolveLinks(parts, reflection));
                         },
@@ -99,7 +84,18 @@ let LinkResolverPlugin = (() => {
                 if (reflection.isDocument()) {
                     reflection.content = this.owner.resolveLinks(reflection.content, reflection);
                 }
-                if (reflection instanceof models_1.ContainerReflection) {
+                if (reflection.isParameter() &&
+                    reflection.type?.type === "reference" &&
+                    reflection.type.highlightedProperties) {
+                    const resolved = new Map(Array.from(reflection.type.highlightedProperties, ([name, parts]) => {
+                        return [
+                            name,
+                            this.owner.resolveLinks(parts, reflection),
+                        ];
+                    }));
+                    reflection.type.highlightedProperties = resolved;
+                }
+                if (reflection instanceof ContainerReflection) {
                     if (reflection.groups) {
                         for (const group of reflection.groups) {
                             if (group.description) {
@@ -122,7 +118,7 @@ let LinkResolverPlugin = (() => {
             if (project.readme) {
                 project.readme = this.owner.resolveLinks(project.readme, project);
             }
-            for (const { type, owner } of (0, reflections_1.discoverAllReferenceTypes)(project, false)) {
+            for (const { type, owner } of discoverAllReferenceTypes(project, false)) {
                 if (!type.reflection) {
                     const resolveResult = this.owner.resolveExternalLink(type.toDeclarationReference(), owner, undefined, type.symbolId);
                     switch (typeof resolveResult) {
@@ -141,23 +137,6 @@ let LinkResolverPlugin = (() => {
                 category.description = this.owner.resolveLinks(category.description, owner);
             }
         }
-        constructor() {
-            super(...arguments);
-            _LinkResolverPlugin_validation_accessor_storage.set(this, __runInitializers(this, _validation_initializers, void 0));
-            __runInitializers(this, _validation_extraInitializers);
-        }
     };
-    _LinkResolverPlugin_validation_accessor_storage = new WeakMap();
-    __setFunctionName(_classThis, "LinkResolverPlugin");
-    (() => {
-        const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-        _validation_decorators = [(0, utils_1.Option)("validation")];
-        __esDecorate(_classThis, null, _validation_decorators, { kind: "accessor", name: "validation", static: false, private: false, access: { has: obj => "validation" in obj, get: obj => obj.validation, set: (obj, value) => { obj.validation = value; } }, metadata: _metadata }, _validation_initializers, _validation_extraInitializers);
-        __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
-        LinkResolverPlugin = _classThis = _classDescriptor.value;
-        if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-        __runInitializers(_classThis, _classExtraInitializers);
-    })();
-    return LinkResolverPlugin = _classThis;
 })();
-exports.LinkResolverPlugin = LinkResolverPlugin;
+export { LinkResolverPlugin };

package/dist/lib/converter/plugins/MergeModuleWithPlugin.d.ts

@@ -0,0 +1,12 @@
+import { ConverterComponent } from "../components.js";
+import type { Converter } from "../converter.js";
+/**
+ * Handles `@mergeModuleWith` tags in comments
+ * Warnings if resolution failed are emitted during the validation step, not here.
+ */
+export declare class MergeModuleWithPlugin extends ConverterComponent {
+    constructor(owner: Converter);
+    private onResolveBegin;
+    private onRevive;
+    private checkAndMerge;
+}

package/dist/lib/converter/plugins/MergeModuleWithPlugin.js

@@ -0,0 +1,49 @@
+import { ok } from "assert";
+import { ApplicationEvents } from "../../application-events.js";
+import { Comment, ReflectionKind, } from "../../models/index.js";
+import { ConverterComponent } from "../components.js";
+import { ConverterEvents } from "../converter-events.js";
+/**
+ * Handles `@mergeModuleWith` tags in comments
+ * Warnings if resolution failed are emitted during the validation step, not here.
+ */
+export class MergeModuleWithPlugin extends ConverterComponent {
+    constructor(owner) {
+        super(owner);
+        // Note: This happens before grouping/categorizing
+        this.owner.on(ConverterEvents.RESOLVE_BEGIN, this.onResolveBegin.bind(this), 10000);
+        this.application.on(ApplicationEvents.REVIVE, this.onRevive.bind(this), 10000);
+    }
+    onResolveBegin(context) {
+        this.onRevive(context.project);
+    }
+    onRevive(project) {
+        const mods = project.getReflectionsByKind(ReflectionKind.SomeModule);
+        for (const refl of mods) {
+            this.checkAndMerge(refl);
+        }
+    }
+    checkAndMerge(refl) {
+        ok(refl.isDeclaration());
+        const tag = refl.comment?.getTag("@mergeModuleWith");
+        if (!tag)
+            return;
+        const project = refl.project;
+        const targetStr = Comment.combineDisplayParts(tag.content);
+        const target = targetStr === "<project>"
+            ? project
+            : project.getChildByName(targetStr);
+        if (!target?.isDeclaration() && !target?.isProject()) {
+            return;
+        }
+        let tempRefl = refl;
+        while (tempRefl !== project) {
+            if (tempRefl === target) {
+                this.application.logger.warn(this.application.i18n.reflection_0_tried_to_merge_into_child_1(refl.getFriendlyFullName(), target.getFriendlyFullName()));
+            }
+            tempRefl = refl.parent;
+        }
+        this.application.logger.verbose(`Merging ${refl.getFullName()} into ${target.getFullName()}`);
+        project.mergeModules(refl, target);
+    }
+}

package/dist/lib/converter/plugins/PackagePlugin.d.ts

@@ -1,5 +1,6 @@
-import { ConverterComponent } from "../components";
-import { EntryPointStrategy } from "../../utils";
+import { ConverterComponent } from "../components.js";
+import { EntryPointStrategy } from "../../utils/index.js";
+import type { Converter } from "../converter.js";
 /**
  * A handler that tries to find the package.json and readme.md files of the
  * current project.
@@ -21,7 +22,7 @@ export declare class PackagePlugin extends ConverterComponent {
      * Contents of package.json for the active project
      */
     private packageJson?;
-    initialize(): void;
+    constructor(owner: Converter);
     private onRevive;
     private onBegin;
     private onBeginResolve;