Repository: TypeScript
Issue: Suggestion: Introduce possibility to control rootDirs resolve order
Labels: Suggestion,Awaiting More Feedback

## Search Terms

List of keywords you searched for before creating this issue:
rootDirs, resolve, resolve sources, classpath, source resolve order, sourcepath

## Suggestion

Please add a new compiler option: 
```
rootDirsResolveStrategy = default | ordered
```
as a suplement to existing `rootDirs` option.

Proposed values:
`default` - current behavour. (which would be default, nomen omen ;))
`ordered` - the sources are looked up with respect to the order they are listed in `rootDirs`.

Consider we have `rootDirs` defined as below: 
```
"rootDirs": ["src/generated/ts", "src/main/ts"], 
```

And source tree
```
src
├── generated/ts     
   └── other.ts
├── main/ts              
   └── index.ts   # imports ./other.ts
   └── other.ts
```
now, no matter the order in which `rootDirs` folders are provided, the import "prefers" the file in the same folder.

**The name of the option does not matter** (or if there is an additional option at all). We just need something like java's compiletime classpath (with possibilty to impose resolve order to make generated files obscure the sources).

## Use Cases

What do you want to use this for?

**This would enable possibility to write a "compile-time decorator processor", which could modify class signatures and public interface of the class.**

Both these features are highly requested in existing feature requests [* - see below], (some open since 2015 and still not closed). With this feature, it would be achievable with the current Compiler API.

What shortcomings exist with current approaches?

Now, no matter the order in which `rootDirs` folders are provided, the import "prefers" the file in the same folder. So the generated files will never obscure the sources. 

Currently, there may be two approaches:
1. Write annotation processor which replaces the actual source files with generated files.
2. Force the build script to copy all sources to another directory and there replace actual sources with generated ones before actual compilation.

Both approaches have very strong flaws, which make them not usable in practice.

Ad. 1. This would be one-time transformation. After the transformation is done, no further modification in the original source would be possible. And so it also makes impossible to fire the annotation processor "in watch mode", as the user modifies the actual sources. Finally, it's generally a bad practice to manually edit generated sources or have generated files committed to version control repository (which in this case would be inevitable).

Ad. 2. The effect of replacing sources "somehow magically" before actual build, would make it impossible for IDE to follow actual sources, and so raising errors when generated API is used. This disqualifies this approach from use in practice.

[*] Links to some of the feature requests mentioned above:
- [Request: Class Decorator Mutation](https://github.com/microsoft/TypeScript/issues/4881)
- [Allow class decorators to extend type signature](https://github.com/Microsoft/TypeScript/issues/25119)
- [Suggestion: support compile time annotations alongside runtime decorators](https://github.com/microsoft/TypeScript/issues/30723)
- [Add Support for design-time decorators](https://github.com/microsoft/TypeScript/issues/2900)

## Examples

For example, an annotation processor like Java's [lombok](https://projectlombok.org/). 

## Checklist

My suggestion meets these guidelines:

* [yes] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [yes] This wouldn't change the runtime behavior of existing JavaScript code
* [yes] This could be implemented without emitting different JS based on the types of the expressions
* [yes] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [I think so ;)] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).