Monorepo: workspace subpath imports are not resolved through the target package's exports map, dropping cross-package edges

[cbartens]

Summary

Imports of a workspace package subpath — @scope/pkg/components/Icon — are not resolved, because the importing package's dependency is never mapped to the target package's exports map. On a 21-package pnpm monorepo this drops 323 import edges from 1,233 workspace imports.

Related to #3486 but independent: that one is a suffix-rewriting bug in relative resolution, this one is a resolution path that does not exist. Both are silent, and both bias affected and any reachability pass the same way.

Reproduction

packages/ui/package.json
  { "name": "@acme/ui",
    "exports": { "./components/Icon": { "default": "./src/components/Icon.tsx" } } }
packages/ui/src/components/Icon.tsx        export function Icon() {}

apps/web/src/Page.tsx                       import { Icon } from "@acme/ui/components/Icon";

Expected: Page.tsx → packages/ui/src/components/Icon.tsx. Actual: no edge; Icon.tsx has zero inbound.

The bare-root form (import { x } from "@acme/ui") has the same problem when the package uses exports rather than main.

Three details that matter for a fix

1. types must not be used as the target. The near-universal shape is:

"./components/Icon": {
  "types":        "./dist/components/Icon.web.d.ts",
  "react-native": "./src/components/Icon.native.tsx",
  "default":      "./src/components/Icon.web.tsx"
}

types points into dist/, which is build output and normally excluded from the corpus, so resolving to it creates an edge to a node that does not exist.

2. The condition depends on the importer, not the package. An importer under a React Native app resolves react-native; a web importer resolves default. Picking one globally attributes Icon.web.tsx to mobile code that never imports it. Picking all of them everywhere inflates fan-in. Cheapest correct-enough rule is to choose by the importing file's location/platform suffix and fall back to the union when it is ambiguous.

3. Wildcard targets may not exist on disk. "./controls/*": { "default": "./src/controls/*.tsx" } where the real files are BottomNav.native.tsx and BottomNav.web.tsx — the bundler resolves that through sourceExts/resolveExtensions. An exports target that does not exist should fall through to the platform-suffixed siblings rather than being dropped.

Node's own subpath matching applies: exact key first, then a single * with a fixed prefix and suffix.

Measured impact

21-package pnpm monorepo, 1,430 source files, 10,958 nodes / 19,266 edges:

	Count
Workspace imports in source	1,233
Edges missing from the graph	323

Combined with #3486, 539 edges — and the package-level architecture rollup is materially wrong as a result. Two examples after repairing both out-of-band:

Package edge	graphify	actual
apps/web → packages/ui	41	150
apps/mobile → packages/ui	47	98

Non-test .tsx files reading as zero-inbound fall from 44% to 14% once both gaps are closed.

This is the failure mode worth emphasising: a monorepo's most important edges are exactly the cross-package ones, and those are the ones going missing. The graph looks plausible — it just understates coupling to shared packages by 2-3×.

Note on paths

_read_tsconfig_aliases already handles compilerOptions.paths, which is why some monorepos see cross-package edges resolve. That covers repos aliasing source directly; it does not cover repos that depend on workspace packages by name and publish through exports, which is the pnpm-workspace default.

Happy to open a PR if the approach above sounds right.

[cbartens]

Workaround for anyone hitting this before it lands upstream

Posting what we run, since both this and the sibling issue bite the same repos and the fix is the same shape either way.

We do not patch the installed package — uv tool upgrade silently reverts it, and a workaround that disappears on upgrade is worse than none. Instead we re-derive the missing edges from source and inject them into graph.json as a build step.

Where it goes in the pipeline

graphify extract . --code-only
  └─ graph-repair.py graph.json      <-- inject here
graphify cluster-only . --no-label --no-viz

Before cluster-only, deliberately. Communities, the god-node ranking and the cycle list in GRAPH_REPORT.md are then all computed from the repaired graph rather than one missing a sixth of its imports.

What gets written

One imports_from link per recovered file pair, between the two files' L1 nodes — the shape graphify already uses for a file-to-file dependency:

{"source": file_node[src], "target": file_node[dst],
 "relation": "imports_from", "_origin": "graph-repair",
 "confidence": "EXTRACTED", "confidence_score": 1.0,
 "context": "import", "source_file": src, "source_location": "L1", "weight": 1.0}

The _origin tag matters: injected edges stay greppable and never pass as graphify's own extraction.

Result — graphify explain sees an edge it could not resolve itself:

$ graphify explain "sign-in-magic-link.tsx"
Connections (3):
  <-- auth/actions.ts [imports_from] [EXTRACTED]  packages/services/src/auth/actions.ts:L1

Four things that cost us a debugging cycle each

1. A top-level marker does not survive. Setting graph["import_repair"] = {...} is dropped by cluster-only, which keeps only keys it writes itself — built_at_commit survives because graphify sets it, a custom key does not. Per-link attributes do survive, so detection has to be "are there links with my _origin", not a header field.

2. Strip your previous injection BEFORE computing what already exists. Otherwise run two sees last run's edges, treats every candidate as already present, skips them all, then deletes them — leaving the graph worse than unrepaired, and only ever on the second run. Order:

links = [l for l in links if l.get("_origin") != ORIGIN]   # strip first
existing = {(path(l["source"]), path(l["target"])) for l in links if ...}

3. graphify update rewrites graph.json and drops the injection. So the step has to run on every command that writes the file, not once by hand. Ours is wired into the build / clean / update wrapper and is idempotent, so re-running recovers.

4. Do not also repair on read. We first had our downstream consumers re-derive the same edges when loading graph.json. Once the file itself was repaired that double-counted every pair graphify had partially resolved, and inflated our package-level edge weights by 10-20%. Repair in one place; have readers warn if the marker is missing rather than silently re-deriving.

Scope

The resolver handles relative specifiers (./Foo.js → Foo.ts / Foo.tsx / Foo.d.ts, plus Foo.native.tsx / Foo.web.tsx for bundler platform splits) and workspace subpaths through exports maps, choosing the export condition by the importing file's platform. ~540 edges on a 1,430-file monorepo.

Happy to contribute the resolution logic as a PR against _resolve_js_import_path if that is wanted — it is the same matching, just inside graphify instead of bolted on after.