582 TypeScript files, 11 import cycles, and nine of them disappear when you delete the word type
Every bundler builds a module graph and almost none of them will show you one. I wanted to know the shape of the code behind Nakodo rather than its weight: which file everything depends on, which files depend on nothing,
Every bundler builds a module graph and almost none of them will show you one. I wanted to know the shape of the code behind Nakodo rather than its weight: which file everything depends on, which files depend on nothing, and whether the dependency arrows ever go in a circle.
That took about forty lines of Python and no tooling, and the interesting results were all in the places my first version got wrong.
Resolving the edges
Two kinds of specifier matter in this codebase: @/ for the project root alias and ./ for relatives. Everything else is a package.
def resolve(spec, src):
if spec.startswith("@/"): base = Path("src") / spec[2:]
elif spec.startswith("."): base = (src.parent / spec).resolve()
else: return None # a package, not our code
for c in (base, base.with_suffix(".ts"), base.with_suffix(".tsx"),
base / "index.ts", base / "index.tsx"):
if c.is_file(): return str(c)
The last two lines of that list are the first thing I got wrong. I wrote index.ts only, which silently dropped every import of a directory whose barrel happened to be a .tsx file, and made twenty-one illustration components look like dead code.
Then the totals:
Files under src
|
582 |
| Lines of TypeScript | 72,683 |
import statements |
2,904 |
Of those, edges inside src
|
2,291 |
| Type-only edges | 227 |
| Files importing nothing of ours | 63 |
What everything leans on
Fan-in, counting distinct importing files. Every number below is a count of files that name the file on the right:
| Imported by | File |
|---|---|
| 113 | src/db/schema.ts |
| 79 | src/content/types.ts |
| 64 | src/db/index.ts |
| 60 | src/components/ui/button.tsx |
| 50 |
src/lib/plans.ts (the three plans on the pricing page) |
| 48 | src/lib/utils.ts |
| 46 | src/lib/social/platforms.ts |
| 39 | src/lib/format.ts |
The median file in the project is imported once. Those eight are the spine: the database schema, the type that describes a content page (there are 76 of them, from the guides index to the glossary), the database client, the button, the plan limits, the class-name helper, the list of platforms, the money and number formatters.
Fan-out is lopsided in the other direction. 63 files import nothing of ours at all, 188 import exactly one thing, and then there is a short tail of assembly points:
| Imports | File |
|---|---|
| 45 | campaigns/actions.ts |
| 37 | campaigns/[id]/outreach/page.tsx |
| 29 | campaigns/[id]/results-view.tsx |
| 26 | lib/outreach/send.ts |
| 25 | (marketing)/page.tsx |
That last one is the landing page, and 25 is about right for a page that is one of everything.
11 cycles, and nine of them are types
The cycle search found eleven circular paths. Nine of them pass through one file, src/db/schema.ts:
db/schema.ts -> lib/limits/counters.ts -> db/schema.ts
db/schema.ts -> lib/outreach/classify.ts -> db/schema.ts
db/schema.ts -> lib/outreach/classify.ts -> lib/outreach/levels.ts -> db/schema.ts
db/index.ts -> db/schema.ts -> lib/limits/counters.ts -> lib/limits/pacing.ts -> db/index.ts
db/schema.ts -> lib/outreach/classify.ts -> lib/proposal/details.ts -> lib/proposal/proposal.ts -> db/schema.ts
...
That looked alarming for about a minute. The schema is the most imported file in the project; if it imports its own importers back, module initialisation order starts to matter and a half-initialised table definition is a bad afternoon.
Then I rebuilt the graph with type-only edges removed, because import type is erased at compile time and cannot create a runtime cycle:
runtime = {a: edges[a] - type_edges[a] for a in edges}
Eleven became two, and the two survivors are not the schema's. All nine of the schema's cycles existed only in the type system, where cycles are legal and harmless. The two real ones are between three modules of the search pipeline that genuinely call back into each other.
The schema file imports fourteen modules of ours. Nine are import type, pulling in the shapes that get stored in jsonb columns. Five are value imports, and every one of those comes from a module that imports almost nothing itself:
| Module | Its own imports | What the schema takes |
|---|---|---|
lib/notification-emails.ts |
0 | the switchable email list |
lib/pause.ts |
0 | pause modes and reasons |
lib/support/kinds.ts |
0 | support kinds and statuses |
lib/kinds.ts |
1, type-only | campaign kinds |
lib/social/platforms.ts |
1, the env object | the platform list |
Those are the arrays the schema turns into column enums, and two of the five say why they are shaped that way in their own header comments:
// ...Product news is its own consent
// (email_preferences.marketing). No imports, so the schema can use it.
// ...No imports, so the schema, the
// server and client components can all use it (as src/lib/pause.ts does).
"No imports, so the schema can use it" is the whole rule, written down twice, at the two places where breaking it would hurt, and the second one names the first as precedent. A constant list the database layer needs has to be a leaf.
174 files that nobody imports
A file with no importer is either an entry point or dead weight, and the only way to tell is to classify:
| Reason | Files |
|---|---|
Framework routes (page.tsx, route.ts, layout.tsx, loading.tsx, sitemap.ts...) |
104 |
| Tests | 62 |
Framework entry points (proxy.ts, instrumentation) |
3 |
| Neither | 5 |
104 of them are files the framework finds by their filename, which is the deal you accept with a file-system router: the orphan count of an App Router project is mostly a count of its pages. 62 are tests, which import the code and are imported by nothing but the runner.
That leaves five. Four are UI primitives a CLI wrote that we never used, which I already knew about. The fifth is a 68-line module in the research folder, holding one exported async function that nothing anywhere calls. It typechecks, it is covered by no test, and it has been quietly paid for in every install and every build since the day it stopped being called.
The three edges a naive parser misses
Each of these produced a wrong answer before I fixed it, and each is worth knowing before you trust a graph you built yourself.
export ... from is not an import. My first pass only matched import, so a barrel that re-exports a module looked like it had no relationship to it, and the module it re-exported looked orphaned. There are 26 such edges here, carrying two barrels.
import() is invisible to a regex looking for from. There are exactly three dynamic imports in the project: a support panel loaded with ssr: false, a native database addon that cannot be bundled, and one function imported lazily to break a cycle.
A comment about the graph can be out of date, because nothing checks it. That third dynamic import says:
// Imported here: launch imports this module.
const { widenCampaigns } = await import("@/lib/pipeline/launch");
There is no path from that module back to this one any more. The cycle it was written to dodge is gone, so the lazy import is now just a lazy import. That is the most honest argument I know for generating this kind of claim instead of writing it: the graph changed, and the sentence describing it did not.
What came out of it
-
Delete the dead module. 68 lines, one function, no callers. Finding it took a graph; deleting it takes one line of
git rm. - Make the leaf rule a test. Five modules are load-bearing precisely because they import nothing. A test that asserts the schema's value imports resolve to files with zero value imports of their own would keep a convenient future import from quietly adding a runtime cycle to the most imported file in the project.
- Promote the stale comment to a check. If an import exists to break a cycle, the assertion that the cycle exists belongs in the same test run as the cycle detector, not in a comment above it.
- The two pipeline cycles stay, for now. They are real, they are between modules that genuinely alternate, and splitting them would mean a third module whose only job is to hold a type. Writing them down is worth more than hiding them.
If you want to try this on your own project, the only parts you have to get right are the resolver, the re-export case, and removing import type before you panic about cycles. The rest is a depth-first search you learned in school.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.