typedoc 0.28.7 → 0.28.9

package/dist/lib/converter/factories/symbol-id.js

@@ -1,13 +1,12 @@
 import { ReflectionSymbolId } from "#models";
-import { findPackageForPath, getCommonDirectory, getQualifiedName, normalizePath, readFile } from "#node-utils";
-import { Validation } from "#utils";
-import { existsSync } from "fs";
-import { join, relative, resolve } from "node:path";
+import { findPackageForPath, getQualifiedName, normalizePath, resolveDeclarationMaps } from "#node-utils";
+import {} from "#utils";
+import { relative } from "node:path";
 import ts from "typescript";
-const declarationMapCache = new Map();
 let transientCount = 0;
 const transientIds = new WeakMap();
-export function createSymbolId(symbol, declaration) {
+// Don't use this directly, use Context.createSymbolId instead.
+export function createSymbolIdImpl(symbol, declaration) {
     declaration ??= symbol.declarations?.[0];
     const tsSource = declaration?.getSourceFile().fileName ?? "";
     const sourceFileName = resolveDeclarationMaps(tsSource);
@@ -46,48 +45,3 @@ export function createSymbolId(symbol, declaration) {
     id.fileName = normalizePath(sourceFileName);
     return id;
 }
-function resolveDeclarationMaps(file) {
-    if (!/\.d\.[cm]?ts$/.test(file))
-        return file;
-    if (declarationMapCache.has(file))
-        return declarationMapCache.get(file);
-    const mapFile = file + ".map";
-    if (!existsSync(mapFile))
-        return file;
-    let sourceMap;
-    try {
-        sourceMap = JSON.parse(readFile(mapFile));
-    }
-    catch {
-        return file;
-    }
-    if (Validation.validate({
-        file: String,
-        sourceRoot: Validation.optional(String),
-        sources: [Array, String],
-    }, sourceMap)) {
-        // There's a pretty large assumption in here that we only have
-        // 1 source file per js file. This is a pretty standard typescript approach,
-        // but people might do interesting things with transpilation that could break this.
-        let source = sourceMap.sources[0];
-        // If we have a sourceRoot, trim any leading slash from the source, and join them
-        // Similar to how it's done at https://github.com/mozilla/source-map/blob/58819f09018d56ef84dc41ba9c93f554e0645169/lib/util.js#L412
-        if (sourceMap.sourceRoot !== undefined) {
-            source = source.replace(/^\//, "");
-            source = join(sourceMap.sourceRoot, source);
-        }
-        const result = resolve(mapFile, "..", source);
-        declarationMapCache.set(file, result);
-        return result;
-    }
-    return file;
-}
-// See also: inferEntryPoints in entry-point.ts
-export function addInferredDeclarationMapPaths(opts, files) {
-    const rootDir = opts.rootDir || getCommonDirectory(files);
-    const declDir = opts.declarationDir || opts.outDir || rootDir;
-    for (const file of files) {
-        const mapFile = normalizePath(resolve(declDir, relative(rootDir, file)).replace(/\.([cm]?[tj]s)x?$/, ".d.$1"));
-        declarationMapCache.set(mapFile, file);
-    }
-}

package/dist/lib/converter/jsdoc.js

@@ -6,7 +6,6 @@ import ts from "typescript";
 import { DeclarationReflection, IntrinsicType, ReflectionKind, ReflectionType, SignatureReflection, } from "../models/index.js";
 import { ConverterEvents } from "./converter-events.js";
 import { convertParameterNodes, convertTemplateParameterNodes } from "./factories/signature.js";
-import { createSymbolId } from "./factories/symbol-id.js";
 export function convertJsDocAlias(context, symbol, declaration, exportSymbol) {
     if (declaration.typeExpression &&
         ts.isJSDocTypeLiteral(declaration.typeExpression)) {
@@ -57,7 +56,7 @@ function convertJsDocSignature(context, node) {
     context.registerReflection(reflection, symbol);
     context.converter.trigger(ConverterEvents.CREATE_DECLARATION, context, reflection);
     const signature = new SignatureReflection("__type", ReflectionKind.CallSignature, reflection);
-    context.project.registerSymbolId(signature, createSymbolId(symbol, node));
+    context.project.registerSymbolId(signature, context.createSymbolId(symbol, node));
     context.registerReflection(signature, void 0);
     const signatureCtx = rc.withScope(signature);
     reflection.signatures = [signature];

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

@@ -40,7 +40,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @returns An array containing all children of the given reflection grouped by their kind.
      */
     getReflectionGroups(parent: ContainerReflection, reflections: Array<DeclarationReflection | DocumentReflection>): ReflectionGroup[];
-    getSortFunction(reflection: ContainerReflection): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;
+    getSortFunction(reflection: ContainerReflection): (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     /**
      * Callback used to sort groups by name.
      */

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

@@ -58,7 +58,9 @@ export class ImplementsPlugin extends ConverterComponent {
         });
     }
     analyzeInheritance(project, reflection) {
-        const extendedTypes = filterMap(reflection.extendedTypes ?? [], (type) => {
+        if (!reflection.extendedTypes)
+            return;
+        const extendedTypes = filterMap(reflection.extendedTypes, (type) => {
             return type instanceof ReferenceType &&
                 type.reflection instanceof DeclarationReflection
                 ? type
@@ -73,13 +75,45 @@ export class ImplementsPlugin extends ConverterComponent {
                         ? "overwrites"
                         : "inheritedFrom";
                     for (const [childSig, parentSig] of zip(child.signatures ?? [], parentMember.signatures ?? [])) {
-                        childSig[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentSig, project);
+                        // If we're already pointing at something because TS said we should reference
+                        // it, then don't overwrite the reference.
+                        if (!childSig[key]?.reflection) {
+                            childSig[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentSig, project);
+                        }
+                    }
+                    if (!child[key]?.reflection) {
+                        child[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentMember, project);
                     }
-                    child[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentMember, project);
                     this.handleInheritedComments(child, parentMember);
                 }
             }
         }
+        // #2978, this is very unfortunate. If a child's parent links are broken at this point,
+        // we replace them with an intentionally broken link so that they won't ever be resolved.
+        // This is done because if we don't do it then we run into issues where we have a link which
+        // points to some ReflectionSymbolId which might not exist now, but once we've gone through
+        // serialization/deserialization, might point to an unexpected location. (See the mixin
+        // converter tests, I suspect this might actually be an indication of something else slightly
+        // broken there, but don't want to spend more time with this right now.)
+        // #2982, even more unfortunately, we only want to keep the link if it is pointing to a reflection
+        // which will receive a link during rendering.
+        const isValidRef = (ref) => ref.reflection && !ref.reflection.parent?.kindOf(ReflectionKind.TypeLiteral);
+        for (const child of reflection.children || []) {
+            if (child.inheritedFrom && !isValidRef(child.inheritedFrom)) {
+                child.inheritedFrom = ReferenceType.createBrokenReference(child.inheritedFrom.name, project);
+            }
+            if (child.overwrites && !isValidRef(child.overwrites)) {
+                child.overwrites = ReferenceType.createBrokenReference(child.overwrites.name, project);
+            }
+            for (const childSig of child.getAllSignatures()) {
+                if (childSig.inheritedFrom && !isValidRef(childSig.inheritedFrom)) {
+                    childSig.inheritedFrom = ReferenceType.createBrokenReference(childSig.inheritedFrom.name, project);
+                }
+                if (childSig.overwrites && !isValidRef(childSig.overwrites)) {
+                    childSig.overwrites = ReferenceType.createBrokenReference(childSig.overwrites.name, project);
+                }
+            }
+        }
     }
     onResolveEnd(context) {
         this.resolve(context.project);
@@ -310,8 +344,19 @@ function findProperty(reflection, parent) {
     });
 }
 function createLink(context, reflection, clause, expr, symbol, isInherit) {
-    const project = context.project;
     const name = `${expr.expression.getText()}.${getHumanName(symbol.name)}`;
+    // We should always have rootSymbols, but check just in case. We use the first
+    // symbol here as TypeDoc's models don't have multiple symbols for the parent
+    // reference. This is technically wrong because symbols might be declared in
+    // multiple locations (interface declaration merging), but that's an uncommon
+    // enough use case that it doesn't seem worthwhile to complicate the rest of the
+    // world to deal with it.
+    // Note that we also need to check that the root symbol isn't this symbol.
+    // This seems to happen sometimes when dealing with interface inheritance.
+    const rootSymbols = context.checker.getRootSymbols(symbol);
+    const ref = rootSymbols.length && rootSymbols[0] != symbol
+        ? context.createSymbolReference(rootSymbols[0], context, name)
+        : ReferenceType.createBrokenReference(name, context.project);
     link(reflection);
     link(reflection.getSignature);
     link(reflection.setSignature);
@@ -321,23 +366,19 @@ function createLink(context, reflection, clause, expr, symbol, isInherit) {
     for (const sig of reflection.signatures ?? []) {
         link(sig);
     }
-    // Intentionally create broken links here. These will be replaced with real links during
-    // resolution if we can do so. We create broken links rather than real links because in the
-    // case of an inherited symbol, we'll end up referencing a single symbol ID rather than one
-    // for each class.
     function link(target) {
         if (!target)
             return;
         if (clause.token === ts.SyntaxKind.ImplementsKeyword) {
-            target.implementationOf ??= ReferenceType.createBrokenReference(name, project);
+            target.implementationOf ??= ref;
             return;
         }
         if (isInherit) {
             target.setFlag(ReflectionFlag.Inherited);
-            target.inheritedFrom ??= ReferenceType.createBrokenReference(name, project);
+            target.inheritedFrom ??= ref;
         }
         else {
-            target.overwrites ??= ReferenceType.createBrokenReference(name, project);
+            target.overwrites ??= ref;
         }
     }
 }

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

@@ -37,7 +37,7 @@ import { ConverterComponent } from "../components.js";
 import { ApplicationEvents } from "../../application-events.js";
 import { ConverterEvents } from "../converter-events.js";
 import { i18n, MinimalSourceFile, NormalizedPathUtils } from "#utils";
-import { discoverPackageJson, getCommonDirectory, nicePath, normalizePath, Option, readFile, } from "#node-utils";
+import { deriveRootDir, discoverPackageJson, nicePath, normalizePath, Option, readFile, } from "#node-utils";
 import { existsSync } from "fs";
 /**
  * A handler that tries to find the package.json and readme.md files of the
@@ -117,7 +117,7 @@ let PackagePlugin = (() => {
             this.readmeContents = undefined;
             this.packageJson = undefined;
             const dirName = this.application.options.packageDir ??
-                Path.resolve(getCommonDirectory(this.entryPoints.map(g => `${g}/`)));
+                Path.resolve(deriveRootDir(this.entryPoints));
             this.application.logger.verbose(`Begin package.json search at ${nicePath(dirName)}`);
             const packageJson = discoverPackageJson(dirName);
             this.packageJson = packageJson?.content;

package/dist/lib/converter/types.js

@@ -8,7 +8,6 @@ import { convertParameterNodes, convertTypeParameterNodes, createSignature } fro
 import { convertSymbol } from "./symbols.js";
 import { isObjectType, isTypeReference } from "./utils/nodes.js";
 import { removeUndefined } from "./utils/reflections.js";
-import { createSymbolId } from "./factories/symbol-id.js";
 const converters = new Map();
 export function loadConverters() {
     if (converters.size)
@@ -159,7 +158,7 @@ const constructorConverter = {
         if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.AbstractKeyword)) {
             signature.setFlag(ReflectionFlag.Abstract);
         }
-        context.project.registerSymbolId(signature, createSymbolId(symbol, node));
+        context.project.registerSymbolId(signature, context.createSymbolId(symbol, node));
         context.registerReflection(signature, void 0);
         const signatureCtx = rc.withScope(signature);
         reflection.signatures = [signature];
@@ -208,7 +207,7 @@ const functionTypeConverter = {
         context.registerReflection(reflection, symbol);
         context.converter.trigger(ConverterEvents.CREATE_DECLARATION, context, reflection);
         const signature = new SignatureReflection("__type", ReflectionKind.CallSignature, reflection);
-        context.project.registerSymbolId(signature, createSymbolId(symbol, node));
+        context.project.registerSymbolId(signature, context.createSymbolId(symbol, node));
         context.registerReflection(signature, undefined);
         const signatureCtx = rc.withScope(signature);
         reflection.signatures = [signature];

package/dist/lib/internationalization/locales/en.cjs

@@ -276,6 +276,7 @@ module.exports = {
     favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}",
     option_0_must_be_an_object: "The '{0}' option must be a non-array object",
     option_0_must_be_an_array_of_string: "The '{0}' option must be set to an array of strings",
+    option_0_must_be_an_array_of_string_or_functions: "The '{0}' option must be set to an array of strings/functions",
     option_0_must_be_a_function: "The '{0}' option must be a function",
     option_0_must_be_object_with_urls: `{0} must be an object with string labels as keys and URL values`,
     visibility_filters_only_include_0: `visibilityFilters can only include the following non-@ keys: {0}`,

package/dist/lib/internationalization/locales/en.d.cts

@@ -260,6 +260,7 @@ declare const _default: {
     readonly favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}";
     readonly option_0_must_be_an_object: "The '{0}' option must be a non-array object";
     readonly option_0_must_be_an_array_of_string: "The '{0}' option must be set to an array of strings";
+    readonly option_0_must_be_an_array_of_string_or_functions: "The '{0}' option must be set to an array of strings/functions";
     readonly option_0_must_be_a_function: "The '{0}' option must be a function";
     readonly option_0_must_be_object_with_urls: "{0} must be an object with string labels as keys and URL values";
     readonly visibility_filters_only_include_0: "visibilityFilters can only include the following non-@ keys: {0}";

package/dist/lib/internationalization/locales/zh.cjs

@@ -56,6 +56,7 @@ module.exports = localeUtils.buildIncompleteTranslation({
     open_brace_within_inline_tag: "在内联标签中遇到左括号，这可能是一个错误",
     inline_tag_not_closed: "内联标签未关闭",
     // validation
+    comment_for_0_links_to_1_not_included_in_docs_use_external_link_2: `{0} 注释中指向 “{1}” 的已解析的链接不会被包含在文档中。请将 {2} 导出或添加至 externalSymbolLinkMappings 选项以修复该警告`,
     failed_to_resolve_link_to_0_in_comment_for_1: "无法解析 {1} 注释中指向 “{0}” 的链接",
     failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2: "无法解析 {1} 的注释中指向 “{0}” 的链接。您可能想要 “{2}”",
     failed_to_resolve_link_to_0_in_readme_for_1: "无法解析 {1} 的自述文件中指向 “{0}” 的链接",
@@ -71,8 +72,9 @@ module.exports = localeUtils.buildIncompleteTranslation({
     // conversion plugins
     not_all_search_category_boosts_used_0: "文档中并未使用 searchCategoryBoosts 中指定的所有类别。未使用的类别包括：\n{0}",
     not_all_search_group_boosts_used_0: "文档中并未使用 searchGroupBoosts 中指定的所有组。未使用的组为：\n{0}",
-    comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "{0} 的评论包含“{1}”的 @categoryDescription，但该类别中没有子项",
-    comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: "{0} 的注释包含“{1}”的 @groupDescription，但该组中没有子项",
+    comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "{0} 的注释中包含了 “{1}” 的 @categoryDescription，但该类别中没有子项",
+    comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: "{0} 的注释中包含了 “{1}” 的 @groupDescription，但该分组中没有子项",
+    comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid: `{0} 的注释中指定的 “{1}” 的 @sortStrategy 无效，以下是有效的选项：\n\t{2}`,
     label_0_for_1_cannot_be_referenced: "无法使用声明引用来引用 {1} 的标签“{0}”。标签只能包含 A-Z、0-9 和 _，并且不能以数字开头",
     modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2: "修饰符标签 {0} 与 {2} 注释中的 {1} 互斥",
     signature_0_has_unused_param_with_name_1: "签名 {0} 有一个名为“{1}”的 @param，但未被使用",
@@ -130,6 +132,7 @@ module.exports = localeUtils.buildIncompleteTranslation({
     // options
     circular_reference_extends_0: "{0} 的“extends”字段出现循环引用",
     failed_resolve_0_to_file_in_1: "无法将 {0} 解析为 {1} 中的文件",
+    glob_0_should_use_posix_slash: `该 glob “{0}” 中转义了不是特殊字符的字符。输入 TypeDoc 的 glob 可能不会使用 Windows 路径分隔符（\\），请尝试将其替换为 POSIX 路径分隔符（/）`,
     option_0_can_only_be_specified_by_config_file: "“{0}”选项只能通过配置文件指定",
     option_0_expected_a_value_but_none_provided: "--{0} 需要一个值，但没有给出任何参数",
     unknown_option_0_may_have_meant_1: "未知选项：{0}，你可能指的是：\n\t{1}",
@@ -274,6 +277,8 @@ module.exports = localeUtils.buildIncompleteTranslation({
     useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "useHostedBaseUrlForAbsoluteLinks 选项要求设置 hostingBaseUrl",
     favicon_must_have_one_of_the_following_extensions_0: "favicon 的后缀名必须是下列之一：{0}",
     option_0_must_be_an_object: "“{0}”选项必须是非数组对象",
+    option_0_must_be_an_array_of_string: "“{0}”选项必须是字符串数组",
+    option_0_must_be_an_array_of_string_or_functions: "“{0}”选项必须是由字符串或函数构成的数组",
     option_0_must_be_a_function: "‘{0}’ 选项必须是一个函数",
     option_0_must_be_object_with_urls: "{0} 必须是具有字符串标签作为键和 URL 值的对象",
     visibility_filters_only_include_0: "visibilityFilters 只能包含以下非@键：{0}",
@@ -431,6 +436,7 @@ module.exports = localeUtils.buildIncompleteTranslation({
     tag_return: "返回",
     tag_satisfies: "满足",
     tag_since: "添加于",
+    tag_sortStrategy: "排序策略",
     tag_template: "类型参数",
     tag_type: "类型",
     tag_typedef: "类型定义",
@@ -460,6 +466,7 @@ module.exports = localeUtils.buildIncompleteTranslation({
     tag_virtual: "虚函数",
     tag_abstract: "抽象类",
     tag_class: "类",
+    tag_disableGroups: "禁用分组",
     tag_enum: "枚举",
     tag_event: "事件",
     tag_expand: "展开",

package/dist/lib/internationalization/locales/zh.d.cts

@@ -49,6 +49,7 @@ declare const _default: {
     unknown_inline_tag_0: "遇到未知的内联标签 {0}";
     open_brace_within_inline_tag: string;
     inline_tag_not_closed: string;
+    comment_for_0_links_to_1_not_included_in_docs_use_external_link_2: "{0} 注释中指向 “{1}” 的已解析的链接不会被包含在文档中。请将 {2} 导出或添加至 externalSymbolLinkMappings 选项以修复该警告";
     failed_to_resolve_link_to_0_in_comment_for_1: "无法解析 {1} 注释中指向 “{0}” 的链接";
     failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2: "无法解析 {1} 的注释中指向 “{0}” 的链接。您可能想要 “{2}”";
     failed_to_resolve_link_to_0_in_readme_for_1: "无法解析 {1} 的自述文件中指向 “{0}” 的链接";
@@ -63,8 +64,9 @@ declare const _default: {
     reflection_0_links_to_1_with_text_2_but_resolved_to_3: "“{0}”中的链接“{2}”指向“{1}”，目标虽然存在但并没有直接的链接，因此将改为链接至“{3}”。";
     not_all_search_category_boosts_used_0: "文档中并未使用 searchCategoryBoosts 中指定的所有类别。未使用的类别包括：\n{0}";
     not_all_search_group_boosts_used_0: "文档中并未使用 searchGroupBoosts 中指定的所有组。未使用的组为：\n{0}";
-    comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "{0} 的评论包含“{1}”的 @categoryDescription，但该类别中没有子项";
-    comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: "{0} 的注释包含“{1}”的 @groupDescription，但该组中没有子项";
+    comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "{0} 的注释中包含了 “{1}” 的 @categoryDescription，但该类别中没有子项";
+    comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: "{0} 的注释中包含了 “{1}” 的 @groupDescription，但该分组中没有子项";
+    comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid: "{0} 的注释中指定的 “{1}” 的 @sortStrategy 无效，以下是有效的选项：\n\t{2}";
     label_0_for_1_cannot_be_referenced: "无法使用声明引用来引用 {1} 的标签“{0}”。标签只能包含 A-Z、0-9 和 _，并且不能以数字开头";
     modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2: "修饰符标签 {0} 与 {2} 注释中的 {1} 互斥";
     signature_0_has_unused_param_with_name_1: "签名 {0} 有一个名为“{1}”的 @param，但未被使用";
@@ -117,6 +119,7 @@ declare const _default: {
     saved_relative_path_0_resolved_from_1_does_not_exist: "序列化项目引用的 {0} 不存在或无法在 {1} 下找到";
     circular_reference_extends_0: "{0} 的“extends”字段出现循环引用";
     failed_resolve_0_to_file_in_1: "无法将 {0} 解析为 {1} 中的文件";
+    glob_0_should_use_posix_slash: "该 glob “{0}” 中转义了不是特殊字符的字符。输入 TypeDoc 的 glob 可能不会使用 Windows 路径分隔符（\\），请尝试将其替换为 POSIX 路径分隔符（/）";
     option_0_can_only_be_specified_by_config_file: "“{0}”选项只能通过配置文件指定";
     option_0_expected_a_value_but_none_provided: "--{0} 需要一个值，但没有给出任何参数";
     unknown_option_0_may_have_meant_1: "未知选项：{0}，你可能指的是：\n\t{1}";
@@ -256,6 +259,8 @@ declare const _default: {
     useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: string;
     favicon_must_have_one_of_the_following_extensions_0: "favicon 的后缀名必须是下列之一：{0}";
     option_0_must_be_an_object: "“{0}”选项必须是非数组对象";
+    option_0_must_be_an_array_of_string: "“{0}”选项必须是字符串数组";
+    option_0_must_be_an_array_of_string_or_functions: "“{0}”选项必须是由字符串或函数构成的数组";
     option_0_must_be_a_function: "‘{0}’ 选项必须是一个函数";
     option_0_must_be_object_with_urls: "{0} 必须是具有字符串标签作为键和 URL 值的对象";
     visibility_filters_only_include_0: "visibilityFilters 只能包含以下非@键：{0}";
@@ -396,6 +401,7 @@ declare const _default: {
     tag_return: string;
     tag_satisfies: string;
     tag_since: string;
+    tag_sortStrategy: string;
     tag_template: string;
     tag_type: string;
     tag_typedef: string;
@@ -423,6 +429,7 @@ declare const _default: {
     tag_virtual: string;
     tag_abstract: string;
     tag_class: string;
+    tag_disableGroups: string;
     tag_enum: string;
     tag_event: string;
     tag_expand: string;

package/dist/lib/serialization/schema.d.ts

@@ -37,7 +37,7 @@ export declare const SCHEMA_VERSION = "2.0";
 export type ModelToObject<T> = [T] extends [Array<infer U>] ? ModelToObject<U>[] : [
     M.SomeType
 ] extends [T] ? SomeType : _ModelToObject<T>;
-type _ModelToObject<T> = T extends Primitive ? T : Required<T> extends Required<M.ReflectionGroup> ? ReflectionGroup : Required<T> extends Required<M.ReflectionCategory> ? ReflectionCategory : T extends M.ReflectionVariant[keyof M.ReflectionVariant] ? ReflectionVariantMap[T["variant"]] : T extends M.SomeType ? TypeKindMap[T["type"]] : T extends M.Type ? SomeType : T extends M.Comment ? Comment : T extends M.CommentTag ? CommentTag : T extends M.CommentDisplayPart ? CommentDisplayPart : T extends M.SourceReference ? SourceReference : T extends M.FileRegistry ? FileRegistry : never;
+type _ModelToObject<T> = T extends Primitive ? T : Required<T> extends Required<M.ReflectionGroup> ? ReflectionGroup : Required<T> extends Required<M.ReflectionCategory> ? ReflectionCategory : T extends M.ReflectionVariant[keyof M.ReflectionVariant] ? ReflectionVariantMap[T["variant"]] : T extends M.SomeType ? TypeKindMap[T["type"]] : T extends M.Type ? SomeType : T extends M.Comment ? Comment : T extends M.CommentTag ? CommentTag : T extends M.CommentDisplayPart ? CommentDisplayPart : T extends M.SourceReference ? SourceReference : T extends M.FileRegistry ? FileRegistry : T extends M.ReflectionSymbolId ? ReflectionSymbolId : never;
 type Primitive = string | number | undefined | null | boolean;
 type ToSerialized<T> = T extends Primitive ? T : T extends bigint ? {
     value: string;

package/dist/lib/utils/declaration-maps.d.ts

@@ -0,0 +1,3 @@
+import type ts from "typescript";
+export declare function resolveDeclarationMaps(file: string): string;
+export declare function addInferredDeclarationMapPaths(opts: ts.CompilerOptions, files: readonly string[]): void;

package/dist/lib/utils/declaration-maps.js

@@ -0,0 +1,51 @@
+import { existsSync } from "fs";
+import { readFile } from "./fs.js";
+import { Validation } from "#utils";
+import { join, relative, resolve } from "path";
+import { getCommonDirectory, normalizePath } from "./paths.js";
+const declarationMapCache = new Map();
+export function resolveDeclarationMaps(file) {
+    if (!/\.d\.[cm]?ts$/.test(file))
+        return file;
+    if (declarationMapCache.has(file))
+        return declarationMapCache.get(file);
+    const mapFile = file + ".map";
+    if (!existsSync(mapFile))
+        return file;
+    let sourceMap;
+    try {
+        sourceMap = JSON.parse(readFile(mapFile));
+    }
+    catch {
+        return file;
+    }
+    if (Validation.validate({
+        file: String,
+        sourceRoot: Validation.optional(String),
+        sources: [Array, String],
+    }, sourceMap)) {
+        // There's a pretty large assumption in here that we only have
+        // 1 source file per js file. This is a pretty standard typescript approach,
+        // but people might do interesting things with transpilation that could break this.
+        let source = sourceMap.sources[0];
+        // If we have a sourceRoot, trim any leading slash from the source, and join them
+        // Similar to how it's done at https://github.com/mozilla/source-map/blob/58819f09018d56ef84dc41ba9c93f554e0645169/lib/util.js#L412
+        if (sourceMap.sourceRoot !== undefined) {
+            source = source.replace(/^\//, "");
+            source = join(sourceMap.sourceRoot, source);
+        }
+        const result = resolve(mapFile, "..", source);
+        declarationMapCache.set(file, result);
+        return result;
+    }
+    return file;
+}
+// See also: inferEntryPoints in entry-point.ts
+export function addInferredDeclarationMapPaths(opts, files) {
+    const rootDir = opts.rootDir || getCommonDirectory(files);
+    const declDir = opts.declarationDir || opts.outDir || rootDir;
+    for (const file of files) {
+        const mapFile = normalizePath(resolve(declDir, relative(rootDir, file)).replace(/\.([cm]?[tj]s)x?$/, ".d.$1"));
+        declarationMapCache.set(mapFile, file);
+    }
+}

package/dist/lib/utils/entry-point.js

@@ -5,6 +5,7 @@ import { expandPackages } from "./package-manifest.js";
 import { deriveRootDir, getCommonDirectory, MinimatchSet, nicePath, normalizePath } from "./paths.js";
 import { discoverPackageJson, glob, inferPackageEntryPointPaths, isDir } from "./fs.js";
 import { assertNever, i18n } from "#utils";
+import { addInferredDeclarationMapPaths, resolveDeclarationMaps } from "./declaration-maps.js";
 /**
  * Defines how entry points are interpreted.
  * @enum
@@ -39,7 +40,7 @@ export function inferEntryPoints(logger, options, programs) {
     const pathEntries = inferPackageEntryPointPaths(packageJson.file);
     const entryPoints = [];
     programs ||= getEntryPrograms(pathEntries.map((p) => p[1]), logger, options);
-    // See also: addInferredDeclarationMapPaths in ReflectionSymbolId
+    // See also: addInferredDeclarationMapPaths in symbol-id factory
     const jsToTsSource = new Map();
     for (const program of programs) {
         const opts = program.getCompilerOptions();
@@ -53,7 +54,7 @@ export function inferEntryPoints(logger, options, programs) {
     for (const [name, path] of pathEntries) {
         // Strip leading ./ from the display name
         const displayName = name.replace(/^\.\/?/, "");
-        const targetPath = jsToTsSource.get(path) || path;
+        const targetPath = jsToTsSource.get(path) || resolveDeclarationMaps(path) || path;
         const program = programs.find((p) => p.getSourceFile(targetPath));
         if (program) {
             entryPoints.push({
@@ -70,6 +71,7 @@ export function inferEntryPoints(logger, options, programs) {
         logger.warn(i18n.no_entry_points_provided());
         return [];
     }
+    logger.verbose(`Inferred entry points to be:\n\t${entryPoints.map(e => nicePath(e.sourceFile.fileName)).join("\n\t")}`);
     return entryPoints;
 }
 export function getEntryPoints(logger, options) {
@@ -257,6 +259,7 @@ function getEntryPrograms(inputFiles, logger, options) {
             options: options.getCompilerOptions(),
             projectReferences: options.getProjectReferences(),
         });
+    addInferredDeclarationMapPaths(options.getCompilerOptions(), options.getFileNames());
     const programs = [rootProgram];
     // This might be a solution style tsconfig, in which case we need to add a program for each
     // reference so that the converter can look through each of these.
@@ -271,6 +274,7 @@ function getEntryPrograms(inputFiles, logger, options) {
                 rootNames: ref.commandLine.fileNames,
                 projectReferences: ref.commandLine.projectReferences,
             }));
+            addInferredDeclarationMapPaths(ref.commandLine.options, ref.commandLine.fileNames);
         }
     }
     return programs;

package/dist/lib/utils/index.d.ts

@@ -9,6 +9,7 @@ export { loadPlugins } from "./plugins.js";
 export { getSortFunction } from "./sort.js";
 export type { SortStrategy } from "./sort.js";
 export * from "./entry-point.js";
+export * from "./declaration-maps.js";
 export * from "./highlighter.js";
 export * from "./html.js";
 export * from "./tsconfig.js";

package/dist/lib/utils/index.js

@@ -7,6 +7,7 @@ export * from "./paths.js";
 export { loadPlugins } from "./plugins.js";
 export { getSortFunction } from "./sort.js";
 export * from "./entry-point.js";
+export * from "./declaration-maps.js";
 export * from "./highlighter.js";
 export * from "./html.js";
 export * from "./tsconfig.js";

package/dist/lib/utils/options/declaration.d.ts

@@ -2,8 +2,9 @@ import type { BundledTheme as ShikiTheme } from "@gerrit0/mini-shiki";
 import type { SortStrategy } from "../sort.js";
 import type { EntryPointStrategy } from "../entry-point.js";
 import type { ReflectionKind } from "../../models/kind.js";
-import { type GlobString, type LogLevel, type NeverIfInternal, type NormalizedPath, type NormalizedPathOrModule } from "#utils";
+import { type GlobString, type LogLevel, type NeverIfInternal, type NormalizedPath, type NormalizedPathOrModule, type NormalizedPathOrModuleOrFunction } from "#utils";
 import type { TranslationProxy } from "../../internationalization/internationalization.js";
+import type { Application } from "../../application.js";
 /** @enum */
 export declare const EmitStrategy: {
     readonly both: "both";
@@ -40,7 +41,7 @@ export declare const rootPackageOptions: readonly ["plugin", "packageOptions", "
  * @interface
  */
 export type TypeDocOptions = {
-    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes all TypeDoc specific options as returned by {@link Options.getValue}, this is
@@ -50,7 +51,7 @@ export type TypeDocOptions = {
  * @interface
  */
 export type TypeDocOptionValues = {
-    [K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | GlobString[] | number | boolean | Record<string, boolean> ? TypeDocOptionMap[K] : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | GlobString[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] | number | boolean | Record<string, boolean> ? TypeDocOptionMap[K] : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes TypeDoc options suitable for setting within the `packageOptions` setting.
@@ -78,7 +79,7 @@ export interface TypeDocOptionMap {
     options: NormalizedPath;
     tsconfig: NormalizedPath;
     compilerOptions: unknown;
-    plugin: NormalizedPathOrModule[];
+    plugin: NormalizedPathOrModuleOrFunction[];
     lang: string;
     locales: ManuallyValidatedOption<Record<string, Record<string, string>>>;
     packageOptions: ManuallyValidatedOption<TypeDocPackageOptions>;
@@ -276,7 +277,7 @@ export type JsDocCompatibility = {
 /**
  * Converts a given TypeDoc option key to the type of the declaration expected.
  */
-export type KeyToDeclaration<K extends keyof TypeDocOptionMap> = TypeDocOptionMap[K] extends boolean ? BooleanDeclarationOption : TypeDocOptionMap[K] extends string | NormalizedPath ? StringDeclarationOption : TypeDocOptionMap[K] extends number ? NumberDeclarationOption : TypeDocOptionMap[K] extends GlobString[] ? GlobArrayDeclarationOption : TypeDocOptionMap[K] extends string[] | NormalizedPath[] | NormalizedPathOrModule[] ? ArrayDeclarationOption : unknown extends TypeDocOptionMap[K] ? MixedDeclarationOption | ObjectDeclarationOption : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown> ? (MixedDeclarationOption & {
+export type KeyToDeclaration<K extends keyof TypeDocOptionMap> = TypeDocOptionMap[K] extends boolean ? BooleanDeclarationOption : TypeDocOptionMap[K] extends string | NormalizedPath ? StringDeclarationOption : TypeDocOptionMap[K] extends number ? NumberDeclarationOption : TypeDocOptionMap[K] extends GlobString[] ? GlobArrayDeclarationOption : TypeDocOptionMap[K] extends string[] | NormalizedPath[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] ? ArrayDeclarationOption : unknown extends TypeDocOptionMap[K] ? MixedDeclarationOption | ObjectDeclarationOption : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown> ? (MixedDeclarationOption & {
     validate(value: unknown, i18n: TranslationProxy): void;
 }) | (ObjectDeclarationOption & {
     validate(value: unknown, i18n: TranslationProxy): void;
@@ -306,20 +307,26 @@ export declare enum ParameterType {
     PathArray = 8,
     /**
      * Resolved according to the config directory if it starts with `.`
+     * @deprecated since 0.28.8, will be removed in 0.29
      */
     ModuleArray = 9,
+    /**
+     * Resolved according to the config directory if it starts with `.`
+     * @internal - only intended for use with the plugin option
+     */
+    PluginArray = 10,
     /**
      * Relative to the config directory.
      */
-    GlobArray = 10,
+    GlobArray = 11,
     /**
      * An object which partially merges user-set values into the defaults.
      */
-    Object = 11,
+    Object = 12,
     /**
      * An object with true/false flags
      */
-    Flags = 12
+    Flags = 13
 }
 export interface DeclarationOptionBase {
     /**
@@ -401,7 +408,7 @@ export interface BooleanDeclarationOption extends DeclarationOptionBase {
     defaultValue?: boolean;
 }
 export interface ArrayDeclarationOption extends DeclarationOptionBase {
-    type: ParameterType.Array | ParameterType.PathArray | ParameterType.ModuleArray;
+    type: ParameterType.Array | ParameterType.PathArray | ParameterType.ModuleArray | ParameterType.PluginArray;
     /**
      * If not specified defaults to an empty array.
      */
@@ -482,6 +489,7 @@ export interface ParameterTypeToOptionTypeMap {
     [ParameterType.Array]: string[];
     [ParameterType.PathArray]: NormalizedPath[];
     [ParameterType.ModuleArray]: NormalizedPathOrModule[];
+    [ParameterType.PluginArray]: Array<NormalizedPathOrModule | ((app: Application) => void | Promise<void>)>;
     [ParameterType.GlobArray]: GlobString[];
     [ParameterType.Flags]: Record<string, boolean>;
     [ParameterType.Map]: unknown;