Repository: TypeScript
Issue: Feature request: Report an error for missing or unused project references
Labels: Suggestion,Awaiting More Feedback

## 🔍 Search Terms

composite project missing unused project reference

## ✅ Viability Checklist

My suggestion meets these guidelines:

* [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 feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

Please add compiler options that would report an error if:
* A module is imported from another package in the composite project without a corresponding project reference in `tsconfig.json`.
* A project reference exists in `tsconfig.json` that doesn't correspond to any imported module.

## 📃 Motivating Example

I work on a very large monorepo-based project that uses a TypeScript composite project. I'll explain the setup in detail just to make sure I don't leave anything out that might be helpful. The file system layout looks similar to this:

```
package.json
packages/
├── tsconfig.json
├── foo/
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   └── dist/
├── bar/
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   └── dist/
├── ...
```

We "install" all of these packages in the root `package.json` using, for example:
```
npm install packages/foo
```

This symlinks them into `node_modules` so that they can be imported by other packages. The name of each package is `@company/PACKAGE`, so that `packages/foo` is symlinked to `node_modules/@company/foo`.

Using this setup, we can build all packages using `tsc --build packages`. The root `tsconfig.json` uses a solution-style configuration and just references all of the individual packages.

For `tsc` to understand the dependencies between these packages, so that they can be built in the right order, we naturally need to specify project references in each package's `tsconfig.json`. For example, if `bar` contains a source file that includes this import statement:
```
import { value } from '@company/foo';
```
...then `bar` needs to contain a corresponding project reference for `foo` in `tsconfig.json`:
```
{
  // ...
  "references": [
    { "path": "../foo" },
  }
}
```

That's the setup. The actual problem is simply this: there is no way to ask the compiler to report an error if one of these project references is missing or unused. Without this feature, this entire setup is a gigantic footgun:
* If a project reference that should be there is missing, the packages may be built in the wrong order, or dependencies may not be rebuilt when they should be. This may cause the build to fail, or cause types to be checked against a previous version of the code, or may just work by coincidence until someone tries to make a seemingly-unrelated change and breaks the build.
* If a project reference that is no longer necessary is not removed, it may cause false dependencies to be rebuilt unnecessarily often, slowing down incremental builds.

To avoid this, we've implemented a tool that parses the output of `--traceResolution` and compares it to the content of each package's `tsconfig.json` to detect such cases and cause a CI job to fail. (Today, we might implement it on top of `--explainFiles` instead.) This tool is very slow, because to get complete output from `--traceResolution`, it needs to rebuild everything. It's also based on an unstable interface - parsing compiler log output - that might break at any time.

It would be incredibly helpful if there were compiler options that would do this job for us as part of the normal process of compilation. The really critical thing is to detect missing project references, since they're necessary for correctness, but being able to detect unused ones would be a huge help as well.