Skip to content

Parse JSDoc @augments and @implements as TypeReference - #65537

Merged
Jake Bailey (jakebailey) merged 4 commits into
microsoft:mainfrom
jakebailey:compiler-fixes/jsdoc-heritage-type-references
Nov 17, 2026
Merged

Jake Bailey (jakebailey) merged 4 commits into
microsoft:mainfrom
jakebailey:compiler-fixes/jsdoc-heritage-type-references

Conversation

@jakebailey

Copy link
Copy Markdown
Member

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 TypeReference like real TS, then #65502 becomes a lot easier.

Also fixes a bug where we gave a diag suggesting @extends when that doesn't make any sense.

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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 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 @implements type arguments, avoiding an inappropriate @extends suggestion.
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

Comment thread tsc/internal/parser/jsdoc.go Resolved
@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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 Approval recommended

No active review issues remain for the JSDoc heritage-node changes.

No open issues 🎉

1 resolved since last review
1 file not reviewed
  • tsc/internal/ast/ast_generated.go: Generated file

Review effort: Balanced

@github-project-automation github-project-automation Bot moved this from Not started to Needs merge in PR Backlog Nov 17, 2026
@jakebailey
Jake Bailey (jakebailey) added this pull request to the merge queue Nov 17, 2026
Merged via the queue into microsoft:main with commit 0f7a537 Nov 17, 2026
34 checks passed
@jakebailey
Jake Bailey (jakebailey) deleted the compiler-fixes/jsdoc-heritage-type-references branch November 17, 2026 22:13
@github-project-automation github-project-automation Bot moved this from Needs merge to Done in PR Backlog Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Author: Team For Uncommitted Bug PR for untriaged, rejected, closed or missing bug

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants