Warning 6133 ignores @link tags

[DanielSWolf]

Bug Report

🔎 Search Terms

• "@link"
• is declared but its value is never read. (6133)

🕗 Version & Regression Information

• This changed between versions 4.2.3 and 4.3. The problem concerns the @link tag, which was introduced in version 4.3.

⏯ Playground Link

Playground link with relevant code

💻 Code

// @filename: wheel.ts

import type { Car } from './car';

/** A wheel for use with a {@link Car}. */
export interface Wheel {
  // ...
}

// @filename: car.ts

export interface Car {
  // ...
}

🙁 Actual behavior

The line import type { Car } from './car'; has the following compiler warning:

'Car' is declared but its value is never read. (6133)

🙂 Expected behavior

There should be no compiler warning for the type import. The purpose of this warning is to indicate superfluous imports, and this type import isn't superfluous: It is required for the @link tag to work property.

Without the type import, TypeScript could not resolve the target of the link. As a result, the tooltip in VS code would contain the Car reference in plain text rather than as a link.

Compare the following screenshots:

With type import:

Without type import:

[RyanCavanaugh]

I'm not sure if this is going to be fixable per se - @sandersn do we parse link tags at all during TS checking?

[sandersn]

Link tags are parsed and are in principle bindable and checkable. Neither one happens today, though -- name resolution happens on a services-only code path.

Looking at the code that leads to "value is never read" errors, it looks like checking link tags would fix this. It would also put errors on unresolved links in Typescript, which I don't think is desirable. But (1) it might be, actually or (2) it would be pretty easy to squelch the error for link tags.

Edit: link tags use special name resolution rules that would have to be moved from their services-only location to the central resolveName code path.

[DanielSWolf]

Link tags are parsed and are in principle bindable and checkable.

That's great! 😀

It would also put errors on unresolved links in Typescript, which I don't think is desirable. But (1) it might be, actually or (2) it would be pretty easy to squelch the error for link tags.

From my point of view, it would certainly be desirable. The reason why I use the @link syntax is because I want TypeScript to create an actual link. If TypeScript can't do that because I'm missing an import, I find that important to know.

I regularly spend time double-checking generated documentation to make sure everything worked, and I certainly don't enjoy it. If TypeScript can support me by flagging unresolved links, I'd certainly appreciate it!

[JaegerJens]

Without TypeScript support writing public API documentation requires a lot of house keeping:

• Detecting dead links
• Rename refactoring breaks API documentation
• Workarounds for false TypeScript errors

[komyg]

I will try to fix this along with the other related issue that I am working on: #47753.

Here is the PR: #47824

[WillsterJohnson]

Had this pop up in my code today,

Specifically what I want is for the emitted .d.ts files to maintain the imports, I don't much care about the JS files as I have removeComments enabled for them anyway.

I'm completely unfamiliar with TypeScript's code, but it's probably worth removeComments = true causing the compiler to ignore checking syntax within comments (for efficiency and to prevent accidentally flagging good code as invalid or vice versa), however this should only be at compile time. For example, using @link for internal documentation while having removeComments = true should ignore the @link when compiling, but respect it while checking the file in an editor such as VSCode.

Either way, I hope this can be resolved soon as I'm halfway to bodging a syntax & post processor to re-insert the imports at compile time.

[sandersn]

@willster277 I tried to make a small repro for the case you mentioned and could only get the editor to put a suggestion on the now-unused import. Can you file a new issue that shows how to get a compiler error for it?

[WillsterJohnson]

@sandersn the error message in editor was;
'imported_object_name' is declared but its value is never read. ts(6133)
and in the compiler logs;
file.ts: - error TS6133: 'imported_object_name' is declared but its value is never read.

I believe the compiler error is from "noUnusedLocals": true as once it's imported, a type/object counts as a local variable for the file. Disabling the option removes the compiler error (but doesn't fix the actual problem), but the editor error still persists.

Here is the repo reproducing the problem, though looking through #47822 I believe it will be resolved. I haven't opened a new issue as it would simply duplicate this one.
Hopefully we'll be able to test if it's fixed on the next @next release!