typedoc 0.28.6 → 0.28.8

package/dist/lib/converter/context.js

@@ -4,10 +4,10 @@ import { Comment, ContainerReflection, DeclarationReflection, ReferenceType, Ref
 import { isNamedNode } from "./utils/nodes.js";
 import { ConverterEvents } from "./converter-events.js";
 import { resolveAliasedSymbol } from "./utils/symbols.js";
-import { getComment, getFileComment, getJsDocComment, getNodeComment, getSignatureComment } from "./comments/index.js";
+import { getComment, getFileComment, getJsDocComment, getNodeComment, getSignatureComment, } from "./comments/index.js";
 import { getHumanName, getQualifiedName } from "../utils/tsutils.js";
 import { findPackageForPath, normalizePath } from "#node-utils";
-import { createSymbolId } from "./factories/symbol-id.js";
+import { createSymbolIdImpl } from "./factories/symbol-id.js";
 import { removeIf } from "#utils";
 /**
  * The context describes the current state the converter is in.
@@ -185,7 +185,7 @@ export class Context {
      * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
      */
     createSymbolReference(symbol, context, name) {
-        const ref = ReferenceType.createUnresolvedReference(name ?? symbol.name, createSymbolId(symbol), context.project, getQualifiedName(symbol, name ?? symbol.name));
+        const ref = ReferenceType.createUnresolvedReference(name ?? symbol.name, this.createSymbolId(symbol), context.project, getQualifiedName(symbol, name ?? symbol.name));
         ref.refersToTypeParameter = !!(symbol.flags & ts.SymbolFlags.TypeParameter);
         const symbolPath = symbol.declarations?.[0]?.getSourceFile().fileName;
         if (!symbolPath)
@@ -193,6 +193,17 @@ export class Context {
         ref.package = findPackageForPath(symbolPath)?.[0];
         return ref;
     }
+    /**
+     * Create a stable {@link ReflectionSymbolId} for the provided symbol,
+     * optionally targeting a specific declaration.
+     *
+     * @privateRemarks
+     * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
+     * It might also turn out to be generally useful for other plugin users.
+     */
+    createSymbolId(symbol, declaration) {
+        return createSymbolIdImpl(symbol, declaration);
+    }
     addChild(reflection) {
         if (this.scope instanceof ContainerReflection) {
             this.scope.addChild(reflection);
@@ -211,7 +222,7 @@ export class Context {
     registerReflection(reflection, symbol, filePath) {
         if (symbol) {
             this.reflectionIdToSymbolMap.set(reflection.id, symbol);
-            const id = createSymbolId(symbol);
+            const id = this.createSymbolId(symbol);
             // #2466
             // If we just registered a member of a class or interface, then we need to check if
             // we've registered this symbol before under the wrong parent reflection.
@@ -237,7 +248,7 @@ export class Context {
         }
     }
     getReflectionFromSymbol(symbol) {
-        return this.project.getReflectionFromSymbolId(createSymbolId(symbol));
+        return this.project.getReflectionFromSymbolId(this.createSymbolId(symbol));
     }
     getSymbolFromReflection(reflection) {
         return this.reflectionIdToSymbolMap.get(reflection.id);
@@ -246,20 +257,29 @@ export class Context {
     setActiveProgram(program) {
         this._program = program;
     }
+    createCommentContext() {
+        return {
+            config: this.converter.config,
+            logger: this.logger,
+            checker: this.checker,
+            files: this.project.files,
+            createSymbolId: (s, d) => this.createSymbolId(s, d),
+        };
+    }
     getComment(symbol, kind) {
-        return getComment(symbol, kind, this.converter.config, this.logger, this.checker, this.project.files);
+        return getComment(symbol, kind, this.createCommentContext());
     }
     getNodeComment(node, moduleComment) {
-        return getNodeComment(node, moduleComment, this.converter.config, this.logger, this.checker, this.project.files);
+        return getNodeComment(node, moduleComment, this.createCommentContext());
     }
     getFileComment(node) {
-        return getFileComment(node, this.converter.config, this.logger, this.checker, this.project.files);
+        return getFileComment(node, this.createCommentContext());
     }
     getJsDocComment(declaration) {
-        return getJsDocComment(declaration, this.converter.config, this.logger, this.checker, this.project.files);
+        return getJsDocComment(declaration, this.createCommentContext());
     }
     getSignatureComment(declaration) {
-        return getSignatureComment(declaration, this.converter.config, this.logger, this.checker, this.project.files);
+        return getSignatureComment(declaration, this.createCommentContext());
     }
     shouldInline(symbol, name) {
         if (this.preventInline.has(name))

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

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import type { Application } from "../application.js";
-import { Comment, type CommentDisplayPart, type ContainerReflection, type DeclarationReflection, DocumentReflection, type ParameterReflection, ProjectReflection, type Reflection, type ReflectionSymbolId, type SignatureReflection, type SomeType, type TypeParameterReflection } from "../models/index.js";
+import { Comment, type CommentDisplayPart, type ContainerReflection, type DeclarationReflection, DocumentReflection, type ParameterReflection, ProjectReflection, Reflection, type ReflectionSymbolId, type SignatureReflection, type SomeType, type TypeParameterReflection } from "../models/index.js";
 import { Context } from "./context.js";
 import { AbstractComponent } from "../utils/component.js";
 import { type GlobString, MinimalSourceFile } from "#utils";
@@ -187,6 +187,8 @@ export declare class Converter extends AbstractComponent<Application, ConverterE
     addUnknownSymbolResolver(resolver: ExternalSymbolResolver): void;
     /** @internal */
     resolveExternalLink(ref: DeclarationReference, refl: Reflection, part: CommentDisplayPart | undefined, symbolId: ReflectionSymbolId | undefined): ExternalResolveResult | string | undefined;
+    resolveLinks(reflection: Reflection): void;
+    /** @deprecated just pass the reflection */
     resolveLinks(comment: Comment, owner: Reflection): void;
     resolveLinks(parts: readonly CommentDisplayPart[], owner: Reflection): CommentDisplayPart[];
     /**

package/dist/lib/converter/converter.js

@@ -34,7 +34,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 };
 import ts from "typescript";
 import { ok } from "assert";
-import { Comment, DocumentReflection, ProjectReflection, ReflectionKind, } from "../models/index.js";
+import { Comment, DocumentReflection, ProjectReflection, Reflection, ReflectionKind, } from "../models/index.js";
 import { Context } from "./context.js";
 import { AbstractComponent } from "../utils/component.js";
 import { getDocumentEntryPoints, Option, readFile } from "../utils/index.js";
@@ -374,8 +374,11 @@ let Converter = (() => {
             }
         }
         resolveLinks(comment, owner) {
-            if (comment instanceof Comment) {
-                resolveLinks(comment, owner, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });
+            if (comment instanceof Reflection) {
+                resolveLinks(comment, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });
+            }
+            else if (comment instanceof Comment) {
+                resolveLinks(owner, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });
             }
             else {
                 return resolvePartLinks(owner, comment, (ref, part, refl, id) => this.resolveExternalLink(ref, part, refl, id), { preserveLinkText: this.preserveLinkText });

package/dist/lib/converter/factories/signature.js

@@ -4,7 +4,6 @@ import { DeclarationReflection, IntrinsicType, ParameterReflection, PredicateTyp
 import { ConverterEvents } from "../converter-events.js";
 import { convertDefaultValue } from "../convert-expression.js";
 import { removeUndefined } from "../utils/reflections.js";
-import { createSymbolId } from "./symbol-id.js";
 export function createSignature(context, kind, signature, symbol, declaration) {
     assert(context.scope instanceof DeclarationReflection);
     declaration ||= signature.getDeclaration();
@@ -17,7 +16,7 @@ export function createSignature(context, kind, signature, symbol, declaration) {
         sigRef.setFlag(ReflectionFlag.Static);
     }
     if (symbol && declaration) {
-        context.project.registerSymbolId(sigRef, createSymbolId(symbol, declaration));
+        context.project.registerSymbolId(sigRef, context.createSymbolId(symbol, declaration));
     }
     let parentReflection = context.scope;
     if (parentReflection.kindOf(ReflectionKind.TypeLiteral) &&

package/dist/lib/converter/factories/symbol-id.d.ts

@@ -1,4 +1,4 @@
 import { ReflectionSymbolId } from "#models";
 import ts from "typescript";
-export declare function createSymbolId(symbol: ts.Symbol, declaration?: ts.Declaration): ReflectionSymbolId;
+export declare function createSymbolIdImpl(symbol: ts.Symbol, declaration?: ts.Declaration): ReflectionSymbolId;
 export declare function addInferredDeclarationMapPaths(opts: ts.CompilerOptions, files: readonly string[]): void;

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

@@ -7,7 +7,8 @@ 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);

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/CategoryPlugin.d.ts

@@ -1,4 +1,4 @@
-import { type DeclarationReflection, type DocumentReflection } from "../../models/index.js";
+import { ContainerReflection, type DeclarationReflection, type DocumentReflection } from "../../models/index.js";
 import { ConverterComponent } from "../components.js";
 import type { Converter } from "../converter.js";
 /**
@@ -7,7 +7,7 @@ import type { Converter } from "../converter.js";
  * The handler sets the ´category´ property of all reflections.
  */
 export declare class CategoryPlugin extends ConverterComponent {
-    sortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
+    defaultSortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     accessor defaultCategory: string;
     accessor categoryOrder: string[];
     accessor categorizeByGroup: boolean;
@@ -35,6 +35,7 @@ export declare class CategoryPlugin extends ConverterComponent {
      * @returns An array containing all children of the given reflection categorized
      */
     private getReflectionCategories;
+    getSortFunction(reflection: ContainerReflection): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;
     /**
      * Callback used to sort categories by name.
      *

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

@@ -39,6 +39,7 @@ import { getSortFunction, Option } from "../../utils/index.js";
 import { ConverterComponent } from "../components.js";
 import { ConverterEvents } from "../converter-events.js";
 import { i18n } from "#utils";
+import { isValidSortStrategy } from "../../utils/sort.js";
 /**
  * A handler that sorts and categorizes the found reflections in the resolving phase.
  *
@@ -66,7 +67,7 @@ let CategoryPlugin = (() => {
             __esDecorate(this, null, _categorizeByGroup_decorators, { kind: "accessor", name: "categorizeByGroup", static: false, private: false, access: { has: obj => "categorizeByGroup" in obj, get: obj => obj.categorizeByGroup, set: (obj, value) => { obj.categorizeByGroup = value; } }, metadata: _metadata }, _categorizeByGroup_initializers, _categorizeByGroup_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        sortFunction;
+        defaultSortFunction;
         #defaultCategory_accessor_storage = __runInitializers(this, _defaultCategory_initializers, void 0);
         get defaultCategory() { return this.#defaultCategory_accessor_storage; }
         set defaultCategory(value) { this.#defaultCategory_accessor_storage = value; }
@@ -97,7 +98,7 @@ let CategoryPlugin = (() => {
          * Triggered when the converter begins converting a project.
          */
         setup() {
-            this.sortFunction = getSortFunction(this.application.options);
+            this.defaultSortFunction = getSortFunction(this.application.options);
             // Set up static properties
             if (this.defaultCategory) {
                 CategoryPlugin.defaultCategory = this.defaultCategory;
@@ -201,10 +202,21 @@ let CategoryPlugin = (() => {
                 }
             }
             for (const cat of categories.values()) {
-                this.sortFunction(cat.children);
+                this.getSortFunction(parent)(cat.children);
             }
             return Array.from(categories.values());
         }
+        getSortFunction(reflection) {
+            const tag = reflection.comment?.getTag("@sortStrategy");
+            if (tag) {
+                const text = Comment.combineDisplayParts(tag.content);
+                // We don't need to warn about invalid strategies here because the group plugin
+                // runs first and will have already warned.
+                const strategies = text.split(/[,\s]+/).filter(isValidSortStrategy);
+                return getSortFunction(this.application.options, strategies);
+            }
+            return this.defaultSortFunction;
+        }
         /**
          * Callback used to sort categories by name.
          *

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

@@ -8,7 +8,7 @@ import type { Converter } from "../converter.js";
  * The handler sets the `groups` property of all container reflections.
  */
 export declare class GroupPlugin extends ConverterComponent {
-    sortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
+    defaultSortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     accessor groupOrder: string[];
     accessor sortEntryPoints: boolean;
     accessor groupReferencesByType: boolean;
@@ -40,6 +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: Array<DeclarationReflection | DocumentReflection>) => void;
     /**
      * Callback used to sort groups by name.
      */

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

@@ -35,13 +35,13 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 import { ContainerReflection, ReferenceReflection, ReflectionKind, } from "../../models/index.js";
 import { ReflectionGroup } from "../../models/ReflectionGroup.js";
 import { ConverterComponent } from "../components.js";
-import { getSortFunction } from "../../utils/sort.js";
+import { getSortFunction, isValidSortStrategy, SORT_STRATEGIES } from "../../utils/sort.js";
 import { Option } from "../../utils/index.js";
 import { Comment } from "../../models/index.js";
 import { ConverterEvents } from "../converter-events.js";
 import { ApplicationEvents } from "../../application-events.js";
 import assert from "assert";
-import { i18n } from "#utils";
+import { i18n, partition } from "#utils";
 // Same as the defaultKindSortOrder in sort.ts
 const defaultGroupOrder = [
     ReflectionKind.Document,
@@ -89,7 +89,7 @@ let GroupPlugin = (() => {
             __esDecorate(this, null, _groupReferencesByType_decorators, { kind: "accessor", name: "groupReferencesByType", static: false, private: false, access: { has: obj => "groupReferencesByType" in obj, get: obj => obj.groupReferencesByType, set: (obj, value) => { obj.groupReferencesByType = value; } }, metadata: _metadata }, _groupReferencesByType_initializers, _groupReferencesByType_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        sortFunction;
+        defaultSortFunction;
         #groupOrder_accessor_storage = __runInitializers(this, _groupOrder_initializers, void 0);
         get groupOrder() { return this.#groupOrder_accessor_storage; }
         set groupOrder(value) { this.#groupOrder_accessor_storage = value; }
@@ -130,25 +130,26 @@ let GroupPlugin = (() => {
             }
         }
         setup() {
-            this.sortFunction = getSortFunction(this.application.options);
+            this.defaultSortFunction = getSortFunction(this.application.options);
             GroupPlugin.WEIGHTS = this.groupOrder;
             if (GroupPlugin.WEIGHTS.length === 0) {
                 GroupPlugin.WEIGHTS = defaultGroupOrder.map((kind) => ReflectionKind.pluralString(kind));
             }
         }
         group(reflection) {
+            const sortFunction = this.getSortFunction(reflection);
             if (reflection.childrenIncludingDocuments && !reflection.groups) {
                 if (reflection.children) {
                     if (this.sortEntryPoints ||
                         !reflection.children.some((c) => c.kindOf(ReflectionKind.Module))) {
-                        this.sortFunction(reflection.children);
-                        this.sortFunction(reflection.documents || []);
-                        this.sortFunction(reflection.childrenIncludingDocuments);
+                        sortFunction(reflection.children);
+                        sortFunction(reflection.documents || []);
+                        sortFunction(reflection.childrenIncludingDocuments);
                     }
                 }
                 else if (reflection.documents) {
-                    this.sortFunction(reflection.documents);
-                    this.sortFunction(reflection.childrenIncludingDocuments);
+                    sortFunction(reflection.documents);
+                    sortFunction(reflection.childrenIncludingDocuments);
                 }
                 if (reflection.comment?.hasModifier("@disableGroups")) {
                     return;
@@ -239,6 +240,19 @@ let GroupPlugin = (() => {
             }
             return Array.from(groups.values()).sort(GroupPlugin.sortGroupCallback);
         }
+        getSortFunction(reflection) {
+            const tag = reflection.comment?.getTag("@sortStrategy");
+            if (tag) {
+                const text = Comment.combineDisplayParts(tag.content);
+                const strategies = text.split(/[,\s]+/);
+                const [valid, invalid] = partition(strategies, isValidSortStrategy);
+                for (const inv of invalid) {
+                    this.application.logger.warn(i18n.comment_for_0_specifies_1_as_sort_strategy_but_only_2_is_valid(reflection.getFriendlyFullName(), inv, SORT_STRATEGIES.join("\n\t")));
+                }
+                return getSortFunction(this.application.options, valid);
+            }
+            return this.defaultSortFunction;
+        }
         /**
          * 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,42 @@ 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.)
+        for (const child of reflection.children || []) {
+            if (child.inheritedFrom && !child.inheritedFrom.reflection) {
+                child.inheritedFrom = ReferenceType.createBrokenReference(child.inheritedFrom.name, project);
+            }
+            if (child.overwrites && !child.overwrites.reflection) {
+                child.overwrites = ReferenceType.createBrokenReference(child.overwrites.name, project);
+            }
+            for (const childSig of child.getAllSignatures()) {
+                if (childSig.inheritedFrom && !childSig.inheritedFrom.reflection) {
+                    childSig.inheritedFrom = ReferenceType.createBrokenReference(childSig.inheritedFrom.name, project);
+                }
+                if (childSig.overwrites && !childSig.overwrites.reflection) {
+                    childSig.overwrites = ReferenceType.createBrokenReference(childSig.overwrites.name, project);
+                }
+            }
+        }
     }
     onResolveEnd(context) {
         this.resolve(context.project);
@@ -310,8 +341,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 +363,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/LinkResolverPlugin.d.ts

@@ -1,7 +1,7 @@
 import { ConverterComponent } from "../components.js";
 import type { Context, Converter } from "../../converter/index.js";
 import { type ValidationOptions } from "../../utils/index.js";
-import { type ProjectReflection } from "../../models/index.js";
+import type { ProjectReflection } from "../../models/index.js";
 /**
  * A plugin that resolves `{@link Foo}` tags.
  */
@@ -10,5 +10,4 @@ export declare class LinkResolverPlugin extends ConverterComponent {
     constructor(owner: Converter);
     onResolve(context: Context): void;
     resolveLinks(project: ProjectReflection): void;
-    private resolveCategoryLinks;
 }

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/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/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/en.cjs

@@ -72,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`,
@@ -274,13 +275,15 @@ 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_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}`,
     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