Skip to content

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

Open
Jake Bailey (jakebailey) wants to merge 4 commits into
microsoft:mainfrom
jakebailey:compiler-fixes/jsdoc-heritage-type-references
Open

Jake Bailey (jakebailey) wants to merge 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

This branch has not been deployed

No deployments
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: Not started

Development

Successfully merging this pull request may close these issues.

2 participants