fix(PD002): false positives on workspace roots — member-declared dependencies reported as transitive-only phantoms

[alamb-hex]

Summary

When scanning a monorepo root, PD002 reports dependencies that are declared directly in a workspace member's package.json as transitive-only phantoms. Declaration appears to be resolved against the root manifest only, while imports are collected from the whole tree — so every workspace-member dependency that is imported in that member's source is flagged.

Version: 1.28.0 · Package manager: pnpm (workspace via pnpm-workspace.yaml)

Minimal reproduction

repro/
├── package.json            { "name": "pd002-repro", "private": true, "version": "1.0.0" }
├── pnpm-workspace.yaml     packages: ["apps/*"]
└── apps/web/
    ├── package.json        { "name": "@repro/web", "dependencies": { "js-yaml": "^4.1.0" } }
    └── src/index.ts        import yaml from 'js-yaml';

pnpm install
cve-lite . overrides --json

Actual

PD002  medium  js-yaml
  js-yaml is imported in source but only present as a transitive dependency - declare it explicitly
  details: Imported in: apps/web/src/index.ts. If the parent package drops or changes this
           dependency, your code will break without warning. Run: pnpm add js-yaml

Expected

No finding. js-yaml is a declared direct dependency of @repro/web, which is the package that imports it.

The suggested remediation (pnpm add js-yaml) would add a redundant second declaration at the root.

The detail line points at the fix

The finding already reports Imported in: apps/web/src/index.ts. So the import's owning workspace is known at the point the finding is produced — it just isn't used to pick which manifest to resolve the declaration against. Resolving against the nearest enclosing workspace member's package.json (falling back to the root) should close this.

Corroborating: scanning the member directly is clean.

cve-lite ./apps/web overrides --json   # 0 findings
cve-lite .            overrides --json # 1 PD002 finding

Real-world impact

On a real 2-app pnpm monorepo (root manifest declares one devDependency; apps/web declares the rest), a root scan produces 11 PD002 findings, all false — next, react, vitest, tailwindcss, @tanstack/react-query, lucide-react, clsx, tailwind-merge, @testing-library/react, @testing-library/jest-dom, @vitejs/plugin-react.

For a dashboard aggregating findings across many repos, that one project dominates the view with noise, which is what led us to filter PD001/PD002 out of our integration entirely rather than lose the signal from the OA rules.

Notes

• The scan notes already say "Monorepo workspace boundaries are only partially modeled in this version" — this is a concrete instance.
• I verified PD002 only. PD001 (override-only phantom) plausibly shares the same declaration-resolution path, but I have not confirmed it.
• Possibly related in spirit: npm: transitives via workspaces or peer deps show "No parent identified" #943, fix: Yarn parser misclassifies dev/prod for workspace and shared dependencies #947, fix: pnpm v9 parser misclassifies dev/prod for packages shared across workspaces #949 corrected workspace attribution for dev/prod classification. The PD rules may need the equivalent treatment.

[sonukapoor]

Thanks for this @alamb-hex - genuinely one of the best bug reports I've seen on this project. The repro, the root-cause diagnosis (resolving against the nearest enclosing workspace member's package.json instead of just the root), the quantified real-world impact, and even flagging the likely PD001 connection - all of that is exactly right and saves a ton of investigation time.

Would you be interested in submitting a fix yourself, or would you rather I take it? Either way works for me - just let me know which you'd prefer.

[alamb-hex]

@sonukapoor I will dive into it deeper, something that surfaced while doing some integration work

[alamb-hex]

Second, independent defect on the same code path: type-only imports counted as runtime imports

Filing this here rather than separately — it is a different defect, but it lands on the same comparison in the PD detectors, so the two are best fixed together.

for (const [pkgName, files] of ctx.importedPackageNames)   // <- defect B, below
  if (declared.has(pkgName)) continue;                     // <- defect A, this issue

A (this issue): declared is resolved against the root manifest instead of the enclosing workspace member.
B (below): importedPackageNames contains references that were never runtime imports.

They are independent — fixing A leaves every finding below in place, because none of the affected projects is a workspace.

---

B — scanAllImports collects JSDoc import() type annotations

Version 1.29.0.

A stock Next.js + Tailwind 3 postcss.config.mjs, exactly as create-next-app and the Tailwind docs emit it:

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: { tailwindcss: {}, autoprefixer: {} },
};
export default config;

That annotation is the only occurrence of the string in the repo:

$ grep -rn "postcss-load-config" --include=*.mjs . | grep -v node_modules
postcss.config.mjs:1:/** @type {import('postcss-load-config').Config} */

It is erased at compile time — nothing loads the package at runtime. In the projects observed it is not even type-checked: checkJs is unset and tsconfig.include covers **/*.ts / **/*.tsx, not .mjs. It exists purely for editor intellisense.

postcss-load-config reaches the tree as a transitive dependency of tailwindcss 3, and whether an override entry happens to exist decides which rule reports it:

override present	rule	severity
yes	PD001	high
no	PD002	medium

Same phantom import, two rules, two severities. Note this means B also affects PD001, which A does not touch.

Scope, measured

From a 34-project sweep on 1.29.x:

tailwind	postcss-load-config in tree	result
3.x	yes, + override	PD001 high (3 projects)
3.x	yes, no override	PD002 medium (1 project)
4.x	no	clean (18 projects)

21/21 predicted correctly once the pattern was identified. Tailwind 4 is unaffected only because @tailwindcss/postcss does not depend on postcss-load-config, so PD002's if (!ctx.lockfilePackageNames.has(pkgName)) continue guard suppresses it — incidental, since it fires on the package being absent rather than on the reference being type-only.

All four affected projects are single-package (no pnpm-workspace.yaml members), so defect A cannot account for any of them.

Suggested fix

Exclude type-only references when building importedPackageNames:

• JSDoc @type / @param / @returns containing import('pkg')
• TS import type { X } from 'pkg' and import { type X } from 'pkg' (same collection path; not separately verified)

A package referenced only in type position is a devDependency question at most, never a runtime phantom — and certainly not high.

Not affected

Both true-positive PD002 findings in the same sweep were verified as genuine runtime imports and are correct: an undeclared vfile, and an undeclared jszip reached through a dynamic await import('jszip'). Import detection is otherwise working well, dynamic imports included.