Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(60908): Unexpected "'Type' is declared but its value is never read." error with jsdoc @import syntax #60921

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

fix(60908): Unexpected "'Type' is declared but its value is never read." error with jsdoc @import syntax #60921

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7d1ed12
fix(60908): avoid binding jsdocimport children to the jsdoc host cont…
a-tarasyuk Jan 6, 2025
49cdbda
add additional tests
a-tarasyuk Jan 12, 2025
7c18a9c
prevent early binding of importClause in jsdoc imports
a-tarasyuk Jan 19, 2025
9f439bb
Merge branch 'main' of https://github.com/microsoft/TypeScript into f…
a-tarasyuk Jan 19, 2025
58f9d2f
add tests
a-tarasyuk Jan 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions src/compiler/binder.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@ import {
isInTopLevelContext,
isJSDocConstructSignature,
isJSDocEnumTag,
isJSDocImportTag,
isJSDocTemplateTag,
isJSDocTypeAlias,
isJSDocTypeAssertion,
Expand Down Expand Up @@ -1108,6 +1109,9 @@ function createBinder(): (file: SourceFile, options: CompilerOptions) => void {
if (canHaveFlowNode(node) && node.flowNode) {
node.flowNode = undefined;
}
if (isJSDocImportTag(node)) {
return;
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the import tag special here?

Also, this early return will leave inAssignmentPattern in a bad state, so I think it's better to skip the steps below that are broken with import tags if needed, or maybe there's something else wrong otherwise.

Copy link
Contributor Author

@a-tarasyuk a-tarasyuk Jan 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jakebailey thanks for the feedback. These changes are open for discussion :). This applies to the case when we have

/** @import { Foo } from 'foo' */
function foo() {}

The function acts as a container that holds locals (bind importClause), including the symbol Foo. Since this symbol is unused (and doesn't have an exportSymbol like the typedef does), the checker triggers an error.

if (.... local.exportSymbol) {
    return;
}

Perhaps the container for the import tag should be treated like a SourceFile...

ContainerFlags.IsContainer | ContainerFlags.IsControlFlowContainer | ContainerFlags.HasLocals;

Anyway, I’d be grateful for any ideas or suggestions regarding this case. thanks

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mainly, I'm trying to understand why import tags have to be special cased, but other JSDoc "declarations" don't.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jakebailey JsDocImportTag reuses importClause, however, it doesn't bind it immediately, opting for a delayed binding instead

TypeScript/src/compiler/binder.ts

Lines 1202 to 1204 in 8da951c

case SyntaxKind.JSDocImportTag:
bindJSDocImportTag(node as JSDocImportTag);
break;

TypeScript/src/compiler/binder.ts

Lines 2126 to 2135 in 8da951c

function bindJSDocImportTag(node: JSDocImportTag) {
// don't bind the importClause yet; that's delayed until bindJSDocImports
bind(node.tagName);
bind(node.moduleSpecifier);
bind(node.attributes);
if (typeof node.comment !== "string") {
bindEach(node.comment);
}
}

When the binder executes bindChildren and bindEachChild, it iterates through all child nodes, including importClause, and binds them

TypeScript/src/compiler/binder.ts

Lines 3062 to 3063 in 8da951c

case SyntaxKind.ImportClause:
return bindImportClause(node as ImportClause);

TypeScript/src/compiler/binder.ts

Lines 3058 to 3059 in 8da951c

case SyntaxKind.ExportSpecifier:
return declareSymbolAndAddToSymbolTable(node as Declaration, SymbolFlags.Alias, SymbolFlags.AliasExcludes);

this creates incorrect locals for the parent container. Other tags, such as @typedef and @callback, don't rely on such nodes.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, I see; this honestly makes me wonder why the code doesn't just fall through into the code below, which seems to have a lot more special cases that feel like they'd matter in the same way...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As in, be written:

// ...
if (checkUnreachable(node)) {
    if (canHaveFlowNode(node) && node.flowNode) {
        node.flowNode = undefined;
    }
} else if (node.kind >= SyntaxKind.FirstStatement && node.kind <= SyntaxKind.LastStatement && (!options.allowUnreachableCode || node.kind === SyntaxKind.ReturnStatement)) {
    (node as HasFlowNode).flowNode = currentFlow;
}
switch (node.kind) {
// ...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean it falls over, so that can't be right either

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think unreachable flow cannot be handled properly without

bindEachChild(node);
bindJSDoc(node);

I'm exploring other options to skip processing child nodes for JSDoc imports...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think unreachable flow can remain as is. Alternatively, an additional flag could be added to symbols bound from the JSDoc import (ImportSpecifier) to exclude them from the unused locals check. @sandersn @jakebailey what do you think?

bindEachChild(node);
bindJSDoc(node);
inAssignmentPattern = saveInAssignmentPattern;
Expand Down
25 changes: 25 additions & 0 deletions tests/baselines/reference/importTag23.symbols
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
//// [tests/cases/conformance/jsdoc/importTag23.ts] ////

=== types.d.ts ===
export type T = {
>T : Symbol(T, Decl(types.d.ts, 0, 0))

a: number;
>a : Symbol(a, Decl(types.d.ts, 0, 17))

};

=== foo.js ===
/** @import { T } from "./types.d.ts" */

export default async function f() {
>f : Symbol(f, Decl(foo.js, 0, 0))

/** @type {T[]} */
const types = [];
>types : Symbol(types, Decl(foo.js, 4, 6))

return types;
>types : Symbol(types, Decl(foo.js, 4, 6))
}

32 changes: 32 additions & 0 deletions tests/baselines/reference/importTag23.types
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
//// [tests/cases/conformance/jsdoc/importTag23.ts] ////

=== types.d.ts ===
export type T = {
>T : T
> : ^

a: number;
>a : number
> : ^^^^^^

};

=== foo.js ===
/** @import { T } from "./types.d.ts" */

export default async function f() {
>f : () => Promise<T[]>
> : ^^^^^^^^^^^^^^^^^^

/** @type {T[]} */
const types = [];
>types : T[]
> : ^^^
>[] : undefined[]
> : ^^^^^^^^^^^

return types;
>types : T[]
> : ^^^
}

38 changes: 38 additions & 0 deletions tests/baselines/reference/importTag24.errors.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
a.js(3,10): error TS6133: 'f1' is declared but its value is never read.
a.js(11,10): error TS6133: 'f3' is declared but its value is never read.
a.js(19,10): error TS6133: 'f4' is declared but its value is never read.
a.js(19,17): error TS2322: Type 'number' is not assignable to type 'string'.


==== types.d.ts (0 errors) ====
export type Foo = string;

==== a.js (4 errors) ====
/** @import { Foo } from './types.d.ts') */

function f1() { return undefined; }
~~
!!! error TS6133: 'f1' is declared but its value is never read.

export function f2() {
/** @type {Set<Foo>} */
const foo = new Set([ 'a', 'b' ]);
return foo;
}

function f3() { return undefined; }
~~
!!! error TS6133: 'f3' is declared but its value is never read.

/** @type {Set<Foo>} */
export const foo = new Set([ 'a', 'b' ]);

/**
* @returns {Foo}
*/
function f4() { return 1; }
~~
!!! error TS6133: 'f4' is declared but its value is never read.
~~~~~~
!!! error TS2322: Type 'number' is not assignable to type 'string'.

40 changes: 40 additions & 0 deletions tests/baselines/reference/importTag24.symbols
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
//// [tests/cases/conformance/jsdoc/importTag24.ts] ////

=== types.d.ts ===
export type Foo = string;
>Foo : Symbol(Foo, Decl(types.d.ts, 0, 0))

=== a.js ===
/** @import { Foo } from './types.d.ts') */

function f1() { return undefined; }
>f1 : Symbol(f1, Decl(a.js, 0, 0))
>undefined : Symbol(undefined)

export function f2() {
>f2 : Symbol(f2, Decl(a.js, 2, 35))

/** @type {Set<Foo>} */
const foo = new Set([ 'a', 'b' ]);
>foo : Symbol(foo, Decl(a.js, 6, 9))
>Set : Symbol(Set, Decl(lib.es2015.collection.d.ts, --, --), Decl(lib.es2015.collection.d.ts, --, --), Decl(lib.es2015.iterable.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --), Decl(lib.esnext.collection.d.ts, --, --))

return foo;
>foo : Symbol(foo, Decl(a.js, 6, 9))
}

function f3() { return undefined; }
>f3 : Symbol(f3, Decl(a.js, 8, 1))
>undefined : Symbol(undefined)

/** @type {Set<Foo>} */
export const foo = new Set([ 'a', 'b' ]);
>foo : Symbol(foo, Decl(a.js, 13, 12))
>Set : Symbol(Set, Decl(lib.es2015.collection.d.ts, --, --), Decl(lib.es2015.collection.d.ts, --, --), Decl(lib.es2015.iterable.d.ts, --, --), Decl(lib.es2015.symbol.wellknown.d.ts, --, --), Decl(lib.esnext.collection.d.ts, --, --))

/**
* @returns {Foo}
*/
function f4() { return 1; }
>f4 : Symbol(f4, Decl(a.js, 13, 41))

74 changes: 74 additions & 0 deletions tests/baselines/reference/importTag24.types
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
//// [tests/cases/conformance/jsdoc/importTag24.ts] ////

=== Performance Stats ===
Type Count: 1,000
Instantiation count: 2,500

=== types.d.ts ===
export type Foo = string;
>Foo : string
> : ^^^^^^

=== a.js ===
/** @import { Foo } from './types.d.ts') */

function f1() { return undefined; }
>f1 : () => any
> : ^^^^^^^^^
>undefined : undefined
> : ^^^^^^^^^

export function f2() {
>f2 : () => Set<string>
> : ^^^^^^^^^^^^^^^^^

/** @type {Set<Foo>} */
const foo = new Set([ 'a', 'b' ]);
>foo : Set<string>
> : ^^^^^^^^^^^
>new Set([ 'a', 'b' ]) : Set<string>
> : ^^^^^^^^^^^
>Set : SetConstructor
> : ^^^^^^^^^^^^^^
>[ 'a', 'b' ] : string[]
> : ^^^^^^^^
>'a' : "a"
> : ^^^
>'b' : "b"
> : ^^^

return foo;
>foo : Set<string>
> : ^^^^^^^^^^^
}

function f3() { return undefined; }
>f3 : () => any
> : ^^^^^^^^^
>undefined : undefined
> : ^^^^^^^^^

/** @type {Set<Foo>} */
export const foo = new Set([ 'a', 'b' ]);
>foo : Set<string>
> : ^^^^^^^^^^^
>new Set([ 'a', 'b' ]) : Set<string>
> : ^^^^^^^^^^^
>Set : SetConstructor
> : ^^^^^^^^^^^^^^
>[ 'a', 'b' ] : string[]
> : ^^^^^^^^
>'a' : "a"
> : ^^^
>'b' : "b"
> : ^^^

/**
* @returns {Foo}
*/
function f4() { return 1; }
>f4 : () => Foo
> : ^^^^^^^^^
>1 : 1
> : ^

18 changes: 18 additions & 0 deletions tests/cases/conformance/jsdoc/importTag23.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
// @noUnusedLocals: true
// @allowJs: true
// @checkJs: true
// @noEmit: true

// @filename: types.d.ts
export type T = {
a: number;
};

// @filename: foo.js
/** @import { T } from "./types.d.ts" */

export default async function f() {
/** @type {T[]} */
const types = [];
return types;
}
33 changes: 33 additions & 0 deletions tests/cases/conformance/jsdoc/importTag24.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
// @checkJs: true
// @allowJs: true
// @noEmit: true
// @lib: esnext
// @moduleResolution: bundler
// @module: preserve
// @noUnusedLocals: true
// @noUnusedParameters: true
// @allowImportingTsExtensions: true

// @filename: types.d.ts
export type Foo = string;

// @filename: a.js
/** @import { Foo } from './types.d.ts') */

function f1() { return undefined; }

export function f2() {
/** @type {Set<Foo>} */
const foo = new Set([ 'a', 'b' ]);
return foo;
}

function f3() { return undefined; }

/** @type {Set<Foo>} */
export const foo = new Set([ 'a', 'b' ]);

/**
* @returns {Foo}
*/
function f4() { return 1; }
Loading