⚖️ licensescan

Fast dependency-license triage for Node projects. Classify every installed package's license and flag copyleft / unknown risk for your project's license type — in one command, with no dependencies.

⚠️ Not legal advice. This is a triage tool to surface risks early so you know what to look at. For anything that matters, confirm with a human who reads licenses.

npx @velkina/licensescan

Why

When you ship — commercial or open source — a single GPL/AGPL dependency buried 4 levels deep in node_modules can have real consequences. Most teams never look until it's a problem. licensescan reads the license of every installed package, sorts them into categories, and tells you which ones need a human's eyes given what you're building.

Usage

licensescan                              # scan ./ as a proprietary project
licensescan ./my-app --kind permissive-oss
licensescan --json                       # machine-readable
licensescan --fail-on high               # exit 1 if any dep is high-risk (CI gate)

--kind tells the tool what you're shipping, which changes what counts as risky:

--kind	meaning	what gets flagged
proprietary (default)	closed-source / commercial	strong copyleft = high, weak copyleft = review
permissive-oss	MIT/Apache-style OSS	strong copyleft = high
copyleft-oss	GPL/AGPL OSS	copyleft is fine; only unknown needs review

Example:

licensescan  239 dependencies  ·  project: proprietary

  ▲ @img/sharp-win32-x64@0.34.5   Apache-2.0 AND LGPL-3.0-or-later (weak-copyleft)
  ▲ gsap@3.15.0                   Standard 'no charge' license… (unknown)
  ▲ webgl-constants@1.1.1         (none declared) (unknown)

  236 ok  ·  3 review  ·  0 high-risk

Categories

• permissive — MIT, ISC, Apache-2.0, BSD… safe almost anywhere.
• public-domain — CC0, Unlicense, 0BSD.
• weak-copyleft — MPL, LGPL, EPL. File/library-level obligations; usually fine if you don't modify the library.
• strong-copyleft — GPL, AGPL. Viral into your codebase — the ones to watch in closed-source.
• unknown — missing or non-SPDX license. Always needs a human.

It handles SPDX expressions: MIT OR GPL-3.0 is treated as permissive (you may pick MIT); MIT AND GPL-3.0 is governed by the stricter term.

Library

import { scanProject, classify, riskFor } from "@velkina/licensescan";

const { deps, summary } = await scanProject("./", { projectKind: "proprietary" });
summary.byRisk;           // { ok, review, high }
classify("AGPL-3.0");     // "strong-copyleft"
riskFor("strong-copyleft", "proprietary"); // "high"

Tests

npm test — 12 tests covering classification (incl. OR/AND expressions), the three license-field shapes, the risk matrix, and end-to-end scanning of a tree with nested non-hoisted deps.

Limitations (honest)

• Reads the declared license field in each package.json. It does not read LICENSE file text, detect mismatches between the field and the actual file, or handle every exotic SPDX id (unrecognized ids → unknown, the safe default — they get flagged).
• Scans installed node_modules (run your install first), including nested non-hoisted deps. It doesn't resolve the full registry graph itself.
• Dual licenses (A OR B) are reported as the most permissive option, since you may choose it — but a choice exists and may need recording. A AND B is governed by the stricter term.
• The copyleft-oss mode is a simplification: GPL/LGPL/MPL/AGPL and their version constraints are not freely interchangeable. If you ship a copyleft project, confirm the specific combinations.
• Triage, not compliance certification. Not legal advice.

License

MIT © Velkina (Ömer Can Nalbant, Baha Taşkın)