# All package imports resolve to a known package

- **Pattern:** `ab-000022` (`ai-slop-hallucinations.module-references.package-imports-resolve`)
- **Severity:** critical
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000022
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000022)

## Why it matters

An unresolved bare package import fails the production build the moment the bundler reaches the file, and if you ship via a platform that pre-builds only the routes it needs, the failure may surface mid-deploy rather than in local dev. AI models hallucinate confident-looking names from their training data — `react-icons/fi` when only `react-icons/fa` is installed, `lodash` when the codebase uses `lodash-es`, or outright typos like `expres`. Each one is a reference-integrity failure the tsconfig and bundler cannot silently paper over.

## Severity rationale

Critical because a single unresolved import breaks the build and blocks every deployment until it is fixed.

## Remediation

Confirm each flagged import names a package that exists on npm before trusting it, then either install it or correct the specifier. Run the verification and install in one pass:

```bash
npm view react-icons
npm install react-icons
```

For workspace packages, declare the package in the root `package.json` `workspaces` field so resolution finds the sibling directory.

## Detection

- **ID:** `package-imports-resolve`
- **Severity:** `critical`
- **What to look for:** Walk every `.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs` source file (excluding the directories listed in the Anti-Sycophancy Rules). For each `import ... from "X"`, `import("X")`, `require("X")`, or `await import("X")` statement, extract the literal string `X`. Skip imports where `X` is a relative path (starts with `.` or `..`). Skip imports where `X` matches a `tsconfig.json` `compilerOptions.paths` alias prefix. Then verify the remaining bare-package import resolves to one of: (a) a package in `KNOWN_PACKAGES`, (b) a Node built-in from this exact allowlist — `assert`, `async_hooks`, `buffer`, `child_process`, `cluster`, `console`, `constants`, `crypto`, `dgram`, `diagnostics_channel`, `dns`, `events`, `fs`, `fs/promises`, `http`, `http2`, `https`, `inspector`, `module`, `net`, `os`, `path`, `path/posix`, `path/win32`, `perf_hooks`, `process`, `punycode`, `querystring`, `readline`, `repl`, `stream`, `stream/promises`, `stream/web`, `string_decoder`, `sys`, `timers`, `timers/promises`, `tls`, `trace_events`, `tty`, `url`, `util`, `util/types`, `v8`, `vm`, `wasi`, `worker_threads`, `zlib`, (c) a `node:`-prefixed import of any of those names, (d) a `bun:`/`deno:` namespaced import (skip these — runtime built-ins), (e) a virtual module from a build tool (`virtual:*`, `~icons/*`, `astro:*`, `$app/*`, `$env/*`, `$lib/*`, `vue/server-renderer`), (f) a workspace package declared in the root `package.json` `workspaces` field. For scoped packages (`@scope/name`), match the full scoped name. For subpath imports (`pkg/subpath`), strip the subpath and match the base package name. Count all bare imports scanned, total resolved, total unresolved.
- **Pass criteria:** 100% of bare package imports resolve to a known package, Node built-in, virtual module, or workspace package. Report: "X bare imports scanned, Y resolved, 0 unresolved."
- **Fail criteria:** At least 1 bare package import does not resolve. Report each unresolved import with its file path and the import statement.
- **Do NOT pass when:** Any unresolved import exists, even if it could be installed by running `npm install` — the check is about the current state of the codebase.
- **Skip (N/A) when:** No `package.json` exists at the project root (not a Node/JS project).
- **Report even on pass:** Always report the total count of imports scanned and the count resolved. Example: "421 bare imports scanned, 421 resolved (100%)."
- **Cross-reference:** For deeper supply-chain analysis including known vulnerabilities and typosquatting, the Dependency & Supply Chain audit (`dependency-supply-chain`) covers package security in depth.
- **Detail on fail:** `"3 unresolved imports: 'react-icons/fi' in src/components/Header.tsx (not in dependencies), '@/lib/missing' in src/app/page.tsx (alias resolves but file missing), 'expres' in server.ts (typo of 'express')"`
- **Remediation:** Unresolved imports cause build failures and runtime crashes. AI tools commonly hallucinate package names from training data — especially for popular libraries with multiple variants (`react-icons/fi` vs `react-icons/fa`, `lodash` vs `lodash-es`). Fix each unresolved import:

  ```bash
  # Verify the package exists on npm before installing
  npm view <package-name>

  # If the package is real, add it to package.json
  npm install <package-name>

  # If the package was hallucinated, find the correct name or remove the import
  ```

  For typos, use the editor's "find references" to make sure the wrong name isn't used elsewhere. For workspace packages, ensure the package is declared in the root `workspaces` field.

Taxons: reference-integrity

HTML version: https://auditbuffet.com/patterns/ab-000022