Repository: TypeScript
Issue: Provide Compiler API way to disable type checking for a source file
Labels: Suggestion,Awaiting More Feedback

### ⭐ 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](https://www.typescriptlang.org/docs/handbook/project-references.html) 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()`](https://github.com/microsoft/TypeScript/blob/72d497352fe5aa747ee9008395fe5999bb63a356/src/compiler/utilities.ts#L9876C17-L9876C17) 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

- [X] This wouldn't be a breaking change in existing TypeScript/JavaScript code
- [X] This wouldn't change the runtime behavior of existing JavaScript code
- [X] This could be implemented without emitting different JS based on the types of the expressions
- [X] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- [X] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [X] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals