typedoc 0.28.5 → 0.28.6

package/dist/lib/converter/comments/textParser.d.ts

@@ -18,6 +18,7 @@ import type { NormalizedPath, TranslatedString } from "#utils";
  */
 export declare class TextParserReentryState {
     withinLinkLabel: boolean;
+    withinLinkDest: boolean;
     private lastPartWasNewline;
     checkState(token: Token): void;
 }

package/dist/lib/converter/comments/textParser.js

@@ -10,17 +10,20 @@ const MdHelpers = new MarkdownIt().helpers;
  */
 export class TextParserReentryState {
     withinLinkLabel = false;
+    withinLinkDest = false;
     lastPartWasNewline = false;
     checkState(token) {
         switch (token.kind) {
             case TokenSyntaxKind.Code:
                 if (/\n\s*\n/.test(token.text)) {
                     this.withinLinkLabel = false;
+                    this.withinLinkDest = false;
                 }
                 break;
             case TokenSyntaxKind.NewLine:
                 if (this.lastPartWasNewline) {
                     this.withinLinkLabel = false;
+                    this.withinLinkDest = false;
                 }
                 break;
         }
@@ -33,16 +36,17 @@ export class TextParserReentryState {
  */
 export function textContent(sourcePath, token, i18n, warning, outContent, files, atNewLine, reentry) {
     let lastPartEnd = 0;
+    let canEndMarkdownLink = true;
     const data = {
         sourcePath,
         token,
         pos: 0, // relative to the token
-        i18n,
         warning,
         files: files,
         atNewLine,
     };
     function addRef(ref) {
+        canEndMarkdownLink = true;
         outContent.push({
             kind: "text",
             text: token.text.slice(lastPartEnd, ref.pos),
@@ -66,10 +70,15 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
         }
     }
     while (data.pos < token.text.length) {
-        const link = checkMarkdownLink(data, reentry);
-        if (link) {
-            addRef(link);
-            continue;
+        if (canEndMarkdownLink) {
+            const link = checkMarkdownLink(data, reentry);
+            if (link) {
+                addRef(link);
+                continue;
+            }
+            // If we're within a Markdown link, then `checkMarkdownLink`
+            // already scanned `token` up to a line feed (if any).
+            canEndMarkdownLink = !reentry.withinLinkLabel && !reentry.withinLinkDest;
         }
         const reference = checkReference(data);
         if (reference) {
@@ -81,7 +90,10 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
             addRef(tagLink);
             continue;
         }
-        data.atNewLine = token.text[data.pos] === "\n";
+        const atNewLine = token.text[data.pos] === "\n";
+        data.atNewLine = atNewLine;
+        if (atNewLine && !reentry.withinLinkDest)
+            canEndMarkdownLink = true;
         ++data.pos;
     }
     if (lastPartEnd !== token.text.length) {
@@ -101,9 +113,8 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
 function checkMarkdownLink(data, reentry) {
     const { token, sourcePath, files } = data;
     let searchStart;
-    if (reentry.withinLinkLabel) {
+    if (reentry.withinLinkLabel || reentry.withinLinkDest) {
         searchStart = data.pos;
-        reentry.withinLinkLabel = false;
     }
     else if (token.text[data.pos] === "[") {
         searchStart = data.pos + 1;
@@ -111,34 +122,60 @@ function checkMarkdownLink(data, reentry) {
     else {
         return;
     }
-    const labelEnd = findLabelEnd(token.text, searchStart);
-    if (labelEnd === -1) {
-        // This markdown link might be split across multiple display parts
-        // [ `text` ](link)
-        // ^^ text
-        //   ^^^^^^ code
-        //         ^^^^^^^^ text
-        reentry.withinLinkLabel = true;
-        return;
+    if (!reentry.withinLinkDest) {
+        const labelEnd = findLabelEnd(token.text, searchStart);
+        if (labelEnd === -1 || token.text[labelEnd] === "\n") {
+            // This markdown link might be split across multiple lines or input tokens
+            //     [prefix `code` suffix](target)
+            //     ........^^^^^^................
+            // Unless we encounter two consecutive line feeds, expect it to keep going.
+            reentry.withinLinkLabel = labelEnd !== data.pos || !data.atNewLine;
+            return;
+        }
+        reentry.withinLinkLabel = false;
+        if (!token.text.startsWith("](", labelEnd))
+            return;
+        searchStart = labelEnd + 2;
     }
-    if (token.text[labelEnd] === "]" && token.text[labelEnd + 1] === "(") {
-        const link = MdHelpers.parseLinkDestination(token.text, labelEnd + 2, token.text.length);
-        if (link.ok) {
-            // Only make a relative-link display part if it's actually a relative link.
-            // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
-            if (isRelativePath(link.str)) {
-                const { target, anchor } = files.register(sourcePath, link.str) || { target: undefined, anchor: undefined };
-                return {
-                    pos: labelEnd + 2,
-                    end: link.pos,
-                    target,
-                    targetAnchor: anchor,
-                };
-            }
-            // This was a link, skip ahead to ensure we don't happen to parse
-            // something else as a link within the link.
-            data.pos = link.pos - 1;
+    // Skip whitespace (including line breaks) between "](" and the link destination.
+    // https://spec.commonmark.org/0.31.2/#links
+    const end = token.text.length;
+    let lookahead = searchStart;
+    for (let newlines = 0;; ++lookahead) {
+        if (lookahead === end) {
+            reentry.withinLinkDest = true;
+            return;
+        }
+        switch (token.text[lookahead]) {
+            case "\n":
+                if (++newlines === 2) {
+                    reentry.withinLinkDest = false;
+                    return;
+                }
+                continue;
+            case " ":
+            case "\t":
+                continue;
         }
+        break;
+    }
+    reentry.withinLinkDest = false;
+    const link = MdHelpers.parseLinkDestination(token.text, lookahead, end);
+    if (link.ok) {
+        // Only make a relative-link display part if it's actually a relative link.
+        // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
+        if (isRelativePath(link.str)) {
+            const { target, anchor } = files.register(sourcePath, link.str) || { target: undefined, anchor: undefined };
+            return {
+                pos: lookahead,
+                end: link.pos,
+                target,
+                targetAnchor: anchor,
+            };
+        }
+        // This was a link, skip ahead to ensure we don't happen to parse
+        // something else as a link within the link.
+        data.pos = link.pos - 1;
     }
 }
 /**
@@ -230,6 +267,11 @@ function isRelativePath(link) {
 function findLabelEnd(text, pos) {
     while (pos < text.length) {
         switch (text[pos]) {
+            case "\\":
+                ++pos;
+                if (pos < text.length && text[pos] === "\n")
+                    return pos;
+                break;
             case "\n":
             case "]":
             case "[":

package/dist/lib/converter/context.js

@@ -130,14 +130,25 @@ export class Context {
         return reflection;
     }
     postReflectionCreation(reflection, symbol, exportSymbol) {
-        if (exportSymbol &&
-            reflection.kind &
-                (ReflectionKind.SomeModule | ReflectionKind.Reference)) {
+        // Allow comments on export declarations to take priority over comments directly
+        // on the symbol to enable overriding comments on modules/references, #1504
+        if (!reflection.comment &&
+            exportSymbol &&
+            (reflection.kind &
+                (ReflectionKind.SomeModule | ReflectionKind.Reference))) {
             reflection.comment = this.getComment(exportSymbol, reflection.kind);
         }
+        // If that didn't get us a comment (the normal case), then get the comment from
+        // the source declarations, this is the common case.
         if (symbol && !reflection.comment) {
             reflection.comment = this.getComment(symbol, reflection.kind);
         }
+        // If we still don't have a comment, check for any comments on the export declaration,
+        // we don't have to worry about functions being weird in this case as the regular declaration
+        // doesn't have any comment.
+        if (exportSymbol && !reflection.comment) {
+            reflection.comment = this.getComment(exportSymbol, ReflectionKind.Reference);
+        }
         if (this.shouldBeStatic) {
             reflection.setFlag(ReflectionFlag.Static);
         }

package/dist/lib/converter/converter.js

@@ -305,6 +305,9 @@ let Converter = (() => {
             const programs = unique(entryPoints.map((e) => e.program));
             this.externalPatternCache = void 0;
             const project = new ProjectReflection(this.application.options.getValue("name"), this.application.files);
+            if (this.owner.options.packageDir) {
+                project.files.registerReflectionPath(normalizePath(this.owner.options.packageDir), project);
+            }
             const context = new Context(this, programs, project);
             this.trigger(Converter.EVENT_BEGIN, context);
             this.addProjectDocuments(project);

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/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}`,
@@ -124,7 +125,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}`,

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}";
@@ -114,7 +115,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 (/)";

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/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

@@ -99,6 +99,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;
 };

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));
+                    }
                 }
             }
         }

package/dist/lib/output/themes/MarkedPlugin.js

@@ -129,8 +129,8 @@ let MarkedPlugin = (() => {
         getHighlighted(text, lang) {
             lang = lang || "typescript";
             lang = lang.toLowerCase();
-            if (!isSupportedLanguage(lang)) {
-                if (isLoadedLanguage(lang)) {
+            if (!isLoadedLanguage(lang)) {
+                if (isSupportedLanguage(lang)) {
                     this.application.logger.warn(i18n.unloaded_language_0_not_highlighted_in_comment_for_1(lang, getFriendlyFullName(this.page?.model || { name: "(unknown)" })));
                 }
                 else {

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

@@ -1,4 +1,4 @@
-import { type FileRegistry, ProjectReflection, type ReflectionVariant, type TypeKindMap } from "#models";
+import { type FileId, type FileRegistry, ProjectReflection, type ReflectionId, type ReflectionVariant, type TypeKindMap } from "#models";
 import { type Logger, type NormalizedPath } from "#utils";
 import * as JSONOutput from "./schema.js";
 export interface DeserializerComponent {
@@ -30,8 +30,8 @@ export declare class Deserializer {
      * Only set when deserializing.
      */
     projectRoot: NormalizedPath;
-    oldIdToNewId: Record<number, number | undefined>;
-    oldFileIdToNewFileId: Record<number, number | undefined>;
+    oldIdToNewId: Record<ReflectionId, ReflectionId | undefined>;
+    oldFileIdToNewFileId: Record<FileId, FileId | undefined>;
     project: ProjectReflection | undefined;
     constructor(logger: Logger);
     addDeserializer(de: DeserializerComponent): void;

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

@@ -52,6 +52,8 @@ type ToSerialized<T> = T extends Primitive ? T : T extends bigint ? {
 type S<T, K extends keyof T> = {
     -readonly [K2 in K]: ToSerialized<T[K2]>;
 };
+export type ReflectionId = M.ReflectionId;
+export type FileId = M.FileId;
 export interface ReflectionSymbolId {
     packageName: string;
     packagePath: NormalizedPath;
@@ -85,7 +87,7 @@ export interface ReferenceReflection extends Omit<DeclarationReflection, "varian
      * -1 if the reference refers to a symbol that does not exist in the documentation.
      * Otherwise, the reflection ID.
      */
-    target: number;
+    target: ReflectionId;
 }
 /** @category Reflections */
 export interface SignatureReflection extends Omit<Reflection, "variant">, S<M.SignatureReflection, "variant" | "sources" | "parameters" | "typeParameters" | "type" | "overwrites" | "inheritedFrom" | "implementationOf"> {
@@ -107,12 +109,12 @@ export interface ProjectReflection extends Omit<ContainerReflection, "variant">,
      * See {@link SCHEMA_VERSION} for the current version.
      */
     schemaVersion: string;
-    symbolIdMap: Record<number, ReflectionSymbolId> | IfInternal<undefined, never>;
+    symbolIdMap: Record<ReflectionId, ReflectionSymbolId> | IfInternal<undefined, never>;
     files: FileRegistry;
 }
 /** @category Reflections */
 export interface ContainerReflection extends Reflection, S<M.ContainerReflection, "children" | "documents" | "groups" | "categories"> {
-    childrenIncludingDocuments?: number[];
+    childrenIncludingDocuments?: ReflectionId[];
 }
 /** @category Reflections */
 export interface Reflection extends S<M.Reflection, "id" | "variant" | "name" | "kind" | "comment"> {
@@ -172,7 +174,7 @@ export interface QueryType extends Type, S<M.QueryType, "type" | "queryType"> {
 }
 /** @category Types */
 export interface ReferenceType extends Type, S<M.ReferenceType, "type" | "name" | "typeArguments" | "package" | "externalUrl"> {
-    target: number | ReflectionSymbolId;
+    target: ReflectionId | ReflectionSymbolId;
     qualifiedName?: string;
     refersToTypeParameter?: boolean;
     preferValues?: boolean;
@@ -247,7 +249,7 @@ export interface InlineTagDisplayPart {
     kind: "inline-tag";
     tag: `@${string}`;
     text: string;
-    target?: string | number | ReflectionSymbolId;
+    target?: string | ReflectionId | ReflectionSymbolId;
     tsLinkText?: string;
 }
 /**
@@ -264,7 +266,7 @@ export interface RelativeLinkDisplayPart {
     /**
      * File ID, if present
      */
-    target?: number;
+    target?: FileId;
     /**
      * Anchor within the target file, if present
      */
@@ -274,8 +276,8 @@ export interface SourceReference extends S<M.SourceReference, "fileName" | "line
 }
 export interface FileRegistry {
     /** Relative path according to the serialization root */
-    entries: Record<number, NormalizedPath>;
+    entries: Record<FileId, NormalizedPath>;
     /** File ID to reflection ID */
-    reflections: Record<number, number>;
+    reflections: Record<FileId, ReflectionId>;
 }
 export {};

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

@@ -1,9 +1,9 @@
-import { FileRegistry } from "../models/FileRegistry.js";
+import { type FileId, FileRegistry } from "../models/FileRegistry.js";
 import type { Deserializer, JSONOutput } from "#serialization";
 import { type NormalizedPath } from "#utils";
 export declare class ValidatingFileRegistry extends FileRegistry {
     register(sourcePath: NormalizedPath, relativePath: NormalizedPath): {
-        target: number;
+        target: FileId;
         anchor: string | undefined;
     } | undefined;
     fromObject(de: Deserializer, obj: JSONOutput.FileRegistry): void;

package/dist/lib/utils/ValidatingFileRegistry.js

@@ -1,11 +1,14 @@
 import { FileRegistry } from "../models/FileRegistry.js";
-import { isFile } from "./fs.js";
 import { i18n, NormalizedPathUtils } from "#utils";
+import { existsSync } from "fs";
 export class ValidatingFileRegistry extends FileRegistry {
     register(sourcePath, relativePath) {
         const absolute = NormalizedPathUtils.resolve(NormalizedPathUtils.dirname(sourcePath), relativePath);
         const absoluteWithoutAnchor = absolute.replace(/#.*/, "");
-        if (!isFile(absoluteWithoutAnchor)) {
+        // Note: We allow paths to directories to be registered here, but the AssetsPlugin will not
+        // copy them to the output path. This is so that we can link to directories and associate them
+        // with reflections in packages mode.
+        if (!existsSync(absoluteWithoutAnchor)) {
             return;
         }
         return this.registerAbsolute(absolute);
@@ -13,8 +16,8 @@ export class ValidatingFileRegistry extends FileRegistry {
     fromObject(de, obj) {
         for (const [key, val] of Object.entries(obj.entries)) {
             const absolute = NormalizedPathUtils.resolve(de.projectRoot, val);
-            if (!isFile(absolute)) {
-                de.logger.warn(i18n.saved_relative_path_0_resolved_from_1_is_not_a_file(val, de.projectRoot));
+            if (!existsSync(absolute)) {
+                de.logger.warn(i18n.saved_relative_path_0_resolved_from_1_does_not_exist(val, de.projectRoot));
                 continue;
             }
             de.oldFileIdToNewFileId[+key] = this.registerAbsolute(absolute).target;

package/dist/lib/validation/links.js

@@ -7,7 +7,7 @@ function getBrokenPartLinks(parts) {
         if (part.kind === "inline-tag" &&
             linkTags.includes(part.tag) &&
             (!part.target || part.target instanceof ReflectionSymbolId)) {
-            links.push(part.text.trim());
+            links.push(part);
         }
     }
     return links;
@@ -32,52 +32,50 @@ export function validateLinks(project, logger) {
 function checkReflection(reflection, logger) {
     if (reflection.isProject() || reflection.isDeclaration()) {
         for (const broken of getBrokenPartLinks(reflection.readme || [])) {
+            const linkText = broken.text.trim();
             // #2360, "@" is a future reserved character in TSDoc component paths
             // If a link starts with it, and doesn't include a module source indicator "!"
             // then the user probably is trying to link to a package containing "@" with an absolute link.
-            if (broken.startsWith("@") && !broken.includes("!")) {
-                logger.warn(i18n.failed_to_resolve_link_to_0_in_readme_for_1_may_have_meant_2(broken, reflection.getFriendlyFullName(), broken.replace(/[.#~]/, "!")));
+            if (linkText.startsWith("@") && !linkText.includes("!")) {
+                logger.warn(i18n.failed_to_resolve_link_to_0_in_readme_for_1_may_have_meant_2(linkText, reflection.getFriendlyFullName(), linkText.replace(/[.#~]/, "!")));
             }
             else {
-                logger.warn(i18n.failed_to_resolve_link_to_0_in_readme_for_1(broken, reflection.getFriendlyFullName()));
+                logger.warn(i18n.failed_to_resolve_link_to_0_in_readme_for_1(linkText, reflection.getFriendlyFullName()));
             }
         }
     }
     if (reflection.isDocument()) {
         for (const broken of getBrokenPartLinks(reflection.content)) {
-            // #2360, "@" is a future reserved character in TSDoc component paths
-            // If a link starts with it, and doesn't include a module source indicator "!"
-            // then the user probably is trying to link to a package containing "@" with an absolute link.
-            if (broken.startsWith("@") && !broken.includes("!")) {
-                logger.warn(i18n.failed_to_resolve_link_to_0_in_document_1_may_have_meant_2(broken, reflection.getFriendlyFullName(), broken.replace(/[.#~]/, "!")));
+            const linkText = broken.text.trim();
+            if (linkText.startsWith("@") && !linkText.includes("!")) {
+                logger.warn(i18n.failed_to_resolve_link_to_0_in_document_1_may_have_meant_2(linkText, reflection.getFriendlyFullName(), linkText.replace(/[.#~]/, "!")));
             }
             else {
-                logger.warn(i18n.failed_to_resolve_link_to_0_in_document_1(broken, reflection.getFriendlyFullName()));
+                logger.warn(i18n.failed_to_resolve_link_to_0_in_document_1(linkText, reflection.getFriendlyFullName()));
             }
         }
     }
     for (const broken of getBrokenLinks(reflection.comment)) {
-        // #2360, "@" is a future reserved character in TSDoc component paths
-        // If a link starts with it, and doesn't include a module source indicator "!"
-        // then the user probably is trying to link to a package containing "@" with an absolute link.
-        if (broken.startsWith("@") && !broken.includes("!")) {
-            logger.warn(i18n.failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2(broken, reflection.getFriendlyFullName(), broken.replace(/[.#~]/, "!")));
-        }
-        else {
-            logger.warn(i18n.failed_to_resolve_link_to_0_in_comment_for_1(broken, reflection.getFriendlyFullName()));
-        }
+        reportBrokenCommentLink(broken, reflection, logger);
     }
     if (reflection.isDeclaration() &&
         reflection.kindOf(ReflectionKind.TypeAlias) &&
         reflection.type?.type === "union" &&
         reflection.type.elementSummaries) {
         for (const broken of reflection.type.elementSummaries.flatMap(getBrokenPartLinks)) {
-            if (broken.startsWith("@") && !broken.includes("!")) {
-                logger.warn(i18n.failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2(broken, reflection.getFriendlyFullName(), broken.replace(/[.#~]/, "!")));
-            }
-            else {
-                logger.warn(i18n.failed_to_resolve_link_to_0_in_comment_for_1(broken, reflection.getFriendlyFullName()));
-            }
+            reportBrokenCommentLink(broken, reflection, logger);
         }
     }
 }
+function reportBrokenCommentLink(broken, reflection, logger) {
+    const linkText = broken.text.trim();
+    if (broken.target instanceof ReflectionSymbolId) {
+        logger.warn(i18n.comment_for_0_links_to_1_not_included_in_docs_use_external_link_2(reflection.getFriendlyFullName(), linkText, `{ "${broken.target.packageName}": { "${broken.target.qualifiedName}": "#" }}`));
+    }
+    else if (linkText.startsWith("@") && !linkText.includes("!")) {
+        logger.warn(i18n.failed_to_resolve_link_to_0_in_comment_for_1_may_have_meant_2(linkText, reflection.getFriendlyFullName(), linkText.replace(/[.#~]/, "!")));
+    }
+    else {
+        logger.warn(i18n.failed_to_resolve_link_to_0_in_comment_for_1(linkText, reflection.getFriendlyFullName()));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.28.5",
+  "version": "0.28.6",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {