Provide Compiler API way to disable type checking for a source file

⭐ Suggestion

This request is for a public Compiler API means to disable type checking for individual SourceFile instances that are part of a ts.Program.

There are several ways to indirectly tap into this behavior, but none of them seem to be convenient to use from a Compiler API script.

• A source file could have // @ts-nocheck explicitly written out.
• Setting skipLibCheck / skipDefaultLibCheck will skip type checking for declaration source files.
• JavaScript files under allowJs without checkJs I believe are another flavor of skipping type checking.

It would be nice if it was as simple as sourceFile.skipTypeChecking = true followed by requesting diagnostics. Or have the APIs accept a function (sourceFile: SourceFile) => boolean that is called to make the decision to type check or not.

📃 Motivating Example

I am trying to improve the compile performance of a very large TypeScript monorepo. This is on the scale of thousands of tsconfig.json files, and tens of thousands of source files.

Across the repository, source files have freely referenced each other. The tsconfig.json projects all extend from a common base and the purpose of them was mainly to just to light up IDE support and split out reasonably-sized chunks of source files to compile together.

As the codebase has grown over time, performance has plummeted under the default behavior of the compiler:

• One tsconfig.json might "own" say 15 files, those within the subdirectory it is in.
• The compiler parses those 15, then finds more dependencies, and more dependencies of those... and more dependencies of those.
• Suddenly each ts.Program balloons into doing compilation work for thousands of transitive dependencies. That effort is unwanted, because those dependencies really should ideally just be checked when "their own" tsconfig.json is being compiled.

I know that Project References would be the best way to address this performance problem. We'd create strict project boundaries, and the "15 source files" in the example above would be type checked against .d.ts files rather than other full source files. It is a very large undertaking to take existing code that hasn't "followed the rules" and conform it though.

We already use the Compiler API for other reasons, and I've been experimenting with tweaks to ts.skipTypeChecking() to try to reduce the unwanted type checking work. It seems really promising to have skipTypeChecking short-circuit the type checking work for the transitive dependencies that pull into a ts.Program in my case.

---

I'd also note that a feature like this in the Compiler API could enable "power users" to implement something like #28260 on their own.

---

Finally, I'd note that I'm certainly open to other suggestions here, or any advice / caution about the skipTypeChecking trickery I'm delving into!

💻 Use Cases

What do you want to use this for?

• A power user feature in the Compiler API to control what source files get type checked.

What shortcomings exist with current approaches?

• Trying to tap into // @ts-nocheck dynamically feels extremely roundabout, and in particular has some bugs (#56956)
• skipLibCheck is similar functionality, except I want to skip "a certain large swath of non-declaration files" instead.

What workarounds are you using in the meantime?

• The most practical approach I have found to achieve an immediate widespread performance improvement is to patch the internal skipTypeChecking function with extra logic like if (sourceFile.skipTypeChecking) { return true; } and then set sourceFile.skipTypeChecking = true on the transitive dependency source files.

🔍 Search Terms

skipTypeChecking, ts-nocheck

✅ 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

Start by reading src/compiler/utilities.ts at the mentioned skipTypeChecking function and the Compiler API paths that request diagnostics. Compare the proposed per-SourceFile flag with a callback-based API and existing ts-nocheck, skipLibCheck, and skipDefaultLibCheck behavior. Done means a supported API can selectively skip type checking for SourceFile instances without changing emitted JavaScript.