Support relative links to package dir

Resolves #2961

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,10 @@ title: Changelog
 
 ## Unreleased
 
+### Features
+
+- TypeDoc now supports resolving relative paths in links to the package directory as belonging to the project, #2961.
+
 ### Bug Fixes
 
 - Attempting to highlight a supported language which is not enabled is now a warning, not an error, #2956.

src/lib/converter/comments/textParser.ts

@@ -7,7 +7,7 @@
  */
 import type { TranslationProxy } from "../../internationalization/index.js";
 import type { CommentDisplayPart, RelativeLinkDisplayPart } from "../../models/index.js";
-import type { FileRegistry } from "../../models/FileRegistry.js";
+import type { FileId, FileRegistry } from "../../models/FileRegistry.js";
 import { HtmlAttributeParser, ParserState } from "#node-utils";
 import { type Token, TokenSyntaxKind } from "./lexer.js";
 
@@ -28,7 +28,7 @@ interface RelativeLink {
     pos: number;
     end: number;
     /** May be undefined if the registry can't find this file */
-    target: number | undefined;
+    target: FileId | undefined;
     targetAnchor: string | undefined;
 }
 

src/lib/converter/converter.ts

@@ -322,6 +322,10 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
             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);

src/lib/converter/plugins/PackagePlugin.ts

@@ -6,7 +6,7 @@ import type { ProjectReflection } from "../../models/index.js";
 import { ApplicationEvents } from "../../application-events.js";
 import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.js";
-import { type GlobString, i18n, MinimalSourceFile, type NormalizedPath } from "#utils";
+import { type GlobString, i18n, MinimalSourceFile, type NormalizedPath, NormalizedPathUtils } from "#utils";
 import {
     discoverPackageJson,
     type EntryPointStrategy,
@@ -139,6 +139,10 @@ export class PackagePlugin extends ConverterComponent {
             );
 
             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...

src/lib/internationalization/locales/de.cts

@@ -221,7 +221,7 @@ export = localeUtils.buildIncompleteTranslation({
     // 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:
+    saved_relative_path_0_resolved_from_1_does_not_exist:
         "Serialisiertes Projekt referenziert {0}, was relativ zu {1} nicht existiert",
 
     // options

src/lib/internationalization/locales/en.cts

@@ -210,7 +210,7 @@ export = {
     // 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:
+    saved_relative_path_0_resolved_from_1_does_not_exist:
         `Serialized project referenced {0}, which does not exist relative to {1}`,
 
     // options

src/lib/internationalization/locales/ja.cts

@@ -146,7 +146,7 @@ export = localeUtils.buildIncompleteTranslation({
     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}' オプションは設定ファイル経由でのみ指定できます",

src/lib/internationalization/locales/zh.cts

@@ -181,7 +181,7 @@ export = localeUtils.buildIncompleteTranslation({
 
     // 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”字段出现循环引用",

src/lib/models/Comment.ts

@@ -1,8 +1,9 @@
 import { assertNever, i18n, NonEnumerable, type NormalizedPath, removeIf } from "#utils";
-import type { Reflection } from "./Reflection.js";
+import type { Reflection, ReflectionId } 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.
@@ -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
      */
@@ -238,10 +239,10 @@ export class Comment {
         parts: JSONOutput.CommentDisplayPart[],
     ): CommentDisplayPart[] {
         const links: [
-            number,
+            ReflectionId,
             InlineTagDisplayPart | RelativeLinkDisplayPart,
         ][] = [];
-        const files: [number, RelativeLinkDisplayPart][] = [];
+        const files: [FileId, RelativeLinkDisplayPart][] = [];
 
         const result = parts.map((part): CommentDisplayPart => {
             switch (part.kind) {

src/lib/models/DeclarationReflection.ts

@@ -1,5 +1,5 @@
 import { type ReferenceType, ReflectionType, type SomeType } from "./types.js";
-import { type TraverseCallback, TraverseProperty } from "./Reflection.js";
+import { type ReflectionId, type TraverseCallback, TraverseProperty } from "./Reflection.js";
 import { ContainerReflection } from "./ContainerReflection.js";
 import type { SignatureReflection } from "./SignatureReflection.js";
 import type { TypeParameterReflection } from "./TypeParameterReflection.js";
@@ -346,7 +346,7 @@ export class DeclarationReflection extends ContainerReflection {
             de.defer(() => {
                 for (const [id, sid] of Object.entries(obj.symbolIdMap || {})) {
                     const refl = this.project.getReflectionById(
-                        de.oldIdToNewId[+id] ?? -1,
+                        de.oldIdToNewId[+id as ReflectionId] ?? -1,
                     );
                     if (refl) {
                         this.project.registerSymbolId(