[Titian Cernicova-Dragomir (dragomirtitian)]

Fixes #64429

[typescript-automation]

This PR doesn't have any linked issues. Please open an issue that references this PR. From there we can discuss and prioritise.

[Copilot]

Copilot review overview

🟡 Changes recommended

Public API compatibility gaps, omitted enum members, and a nullable protocol entry that can panic must be addressed.

Review effort: Balanced
Findings: 1 · 1 · 1

Open (3)

• Null request entries can trigger an emitNode nil dereference · New
• Generated enum omits native zero and composed EmitFlags constants · New
• Mark emitContext as undefined-compatible for exact optional properties · New

What changed in this PR

Adds emit flags and synthetic-comment support to the TypeScript API printer.

Changes:

• Introduces EmitContext and EmitFlags.
• Transfers emit metadata alongside encoded AST nodes.
• Adds synchronous and asynchronous API tests.

File	Description
tsc/​internal/​printer/​printer.go	Enables synthetic comments without a source file.
tsc/​internal/​api/​session.go	Reconstructs emit metadata for printing.
tsc/​internal/​api/​proto.go	Defines emit metadata protocol types.
tsc/​internal/​api/​enum_values_generated.go	Adds generated emit flag values.
tsc/​internal/​api/​encoder/​decoder.go	Adds per-node decode callbacks.
tools/​scripts/​tsc/​generate-enums.ts	Configures EmitFlags generation.
packages/​typescript/​test/​sync/​api.test.ts	Adds generated synchronous tests.
packages/​typescript/​test/​async/​api.test.ts	Tests comments and emit flags.
packages/​typescript/​src/​enums/​emitFlags.ts	Adds runtime enum output.
packages/​typescript/​src/​enums/​emitFlags.enum.ts	Adds typed enum output.
packages/​typescript/​src/​api/​sync/​api.ts	Adds generated synchronous APIs.
packages/​typescript/​src/​api/​proto.generated.ts	Adds generated protocol declarations.
packages/​typescript/​src/​api/​node/​encoder.ts	Reports encoded node indices.
packages/​typescript/​src/​api/​async/​api.ts	Implements the public emit context API.

Files not reviewed (1)

• tsc/internal/api/enum_values_generated.go: Generated file

[Copilot]

🟡 Changes recommended

Synthetic comment handling can change program semantics or produce invalid syntax, and deferred prints retain mutable metadata.

3 open findings

• Copy mutable emit records for deferred print requests · New
• Force newlines after trailing single-line comments · New
• Parenthesize return and throw operands after synthetic comment breaks · New

3 resolved since last review

• Null request entries can trigger an emitNode nil dereference
• Generated enum omits native zero and composed EmitFlags constants
• Mark emitContext as undefined-compatible for exact optional properties

Files not reviewed (1)

• tsc/internal/api/enum_values_generated.go: Generated file

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Synthetic-comment handling can alter expression semantics, produce invalid syntax, and lose attached metadata.

3 open issues

• Preserve optional-chain short-circuiting when wrapping comments · New
• Parenthesize commented operands before postfix operators · New
• Preserve synthetic comments when rebuilding ancestor nodes · New

2 previously missed issues

In code that hasn't changed since last review

Detect line terminators in multiline comments

tsc/​internal/​printer/​printer.go:3061

A multiline comment can contain a line terminator even when both newline flags are false. A leading comment with text a\nb on the operand of return 1 bypasses this check and emits return /*a\nb*/ 1;. Automatic semicolon insertion makes that return undefined; the corresponding throw is invalid syntax. Include line terminators in comment.Text when deciding whether parentheses are needed.

Honor HasLeadingNewLine for trailing comments

tsc/​internal/​printer/​printer.go:5519

The newly exposed hasLeadingNewLine option is ignored for trailing comments. For example, addSyntheticTrailingComment(node, MultiLineCommentTrivia, " note ", false, true) still places the comment on the node's line. Honor comment.HasLeadingNewLine before writing the trailing comment, as the leading-comment emitter already does.

3 resolved since last review

• Parenthesize return and throw operands after synthetic comment breaks
• Force newlines after trailing single-line comments
• Copy mutable emit records for deferred print requests

1 file not reviewed

• tsc/internal/api/enum_values_generated.go: Generated file

_{Review effort: Balanced}

[Andrew Branch (andrewbranch)]

Are these new bugs or inherited from Strada?

[el-j (el-j)]

Heads-up from #65058 (JSDoc node emission in the printer), which also added synthetic-comment transport for printNode before I saw this PR. Having compared the two, I think this one should be the design that lands, and I plan to drop the overlapping part from #65058 once it merges.

Overlap: both send synthetic leading/trailing comments through the encoder and printNode, keyed by node index, and apply them to an EmitContext in session.go.

Where this PR is the better fit:

• It also covers EmitFlags, which [api] Add back missing: setEmitFlags and addSynthetic*Comment #64429 asks for and ours doesn't.
• It adds hasLeadingNewLine on comments and keeps a single-line comment from commenting out the following code.
• It removes the currentSourceFile != nil gating in the printer generally (including the parenthesization checks) rather than through an opt-in option like ours (EmitSyntheticCommentsWithoutSourceFile).
• It validates out-of-range emit-node indices.

What ours has that may be worth checking here: a JSDoc-shaped test (a /** ... */ multi-line comment with hasTrailingNewLine printed before a statement, then reparsed), plus trailing // comments after a statement with no source file. I can contribute those as tests here if useful.

Pointers: #65058 adds emitJSDocNode, which fixes #65057 (printing JSDoc nodes panicked), so the two are complementary rather than competing. No action needed from the author; this is only so maintainers know the two PRs touch the same code in encoder.ts, proto.go, session.go and decoder.go.