convez.ai
Skill
shcherbak-ai

licenseal

shcherbak-ai/licenseal

Ver no GitHub
BomPluginScore · de 0 a 100

Fast cross-ecosystem dependency license compatibility checker + Claude Code review skill

Instalação

$npx convez-ai shcherbak-ai/licenseal

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
15
Forks
0
Acompanhando
1
Saúde
62%
Último commit
há 1 semana
Versão
v1.0.3
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

licenseal is a fast license compatibility checker for dependency trees across language ecosystems. It makes that compliance check cheap enough to run in CI: scan manifests, lockfiles, and public registry metadata, then tell you whether your dependency licenses are compatible with the license you ship under. It does not install dependencies, run package-manager commands, execute build scripts, or download package archives.

uvx licenseal check

Not legal advice. licenseal automates dependency-license discovery and compatibility classification. It is a CI/audit aid, not a substitute for legal review.

🧭 Why This Matters

License non-compliance is a quiet delivery risk: it usually does not break the build, but it can block a shipment, customer approval, funding round, or acquisition when discovered late. The problem usually surfaces when a customer, investor, legal reviewer, or procurement team asks what is inside your dependency tree:

BlockerWhat can happen
Enterprise adoptionSecurity and procurement teams ask for an open-source license report before approval.
Due diligenceInvestors, acquirers, or partners flag copyleft, source-available, or unknown-license dependencies late.
Release timingA problematic dependency forces a replacement, upgrade, or architecture change when the team is trying to ship.
Hidden transitivesThe risky license is several levels down, pulled in by a package that looked harmless.
Product obligationsGPL, AGPL, SSPL, BUSL, Elastic, non-commercial Creative Commons, and similar terms may be incompatible with how you distribute or host the product.
Audit trailReview decisions need to be explicit and checked in, not buried in a spreadsheet or chat thread.

licenseal turns that hidden risk into fast CI feedback: it scans the transitive dependency tree, flags compatibility issues, and records reviewed decisions for cases that need human judgment. It is designed for PR gates, using manifests, lockfiles, and registries without install or build steps.

[!IMPORTANT] In a benchmark of 50 widely used open-source repositories across ten ecosystems, licenseal flagged 485 license-compatibility issues at default settings — 405 warnings and 80 outright violations, spanning 9 of the 10 ecosystems — each a dependency whose license needed compatibility review against the project's own declared license. Inventory-only license tools surface none of these.

Public engineering policies and case history show why dependency-license checks matter. Google and Power publish restrictive guidance for licenses such as AGPL and SSPL, while Salesforce and Uber have written about license review in production software governance. GPL enforcement cases such as Artifex v. Hancom and Software Freedom Conservancy v. Vizio also show that dependency-license obligations can become real delivery and legal risk.

⚙️ How It Works

1. Read2. Resolve3. Classify4. Report
Manifests and lockfilesTransitive dependency tree plus public registry license metadataProject license vs dependency license compatibilityCI verdict, Markdown/JSON report, and checked-in review overrides

🚀 Quick Start

Install-free one-shot:

uvx licenseal check

Persistent install:

uv tool install licenseal
# or
pipx install licenseal

Inside a Python project:

uv add --dev licenseal
# or
pip install licenseal

Example output:

licenseal terminal output showing a transitive dependency table, one weak-copyleft warning, and a reviewed dependency count

The exit code is non-zero when there are unreviewed violations, warnings, unknown licenses, or analysis gaps. See USAGE.md for every flag and report format.

🤖 Claude Code Review Skill

CI can tell you which dependency licenses need attention; the bundled Claude Code skill helps turn those findings into documented decisions. Install it in the project being audited, then run /licenseal-review in Claude Code:

licenseal install-skill

The skill runs licenseal check, walks through warnings, violations, unknown licenses, and analysis gaps, and asks verdict-aware questions based on how your project is distributed, hosted, modified, or shipped. It fills licenseal.review.toml only when there is a concrete reviewable rationale, keeps genuine incompatibilities flagged, and re-runs the strict scan so the remaining compliance gaps are explicit.

Claude Code licenseal review skill asking whether MPL dependencies were modified before marking them reviewed

✨ What Licenseal Does

Compatibility verdictChecks dependencies against your project license.Transitive by defaultFinds risks several levels down.Install-freeReads manifests, lockfiles, and registries only.
Agent-assisted reviewClaude Code skill investigates flagged findings and asks verdict-aware questions.Cross-ecosystemOne scan for polyglot repos.CI-ready speedSeconds-scale scans in benchmark runs, with strict exits and JSON/Markdown output.

🌐 Supported Ecosystems

Python npm Rust Go Java .NET PHP Ruby Elixir/Erlang R

Supported registries include PyPI, npm, crates.io, deps.dev, proxy.golang.org, Maven Central, NuGet.org, Packagist, RubyGems, Hex, and CRAN. See USAGE.md for manifest and lockfile details.

📊 How It Compares

Comparison last reviewed: June 2026. Tool capabilities change; check each project before making a buying or compliance decision.

CI license-compatibility workflow

Capabilitylicensealpip-licenseslicense-checkerLicenseFinderfossa-cli
Project-license compatibility verdict✓--~~
Transitive discovery before install✓---~
No successful install/restore required✓---~
No dependency install/build step✓---~
Fast, seconds-scale CI path✓~~--
Agent-assisted flagged-finding review✓----
Manual review override file✓-~✓~

Coverage and artifacts

Capabilitylicensealpip-licenseslicense-checkerLicenseFinderfossa-cli
Multiple ecosystems in one tool✓ (10)--✓✓
Dependency license report✓✓✓✓✓
Local-only full workflow, no hosted service✓✓✓✓-
Offline operation-✓✓~-
Standards SBOM export (CycloneDX / SPDX)----✓

✓ supported · ~ partial · - not supported

No tool clears every row. The discovery rows are about source-tree analysis: manifests, lockfiles, and registry metadata before a successful package-manager install is assumed. Some tools can produce broader inventories after installation or hosted analysis; licenseal is optimized for transitive dependency coverage in CI without that prerequisite. ~ means the capability exists, but with a different workflow, hosted service, package-manager prerequisite, or policy model. The speed row reflects benchmark runs on public repositories, not a vendor guarantee. Pair licenseal with an SBOM generator, hosted compliance platform, or installed-metadata scanner when those are the artifacts or workflows you need.

🧰 Important Defaults

DefaultMeaning
--transitiveScans the transitive dependency tree by default. Use --no-transitive for direct deps only.
--no-devDev dependencies are excluded unless --dev is set.
--strictWarnings, unknowns, and analysis gaps fail CI in addition to violations.
Violations always fail--no-strict demotes warnings, unknowns, and gaps only; definite incompatibilities still fail.
Missing project license -> ProprietaryIf no project license is detected, licenseal labels the project Proprietary and checks dependencies as if it were permissively licensed — copyleft dependencies are still flagged, so the default errs strict, not lenient.
Registry-only resolutionNo installs, builds, package archive downloads, or source-prose license extraction.

🎯 Scope

licenseal is intentionally narrow:

  • It is a license compatibility checker, not a legal approval workflow or policy-exception manager.
  • It checks published dependency license metadata, not vulnerability status, provenance, or SBOM completeness.
  • It reads manifests, lockfiles, and public registry metadata endpoints only. It does not honor private registry declarations from scanned manifests, because that would expand the network trust boundary.
  • It does not infer dependency licenses by pattern-matching local LICENSE files or source comments. Free-form license text is easy to misread, spoof, or partially match; missing structured metadata is reported as UNKNOWN and routed to manual review instead.
  • It produces Markdown/JSON dependency license reports, but not standards-compliant CycloneDX or SPDX SBOMs; use a dedicated SBOM tool when you need that artifact.
  • Manual review can override flagged findings when a maintainer has better information, but the review file is an audit record, not hidden legal sign-off.

The full trust boundary and network allowlist are documented in SECURITY.md.

✅ CI Integration

GitHub Actions:

# .github/workflows/licenseal.yml
name: License compatibility
on: [push, pull_request]
jobs:
  licenseal:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v6
      - run: uvx licenseal check

README badge:

[![License compatibility](https://github.com/OWNER/REPO/actions/workflows/licenseal.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/licenseal.yml)

Preview:

License compatibility badge preview

Use the workflow status badge as the primary signal: it shows that license compatibility is checked in CI and that the latest run passed.

For a PR comment or audit artifact, write Markdown or JSON. The file is saved before the gate runs, so CI can publish it even on a failing check:

licenseal check -f markdown -o LICENSES.md   # PR-comment-friendly audit
licenseal check -f json -o report.json       # stable machine-readable schema

For projects that want a checked-in audit trail, commit the generated Markdown report as LICENSES.md. This repository follows that convention in LICENSES.md.

The JSON schema is documented in JSON_OUTPUT.md.

🧾 Manual Review Overrides

When a dependency is flagged but you have better license information than the resolver, record the reviewed license in a checked-in licenseal.review.toml:

[[review]]
ecosystem = "python"
package = "mystery-lib"
version = "1.0.0"
license = "MIT"
note = "reviewed packaged LICENSE file"

Workflow:

licenseal check -f json -o report.json                       # 1. capture flagged deps
licenseal init-review-file --from-report report.json         # 2. scaffold blank entries offline
# 3. fill in `license` and optional `note` for each entry
licenseal check                                              # 4. overrides apply

Reviews can only override flagged dependencies, never compatible ones. A reviewed dependency passes strict mode while staying visible in its warning, violation, or unknown bucket with both the detected and reviewed licenses shown.

licenseal also ships a Claude Code skill (licenseal install-skill, then /licenseal-review) that walks through unknowns, warnings, and violations interactively. It can inspect package links, license links, and project context, then ask the questions that matter for how your software is distributed, hosted, or modified. Full review rules are in USAGE.md.

🧩 How Licenseal Decides

licenseal classifies each dependency license into a risk level and compares that risk against the detected project license.

Project \ DependencyPermissiveWeak CopyleftStrong CopyleftNetwork Copyleft
PermissiveOKWarningViolationViolation
Weak CopyleftOKOKViolationViolation
Strong CopyleftOKOKOKWarning
Network CopyleftOKOKOKOK

Pair-level overrides strengthen the matrix where two licenses share a cell but are documented as legally incompatible: GPL-family version conflicts (a GPLv3-family dependency — GPL-3.0-*, LGPL-3.0-*, AGPL-3.0-* — in a GPL-2.0-only project, or a GPL-2.0-only dependency in a GPL-3.0-* / AGPL-3.0-* project), Apache-2.0 in a GPL-2.0-only project, and FSF-documented GPL-incompatible weak copyleft (EPL-1.0, CDDL-*, MPL-1.1) in any GPL-family project are all violations; EPL-2.0 in a GPL-family project is a warning, because its GPL compatibility depends on a secondary-license designation that package metadata cannot reveal. -or-later forms are exempt where the upgrade clause resolves the conflict, and an OR expression escapes when a conflict-free arm is electable.

A dual-licensed project (e.g. AGPL-3.0-only OR Proprietary) is checked against the strictest of its arms: dependencies must be compatible with every license the project distributes under, so the commercial arm of an open-core project still flags copyleft dependencies.

When --dev is set, copyleft violations on dev dependencies are downgraded to warnings — licenseal treats dev deps as lower risk because they usually do not ship with the project.

Risk levelExamplesMeaning
PermissiveMIT, BSD, Apache-2.0, ISCNo significant restrictions
Weak CopyleftLGPL, MPL-2.0, EPL, CDDL, GPL with Classpath exceptionFile-scope reciprocity; linking from other files is usually allowed
Strong CopyleftGPL, OSL, EUPL, CC-BY-SAShare-alike obligations can extend to the derivative work
Network CopyleftAGPL-3.0-onlyStrong copyleft with network-use source-offer obligations
UnknownSSPL, BUSL, Elastic, CC-BY-NC; missing or unrecognized licensesCannot be auto-classified; routed to manual review

A dependency is Unknown when the registry returns no license, a non-SPDX string, or a source-available / use-restricted license (SSPL, BUSL, Elastic, FSL, Parity, PolyForm, CC-BY-NC* / CC-BY-ND*) whose custom terms are not auto-evaluated. The full matrix rationale is in USAGE.md.

Learn More

  • USAGE.md - full CLI reference, transitive-resolution behavior, per-ecosystem detail, review-file rules, and the Claude Code skill
  • SECURITY.md - the manifest-and-registry trust boundary and exact network-egress allowlist
  • JSON_OUTPUT.md - stable machine-readable schema

Contributing

See CONTRIBUTING.md for development setup and guidelines.

If licenseal helps your project, star ⭐ this repo to help other teams find it too.

License

Apache-2.0. See LICENSE for the full text and NOTICE for attribution.

More from shcherbak_ai

ProjectWhat it does
💎 ContextGemStructured extraction from documents with LLMs.
🪁 tetheredNetwork egress control for CLI tools and agent workflows.

Connect

Questions or collaboration ideas? Reach out on LinkedIn or X.

Built with ❤️ in Oslo, Norway.

Ver o original no GitHub

Bom para

Relacionados