Add tests for declaration reference resolution

Gerrit0 · Gerrit0 · commit 5d442750e670 · 2022-06-19T16:01:55.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,7 +15,7 @@
 -   The `gaSite` option has been removed since Google Analytics now infers the site automatically, updated Google Analytics script to latest version, #1846.
 -   Comments on export declarations will only overrides comments for references and namespaces, #1901.
 -   The deprecated `listInvalidSymbolLinks` option has been removed. Use `validation.invalidLink` instead.
--   The deprecated `true` and `false` values have been removed from `--emit`, to migrate replace `true` with `"both"` and `false` with `"docs"`.
+-   The deprecated `true` and `false` values have been removed from `--emit`, to migrate replace `true` with `"both"` and `false` with `"docs"` (the default).
 -   Links are no longer be resolved against a global list of all symbols. See [the documentation](https://typedoc.org/guides/link-resolution/) for details on link resolution.
 -   The `validation.invalidLink` option is now on by default.
 -   `reflection.decorates`, `reflection.decorators`, and their corresponding interfaces have been removed as no code in TypeDoc used them.
diff --git a/package.json b/package.json
@@ -94,7 +94,7 @@
       ".tsx"
     ],
     "reporter": [
-      "html",
+      "html-spa",
       "text-summary"
     ],
     "exclude": [
diff --git a/src/lib/converter/comments/declarationReference.ts b/src/lib/converter/comments/declarationReference.ts
@@ -6,6 +6,8 @@
  * @module
  */
 
+import type { Chars } from "../../utils";
+
 export const MeaningKeywords = [
     "class", // SymbolFlags.Class
     "interface", // SymbolFlags.Interface
@@ -51,10 +53,6 @@ export interface ComponentPath {
     path: string;
 }
 
-type Chars<T extends string> = T extends `${infer C}${infer R}`
-    ? C | Chars<R>
-    : never;
-
 // <TAB> <VT> <FF> <SP> <NBSP> <ZWNBSP> <USP>
 const WhiteSpace = /[\t\u2B7F\u240C \u00A0\uFEFF\p{White_Space}]/u;
 const LineTerminator = "\r\n\u2028\u2029";
diff --git a/src/lib/converter/plugins/LinkResolverPlugin.ts b/src/lib/converter/plugins/LinkResolverPlugin.ts
@@ -65,7 +65,14 @@ export class LinkResolverPlugin extends ConverterComponent {
             const { target, caption } =
                 LinkResolverPlugin.splitLinkText(content);
 
-            if (!urlPrefix.test(target)) {
+            if (urlPrefix.test(target)) {
+                parts.push({
+                    kind: "inline-tag",
+                    tag: "@link",
+                    text: caption,
+                    target,
+                });
+            } else {
                 const targetRefl = reflection.findReflectionByName(target);
                 if (targetRefl) {
                     parts.push({
@@ -75,22 +82,17 @@ export class LinkResolverPlugin extends ConverterComponent {
                         target: targetRefl,
                     });
                 } else {
-                    this.application.logger.warn(
-                        "Failed to find target: " + content
-                    );
+                    if (this.validation.invalidLink) {
+                        this.application.logger.warn(
+                            "Failed to find target: " + content
+                        );
+                    }
                     parts.push({
                         kind: "inline-tag",
                         tag: "@link",
                         text: content,
                     });
                 }
-            } else {
-                parts.push({
-                    kind: "inline-tag",
-                    tag: "@link",
-                    text: caption,
-                    target,
-                });
             }
         }
         parts.push({
@@ -219,11 +221,6 @@ function resolveLinkTag(
     let pos = 0;
     const end = part.text.length;
 
-    // Skip any leading white space, which isn't allowed in a declaration reference.
-    while (pos < end && ts.isWhiteSpaceLike(part.text.charCodeAt(pos))) {
-        pos++;
-    }
-
     // Try to parse one
     const declRef = parseDeclarationReference(part.text, pos, end);
 
@@ -237,12 +234,15 @@ function resolveLinkTag(
     // If resolution via a declaration reference failed, revert to the legacy "split and check"
     // method... this should go away in 0.24, once people have had a chance to migrate any failing links.
     if (!target) {
-        warn(
-            `Failed to resolve {@link ${
-                part.text
-            }} in ${reflection.getFriendlyFullName()} with declaration references. This link will break in v0.24.`
-        );
-        return legacyResolveLinkTag(reflection, part);
+        const resolved = legacyResolveLinkTag(reflection, part);
+        if (resolved) {
+            warn(
+                `Failed to resolve {@link ${
+                    part.text
+                }} in ${reflection.getFriendlyFullName()} with declaration references. This link will break in v0.24.`
+            );
+        }
+        return resolved;
     }
 
     // Remaining text after an optional pipe is the link text, so advance
@@ -369,7 +369,9 @@ function resolveKeyword(
 ): Reflection[] | undefined {
     switch (kw) {
         case undefined:
-            return [refl];
+            return refl instanceof DeclarationReflection && refl.signatures
+                ? refl.signatures
+                : [refl];
         case "class":
             if (refl.kindOf(ReflectionKind.Class)) return [refl];
             break;
@@ -396,22 +398,25 @@ function resolveKeyword(
 
         case "new":
         case "constructor":
-            if (refl.kindOf(ReflectionKind.Class)) {
+            if (
+                refl.kindOf(
+                    ReflectionKind.ClassOrInterface | ReflectionKind.TypeLiteral
+                )
+            ) {
                 const ctor = (refl as ContainerReflection).children?.find((c) =>
                     c.kindOf(ReflectionKind.Constructor)
                 );
                 return (ctor as DeclarationReflection)?.signatures;
             }
-            if (refl.kindOf(ReflectionKind.Constructor)) {
-                return (refl as DeclarationReflection).signatures;
-            }
             break;
 
         case "member":
             if (refl.kindOf(ReflectionKind.SomeMember)) return [refl];
             break;
         case "event":
-            if (refl.comment?.hasModifier("@event")) return [refl];
+            // Never resolve. Nobody should use this.
+            // It's required by the grammar, but is not documented by TypeDoc
+            // nor by the comments in the grammar.
             break;
         case "call":
             return (refl as DeclarationReflection).signatures;
diff --git a/src/lib/utils/general.ts b/src/lib/utils/general.ts
@@ -35,6 +35,13 @@ export type IfInternal<T, F> = InternalOnly extends true ? T : F;
  */
 export type NeverIfInternal<T> = IfInternal<never, T>;
 
+/**
+ * Resolves a string type into a union of characters, `"ab"` turns into `"a" | "b"`.
+ */
+export type Chars<T extends string> = T extends `${infer C}${infer R}`
+    ? C | Chars<R>
+    : never;
+
 /**
  * Utility to help type checking ensure that there is no uncovered case.
  */
diff --git a/src/lib/utils/index.ts b/src/lib/utils/index.ts
@@ -17,7 +17,7 @@ export {
     writeFile,
     writeFileSync,
 } from "./fs";
-export type { IfInternal, NeverIfInternal } from "./general";
+export type { IfInternal, NeverIfInternal, Chars } from "./general";
 export { assertNever } from "./general";
 export { CallbackLogger, ConsoleLogger, Logger, LogLevel } from "./loggers";
 export { DefaultMap } from "./map";
diff --git a/src/test/behaviorTests.ts b/src/test/behaviorTests.ts
@@ -8,7 +8,10 @@ import {
     Comment,
     CommentDisplayPart,
     CommentTag,
+    Reflection,
+    SignatureReflection,
 } from "../lib/models";
+import { Chars, filterMap } from "../lib/utils";
 import { CommentStyle } from "../lib/utils/options/declaration";
 import type { TestLogger } from "./TestLogger";
 
@@ -18,33 +21,7 @@ function query(project: ProjectReflection, name: string) {
     return reflection;
 }
 
-type Letters =
-    | "a"
-    | "b"
-    | "c"
-    | "d"
-    | "e"
-    | "f"
-    | "g"
-    | "h"
-    | "i"
-    | "j"
-    | "k"
-    | "l"
-    | "m"
-    | "n"
-    | "o"
-    | "p"
-    | "q"
-    | "r"
-    | "s"
-    | "t"
-    | "u"
-    | "v"
-    | "w"
-    | "x"
-    | "y"
-    | "z";
+type Letters = Chars<"abcdefghijklmnopqrstuvwxyz">;
 
 export const behaviorTests: {
     [issue: `_${string}`]: (app: Application) => void;
@@ -364,6 +341,95 @@ export const behaviorTests: {
         equal(Comment.combineDisplayParts(c.comment?.summary), "");
     },
 
+    _linkResolution(app) {
+        app.options.setValue("sort", ["source-order"]);
+    },
+    linkResolution(project) {
+        function getLinks(refl: Reflection) {
+            ok(refl.comment);
+            return filterMap(refl.comment.summary, (p) => {
+                if (p.kind === "inline-tag" && p.tag === "@link") {
+                    if (typeof p.target === "string") {
+                        return p.target;
+                    }
+                    if (p.target instanceof SignatureReflection) {
+                        return [
+                            p.target.getFullName(),
+                            p.target.parent.signatures?.indexOf(p.target),
+                        ];
+                    }
+                    return [p.target?.kind, p.target?.getFullName()];
+                }
+            });
+        }
+
+        for (const [refl, target] of [
+            ["Scoping.abc", "Scoping.abc"],
+            ["Scoping.Foo", "Scoping.Foo.abc"],
+            ["Scoping.Foo.abc", "Scoping.Foo.abc"],
+            ["Scoping.Bar", "Scoping.abc"],
+            ["Scoping.Bar.abc", "Scoping.abc"],
+        ] as const) {
+            equal(
+                getLinks(query(project, refl)).map((x) => x[1]),
+                [query(project, target).getFullName()]
+            );
+        }
+
+        const links = getLinks(query(project, "Meanings"));
+        equal(links, [
+            [ReflectionKind.Enum, "Meanings.A"],
+            [ReflectionKind.Namespace, "Meanings.A"],
+            [ReflectionKind.Enum, "Meanings.A"],
+
+            [undefined, undefined],
+            [ReflectionKind.Class, "Meanings.B"],
+
+            [ReflectionKind.Interface, "Meanings.C"],
+            [ReflectionKind.TypeAlias, "Meanings.D"],
+            ["Meanings.E.E", 0],
+            [ReflectionKind.Variable, "Meanings.F"],
+
+            ["Meanings.B.constructor.new B", 0],
+            ["Meanings.B.constructor.new B", 0],
+            ["Meanings.B.constructor.new B", 1],
+
+            [ReflectionKind.EnumMember, "Meanings.A.A"],
+            [undefined, undefined],
+
+            ["Meanings.E.E", 0],
+            ["Meanings.E.E", 1],
+
+            ["Meanings.B.constructor.new B", 0],
+            ["Meanings.B.constructor.new B", 1],
+
+            ["Meanings.B.__index", undefined],
+            [ReflectionKind.Interface, "Meanings.G"],
+
+            ["Meanings.E.E", 1],
+            [ReflectionKind.Class, "Meanings.B"],
+        ]);
+
+        equal(getLinks(query(project, "URLS")), [
+            "https://example.com",
+            "ftp://example.com",
+        ]);
+
+        equal(
+            getLinks(query(project, "Globals.A")).map((x) => x[1]),
+            ["URLS", "A", "Globals.A"]
+        );
+
+        equal(getLinks(query(project, "Navigation")), [
+            [ReflectionKind.Method, "Navigation.Child.foo"],
+            [ReflectionKind.Property, "Navigation.Child.foo"],
+            [undefined, undefined],
+        ]);
+
+        const foo = query(project, "Navigation.Child.foo").signatures![0];
+        equal(getLinks(foo), [[ReflectionKind.Method, "Navigation.Child.foo"]]);
+    },
+
     mergedDeclarations(project, logger) {
         const a = query(project, "SingleCommentMultiDeclaration");
         equal(
diff --git a/src/test/converter2/behavior/linkResolution.ts b/src/test/converter2/behavior/linkResolution.ts
