Skip to content

fix(resolution): an undeclared package that is installed is the package's (#3271) - #3278

Open
inth3shadows wants to merge 5 commits into
colbymchenry:mainfrom
inth3shadows:fix/3271-undeclared-external-import
Open

inth3shadows wants to merge 5 commits into
colbymchenry:mainfrom
inth3shadows:fix/3271-undeclared-external-import

Conversation

@inth3shadows

@inth3shadows inth3shadows commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #3271

What

A bare JS/TS import of a package that the importing file's package.json (and the ones above it) doesn't declare counted as the project's. So import { useForm } from 'react-hook-form' with the dependency hoisted to a monorepo root fell through to a project-wide exact match and linked to an unrelated useForm the file never imports.

How

isOutOfRepoImport now also treats such a specifier as outside the repository when Node would find it installed. That means the nearest node_modules/<name> at or above the importer's real path, past the project root too, whose real path runs through a node_modules folder: a registry copy, or pnpm's .pnpm store. Names are matched against a case-exact listing of each node_modules folder.

These stay the project's, as on main:

  • A node_modules entry that links to any other folder, which is a sibling package. That covers workspace links, a worktree whose node_modules links to the main checkout, and a packages/ folder linked out of the project.
  • An installed copy of one of the project's own packages: a package.json at or above an indexed folder names it, either as its name or as a workspace:/file:/link:/portal: or bare local-path dependency, under the name it's imported by or the name the copy's own package.json gives. That covers a sibling that yarn's file: or npm's install-links copied in (stale or under another name), and a project that itself lives inside a node_modules folder.
  • An undeclared specifier with nothing installed, such as an alias the resolver doesn't read (webpack's ui, a Deno import map's helpers, a tsconfig paths in a referenced config) or $lib/…, ~/…, @/… and #….

I tried two other designs first and dropped both:

  • Folder or file name matching the specifier. It dropped correct edges through unread aliases.
  • Lockfile entries as evidence. Nested and transitive entries turned unread aliases external, and multi-MB lockfiles were re-parsed every pass.

Measured (base f72c9d2e vs this branch, CODEGRAPH_KERNEL=0)

  • __tests__/undeclared-package-imports.test.ts: 35/35 pass. On main, the 11 wrong-edge cases fail and the 24 kept cases pass.
  • Repos with their real installs (two apps, plus this repo with 125,432 edges): 0 edges removed, 0 added.
  • No-install corpora (zod, hono, express, fastify, effect, part of vscode): 0 changes.
  • Cost: indexing 512 directories × 15 undeclared imports takes 3.55s against 3.40s on main with nothing installed, and about 5% slower with all 15 installed (4.08–4.37s against 3.88–4.24s on a loaded machine). Edges are identical in both cases.
  • Full suite on the final tree: 868 files and 10,554 tests passed. tsc --noEmit exits 0.
  • Installed package.json files are read through the same guard as source files (no blocking open, regular files only, size limit). A FIFO committed at node_modules/<name>/package.json doesn't stall indexing; a test pins this on POSIX.
  • Tested on Linux only. The symlink and junction cases (macOS /var → /private/var, Windows junctions) aren't run here; the tests create links as junction so they can run on Windows.

Checked with graph-assay

I maintain graph-assay, which checks a code graph's edges against the compiler. I added a fixture for this issue: fixtures/oracle-candidates/issue-3271, with react-hook-form installed in the fixture.

  • Fixture replay: issue-3271 is BROKEN on main (f72c9d2e) and FIXED on this PR (381f34db). No other fixture verdict changed.
  • Side effects: on excalidraw dd2f8fc with its yarn-installed dependencies, the TypeScript compiler oracle sees two edges change, both removals:
    • generateElementCanvas -> AppCursor::canvas at packages/element/src/renderElement.ts:325 (rough.canvas(canvas)). The compiler resolves this call to roughjs, so the edge was wrong.
    • woff2ServerPlugin -> which at scripts/woff2/woff2-esbuild-plugins.js:103, an edge to the local const which = require("which") binding. The compiler counts that edge as correct. main already drops the same edge when which is declared in package.json, so this PR makes an undeclared but installed package behave the same way.

To rerun, from a graph-assay checkout at that commit:

node bin/graph-assay replay /path/to/codegraph/dist/bin/codegraph.js issue-3271

Known limits

  • A checkout with nothing installed keeps today's behaviour. That includes the issue's no-package.json repro when node_modules is absent.
  • A project folder whose package.json is named like an installed dependency (a test fixture named react-hook-form) makes that dependency count as the project's, so its imports keep today's behaviour.
  • An alias that shares its name with an installed package (an alias ui while a package ui is installed) now counts as that package, which is what Node would load without the bundler.
  • These all keep today's behaviour: a node_modules that is itself a link to a folder not named node_modules, a symlinked source file, an npm linked checkout elsewhere, a package with only @types/<name> installed (such as vscode), and a package installed as a single file.
  • A nameless sibling copied in through a dependency written as ., .., or a Windows path (..\libs\lib, C:\libs\lib) isn't recognized as the project's, so it counts as installed.
  • A catch-all tsconfig paths entry ("*": ["./src/*"]) that resolves an undeclared installed package to a project folder keeps today's behaviour; the check here runs only for imports no project file answers.
  • A file: tarball or other local dependency in the importer's own manifest makes that name count as the project's, as it does today.
  • A sibling copied in under another name whose package.json has no name (or a different one), declared only from a folder with no indexed source, counts as installed.
  • The existing manifest reader that decides declared dependencies doesn't strip a byte order mark or treat bare local paths as the project's; that behaviour is unchanged here.
  • A sync doesn't re-resolve unchanged files when node_modules changes. The same is true of package.json today, so the CHANGELOG entry asks for a re-index.

…ge's (colbymchenry#3271)

A bare JS/TS import of a package the importing file's package.json (and its
enclosing ones) doesn't declare counted as the project's, so a name it binds
fell through to a project-wide exact match: `import { useForm } from
'react-hook-form'` linked to an unrelated `useForm` the file never imports.

isOutOfRepoImport now also treats such a specifier as outside the repository
when Node would find it installed: the nearest `node_modules/<name>` at or
above the importer's real path (past the project root too) whose real path
runs through a `node_modules` folder (a registry copy or pnpm's store). A
`node_modules` entry linking to any other folder is a sibling package and
stays the project's, as do aliases the resolver doesn't read (a bundler's
`ui`, an import map's `helpers`), which have no installed copy.

Known limits: a checkout with nothing installed keeps today's behaviour; an
alias that shares its name with an installed package now counts as that
package.
An install can copy a sibling package into node_modules as a real folder
(yarn v1's `file:`, npm's install-links), and a project can itself live
inside a node_modules folder. Both looked like registry copies, so an
undeclared import of the sibling lost its edges. A name that a package.json
of an indexed directory owns now stays the project's; the set is read only
when a name would otherwise count as installed.

Also: memoize each node_modules folder's real path, and bring the
isInstalledPackage and importedFromPackage comments in line with the rule.
…sion matches

The previous commit kept any installed name that some project manifest owns,
so a fixture or tool folder named like a real dependency (or a `file:`
tarball dependency) brought the colbymchenry#3271 mislink back. An installed copy now
stays the project's only when a package.json at or above an indexed
directory gives it the same name and version, which a copied sibling or a
project inside node_modules does and a namesake fixture doesn't.

The manifest read is one package.json per directory, built only when a name
would otherwise count as installed, and the answer is memoized per
node_modules folder and name. The node_modules walk now lists each folder
only when it gets to it, so a nearer answer leaves the rest unread.
…rsion

Matching an installed copy to a project package by name and version dropped
correct edges: a copy left behind by a version bump, a copy installed under
another name (`"kit": "file:../libs/lib"`), and a package.json that starts
with a byte order mark. An installed copy is the project's again when a
project manifest names it, either as the name it is imported by or as the
name its own package.json gives, read past a byte order mark. Manifests are
read directly, so the sweep doesn't evict cached source text.
The two package.json reads added for copied siblings opened the file with a
plain read, so a FIFO (or a link to a device) committed at
node_modules/<name>/package.json blocked indexing forever. They now go
through readSourceText, which opens without blocking and takes only a
regular file within the source size limit, and strip a byte order mark.

npm's bare local-path dependency specs (`"lib": "../libs/lib"`) now count as
the project's like `file:` ones, so a nameless sibling copied in that way
keeps its edges.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TypeScript: an import from a package not in package.json links an unimported project export of the same name

1 participant