feat(releasekit): graph based licensing

[yesudeep]

feat(releasekit): Graph-based license compatibility checking

Summary

Adds a complete license compliance subsystem to ReleaseKit — from SPDX
expression parsing through compatibility graph evaluation to interactive
CLI-driven remediation. This is the foundation for the releasekit licenses
command that checks every dependency's license against the project license
and reports incompatibilities with Rust-style diagnostics.

---

What's New

SPDX Expression Parser (spdx_expr.py)

Full parser per SPDX Specification 3.0.1 Annex B:

• Tokenizer + recursive-descent parser producing an AST
• Supports AND, OR, WITH (exception) operators
• LicenseRef-* custom identifiers
• + (or-later) suffix on standard license IDs
• evaluate(project_license, dep_license, graph) compatibility check

License Data (data/)

File	Contents
licenses.toml	167 SPDX licenses with name, category (permissive / weak-copyleft / strong-copyleft / network-copyleft / source-available / proprietary), Google licenseclassifier category, OSI approval status, aliases, patent grant/retaliation flags
license_compatibility.toml	42 directed compatibility rules (edge A → B = code under A can depend on code under B) sourced from GNU, Wikipedia, SPDX spec

License Modules (checks/)

Module	Purpose
_license_graph.py	Loads TOML data into a directed adjacency-set graph; answers is_compatible(project, dep) queries
_license_tree.py	Builds per-package dependency trees with license status (ok, incompatible, denied, no_license, unresolved, exempt); renders Rust-style diagnostics
_license_detect.py	Extracts license strings from manifests across 7 ecosystems (Python, JS, Rust, Go, Dart, Java/Maven, Bazel)
_license_fetch.py	Async fetcher for canonical LICENSE file text from SPDX GitHub + source repos
_license_lookup.py	Async registry lookup (PyPI, npm, crates.io, Maven Central, pub.dev, pkg.go.dev) with disk-backed JSON cache
_license_resolve.py	5-stage fuzzy SPDX resolver: exact → alias → normalized → prefix → Levenshtein
_license_fix.py	Interactive fixer for --fix mode: exempt, allow, deny, override, skip — writes to releasekit.toml with comment preservation via tomlkit
_lockfile.py	Parses uv.lock to extract transitive dependency graphs

Workspace Backends (backends/workspace/)

New workspace discovery backends for lockfile-based dependency resolution:

Backend	Ecosystem
uv.py	Python (uv workspace)
pnpm.py	JavaScript (pnpm workspace)
cargo.py	Rust (Cargo workspace)
go.py	Go modules
dart.py	Dart/Flutter (pub workspace)
maven.py	Java/Kotlin (Maven reactor)
bazel.py	Bazel
clojure.py	Clojure (Leiningen)

CLI Integration (cli.py)

• New releasekit licenses subcommand with full argument parser
• --fix flag triggers interactive license remediation
• --dry-run previews changes without writing
• --workspace filters to a specific workspace
• Collects LicenseTree objects across workspaces, merges, and renders

Config (config.py)

New [license] section in releasekit.toml:

• project — project SPDX license (e.g. Apache-2.0)
• allow_licenses — globally allowed SPDX IDs
• deny_licenses — globally denied SPDX IDs
• exempt_packages — packages to skip
• [license.overrides] — manual SPDX overrides per package

---

Test Coverage

712 tests across 12 test suites:

Test Suite	Tests	What It Covers
rk_spdx_expr_test.py	~100+	Tokenizer, parser, AST evaluation, edge cases
rk_license_graph_test.py	~150+	Graph loading, compatibility queries, categories
rk_license_tree_test.py	~170+	Tree building, status assignment, diagnostic rendering
rk_license_compat_test.py	~130+	End-to-end compatibility matrix
rk_license_detect_test.py	~80+	Manifest extraction across all ecosystems
rk_license_fetch_test.py	~80+	Async fetch with mocked HTTP
rk_license_lookup_test.py	~70+	Registry lookup with disk cache
rk_license_resolve_test.py	~40+	5-stage fuzzy resolver
rk_license_fix_test.py	35	Interactive fixer, TOML writing, dry-run
rk_license_advanced_test.py	~50+	Complex SPDX expressions, dual-licensing
rk_license_data_integ_test.py	~30+	Data file integrity, cross-references
rk_lockfile_test.py	~50+	uv.lock parsing, transitive closure

---

Documentation

• Compliance guide — new "Interactive License Fix" section with quick start, actions table, example session, resulting config
• Slides — new "Demo: Interactive License Fix" slide with terminal mockup
• Roadmap — "AI-Powered License Guidance (Genkit Integration)" section for future ai.generate() + SPDX web lookup
• Internals — license-data.md documenting the data model and sources
• Competitive gap analysis — updated with license checking capabilities
• GEMINI.md — updated development guidelines

Scripts

• scripts/verify_license_data.py — validates licenses.toml and license_compatibility.toml cross-references
• py/bin/check_license_coverage.py — reports license coverage across the workspace
• py/bin/fix_missing_class_docstrings.py — AST-based fixer for missing class docstrings (D101)

---

Architecture

spdx_expr.py                    ← SPDX expression parser (AST)
    │
    ▼
checks/_license_graph.py        ← Compatibility graph (167 licenses, 42 rules)
    │
    ├── checks/_license_detect.py   ← Extract license from manifests (7 ecosystems)
    ├── checks/_license_lookup.py   ← Async registry lookup with disk cache
    ├── checks/_license_resolve.py  ← 5-stage fuzzy SPDX resolver
    ├── checks/_license_fetch.py    ← Fetch canonical LICENSE text
    │
    ▼
checks/_license_tree.py         ← Build dependency tree + assign status
    │
    ├── checks/_lockfile.py         ← Parse uv.lock for transitive deps
    │
    ▼
checks/_license_fix.py          ← Interactive fixer (--fix mode)
    │
    ▼
cli.py                          ← `releasekit licenses [--fix] [--dry-run]`

---

Testing

# Run all license tests (712 tests)
cd py/tools/releasekit
uv run pytest tests/rk_license_*_test.py tests/rk_lockfile_test.py tests/rk_spdx_expr_test.py -v

# Verify data file integrity
uv run python scripts/verify_license_data.py

[gemini-code-assist]

Summary of Changes

Hello @yesudeep, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces core functionality for handling and evaluating software licenses within ReleaseKit by implementing a comprehensive SPDX license expression parser. This foundational component allows the system to understand and process complex license strings, paving the way for advanced license compatibility checks, including those that will leverage a license compatibility graph. Additionally, the documentation slides were updated by removing an outdated comparison table.

Highlights

• SPDX License Expression Parser: A new module _spdx_expr.py has been added to releasekit.checks that provides a robust parser for SPDX license expressions, conforming to SPDX Specification 3.0.1 Annex B. This parser converts license strings into an Abstract Syntax Tree (AST).
• License Expression AST: The parser defines distinct AST node types (e.g., LicenseId, LicenseRef, With, And, Or) to represent the structure and logic of complex SPDX license expressions, enabling programmatic evaluation.
• License Compatibility Evaluation: Functions license_ids and is_compatible are included to extract individual license identifiers from an AST and to evaluate the compatibility of a given license expression against a project's license, laying the groundwork for graph-based license checks.
• Documentation Update: A 'vs. Alternatives' comparison table has been removed from the index.html slides documentation, streamlining the presentation.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• py/tools/releasekit/docs/docs/slides/index.html
  • Removed a comparison table detailing ReleaseKit's capabilities against alternative release tools.
• py/tools/releasekit/src/releasekit/checks/_spdx_expr.py
  • Added a new Python module for parsing SPDX license expressions into an Abstract Syntax Tree (AST).
  • Implemented AST node types for LicenseId, LicenseRef, With, And, and Or expressions.
  • Included tokenizer and recursive descent parser logic for SPDX expressions.
  • Provided utility functions to collect license IDs and evaluate license compatibility based on the parsed AST.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new SPDX license expression parser, which is a crucial component for license compliance checks. The implementation is robust, well-documented, and follows good practices for parsing, including a clear separation of tokenizing and parsing logic, and immutable AST nodes. I have one suggestion to improve the future compatibility evaluation logic by ensuring the or_later flag is correctly propagated. The removal of the 'vs. Alternatives' section from the presentation slides is a straightforward content update. Overall, this is a high-quality contribution.

[yesudeep]

/gemini review

[gemini-code-assist]

Code Review

This is an impressive and comprehensive addition for graph-based license management. The new functionality is well-structured across several new modules for detection, resolution, graph management, and fixing, which is great for maintainability. The use of performance optimizations like lru_cache and trigram similarity for fuzzy matching is well-thought-out. The documentation updates are also thorough. I have one high-severity comment regarding the use of regex for parsing XML in maven.py, which could be made more robust.

[yesudeep]

/gemini review

[gemini-code-assist]

Code Review

The pull request introduces a comprehensive graph-based licensing subsystem to ReleaseKit, enabling SPDX expression parsing, compatibility checking, and interactive remediation. The changes include new modules for license detection, fetching, lookup, and resolution, along with new workspace backends for various ecosystems. Documentation and test coverage have been significantly expanded to support these new features. The changes are well-structured and address a critical aspect of software supply chain compliance.

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.