@depup/typedoc 0.28.17-depup.0

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

@@ -0,0 +1,254 @@
+import path from "path";
+import { ConverterComponent } from "../components.js";
+import { ConverterEvents } from "../converter-events.js";
+import { MinimalSourceFile } from "#utils";
+import { isFile, readFile } from "../../utils/fs.js";
+import { dedent, escapeRegExp, i18n } from "#utils";
+import { normalizePath } from "#node-utils";
+/**
+ * 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_PROJECT, onCreate);
+        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 { filename, regionTarget, requestedLines } = parseIncludeCodeTextPart(part.text);
+            const file = normalizePath(path.resolve(relative, filename));
+            this.application.watchFile(file);
+            if (included.includes(file) && part.tag === "@include") {
+                this.logger.error(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 = readFile(file).replaceAll("\r\n", "\n");
+                const ext = path.extname(file).substring(1);
+                const includedText = regionTarget
+                    ? this.getRegions(refl, file, ext, part.text, text, regionTarget, part.tag, part.tag === "@includeCode")
+                    : requestedLines
+                        ? this.getLines(refl, file, part.text, text, requestedLines, part.tag)
+                        : text;
+                if (part.tag === "@include") {
+                    const sf = new MinimalSourceFile(includedText, 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(ext, includedText),
+                    };
+                }
+            }
+            else {
+                this.logger.error(i18n.include_0_in_1_specified_2_resolved_to_3_does_not_exist(part.tag, refl.getFriendlyFullName(), part.text, file));
+            }
+        }
+    }
+    getRegions(refl, file, ext, textPart, text, regionTargets, tag, ignoreIndent) {
+        const regionTagsList = regionTagREsByExt[ext];
+        if (!regionTagsList) {
+            this.logger.error(i18n.include_0_tag_in_1_region_2_region_not_supported(tag, refl.getFriendlyFullName(), textPart));
+            return "";
+        }
+        const targets = regionTargets.split(",").map((s) => s.trim());
+        let content = "";
+        for (const target of targets) {
+            let found = false;
+            for (const [startTag, endTag] of regionTagsList) {
+                const safeTarget = escapeRegExp(target);
+                const start = text.match(startTag(safeTarget));
+                const end = text.match(endTag(safeTarget));
+                const foundStart = start && start.length > 0;
+                const foundEnd = end && end.length > 0;
+                if (foundStart && !foundEnd) {
+                    this.logger.error(i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_close_not_found(tag, refl.getFriendlyFullName(), textPart, file, target));
+                    return "";
+                }
+                if (!foundStart && foundEnd) {
+                    this.logger.error(i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_open_not_found(tag, refl.getFriendlyFullName(), textPart, file, target));
+                    return "";
+                }
+                if (foundStart && foundEnd) {
+                    if (start.length > 1) {
+                        this.logger.error(i18n
+                            .include_0_tag_in_1_specified_2_file_3_region_4_region_open_found_multiple_times(tag, refl.getFriendlyFullName(), textPart, file, target));
+                        return "";
+                    }
+                    if (end.length > 1) {
+                        this.logger.error(i18n
+                            .include_0_tag_in_1_specified_2_file_3_region_4_region_close_found_multiple_times(tag, refl.getFriendlyFullName(), textPart, file, target));
+                        return "";
+                    }
+                    if (found) {
+                        this.logger.error(i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_found_multiple_times(tag, refl.getFriendlyFullName(), textPart, file, target));
+                        return "";
+                    }
+                    found = text.substring(text.indexOf(start[0]) + start[0].length, text.indexOf(end[0]));
+                }
+            }
+            if (found === false) {
+                this.logger.error(i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_not_found(tag, refl.getFriendlyFullName(), textPart, file, target));
+                return "";
+            }
+            if (found.trim() === "") {
+                this.logger.warn(i18n.include_0_tag_in_1_specified_2_file_3_region_4_region_empty(tag, refl.getFriendlyFullName(), textPart, file, target));
+            }
+            content += ignoreIndent ? dedent(found) + "\n" : found;
+        }
+        return content;
+    }
+    getLines(refl, file, textPart, text, requestedLines, tag) {
+        let output = "";
+        const lines = text.split(/\r\n|\r|\n/);
+        requestedLines.split(",").forEach((requestedLineString) => {
+            if (requestedLineString.includes("-")) {
+                const [start, end] = requestedLineString.split("-").map(Number);
+                if (start > end) {
+                    this.logger.error(i18n.include_0_tag_in_1_specified_2_file_3_lines_4_invalid_range(tag, refl.getFriendlyFullName(), textPart, file, requestedLines));
+                    return "";
+                }
+                if (start > lines.length || end > lines.length) {
+                    this.logger.error(i18n.include_0_tag_in_1_specified_2_file_3_lines_4_but_only_5_lines(tag, refl.getFriendlyFullName(), textPart, file, requestedLines, lines.length.toString()));
+                    return "";
+                }
+                output += lines.slice(start - 1, end).join("\n") + "\n";
+            }
+            else {
+                const requestedLine = Number(requestedLineString);
+                if (requestedLine > lines.length) {
+                    this.logger.error(i18n.include_0_tag_in_1_specified_2_file_3_lines_4_but_only_5_lines(tag, refl.getFriendlyFullName(), textPart, file, requestedLines, lines.length.toString()));
+                    return "";
+                }
+                output += lines[requestedLine - 1] + "\n";
+            }
+        });
+        return output;
+    }
+}
+function makeCodeBlock(lang, code) {
+    const escaped = code.replace(/`(?=`)/g, "`\u200B");
+    return "\n\n```" + lang + "\n" + escaped.trimEnd() + "\n```";
+}
+function parseIncludeCodeTextPart(text) {
+    let filename = text.trim();
+    let regionTarget;
+    let requestedLines;
+    if (filename.includes("#")) {
+        const parsed = filename.split("#");
+        filename = parsed[0];
+        regionTarget = parsed[1];
+    }
+    else if (filename.includes(":")) {
+        const parsed = filename.split(":");
+        filename = parsed[0];
+        requestedLines = parsed[1];
+    }
+    return { filename, regionTarget, requestedLines };
+}
+const regionTagREsByExt = {
+    bat: [
+        [
+            (regionName) => new RegExp(`:: *#region  *${regionName} *\n`, "g"),
+            (regionName) => new RegExp(`:: *#endregion  *${regionName} *\n`, "g"),
+        ],
+        [
+            (regionName) => new RegExp(`REM  *#region  *${regionName} *\n`, "g"),
+            (regionName) => new RegExp(`REM  *#endregion  *${regionName} *\n`, "g"),
+        ],
+    ],
+    cs: [
+        [
+            (regionName) => new RegExp(`#region  *${regionName} *\n`, "g"),
+            (regionName) => new RegExp(`#endregion  *${regionName} *\n`, "g"),
+        ],
+    ],
+    c: [
+        [
+            (regionName) => new RegExp(`#pragma  *region  *${regionName} *\n`, "g"),
+            (regionName) => new RegExp(`#pragma  *endregion  *${regionName} *\n`, "g"),
+        ],
+    ],
+    css: [
+        [
+            (regionName) => new RegExp(`/\\* *#region *\\*/  *${regionName} *\n`, "g"),
+            (regionName) => new RegExp(`/\\* *#endregion *\\*/  *${regionName} *\n`, "g"),
+        ],
+    ],
+    md: [
+        [
+            (regionName) => new RegExp(`<!--  *#region  *${regionName} *--> *\n`, "g"),
+            (regionName) => new RegExp(`<!--  *#endregion  *${regionName} *--> *\n`, "g"),
+        ],
+    ],
+    ts: [
+        [
+            (regionName) => new RegExp(`// *#region  *${regionName} *\n`, "g"),
+            (regionName) => new RegExp(`// *#endregion  *${regionName} *\n`, "g"),
+        ],
+    ],
+    vb: [
+        [
+            (regionName) => new RegExp(`#Region  *${regionName} *\n`, "g"),
+            (regionName) => new RegExp(`#End Region  *${regionName} *\n`, "g"),
+        ],
+    ],
+};
+regionTagREsByExt["fs"] = [
+    ...regionTagREsByExt["ts"],
+    [
+        (regionName) => new RegExp(`(#_region)  *${regionName} *\n`, "g"),
+        (regionName) => new RegExp(`(#_endregion)  *${regionName} *\n`, "g"),
+    ],
+];
+regionTagREsByExt["java"] = [
+    ...regionTagREsByExt["ts"],
+    [
+        (regionName) => new RegExp(`// *<editor-fold>  *${regionName} *\n`, "g"),
+        (regionName) => new RegExp(`// *</editor-fold>  *${regionName} *\n`, "g"),
+    ],
+];
+regionTagREsByExt["cpp"] = regionTagREsByExt["c"];
+regionTagREsByExt["less"] = regionTagREsByExt["css"];
+regionTagREsByExt["scss"] = regionTagREsByExt["css"];
+regionTagREsByExt["coffee"] = regionTagREsByExt["cs"];
+regionTagREsByExt["php"] = regionTagREsByExt["cs"];
+regionTagREsByExt["ps1"] = regionTagREsByExt["cs"];
+regionTagREsByExt["py"] = regionTagREsByExt["cs"];
+regionTagREsByExt["js"] = regionTagREsByExt["ts"];
+regionTagREsByExt["mjs"] = regionTagREsByExt["ts"];
+regionTagREsByExt["mts"] = regionTagREsByExt["ts"];
+regionTagREsByExt["cjs"] = regionTagREsByExt["ts"];
+regionTagREsByExt["cts"] = regionTagREsByExt["ts"];
+regionTagREsByExt["jsx"] = regionTagREsByExt["ts"];
+regionTagREsByExt["tsx"] = regionTagREsByExt["ts"];

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

@@ -0,0 +1,32 @@
+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
+ * a target to inherit from. Those are handled by the ImplementsPlugin class.
+ *
+ * What gets copied:
+ * - short text
+ * - text
+ * - `@remarks` block
+ * - `@params` block
+ * - `@typeParam` block
+ * - `@return` block
+ */
+export declare class InheritDocPlugin extends ConverterComponent {
+    accessor validation: ValidationOptions;
+    private dependencies;
+    /**
+     * Create a new InheritDocPlugin instance.
+     */
+    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
+     * that will provide actual comment.
+     */
+    private processInheritDoc;
+    private copyComment;
+    private createCircularDependencyWarnings;
+}

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

@@ -0,0 +1,220 @@
+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";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { Comment, DeclarationReflection, ReflectionKind, ReflectionType, SignatureReflection, } from "../../models/index.js";
+import { ConverterComponent } from "../components.js";
+import { Option } from "../../utils/index.js";
+import { DefaultMap, i18n, parseDeclarationReference, zip } from "#utils";
+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
+ * a target to inherit from. Those are handled by the ImplementsPlugin class.
+ *
+ * What gets copied:
+ * - short text
+ * - text
+ * - `@remarks` block
+ * - `@params` block
+ * - `@typeParam` block
+ * - `@return` block
+ */
+let InheritDocPlugin = (() => {
+    let _classSuper = ConverterComponent;
+    let _validation_decorators;
+    let _validation_initializers = [];
+    let _validation_extraInitializers = [];
+    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 });
+        }
+        #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.
+         */
+        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.
+         * If encountered, the parameter of the tag is used to determine a source reflection
+         * that will provide actual comment.
+         */
+        processInheritDoc(project) {
+            for (const id in project.reflections) {
+                const reflection = project.reflections[id];
+                const source = extractInheritDocTagReference(reflection);
+                if (!source)
+                    continue;
+                const declRef = parseDeclarationReference(source, 0, source.length);
+                if (!declRef || /\S/.test(source.substring(declRef[1]))) {
+                    this.application.logger.warn(i18n.declaration_reference_in_inheritdoc_for_0_not_fully_parsed(reflection.getFriendlyFullName()));
+                }
+                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 DeclarationReflection) {
+                        const index = reflection.parent
+                            .getAllSignatures()
+                            .indexOf(reflection);
+                        sourceRefl = sourceRefl.getAllSignatures()[index] || sourceRefl;
+                    }
+                }
+                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.
+                    sourceRefl = sourceRefl.getSignature || sourceRefl.setSignature;
+                }
+                if (!sourceRefl) {
+                    if (this.validation.invalidLink) {
+                        this.application.logger.warn(i18n.failed_to_find_0_to_inherit_comment_from_in_1(source, reflection.getFriendlyFullName()));
+                    }
+                    continue;
+                }
+                this.copyComment(sourceRefl, reflection);
+            }
+            this.createCircularDependencyWarnings();
+            this.dependencies.clear();
+        }
+        copyComment(source, target) {
+            if (!target.comment)
+                return;
+            if (!source.comment &&
+                source instanceof DeclarationReflection &&
+                source.signatures) {
+                source = source.signatures[0];
+            }
+            if (!source.comment &&
+                source instanceof DeclarationReflection &&
+                source.type instanceof ReflectionType &&
+                source.type.declaration.signatures) {
+                source = source.type.declaration.signatures[0];
+            }
+            if (!source.comment) {
+                this.application.logger.warn(i18n.reflection_0_tried_to_copy_comment_from_1_but_source_had_no_comment(target.getFullName(), source.getFullName()));
+                return;
+            }
+            // If the source also has a @inheritDoc tag, we can't do anything yet.
+            // We'll try again later, once we've resolved the source's @inheritDoc reference.
+            if (extractInheritDocTagReference(source)) {
+                this.dependencies.get(source).push(target);
+                return;
+            }
+            target.comment.removeTags("@inheritDoc");
+            target.comment.removeTags("@remarks");
+            target.comment.removeTags("@returns");
+            target.comment.summary = Comment.cloneDisplayParts(source.comment.summary);
+            const remarks = source.comment.getTag("@remarks");
+            if (remarks) {
+                target.comment.blockTags.unshift(remarks.clone());
+            }
+            const returns = source.comment.getTag("@returns");
+            if (returns) {
+                target.comment.blockTags.push(returns.clone());
+            }
+            if (source instanceof SignatureReflection &&
+                target instanceof SignatureReflection) {
+                copySummaries(source.parameters, target.parameters);
+                copySummaries(source.typeParameters, target.typeParameters);
+            }
+            else if (source instanceof DeclarationReflection &&
+                target instanceof DeclarationReflection) {
+                copySummaries(source.typeParameters, target.typeParameters);
+            }
+            // Now copy the comment for anyone who depends on me.
+            const dependent = this.dependencies.get(target);
+            this.dependencies.delete(target);
+            for (const target2 of dependent) {
+                this.copyComment(target, target2);
+            }
+        }
+        createCircularDependencyWarnings() {
+            const unwarned = new Set(this.dependencies.keys());
+            const generateWarning = (orig) => {
+                const parts = [orig.name];
+                unwarned.delete(orig);
+                let work = orig;
+                do {
+                    work = this.dependencies.get(work)[0];
+                    unwarned.delete(work);
+                    parts.push(work.name);
+                } while (!this.dependencies.get(work).includes(orig));
+                parts.push(orig.name);
+                this.application.logger.warn(i18n.inheritdoc_circular_inheritance_chain_0(parts.reverse().join(" -> ")));
+            };
+            for (const orig of this.dependencies.keys()) {
+                if (unwarned.has(orig)) {
+                    generateWarning(orig);
+                }
+            }
+        }
+    };
+})();
+export { InheritDocPlugin };
+function copySummaries(source, target) {
+    for (const [s, t] of zip(source || [], target || [])) {
+        t.comment = new Comment(s.comment?.summary);
+        t.comment.sourcePath = s.comment?.sourcePath;
+    }
+}
+function extractInheritDocTagReference(reflection) {
+    const comment = reflection.comment;
+    if (!comment)
+        return;
+    const blockTag = comment.blockTags.find((tag) => tag.tag === "@inheritDoc");
+    if (blockTag) {
+        return blockTag.name;
+    }
+    const inlineTag = comment.summary.find((part) => part.kind === "inline-tag" && part.tag === "@inheritDoc");
+    if (inlineTag) {
+        return inlineTag.text;
+    }
+}

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

@@ -0,0 +1,13 @@
+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;
+    constructor(owner: Converter);
+    onResolve(context: Context): void;
+    resolveLinks(project: ProjectReflection): void;
+}

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

@@ -0,0 +1,88 @@
+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";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { ConverterComponent } from "../components.js";
+import { ConverterEvents } from "../converter-events.js";
+import { Option } from "../../utils/index.js";
+import { discoverAllReferenceTypes } from "../../utils/reflections.js";
+import { ApplicationEvents } from "../../application-events.js";
+/**
+ * A plugin that resolves `{@link Foo}` tags.
+ */
+let LinkResolverPlugin = (() => {
+    let _classSuper = ConverterComponent;
+    let _validation_decorators;
+    let _validation_initializers = [];
+    let _validation_extraInitializers = [];
+    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);
+        }
+        resolveLinks(project) {
+            for (const id in project.reflections) {
+                const reflection = project.reflections[id];
+                this.owner.resolveLinks(reflection);
+            }
+            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) {
+                        case "string":
+                            type.externalUrl = resolveResult;
+                            break;
+                        case "object":
+                            type.externalUrl = resolveResult.target;
+                            break;
+                    }
+                }
+            }
+        }
+    };
+})();
+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,50 @@
+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";
+import { i18n } from "#utils";
+/**
+ * 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(i18n.reflection_0_tried_to_merge_into_child_1(refl.getFriendlyFullName(), target.getFriendlyFullName()));
+            }
+            tempRefl = tempRefl.parent;
+        }
+        this.application.logger.verbose(`Merging ${refl.getFullName()} into ${target.getFullName()}`);
+        project.mergeReflections(refl, target);
+    }
+}