Duolith docs

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's package.json dependencies (not dev dependencies), resolves each from node_modules as Node does (including pnpm's layout) or from its file: 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) or not-installed (E0289). Its overall verdict is the worst of its own and its dependencies'.
  • Findings are read from the text, skipping comments and strings, typeof window guards, properties, and process.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 unsupported or not-installed; web-only passes, since the web build can use it.
  • **A package's browser field is followed** as bundlers follow it: the string form swaps the main file, 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 under replaced. 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.json describes it and the tests check the output against it; add and the build are to read the same shape.

Alternatives considered

OptionWhy not
Bundle each package and test it in each engineNeeds every engine on the machine; slow; the text scan answers most cases at once
A curated list of known packagesThat is the post-v1 public list; it cannot cover a project's own or private packages
Parse every file into a syntax treeMost packages ship minified or transpiled code; the text scan is fast and its known gaps are documented

Consequences

  • A package's react-native field is read like browser: a file it swaps out ships only on the web, so its browser APIs (E0287) do not count. Its exports are followed: a file reached only under node, node-addons, deno, bun or workerd is not shipped. A / after the ) of an if, while, for or with condition 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 exports patterns 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 invalid package.json fails 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.