0073. duolith scan gives each npm dependency a verdict for the targets
- Status: Proposed
- Date: 2026-11-14
- Decided by: production adapters agent, pending the integrator
- Planning item: Roadmap milestone 3, "npm compatibility scanner"; domain map, Modules context ("the compatibility verdict")
Context
An app runs on the web, iOS and Android. A package from npm may use Node's built-in modules (no target has them), the DOM (only the web has it) or a native addon (no target loads one). People need to know before they depend on it. The public compatibility list is after version 1 (post-v1, item 40); the scanner is in version 1.
Decision
- **
duolith scan [project] [--json]** reads the project'spackage.jsondependencies(not dev dependencies), resolves each fromnode_modulesas Node does (including pnpm's layout) or from itsfile:path, and follows their dependencies, never outside the project folder. - Each package gets a verdict:
everywhere,web-only(browser APIs, E0287),unsupported(Node modules E0285, Node globals E0286, native addons E0288) ornot-installed(E0289). Itsoverallverdict is the worst of its own and its dependencies'. - Findings are read from the text, skipping comments and strings,
typeof windowguards, properties, andprocess.env.NODE_ENV; a Node module that also exists as an installed npm package (events,buffer) is not counted. Each finding names the feature, the first file and line, and how many uses. - The command fails when a direct dependency is
unsupportedornot-installed;web-onlypasses, since the web build can use it. - **A package's
browserfield is followed** as bundlers follow it: the string form swaps themainfile, and the object form swaps files and modules, for another or (false) for nothing. What it swaps out is not shipped, so its uses do not count; the swaps are listed underreplaced. This assumes Duolith's bundler honours the field on every target, which the toolchain must confirm. - The JSON output (
ok,targets,packages) lists one module manifest per package: name, version, licence, direct, verdict, overall,targets(web, iOS and Android as booleans), findings, dependencies and replaced.spec/schemas/module.schema.jsondescribes it and the tests check the output against it;addand the build are to read the same shape.
Alternatives considered
| Option | Why not |
|---|---|
| Bundle each package and test it in each engine | Needs every engine on the machine; slow; the text scan answers most cases at once |
| A curated list of known packages | That is the post-v1 public list; it cannot cover a project's own or private packages |
| Parse every file into a syntax tree | Most packages ship minified or transpiled code; the text scan is fast and its known gaps are documented |
Consequences
- A package's
react-nativefield is read likebrowser: a file it swaps out ships only on the web, so its browser APIs (E0287) do not count. Itsexportsare followed: a file reached only undernode,node-addons,deno,bunorworkerdis not shipped. A/after the)of anif,while,fororwithcondition starts a regular expression; after any other)it divides (wave 5, domain F). - Known gaps: a file reached from an exported file by a relative import is not followed through the conditions, and wildcard
exportspatterns are not expanded. Code inside template literals'${}, minified imports and regular expressions elsewhere are read, and the walk keeps its own stack, so no nesting can overflow it. - What is not read is said (E0290, verdict
unchecked): a script over 2 MB or more than 4000 scripts make the package not fully checked, which fails the scan for a direct dependency. Links are followed when they lead inside the project, each folder once. An invalidpackage.jsonfails the command; a missing one is reported as nothing to scan. - The module manifest schema is a new contract (
docs/plan/contracts.md), proposed with this record and pending the integrator's approval.