Skip to content

Code Quality and Compliance

This project uses Ruff for linting and formatting, Mypy for static type checking, Bandit for SAST, pip-audit for dependency vulnerability checks, and REUSE for open-source licensing compliance.

Linting and type checks run automatically in CI on pull requests against the main branch via .github/workflows/lint.yml. Security and package compliance checks are additionally enforced through .github/workflows/quality-gates.yml and .github/workflows/security-pr.yml.

Manual usage for developers

Install development dependencies from the committed lockfile:

uv sync --frozen --all-extras --dev

Then run the local quality checks:

  • Check formatting and linting errors: uv run ruff check .
  • Auto-fix and format code: uv run ruff check --fix . && uv run ruff format .
  • Run static type validation: uv run mypy

mypy uses the default files target from [tool.mypy] in pyproject.toml, which is currently src. Avoid mypy ., because it can pull in packaging setup.py scripts under packages/ and produce duplicate-module noise. To include tests explicitly, run:

mypy src tests

Pre-commit hooks

You can attach .pre-commit-config.yaml so checks run before each commit:

pre-commit install

To run all configured hooks across the repository:

pre-commit run --all-files

The current pre-commit setup includes Ruff, Ruff formatting, Mypy, and Bandit.

This repository enforces open-source licensing compliance using REUSE. First-party files should contain the appropriate SPDX copyright and license headers.

Verify compliance

uv pip install reuse
uv run reuse lint

Add missing headers

If reuse lint reports missing headers, you can apply the repository header template with:

bash scripts/add-license-headers.sh

Dependency lockfile

uv.lock is the source of truth for CI and local development installs. CI uses uv sync --frozen --all-extras --dev, which refuses to resolve new versions and verifies package hashes from the lockfile.

Update workflow

  1. Edit dependency declarations in pyproject.toml.
  2. Regenerate the lockfile: uv lock
  3. Verify freshness: uv lock --check
  4. Commit both pyproject.toml and uv.lock.

DEPENDENCIES.md is a human-readable license inventory (from pip-licenses). sbom.json is a CycloneDX SBOM generated by the compliance script (scripts/run-compliance-checks.sh) and at release time via .github/workflows/github-release.yml.

Dependency inventory and compliance

To maintain an open-source compliant dependency set, the repository tracks third-party packages and their licenses in DEPENDENCIES.md.

License classification criteria

  • Safe (permissive): MIT, Apache-2.0, BSD, PSF. Safe for the Apache-2.0 release.
  • Needs review: Custom or uncommon licenses that require manual review.
  • Risky (copyleft): GPLv2, GPLv3, AGPL. Not allowed in the runtime application. They may be acceptable only for isolated, non-distributed development tooling.

Update the inventory and run compliance checks

When adding dependencies or preparing a release, run the unified compliance script:

bash scripts/run-compliance-checks.sh

That script:

  1. Syncs the locked environment (uv sync --frozen --all-extras --dev).
  2. Regenerates DEPENDENCIES.md.
  3. Generates sbom.json (CycloneDX SBOM).
  4. Runs Bandit for static application security testing.
  5. Runs pip-audit for dependency vulnerability scanning.