Allow circular references of project references

Search Terms

circular reference project references graph

Suggestion

Currently, project reference graphs are required to be acyclical because

• Project references imply a .d.ts file is loaded, and .d.ts files can't exist before the build occurs
• Only acyclic graphs can be topologically sorted

Both of these problems are solvable without too much work.

With the work done in #32028, we can effectively toggle the redirecting behavior, fixing the first issue. This would be done during the initial build phase only when an upstream project dependency isn't built yet.

The other problem is that project build order might not be predictable if we arbitrarily pick some starting point in the unsortable graph. This is fixable if we force solution authors to indicate which edges in the graph should be treated as ignored for the purposes of the topological sort:

    "references": [
        { "path": "../a" },
        { "path": "../b", "circular": true },
                          ^^^^^^^^^^^^^^^^
        { "path": "../c" }
    ],

The benefits of this are:

• In case of suboptimal .d.ts generation or memory pressure, developers can control where the "weak" link occurs in the build process
• The build ordering is fully deterministic regardless of starting point
• Graphs can't become "accidentally" circular - this is a clear opt-in

Use Cases

npm and other package managers do allow circularities in dependency graphs, so this is apparently a thing.
We've also gotten feedback from some industry partners that they want to move to project references, but their dependency graph is circular in a way that would require a lot of work to "fix".

Examples

Given the graph:

A -> B -> C -(circular)-> A

The build order is deterministically C, B, A. During C's compilation, source file redirects from C to A are not active.

Checklist

My suggestion meets these guidelines:

• 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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

まず、project-reference のビルドとグラフ順序付けの実装、および #32028 で説明されている作業を読んでください。project references がどのように宣言ファイルのリダイレクトを意味するのか、またビルド順序がどのようにトポロジカルソートされるのかを追跡してください。循環参照が明示的にマークされ、順序が決定的であり、初回ビルドで例に記載された無効化されたリダイレクトが処理されれば完了です。