Skip to content

Starting from the tree

architecture infer walks your repository, resolves every import, and writes a manifest the code already passes. Use it to adopt a policy on an existing codebase: you start from a clean check and tighten by deleting.

Terminal window
pnpm exec architecture infer # print it
pnpm exec architecture infer --write # save it as architecture.yaml
  • One node per folder, down to --depth (default 2) below each package’s src/. Each node is layout: open, so it admits any file name. Deeper folders are covered by the node above them.
  • An imports allowlist per node, listing what its files import today: other nodes as globs (src/platform/**), builtins by name (node:fs), packages under external.
  • unrestricted: true on every node, marking it as not yet reviewed. Its allowlist is still enforced. limits.unrestricted caps how many remain, so lower it as you review.
  • limits.coverage set to what the manifest covers today.
  • A no-cycles graph rule, only if the repository has no import cycle today.

Each node’s message records the date and how many files it covers.

If a manifest exists, infer reuses its resolve and aliases. Otherwise it resolves through tsconfig.json and walks src/, or every top-level folder holding source files.

When sibling folders look alike (they share at least two subfolders, or half their file kinds), infer offers to describe them as one node:

src/modules/: auth, billing, orders each have commands/, domain/, queries/, index.ts.
Describe them as one node, src/modules/{module}/? [Y/n]
All 12 imports between them land on index.ts.
Restrict what one may reach in another to src/modules/*/index.ts? [Y/n]

Yes to the first merges them into {module}/, with imports between modules written as src/modules/*/**. Yes to the second narrows that to src/modules/*/index.ts.

Flag Effect
--write Save to architecture.yaml instead of printing.
--depth N How many folder levels get their own node. Default 2.
--root DIR Walk this folder. Repeatable.
--tsconfig PATH Resolve through this tsconfig instead of tsconfig.json.
--yes Accept every grouping offer.
--exhaustive Ask nothing; one node per folder. Also the behavior off a terminal.
--collapse Fold a node’s children into it when every child reaches the same things.
Terminal window
pnpm exec architecture check # passes: the manifest describes today
pnpm exec architecture coverage # lists the unreviewed nodes

From here, tighten by editing: delete an allow entry and check lists the imports that relied on it, and remove unrestricted from each node you review. Imports infer could not resolve are reported by check until they resolve or ignoreUnresolved names them with a reason.

infer records what the code does, not what it should do. See adoption for tightening it.