feat(rush-lib): early cycle detection for workspace packages in rush install/update

[Copilot]

Undeclared cycles between workspace packages cause pnpm to fail deep in the install process with a cryptic error. This adds an early validation that detects such cycles before any package-manager work begins and fails immediately with a clear, actionable message.

Changes

• src/logic/WorkspaceCycleDetector.ts (new) — DFS-based O(V+E) cycle detection over RushConfigurationProject.dependencyProjects, which already excludes decoupledLocalDependencies. Exports _findWorkspaceCycle() (returns cycle path or undefined) and detectAndReportWorkspaceCycles() (logs + throws AlreadyReportedError).
• BaseInstallManager.prepareAsync() — calls detectAndReportWorkspaceCycles() immediately after policy validation, before any shrinkwrap or package-manager work.
• WorkspaceCycleDetector.test.ts + three minimal fixture repos — covers no-cycle, undeclared cycle, and decoupledLocalDependencies-broken cycle cases.

Example error

A cyclic dependency was detected among workspace packages:
  pkg-a -> pkg-b -> pkg-a

To fix this, add one of the packages in the cycle to the "decoupledLocalDependencies"
field for the dependent project in rush.json.

Cycles declared via decoupledLocalDependencies are not flagged. Only the first detected cycle is reported per run.

[David Michon (dmichon-msft)]

Copilot Do NOT recommend decoupledLocalDependencies as the default way to break a cycle. Recommend first actually breaking the cycle, e.g. refactoring code out into a project that can be depended on by the projects involved in the cycle, or moving code from one project to another.

[Copilot]

Copilot Do NOT recommend decoupledLocalDependencies as the default way to break a cycle. Recommend first actually breaking the cycle, e.g. refactoring code out into a project that can be depended...

Updated in the latest commit. The error message now leads with refactoring as the recommended fix (extracting shared code into a new package, or moving code so the dependency flows in one direction), and only mentions decoupledLocalDependencies at the end as a last resort — explicitly noting the cost of losing workspace linking for that edge. The JSDoc comment was updated to match.

[David Michon (dmichon-msft)]

Copilot The visiting set and path array are redundant; just iterate visiting and skip nodes until you hit the current one to report the cycle.

[Copilot]

Copilot The visiting set and path array are redundant; just iterate visiting and skip nodes until you hit the current one to report the cycle.

Done. The path array is removed; the back-edge handler now iterates visiting (ES6 insertion order) starting from the cycle-start node to build the cycle path, then appends the start node again to close the loop.