Repository navigation
Parse JSDoc @augments and @implements as TypeReference - #65537
Open
Jake Bailey (jakebailey) wants to merge 4 commits into
Open
Jake Bailey (jakebailey) wants to merge 4 commits into
Jake Bailey (jakebailey) wants to merge 4 commits into
Conversation
A generic class named by @implements without type arguments is reported as needing an @extends tag, which does not apply to @implements.
The tags name a class or interface with optional type arguments, the same thing a TypeScript implements clause or interface extends clause writes. Those clauses parse as type references, but the tags parsed as expressions with type arguments. A JS class's implements clause, built from @implements, then held a different node kind than a TS class's, and a missing type argument in @implements was reported as needing an @extends tag. Parse both tags as type references. @Augments still supplies type arguments to the class's extends expression.
Jake Bailey (jakebailey)
requested review from
Andrew Branch (andrewbranch) and
Wesley Wigham (weswigham)
and
a balanced review from Copilot
November 16, 2026 19:01
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
JSDoc heritage references are incorrectly rewritten as primitive types, causing false mismatch errors for @extends and @implements, including locally shadowed built-in names.
1 open issue
1 file not reviewed
tsc/internal/ast/ast_generated.go: Generated file
What changed in this PR
This PR represents JSDoc @augments and @implements names as TypeReference nodes, aligning them with TypeScript type syntax and simplifying the AST cleanup supporting #65502.
Changes:
- Updates the AST schema, generated APIs, and parser to use type references for JSDoc heritage tags.
- Adapts reparsing, checking, hover documentation, and type-context helpers to the new representation.
- Adds regression coverage for missing
@implementstype arguments, avoiding an inappropriate@extendssuggestion.
| File | Description |
|---|---|
tsc/testdata/tests/cases/compiler/jsdocImplementsTagMissingTypeArguments.ts |
Adds the missing-type-argument regression case. |
tsc/testdata/baselines/reference/compiler/jsdocImplementsTagMissingTypeArguments.types |
Records expected inferred types. |
tsc/testdata/baselines/reference/compiler/jsdocImplementsTagMissingTypeArguments.symbols |
Records expected symbol bindings. |
tsc/testdata/baselines/reference/compiler/jsdocImplementsTagMissingTypeArguments.errors.txt |
Records the generic-type diagnostic. |
tsc/internal/parser/reparser.go |
Matches runtime base expressions against type-reference names. |
tsc/internal/parser/jsdoc.go |
Parses heritage tags as type references. |
tsc/internal/ls/hover.go |
Reads augment names from the new representation. |
tsc/internal/checker/jsdoc.go |
Updates augment mismatch checks for entity names. |
tsc/internal/checker/grammarchecks.go |
Adds an entity-name identifier helper. |
tsc/internal/checker/checker.go |
Simplifies selection of the missing-extends-tag diagnostic. |
tsc/internal/ast/utilities.go |
Removes obsolete expression-based heritage handling. |
tsc/internal/ast/ast_generated.go |
Updates generated Go tag fields and factories. |
tools/scripts/tsc/ast.json |
Defines heritage tag names as type references. |
packages/typescript/src/ast/visitor.generated.ts |
Updates visitor validation for heritage tag children. |
packages/typescript/src/ast/is.ts |
Removes obsolete JSDoc expression-context exceptions. |
packages/typescript/src/ast/factory.generated.ts |
Updates generated tag factory signatures. |
packages/typescript/src/ast/ast.generated.ts |
Updates public heritage tag interfaces. |
Review effort: Balanced
@extends {String} names the String class, and @implements {Boolean} names a local Boolean class, but both are read as primitive types and reported as errors.
JSDoc type references named String, Boolean, Function and similar are read as primitive or built-in types. The name in @Augments, @implements or a heritage clause names the class or interface itself, so it keeps its ordinary meaning. Its type arguments are still read as JSDoc types.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

This is a wart in our AST layout; I had refactored the AST in microsoft/typescript-go#4797 to try and make sure that expressions were expressions and types were types, but I missed JSDoc and so we were left with a bunch of extra checks everywhere.
If we instead make JSDoc actually parse
TypeReferencelike real TS, then #65502 becomes a lot easier.Also fixes a bug where we gave a diag suggesting
@extendswhen that doesn't make any sense.