Research Solution for Circular Dependency Checking

[jakobo]

Problem Statement

madge isn't great with Typescript circular dependencies. We use it right now to avoid the most egregious problems, but there's likely better solutions since the original build scripts were written.

Proposed Solution

This is a research task, which means no code is required (unless you want to do a PR). There's a set of questions we're hoping to answer, informing the project direction.

1. What value are we getting from madge? How could we introduce a circular dependency in DocMQ, and can we trust madge to catch it?
2. What alternatives to madge are out there? Are they better than what we currently have? I found two quickly googling, but this isn't an exhaustive list by any means: dpdm, eslint import rule
3. Is it worth keeping madge, swapping to an alternative, or removing the circular dependency checks altogether?

[jakobo]

To help out whoever takes this on. For (1), the main value we get is to avoid circular dependencies when using import statements. It's really easy to forget a type keyword on an import statement and end up with code that doesn't build.

// a.js
import { BType } from "b.js" // <= should've been a type import

// 2
import { AType } from "a.js"" // <= should've been a type import

In this example, the ESM code will import BType and AType as objects instead of types. While Typescript can manage the circular dependency and sees these as types, node.js running in ESM mode will not and one of these modules will resolve to {} because it must be evaluated first.

This isn't an issue in CommonJS, which does all checks in a single pass (and lets us assign to module.exports after the fact).