licensefile

A repository can only ship what its dependencies' licenses allow. licensefile takes the repository's own license and a list of its dependencies, and turns that into a single catalog you can act on:

• Inventory — one entry per dependency, sorted by name, with the license normalized (trimmed; a missing or empty license becomes unknown) and absent version, author, or homepage carried as null

• Counts by license — how many dependencies carry each normalized license, sorted by count descending with ties broken by license name

• Attribution lines — one line per dependency in name order, shaped name@version — license — author, where a missing version reads unknown and the author segment is left off entirely when no author was supplied

• Flags — at most one per dependency, from the first matching rule: an unknown license warns; a strong-copyleft license whose family (GPL vs AGPL) differs from the repository license's family is an error; a weak-copyleft license in a permissive-licensed repository draws a notice; and a license belonging to none of the known classes, when it is not the repository's own license, is reported as unclassified

• Verdict — blocked when any flag is an error, otherwise ok

License classes are the exact, case-sensitive SPDX ids in the spec: a permissive set (MIT, ISC, the BSD clauses, Apache-2.0, and friends), a strong-copyleft set (the GPL and AGPL variants), and a weak-copyleft set (the LGPL variants, MPL-2.0, EPL, EUPL-1.2). Everything is computed locally from the inputs: no network, no configuration, and no license database is consulted. Invalid input — a missing repository license, an empty dependency list, a dependency without a name, a duplicate name, or a wrongly typed field — is rejected with an error naming the offending path, and no partial catalog is produced.

CLI

npx @reneturcios/licensefile catalog --input args.json
npx @reneturcios/licensefile --version

args.json contains the full arguments object:

{
  "repo_license": "MIT",
  "dependencies": [
    { "name": "alpha", "version": "1.0.0", "license": "MIT", "author": "Ann Example" },
    { "name": "beta", "version": "0.2", "license": "LGPL-2.1-only" },
    { "name": "gamma", "license": "GPL-3.0-only" }
  ]
}

version, license, author, and homepage are optional per dependency. The catalog is printed as JSON.

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

Related MCP server: CodeVitals

MCP server

npx -y @reneturcios/licensefile mcp

MCP client config:

{
  "mcpServers": {
    "licensefile": {
      "command": "npx",
      "args": ["-y", "@reneturcios/licensefile", "mcp"]
    }
  }
}

Tools

• catalog_licenses — Build a dependency license and attribution inventory for a repository.

  • repo_license (string, required) — SPDX id of the repository's own license, e.g. MIT

  • dependencies (array, required, at least one) — dependencies as {name, version?, license?, author?, homepage?} objects; name is required and must be unique

  Returns {repo_license, dependency_count, inventory, by_license, flags, attribution_lines, verdict}.

Docker

docker run -i ghcr.io/cloudcorprecords/licensefile
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/licensefile catalog --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios