[API] No jsDocParsingMode, and reparsed JSDoc types appear as syntax on the declarations they document
@andrewbranch đang làm issue này rồi.
Từ ngày 28/8/2026.
Đánh giá
Issue này chưa được đánh giá.
Mô tả
Description
Two related gaps around JSDoc, which together make it hard for a tool that reproduces source text to work with the 7.x API.
1. There is no jsDocParsingMode. In 6.x a consumer could pass jsDocParsingMode: JSDocParsingMode.ParseNone to createSourceFile and get a tree with no JSDoc in it. The 7.x API exposes no parse options, and JSDocParsingMode is not exported from any path.
2. JSDoc types are reparsed into the syntax tree. A @param/@returns type becomes a real type annotation on the declaration it documents, carrying offsets that point inside the comment:
import { API } from "typescript/unstable/sync";
import { NodeFlags } from "typescript/unstable/ast";
// b.js, with allowJs + checkJs:
// /**
// * @param {number} a
// */
// export function g(a) { return a }
const fn = program.getSourceFile("/probe/b.js").statements[0];
const type = fn.parameters[0].type;
type !== undefined // true — the parameter has a type annotation
(type.flags & NodeFlags.Reparsed) !== 0 // true
[type.pos, type.end] // [15, 21] — inside the comment
The source has no annotation there. A tool that reads node.type and prints it emits syntax the file never contained:
// source
export function resolveMatchingConfig(regularPath, config) { return {} }
// printed back, with the JSDoc types read as syntax
export function resolveMatchingConfig(regularPath, config:Array<string|string[]>|Array<SidebarGroup>|[link:string]):base { return {} }
NodeFlags.Reparsed is exactly the signal needed, and it works — but it has to be consulted at every field access, not only when walking children, because node.type reaches these nodes directly. That is easy to get wrong and gives no diagnostic when you do.
3. Syntax errors are reported from inside JSDoc. With allowJs/checkJs, malformed JSDoc types produce syntactic diagnostics against the file:
(5,74): '}' expected. [1005]
(6,19): '}' expected. [1005]
Handing those to a user as parse errors is wrong when the tool does not consume JSDoc at all. Avoiding that is what ParseNone was for in 6.x; the only workaround I found is to drop diagnostics whose position falls inside a comment range, which requires scanning the file separately.
Suggested resolution
Any one of these would be enough for my case, in rough order of preference:
- A parse option equivalent to
jsDocParsingMode, on whatever carries parse options when #63875'screateSourceFilelands. - Keeping reparsed nodes off the declaration's own fields (reachable through a dedicated accessor instead), so
node.typeis what the source says. - Failing both, documenting that
NodeFlags.Reparsedmust be checked on every node read from a field, and not reporting JSDoc-internal syntax errors as file diagnostics.
Use case
Porting OpenRewrite's JavaScript/TypeScript parser from the 6.x API. It builds a lossless tree and prints it back byte-for-byte, and it sets jsDocParsingMode: ParseNone today precisely because it does not model JSDoc. On 7.x it had to filter NodeFlags.Reparsed in two separate places and post-filter diagnostics by comment range to round-trip the same files.
Verified against 7.0.2 and typescript@next (7.1.0-dev.20260827.1).
Related: #63892 (missing child/token getters) is the other half of what a lossless-syntax consumer needs from this API.
- Ngôn ngữ chính
- Go
- Star
- 111k
- Fork
- 14.4k
- Merge trung bình
- 1 ngày 15 giờ
- Pull request đã merge (30 ngày)
- 106
Hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của microsoft/TypeScript
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100
microsoft/TypeScript#64322 · 2 bình luận · 1 reaction · 2 người được giao ·
-
Possible Improvement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
microsoft/TypeScript#64278 · 1 bình luận · 1 reaction ·
-
Docs
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
microsoft/TypeScript#64118 · 1 bình luận ·
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 88/100
microsoft/TypeScript#64094 ·
-
Docs
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 76/100
microsoft/TypeScript#63959 · 5 bình luận ·
Tất cả issue của microsoft/TypeScript
Issue tương tự
-
Type/Bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
OpenNSW/nsw-srilanka#497 ·
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 92/100
milvus-io/birdwatcher#545 ·
-
kind/bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100
kubernetes-sigs/prow#953 · 1 bình luận ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100
caddyserver/caddy#8046 ·