Fix JSDoc @enum so the tagged name is a type as well as a value by bun-unsafe · Pull Request #64004 · microsoft/TypeScript

Xia Chao (bun-unsafe) · 2026-08-25T14:07:45Z

JSDoc @enum on a const object did not introduce a type. The name was value-only, so @param {E} in the same file and const n: E = E.A against the emitted .d.ts both reported TS2749.

This parses @enum, reparses a type alias named after the host declaration, and merges it with the value. Declaration emit then includes export type E = … next to the existing const. JSDoc function(number): number is parsed as a function type so @enum {function(number): number} prints a valid signature (this also clears the old parse errors on {function(string): boolean} in typedefTagWrapping).

Emit is export type E = T plus export declare const E: { … }, not the 6.x namespace shape. The type+value contract is what consumers need (E in type position, E.A as a value).

Tests: jsDeclarationsEnumTag, enumTag*, jsFileESModuleWithEnumTag, typedefTagWrapping, smartSelection_JSDocTags9.

I used Copilot while writing this patch. I read the change, ran the tests above, and I will handle review myself.

@enum

@enum was parsed as an unknown tag, so names like E were value-only. That made @PARAM {E} and .d.ts consumers report TS2749. Parse the tag, reparse a type alias from the host name, and parse JSDoc function(...) types so @enum {function(number): number} emits a valid signature.

Copilot

Pull request overview

Adds first-class JSDoc @enum type support and Closure-style function type parsing.

Changes:

Adds JSDocEnumTag AST, parser, encoder, checker, and emit support.
Synthesizes type aliases alongside enum values.
Updates compiler and fourslash baselines.

Reviewed changes

Copilot reviewed 28 out of 33 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`tsc/internal/parser/jsdoc.go`	Parses enum tags and function types.
`tsc/internal/parser/parser.go`	Recognizes JSDoc `function(...)` types.
`tsc/internal/parser/reparser.go`	Synthesizes enum type aliases.
`tsc/internal/checker/checker.go`	Classifies enum tags in type space.
`tsc/internal/checker/emitresolver.go`	Handles enum-tag visibility.
`tsc/internal/ast/ast.go`	Integrates enum-tag accessors.
`tsc/internal/ast/ast_generated.go`	Adds generated enum-tag nodes.
`tsc/internal/ast/kind_generated.go`	Adds the enum-tag syntax kind.
`tsc/internal/ast/kind_stringer_generated.go`	Updates generated kind strings.
`tsc/internal/ast/utilities.go`	Enables enum-tag comments.
`tsc/internal/api/encoder/encoder_generated.go`	Encodes enum-tag children.
`tsc/internal/api/encoder/decoder_generated.go`	Decodes enum-tag children.
`tools/scripts/tsc/ast.json`	Defines the enum-tag AST schema.
`smartSelection_JSDocTags9.baseline`	Updates JSDoc selection output.
`typedefTagWrapping.types`	Records parsed function return types.
`typedefTagWrapping.errors.txt`	Removes obsolete parse errors.
`jsDeclarationsEnumTag(target=es2015).types`	Records enum aliases’ resolved types.
`jsDeclarationsEnumTag(target=es2015).symbols`	Records merged symbols.
`jsDeclarationsEnumTag(target=es2015).js`	Records emitted type aliases.
`jsDeclarationsEnumTag(target=es2015).errors.txt`	Removes value-only type errors.
`enumTagUseBeforeDefCrash.types`	Records the enum’s aliased type.
`enumTagUseBeforeDefCrash.symbols`	Records its merged symbol.
`enumTagUseBeforeDefCrash.errors.txt`	Removes the former type error.
`enumTagOnExports.symbols`	Records CommonJS merged symbols.
`enumTagImported.types`	Records imported enum types.
`enumTagImported.symbols`	Records imported merged symbols.
`enumTagImported.errors.txt`	Removes import/type errors.
`enumTagCircularReference.symbols`	Records the circular alias symbol.
`enumTagCircularReference.errors.txt`	Adds the circular-alias diagnostic.
`enumTag.types`	Records local enum alias types.
`enumTag.symbols`	Records local merged symbols.
`enumTag.errors.txt`	Removes value-only type errors.
`jsFileESModuleWithEnumTag.symbols`	Records merged ES-module symbols.

Files not reviewed (5)

tsc/internal/api/encoder/decoder_generated.go: Generated file
tsc/internal/api/encoder/encoder_generated.go: Generated file
tsc/internal/ast/ast_generated.go: Generated file
tsc/internal/ast/kind_generated.go: Generated file
tsc/internal/ast/kind_stringer_generated.go: Generated file

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Xia Chao (bun-unsafe) · 2026-08-25T14:22:57Z

+		case ast.KindElementAccessExpression:
+			arg := expr.AsElementAccessExpression().ArgumentExpression
+			if ast.IsIdentifier(arg) {
+				return arg


Thanks. The identifier check matches Strada nameForNamelessJSDocTypedef (element access only when the argument is an identifier).
Static exports["E"] / numeric literals are a reasonable follow-up (GetElementOrPropertyAccessName + identifier). I left that out of this PR so the @enum const/export case stays reviewable.

Xia Chao (bun-unsafe) · 2026-08-25T14:23:08Z

+		switch expr.Kind {
+		case ast.KindPropertyAccessExpression:
+			return expr.AsPropertyAccessExpression().Name()


Thanks. This is a real remaining @enum hole: we only take the innermost name, so Host.UserMetrics.Action does not become a qualified type. jsEnumCrossFileExport.ts still reports TS2749.
This PR is scoped to a declaration-named const/export (export const E / .d.ts consumers). Wrapping the full static path like dotted @typedef is a follow-up. I can do it in this PR if you want it here.

Xia Chao (bun-unsafe) · 2026-08-25T14:18:03Z

@microsoft-github-policy-service agree

Jake Bailey (jakebailey) · 2026-08-25T14:40:50Z

Everything you're adding back was intentionally removed

https://github.com/microsoft/TypeScript/blob/main/tsc/CHANGES.md

Xia Chao (bun-unsafe) · 2026-08-25T14:47:53Z

You're right — I missed that @enum and Closure function(...) types are intentional Corsa removals, with @typedef / (s: T) => R as the substitute.

I'll close this PR. Sorry for the noise.

Jake Bailey (jakebailey) · 2026-08-25T14:53:00Z

Why did you choose to work on this? Does this personally affect you?

Xia Chao (bun-unsafe) · 2026-08-25T14:54:45Z

I was comparing 6.x vs 7 declaration emit on a small JSDoc fixture (@enum on a const, checkJs + declaration). The .d.ts left E value-only, so const n: E = E.A was TS2749, which I treated as a regression.
It does not affect a product I ship. I should have read CHANGES.md first — @enum / Closure function(...) are intentional removals, not a bug. Sorry for the noise.

Copilot AI balanced review requested due to automatic review settings August 25, 2026 14:07

github-project-automation Bot added this to PR Backlog Aug 25, 2026

github-project-automation Bot moved this to Not started in PR Backlog Aug 25, 2026

Copilot started reviewing on behalf of Xia Chao (bun-unsafe) August 25, 2026 14:08 View session

Xia Chao (bun-unsafe) force-pushed the fix/jsdoc-enum-tag branch from 6382a8b to 0e478d7 Compare August 25, 2026 14:10

Copilot AI reviewed Aug 25, 2026

View reviewed changes

Xia Chao (bun-unsafe) closed this Aug 25, 2026

github-project-automation Bot moved this from Not started to Done in PR Backlog Aug 25, 2026

Navigation Menu

Uh oh!

Fix JSDoc @enum so the tagged name is a type as well as a value - #64004

Fix JSDoc @enum so the tagged name is a type as well as a value#64004
Xia Chao (bun-unsafe) wants to merge 1 commit into
microsoft:mainfrom
bun-unsafe:fix/jsdoc-enum-tag

Xia Chao (bun-unsafe) commented Aug 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Xia Chao (bun-unsafe) Aug 25, 2026

Uh oh!

Uh oh!

Xia Chao (bun-unsafe) Aug 25, 2026

Uh oh!

Xia Chao (bun-unsafe) commented Aug 25, 2026

Uh oh!

Jake Bailey (jakebailey) commented Aug 25, 2026

Uh oh!

Xia Chao (bun-unsafe) commented Aug 25, 2026

Uh oh!

Jake Bailey (jakebailey) commented Aug 25, 2026

Uh oh!

Xia Chao (bun-unsafe) commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Xia Chao (bun-unsafe) commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Xia Chao (bun-unsafe) Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Xia Chao (bun-unsafe) Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

Xia Chao (bun-unsafe) commented Aug 25, 2026

Uh oh!

Jake Bailey (jakebailey) commented Aug 25, 2026

Uh oh!

Xia Chao (bun-unsafe) commented Aug 25, 2026

Uh oh!

Jake Bailey (jakebailey) commented Aug 25, 2026

Uh oh!

Xia Chao (bun-unsafe) commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Xia Chao (bun-unsafe) commented Aug 25, 2026 •

edited

Loading