Make the `sourceFile.commentDirectives` property public

[mrazauskas]

🔍 Search Terms

"SourceFile", "commentDirectives", "public"

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Please consider making the sourceFile.commentDirectives property public. Currently it is marked as internal:

TypeScript/src/compiler/types.ts

Line 4434 in b504a1e

/** @internal */ commentDirectives?: CommentDirective[];

📃 Motivating Example

The sourceFile.commentDirectives property currently is available at run time. Only the types are missing.

The community is actually using it. I am not really good in searching on GitHub, but here are few examples: https://github.com/search?q=Array.isArray%28commentDirectives%29&type=code

And one more here: https://github.com/Dionysusnu/roblox-ts/blob/dcf84ff4477830e47a21818315c71fb20d20e215/src/Project/preEmitDiagnostics/fileUsesCommentDirectives.ts#L12

The idea is simple: the // @ts-ignore and // @ts-expect-error comments are already collected and available just like any other nodes. The community projects could handle them as they like.

💻 Use Cases

What do you want to use this for?

In my project, I want to check the text provided after // @ts-expect-error and to make sure it matches the diagnostic message. Somewhat similarly to typescript-eslint, that has a rule which requires providing a note after // @ts-expect-error, but one step forward.

What shortcomings exist with current approaches?

Based on current usage example, this is possible:

if ("commentDirectives" in sourceFile && Array.isArray(sourceFile.commentDirectives)) {
  // ...
}

, but the type of commentDirectives is any[]. Not a problem to cast it, of course.

What workarounds are you using in the meantime?

Instead of using the internals, a solution could be to call sourceFile.getText() and pass it through some logic which finds directives. That would work, but sounds like duplication, because the scanner did the same job already. (And did it better as well!)

[repo-anuj]

Thank you for raising this! I agree that making sourceFile.commentDirectives public would be valuable for the community. Many tools and custom scripts already depend on this property, and having official typings would make these use cases safer and easier to maintain. Since this property is already available at runtime and exposing it wouldn’t introduce breaking changes, it seems like a low-risk improvement that could unlock more advanced static analysis and linting scenarios.

Would the team have any concerns about the stability of the commentDirectives structure, or is it expected to remain compatible going forward? If stability is a concern, maybe the property could be marked as readonly or documented as "subject to change" initially. Either way, I think exposing it with proper types would be a great step forward!

[RyanCavanaugh]

This field is for an internal optimization and isn't intended for external use.

[mrazauskas]

Thanks for taking a look. All clear. I have to find another solution then.