typedoc 0.28.5 → 0.28.7

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

@@ -35,7 +35,6 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 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";
 /**
@@ -68,55 +67,7 @@ let LinkResolverPlugin = (() => {
         resolveLinks(project) {
             for (const id in project.reflections) {
                 const reflection = project.reflections[id];
-                if (reflection.comment) {
-                    this.owner.resolveLinks(reflection.comment, reflection);
-                }
-                if (reflection.isDeclaration()) {
-                    reflection.type?.visit(makeRecursiveVisitor({
-                        union: (type) => {
-                            type.elementSummaries = type.elementSummaries?.map((parts) => this.owner.resolveLinks(parts, reflection));
-                        },
-                    }));
-                    if (reflection.readme) {
-                        reflection.readme = this.owner.resolveLinks(reflection.readme, reflection);
-                    }
-                }
-                if (reflection.isDocument()) {
-                    reflection.content = this.owner.resolveLinks(reflection.content, reflection);
-                }
-                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) {
-                                group.description = this.owner.resolveLinks(group.description, reflection);
-                            }
-                            if (group.categories) {
-                                for (const cat of group.categories) {
-                                    this.resolveCategoryLinks(cat, reflection);
-                                }
-                            }
-                        }
-                    }
-                    if (reflection.categories) {
-                        for (const cat of reflection.categories) {
-                            this.resolveCategoryLinks(cat, reflection);
-                        }
-                    }
-                }
-            }
-            if (project.readme) {
-                project.readme = this.owner.resolveLinks(project.readme, project);
+                this.owner.resolveLinks(reflection);
             }
             for (const { type, owner } of discoverAllReferenceTypes(project, false)) {
                 if (!type.reflection) {
@@ -132,11 +83,6 @@ let LinkResolverPlugin = (() => {
                 }
             }
         }
-        resolveCategoryLinks(category, owner) {
-            if (category.description) {
-                category.description = this.owner.resolveLinks(category.description, owner);
-            }
-        }
     };
 })();
 export { LinkResolverPlugin };

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

@@ -36,7 +36,7 @@ import * as Path from "path";
 import { ConverterComponent } from "../components.js";
 import { ApplicationEvents } from "../../application-events.js";
 import { ConverterEvents } from "../converter-events.js";
-import { i18n, MinimalSourceFile } from "#utils";
+import { i18n, MinimalSourceFile, NormalizedPathUtils } from "#utils";
 import { discoverPackageJson, getCommonDirectory, nicePath, normalizePath, Option, readFile, } from "#node-utils";
 import { existsSync } from "fs";
 /**
@@ -161,6 +161,10 @@ let PackagePlugin = (() => {
             if (this.readmeFile && this.readmeContents) {
                 const { content } = this.application.converter.parseRawComment(new MinimalSourceFile(this.readmeContents, this.readmeFile), project.files);
                 project.readme = content;
+                project.files.registerReflectionPath(this.readmeFile, project);
+                // In packages mode, this probably won't do anything unless someone uses the readme
+                // option to select a different file.
+                project.files.registerReflectionPath(NormalizedPathUtils.dirname(this.readmeFile), project);
                 // This isn't ideal, but seems better than figuring out the readme
                 // path over in the include plugin...
                 this.owner.includePlugin.checkIncludeTagsParts(project, Path.dirname(this.readmeFile), content);

package/dist/lib/converter/symbols.js

@@ -238,6 +238,25 @@ function convertTypeAlias(context, symbol, exportSymbol) {
         convertJsDocCallback(context, symbol, declaration, exportSymbol);
     }
 }
+function convertTypeAliasFromValueDeclaration(context, symbol, exportSymbol, valueKind) {
+    const comment = context.getComment(symbol, valueKind);
+    const reflection = new DeclarationReflection(exportSymbol?.name || symbol.name, ReflectionKind.TypeAlias, context.scope);
+    reflection.comment = comment;
+    context.postReflectionCreation(reflection, symbol, exportSymbol);
+    context.finalizeDeclarationReflection(reflection);
+    reflection.type = context.converter.convertType(context.withScope(reflection), context.checker.getTypeOfSymbol(symbol));
+    if (reflection.type.type === "reflection" && reflection.type.declaration.children) {
+        // #2817 lift properties of object literal types up to the reflection level.
+        const typeDecl = reflection.type.declaration;
+        reflection.project.mergeReflections(typeDecl, reflection);
+        delete reflection.type;
+        // When created any signatures will be created with __type as their
+        // name, rename them so that they have the alias's name as their name
+        for (const sig of reflection.signatures || []) {
+            sig.name = reflection.name;
+        }
+    }
+}
 function attachUnionComments(context, declaration, union) {
     const list = declaration.type.getChildAt(0);
     if (list.kind !== ts.SyntaxKind.SyntaxList)
@@ -285,6 +304,9 @@ function convertTypeAliasAsInterface(context, symbol, exportSymbol, declaration)
     convertIndexSignatures(rc, type);
 }
 function convertFunctionOrMethod(context, symbol, exportSymbol) {
+    if (isTypeOnlyExport(exportSymbol)) {
+        return convertTypeAliasFromValueDeclaration(context, symbol, exportSymbol, ReflectionKind.Function);
+    }
     // Can't just check method flag because this might be called for properties as well
     // This will *NOT* be called for variables that look like functions, they need a special case.
     const isMethod = !!(symbol.flags &
@@ -330,7 +352,7 @@ function convertFunctionOrMethod(context, symbol, exportSymbol) {
 // getDeclaredTypeOfSymbol gets the INSTANCE type
 // getTypeOfSymbolAtLocation gets the STATIC type
 function convertClassOrInterface(context, symbol, exportSymbol) {
-    const reflection = context.createDeclarationReflection(ts.SymbolFlags.Class & symbol.flags
+    const reflection = context.createDeclarationReflection((ts.SymbolFlags.Class & symbol.flags) && !isTypeOnlyExport(exportSymbol)
         ? ReflectionKind.Class
         : ReflectionKind.Interface, symbol, exportSymbol, void 0);
     const classDeclaration = symbol
@@ -355,7 +377,7 @@ function convertClassOrInterface(context, symbol, exportSymbol) {
         reflection.implementedTypes = implementedTypes;
     }
     context.finalizeDeclarationReflection(reflection);
-    if (classDeclaration) {
+    if (classDeclaration && reflection.kind === ReflectionKind.Class) {
         // Classes can have static props
         const staticType = context.checker.getTypeOfSymbolAtLocation(symbol, classDeclaration);
         reflectionContext.shouldBeStatic = true;
@@ -548,6 +570,9 @@ function createAlias(target, context, symbol, exportSymbol) {
     context.finalizeDeclarationReflection(ref);
 }
 function convertVariable(context, symbol, exportSymbol) {
+    if (isTypeOnlyExport(exportSymbol)) {
+        return convertTypeAliasFromValueDeclaration(context, symbol, exportSymbol, ReflectionKind.Variable);
+    }
     const declaration = symbol.getDeclarations()?.[0];
     const comment = context.getComment(symbol, ReflectionKind.Variable);
     const type = declaration
@@ -826,3 +851,13 @@ function isFunctionLikeInitializer(node) {
     }
     return false;
 }
+function isTypeOnlyExport(symbol) {
+    if (!symbol)
+        return false;
+    const declaration = symbol.declarations?.[0];
+    if (!declaration)
+        return false;
+    if (!ts.isExportSpecifier(declaration))
+        return false;
+    return declaration.isTypeOnly || declaration.parent.parent.isTypeOnly;
+}

package/dist/lib/converter/utils/repository.js

@@ -140,7 +140,7 @@ let GitRepository = (() => {
          */
         static tryCreateRepository(path, sourceLinkTemplate, gitRevision, gitRemote, logger) {
             gitRevision ||= git("-C", path, "rev-parse", "HEAD").stdout.trim();
-            if (!gitRevision)
+            if (gitRevision == "HEAD")
                 return; // Will only happen in a repo with no commits.
             let urlTemplate;
             if (sourceLinkTemplate) {

package/dist/lib/internationalization/internationalization.js

@@ -16,7 +16,7 @@ export function loadTranslations(lang) {
         return req(`./locales/${lang}.cjs`);
     }
     catch {
-        return {};
+        return loadTranslations("en");
     }
 }
 /**

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

@@ -126,7 +126,7 @@ module.exports = localeUtils.buildIncompleteTranslation({
     file_0_not_an_object: "Die Datei {0} ist kein Objekt",
     // deserialization
     serialized_project_referenced_0_not_part_of_project: "Serialisiertes Projekt referenziert Reflection {0}, welche kein Teil des Projekts ist",
-    saved_relative_path_0_resolved_from_1_is_not_a_file: "Serialisiertes Projekt referenziert {0}, was relativ zu {1} nicht existiert",
+    saved_relative_path_0_resolved_from_1_does_not_exist: "Serialisiertes Projekt referenziert {0}, was relativ zu {1} nicht existiert",
     // options
     circular_reference_extends_0: `Zyklische Referenz im "extends"-Feld von {0} gefunden`,
     failed_resolve_0_to_file_in_1: "Konnte {0} in {1} nicht zu einer Datei auflösen",

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

@@ -114,7 +114,7 @@ declare const _default: {
     entry_point_0_did_not_match_any_packages: "Der Einstiegspunkt-Glob {0} passte auf keine Verzeichnisse mit einer package.json-Datei";
     file_0_not_an_object: "Die Datei {0} ist kein Objekt";
     serialized_project_referenced_0_not_part_of_project: "Serialisiertes Projekt referenziert Reflection {0}, welche kein Teil des Projekts ist";
-    saved_relative_path_0_resolved_from_1_is_not_a_file: "Serialisiertes Projekt referenziert {0}, was relativ zu {1} nicht existiert";
+    saved_relative_path_0_resolved_from_1_does_not_exist: "Serialisiertes Projekt referenziert {0}, was relativ zu {1} nicht existiert";
     circular_reference_extends_0: "Zyklische Referenz im \"extends\"-Feld von {0} gefunden";
     failed_resolve_0_to_file_in_1: "Konnte {0} in {1} nicht zu einer Datei auflösen";
     glob_0_should_use_posix_slash: "Der Glob \"{0}\" maskiert nichtspezielle Zeichen. Glob-Eingaben für TypeDoc dürfen keine Windows-Pfadtrennzeichen (\\) verwenden, nutzen Sie stattdessen Posix-Pfadtrennzeichen (/)";

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

@@ -54,6 +54,7 @@ module.exports = {
     open_brace_within_inline_tag: `Encountered an open brace within an inline tag, this is likely a mistake`,
     inline_tag_not_closed: `Inline tag is not closed`,
     // validation
+    comment_for_0_links_to_1_not_included_in_docs_use_external_link_2: `The comment for {0} links to "{1}" which was resolved but is not included in the documentation. To fix this warning export it or add {2} to the externalSymbolLinkMappings option`,
     failed_to_resolve_link_to_0_in_comment_for_1: `Failed to resolve link to "{0}" in comment for {1}`,
     failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2: `Failed to resolve link to "{0}" in comment for {1}. You may have wanted "{2}"`,
     failed_to_resolve_link_to_0_in_readme_for_1: `Failed to resolve link to "{0}" in readme for {1}`,
@@ -71,6 +72,7 @@ module.exports = {
     not_all_search_group_boosts_used_0: `Not all groups specified in searchGroupBoosts were used in the documentation. The unused groups were:\n\t{0}`,
     comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: `Comment for {0} includes @categoryDescription for "{1}", but no child is placed in that category`,
     comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: `Comment for {0} includes @groupDescription for "{1}", but no child is placed in that group`,
+    comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid: `Comment for {0} specifies @sortStrategy with "{1}", which is an invalid sort strategy, the following are valid:\n\t{2}`,
     label_0_for_1_cannot_be_referenced: `The label "{0}" for {1} cannot be referenced with a declaration reference. Labels may only contain A-Z, 0-9, and _, and may not start with a number`,
     modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2: `The modifier tag {0} is mutually exclusive with {1} in the comment for {2}`,
     signature_0_has_unused_param_with_name_1: `The signature {0} has an @param with name "{1}", which was not used`,
@@ -124,7 +126,7 @@ module.exports = {
     file_0_not_an_object: `The file {0} is not an object`,
     // deserialization
     serialized_project_referenced_0_not_part_of_project: `Serialized project referenced reflection {0}, which was not a part of the project`,
-    saved_relative_path_0_resolved_from_1_is_not_a_file: `Serialized project referenced {0}, which does not exist relative to {1}`,
+    saved_relative_path_0_resolved_from_1_does_not_exist: `Serialized project referenced {0}, which does not exist relative to {1}`,
     // options
     circular_reference_extends_0: `Circular reference encountered for "extends" field of {0}`,
     failed_resolve_0_to_file_in_1: `Failed to resolve {0} to a file in {1}`,
@@ -273,13 +275,14 @@ module.exports = {
     useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set",
     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_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}`,
     visibility_filters_must_be_booleans: `All values of visibilityFilters must be booleans`,
     option_0_values_must_be_numbers: "All values of {0} must be numbers",
     option_0_values_must_be_array_of_tags: "{0} must be an array of valid tag names",
-    option_0_specified_1_but_only_2_is_valid: `{0} may only specify known values, and invalid values were provided ({1}). The valid sort strategies are:\n{2}`,
+    option_0_specified_1_but_only_2_is_valid: `{0} may only specify known values, and invalid values were provided ({1}). The valid options are:\n{2}`,
     option_outputs_must_be_array: `"outputs" option must be an array of { name: string, path: string, options?: TypeDocOptions } values.`,
     specified_output_0_has_not_been_defined: `Specified output "{0}" has not been defined.`,
     // https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

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

@@ -49,6 +49,7 @@ declare const _default: {
     readonly unknown_inline_tag_0: "Encountered an unknown inline tag {0}";
     readonly open_brace_within_inline_tag: "Encountered an open brace within an inline tag, this is likely a mistake";
     readonly inline_tag_not_closed: "Inline tag is not closed";
+    readonly comment_for_0_links_to_1_not_included_in_docs_use_external_link_2: "The comment for {0} links to \"{1}\" which was resolved but is not included in the documentation. To fix this warning export it or add {2} to the externalSymbolLinkMappings option";
     readonly failed_to_resolve_link_to_0_in_comment_for_1: "Failed to resolve link to \"{0}\" in comment for {1}";
     readonly failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2: "Failed to resolve link to \"{0}\" in comment for {1}. You may have wanted \"{2}\"";
     readonly failed_to_resolve_link_to_0_in_readme_for_1: "Failed to resolve link to \"{0}\" in readme for {1}";
@@ -65,6 +66,7 @@ declare const _default: {
     readonly not_all_search_group_boosts_used_0: "Not all groups specified in searchGroupBoosts were used in the documentation. The unused groups were:\n\t{0}";
     readonly comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "Comment for {0} includes @categoryDescription for \"{1}\", but no child is placed in that category";
     readonly comment_for_0_includes_groupDescription_for_1_but_no_child_in_group: "Comment for {0} includes @groupDescription for \"{1}\", but no child is placed in that group";
+    readonly comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid: "Comment for {0} specifies @sortStrategy with \"{1}\", which is an invalid sort strategy, the following are valid:\n\t{2}";
     readonly label_0_for_1_cannot_be_referenced: "The label \"{0}\" for {1} cannot be referenced with a declaration reference. Labels may only contain A-Z, 0-9, and _, and may not start with a number";
     readonly modifier_tag_0_is_mutually_exclusive_with_1_in_comment_for_2: "The modifier tag {0} is mutually exclusive with {1} in the comment for {2}";
     readonly signature_0_has_unused_param_with_name_1: "The signature {0} has an @param with name \"{1}\", which was not used";
@@ -114,7 +116,7 @@ declare const _default: {
     readonly entry_point_0_did_not_match_any_packages: "The entry point glob {0} did not match any directories containing package.json";
     readonly file_0_not_an_object: "The file {0} is not an object";
     readonly serialized_project_referenced_0_not_part_of_project: "Serialized project referenced reflection {0}, which was not a part of the project";
-    readonly saved_relative_path_0_resolved_from_1_is_not_a_file: "Serialized project referenced {0}, which does not exist relative to {1}";
+    readonly saved_relative_path_0_resolved_from_1_does_not_exist: "Serialized project referenced {0}, which does not exist relative to {1}";
     readonly circular_reference_extends_0: "Circular reference encountered for \"extends\" field of {0}";
     readonly failed_resolve_0_to_file_in_1: "Failed to resolve {0} to a file in {1}";
     readonly glob_0_should_use_posix_slash: "The glob \"{0}\" escapes a non-special character. Glob inputs to TypeDoc may not use Windows path separators (\\), try replacing with posix path separators (/)";
@@ -257,13 +259,14 @@ declare const _default: {
     readonly useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set";
     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_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}";
     readonly visibility_filters_must_be_booleans: "All values of visibilityFilters must be booleans";
     readonly option_0_values_must_be_numbers: "All values of {0} must be numbers";
     readonly option_0_values_must_be_array_of_tags: "{0} must be an array of valid tag names";
-    readonly option_0_specified_1_but_only_2_is_valid: "{0} may only specify known values, and invalid values were provided ({1}). The valid sort strategies are:\n{2}";
+    readonly option_0_specified_1_but_only_2_is_valid: "{0} may only specify known values, and invalid values were provided ({1}). The valid options are:\n{2}";
     readonly option_outputs_must_be_array: "\"outputs\" option must be an array of { name: string, path: string, options?: TypeDocOptions } values.";
     readonly specified_output_0_has_not_been_defined: "Specified output \"{0}\" has not been defined.";
     readonly alert_note: "Note";

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

@@ -94,7 +94,7 @@ module.exports = localeUtils.buildIncompleteTranslation({
     entry_point_0_did_not_match_any_packages: "エントリ ポイント glob {0} は、package.json を含むディレクトリと一致しませんでした。",
     file_0_not_an_object: "ファイル {0} はオブジェクトではありません",
     serialized_project_referenced_0_not_part_of_project: "シリアル化されたプロジェクトは、プロジェクトの一部ではないリフレクション {0} を参照しました",
-    // saved_relative_path_0_resolved_from_1_is_not_a_file
+    // saved_relative_path_0_resolved_from_1_does_not_exist
     circular_reference_extends_0: '{0} の "extends" フィールドで循環参照が検出されました',
     failed_resolve_0_to_file_in_1: "{0} を {1} 内のファイルに解決できませんでした",
     option_0_can_only_be_specified_by_config_file: "'{0}' オプションは設定ファイル経由でのみ指定できます",

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

@@ -126,7 +126,7 @@ module.exports = localeUtils.buildIncompleteTranslation({
     file_0_not_an_object: "文件 {0} 不是对象",
     // deserialization
     serialized_project_referenced_0_not_part_of_project: "序列化项目引用了反射 {0}，但它不是项目的一部分",
-    saved_relative_path_0_resolved_from_1_is_not_a_file: "序列化项目引用的 {0} 不存在或无法在 {1} 下找到",
+    saved_relative_path_0_resolved_from_1_does_not_exist: "序列化项目引用的 {0} 不存在或无法在 {1} 下找到",
     // options
     circular_reference_extends_0: "{0} 的“extends”字段出现循环引用",
     failed_resolve_0_to_file_in_1: "无法将 {0} 解析为 {1} 中的文件",

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

@@ -114,7 +114,7 @@ declare const _default: {
     entry_point_0_did_not_match_any_packages: "入口点 glob {0} 与任何包含 package.json 的目录不匹配";
     file_0_not_an_object: "文件 {0} 不是对象";
     serialized_project_referenced_0_not_part_of_project: "序列化项目引用了反射 {0}，但它不是项目的一部分";
-    saved_relative_path_0_resolved_from_1_is_not_a_file: "序列化项目引用的 {0} 不存在或无法在 {1} 下找到";
+    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} 中的文件";
     option_0_can_only_be_specified_by_config_file: "“{0}”选项只能通过配置文件指定";

package/dist/lib/models/Comment.d.ts

@@ -2,6 +2,7 @@ import { type NormalizedPath } from "#utils";
 import type { Reflection } from "./Reflection.js";
 import { ReflectionSymbolId } from "./ReflectionSymbolId.js";
 import type { Deserializer, JSONOutput, Serializer } from "#serialization";
+import type { FileId } from "./FileRegistry.js";
 /**
  * Represents a parsed piece of a comment.
  * @category Comments
@@ -62,7 +63,7 @@ export interface RelativeLinkDisplayPart {
      * A link to either some document outside of the project or a reflection.
      * This may be `undefined` if the relative path does not exist.
      */
-    target: number | undefined;
+    target: FileId | undefined;
     /**
      * Anchor within the target page, validated after rendering if possible
      */

package/dist/lib/models/Comment.js

@@ -74,7 +74,7 @@ export class CommentTag {
      */
     similarTo(other) {
         return (this.tag === other.tag &&
-            this.name === other.tag &&
+            this.name === other.name &&
             Comment.combineDisplayParts(this.content) ===
                 Comment.combineDisplayParts(other.content));
     }

package/dist/lib/models/ContainerReflection.d.ts

@@ -49,6 +49,7 @@ export declare abstract class ContainerReflection extends Reflection {
     getChildrenByKind(kind: ReflectionKind): DeclarationReflection[];
     addChild(child: Reflection): void;
     removeChild(child: DeclarationReflection | DocumentReflection): void;
+    isContainer(): this is ContainerReflection;
     traverse(callback: TraverseCallback): void;
     toObject(serializer: Serializer): JSONOutput.ContainerReflection;
     fromObject(de: Deserializer, obj: JSONOutput.ContainerReflection): void;

package/dist/lib/models/ContainerReflection.js

@@ -100,6 +100,9 @@ export class ContainerReflection extends Reflection {
             delete this.childrenIncludingDocuments;
         }
     }
+    isContainer() {
+        return true;
+    }
     traverse(callback) {
         for (const child of this.children?.slice() || []) {
             if (callback(child, TraverseProperty.Children) === false) {

package/dist/lib/models/DocumentReflection.js

@@ -61,6 +61,6 @@ export class DocumentReflection extends Reflection {
         this.content = Comment.deserializeDisplayParts(de, obj.content);
         this.frontmatter = obj.frontmatter;
         this.relevanceBoost = obj.relevanceBoost;
-        this.children = de.reviveMany(obj.children, (obj) => de.reflectionBuilders.document(this, obj));
+        this.children = de.reviveMany(obj.children, (obj) => de.constructReflection(obj));
     }
 }

package/dist/lib/models/FileRegistry.d.ts

@@ -2,27 +2,39 @@ import type { Deserializer, JSONOutput, Serializer } from "#serialization";
 import type { ProjectReflection, Reflection } from "./index.js";
 import type { ReflectionId } from "./Reflection.js";
 import { type NormalizedPath } from "#utils";
+export type FileId = number & {
+    __mediaIdBrand: never;
+};
 export declare class FileRegistry {
     protected nextId: number;
-    protected mediaToReflection: Map<number, ReflectionId>;
-    protected mediaToPath: Map<number, NormalizedPath>;
+    protected mediaToReflection: Map<FileId, ReflectionId>;
+    protected mediaToPath: Map<FileId, NormalizedPath>;
     protected reflectionToPath: Map<ReflectionId, NormalizedPath>;
-    protected pathToMedia: Map<NormalizedPath, number>;
-    protected names: Map<number, string>;
+    protected pathToMedia: Map<NormalizedPath, FileId>;
+    protected names: Map<FileId, string>;
     protected nameUsage: Map<string, number>;
     registerAbsolute(absolute: NormalizedPath): {
-        target: number;
+        target: FileId;
         anchor: string | undefined;
     };
+    /**
+     * Registers the specified path as the canonical file for this reflection
+     */
     registerReflection(absolute: NormalizedPath, reflection: Reflection): void;
+    /**
+     * Registers the specified path as a path which should be resolved to the specified
+     * reflection. A reflection *may* be associated with multiple paths.
+     */
+    registerReflectionPath(absolute: NormalizedPath, reflection: Reflection): void;
     getReflectionPath(reflection: Reflection): string | undefined;
     register(sourcePath: NormalizedPath, relativePath: NormalizedPath): {
-        target: number;
+        target: FileId;
         anchor: string | undefined;
     } | undefined;
     removeReflection(reflection: Reflection): void;
-    resolve(id: number, project: ProjectReflection): string | Reflection | undefined;
-    getName(id: number): string | undefined;
+    resolve(id: FileId, project: ProjectReflection): string | Reflection | undefined;
+    resolvePath(id: FileId): string | undefined;
+    getName(id: FileId): string | undefined;
     getNameToAbsoluteMap(): ReadonlyMap<string, string>;
     toObject(ser: Serializer): JSONOutput.FileRegistry;
     /**

package/dist/lib/models/FileRegistry.js

@@ -16,7 +16,6 @@ export class FileRegistry {
             anchor = absolute.substring(anchorIndex + 1);
             absolute = absolute.substring(0, anchorIndex);
         }
-        absolute = absolute.replace(/#.*/, "");
         const existing = this.pathToMedia.get(absolute);
         if (existing) {
             return { target: existing, anchor };
@@ -25,11 +24,22 @@ export class FileRegistry {
         this.pathToMedia.set(absolute, this.nextId);
         return { target: this.nextId++, anchor };
     }
+    /**
+     * Registers the specified path as the canonical file for this reflection
+     */
     registerReflection(absolute, reflection) {
         const { target } = this.registerAbsolute(absolute);
         this.reflectionToPath.set(reflection.id, absolute);
         this.mediaToReflection.set(target, reflection.id);
     }
+    /**
+     * Registers the specified path as a path which should be resolved to the specified
+     * reflection. A reflection *may* be associated with multiple paths.
+     */
+    registerReflectionPath(absolute, reflection) {
+        const { target } = this.registerAbsolute(absolute);
+        this.mediaToReflection.set(target, reflection.id);
+    }
     getReflectionPath(reflection) {
         return this.reflectionToPath.get(reflection.id);
     }
@@ -50,6 +60,9 @@ export class FileRegistry {
         }
         return this.mediaToPath.get(id);
     }
+    resolvePath(id) {
+        return this.mediaToPath.get(id);
+    }
     getName(id) {
         const absolute = this.mediaToPath.get(id);
         if (!absolute)
@@ -104,15 +117,15 @@ export class FileRegistry {
      * a single object, and should merge in files from the other registries.
      */
     fromObject(de, obj) {
-        for (const [key, val] of Object.entries(obj.entries)) {
-            const absolute = NormalizedPathUtils.resolve(de.projectRoot, val);
-            de.oldFileIdToNewFileId[+key] = this.registerAbsolute(absolute).target;
+        for (const [fileId, path] of Object.entries(obj.entries)) {
+            const absolute = NormalizedPathUtils.resolve(de.projectRoot, path);
+            de.oldFileIdToNewFileId[+fileId] = this.registerAbsolute(absolute).target;
         }
         de.defer((project) => {
-            for (const [media, reflId] of Object.entries(obj.reflections)) {
+            for (const [fileId, reflId] of Object.entries(obj.reflections)) {
                 const refl = project.getReflectionById(de.oldIdToNewId[reflId]);
                 if (refl) {
-                    this.mediaToReflection.set(de.oldFileIdToNewFileId[+media], refl.id);
+                    this.mediaToReflection.set(de.oldFileIdToNewFileId[+fileId], refl.id);
                 }
             }
         });

package/dist/lib/models/ProjectReflection.js

@@ -32,7 +32,7 @@ export class ProjectReflection extends ContainerReflection {
      *
      * This may be replaced with a `Map<number, Reflection>` someday.
      */
-    reflections = { [this.id]: this };
+    reflections = {};
     /**
      * The name of the package that this reflection documents according to package.json.
      */

package/dist/lib/models/Reflection.d.ts

@@ -10,6 +10,7 @@ import type { ParameterReflection } from "./ParameterReflection.js";
 import type { ReferenceReflection } from "./ReferenceReflection.js";
 import type { SignatureReflection } from "./SignatureReflection.js";
 import type { TypeParameterReflection } from "./TypeParameterReflection.js";
+import type { ContainerReflection } from "./ContainerReflection.js";
 /**
  * Reset the reflection id.
  *
@@ -99,6 +100,10 @@ export interface TraverseCallback {
 export type ReflectionVisitor = {
     [K in keyof ReflectionVariant]?: (refl: ReflectionVariant[K]) => void;
 };
+/**
+ * Alias for a `number` which references a reflection.
+ * `-1` may be used for an invalid reflection ID.
+ */
 export type ReflectionId = number & {
     __reflectionIdBrand: never;
 };
@@ -189,6 +194,7 @@ export declare abstract class Reflection {
     isParameter(): this is ParameterReflection;
     isDocument(): this is DocumentReflection;
     isReference(): this is ReferenceReflection;
+    isContainer(): this is ContainerReflection;
     /**
      * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
      */

package/dist/lib/models/Reflection.js

@@ -419,6 +419,9 @@ let Reflection = (() => {
         isReference() {
             return this.variant === "reference";
         }
+        isContainer() {
+            return false;
+        }
         /**
          * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
          */

package/dist/lib/models/types.d.ts

@@ -1,4 +1,4 @@
-import type { Reflection } from "./Reflection.js";
+import type { Reflection, ReflectionId } from "./Reflection.js";
 import type { DeclarationReflection } from "./DeclarationReflection.js";
 import type { ProjectReflection } from "./ProjectReflection.js";
 import type { Deserializer, JSONOutput, Serializer } from "#serialization";
@@ -386,7 +386,7 @@ export declare class ReferenceType extends Type {
     private _project;
     private constructor();
     static createUnresolvedReference(name: string, target: ReflectionSymbolId, project: ProjectReflection, qualifiedName: string): ReferenceType;
-    static createResolvedReference(name: string, target: Reflection | number, project: ProjectReflection | null): ReferenceType;
+    static createResolvedReference(name: string, target: Reflection | ReflectionId, project: ProjectReflection | null): ReferenceType;
     /**
      * This is used for type parameters, which don't actually point to something,
      * and also for temporary references which will be cleaned up with real references

package/dist/lib/models/types.js

@@ -894,20 +894,22 @@ let ReferenceType = (() => {
         }
         fromObject(de, obj) {
             this.typeArguments = de.reviveMany(obj.typeArguments, (t) => de.constructType(t));
-            if (typeof obj.target === "number" && obj.target !== -1) {
-                de.defer((project) => {
-                    const target = project.getReflectionById(de.oldIdToNewId[obj.target] ?? -1);
-                    if (target) {
-                        this._project = project;
-                        this._target = target.id;
-                    }
-                    else {
-                        de.logger.warn(i18n.serialized_project_referenced_0_not_part_of_project(JSON.stringify(obj.target)));
-                    }
-                });
-            }
-            else if (obj.target === -1) {
-                this._target = -1;
+            if (typeof obj.target === "number") {
+                if (obj.target === -1) {
+                    this._target = -1;
+                }
+                else {
+                    de.defer((project) => {
+                        const target = project.getReflectionById(de.oldIdToNewId[obj.target] ?? -1);
+                        if (target) {
+                            this._project = project;
+                            this._target = target.id;
+                        }
+                        else {
+                            de.logger.warn(i18n.serialized_project_referenced_0_not_part_of_project(JSON.stringify(obj.target)));
+                        }
+                    });
+                }
             }
             else {
                 this._project = de.project;

package/dist/lib/output/plugins/AssetsPlugin.js

@@ -34,7 +34,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import { RendererComponent } from "../components.js";
 import { RendererEvent } from "../events.js";
-import { copySync, readFile, writeFileSync } from "../../utils/fs.js";
+import { copySync, isFile, readFile, writeFileSync } from "../../utils/fs.js";
 import { DefaultTheme } from "../themes/default/DefaultTheme.js";
 import { getStyles } from "../../utils/highlighter.js";
 import { getEnumKeys, i18n } from "#utils";
@@ -146,7 +146,12 @@ let AssetsPlugin = (() => {
                 const media = join(event.outputDirectory, "media");
                 const toCopy = event.project.files.getNameToAbsoluteMap();
                 for (const [fileName, absolute] of toCopy.entries()) {
-                    copySync(absolute, join(media, fileName));
+                    if (isFile(absolute)) {
+                        copySync(absolute, join(media, fileName));
+                    }
+                    else {
+                        this.application.logger.warn(i18n.relative_path_0_is_not_a_file_and_will_not_be_copied_to_output(absolute));
+                    }
                 }
             }
         }