|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## What this is |
| 6 | + |
| 7 | +`trivy-py-ecc` is a **pip-installable wrapper around the [Trivy](https://trivy.dev/) binary**. It contains |
| 8 | +no application source code — at install time, `setuptools-download` fetches the correct pre-built Trivy |
| 9 | +binary for the host platform and installs it as a console entry point named `trivy` (`trivy.exe` on Windows). |
| 10 | +It doubles as a [pre-commit](https://pre-commit.com) hook provider (`trivy-fs`, `trivy-config`). |
| 11 | + |
| 12 | +The package is published under the eccenca org but mirrors upstream `trivy-py` (by asottile). Recent commits |
| 13 | +merge from `upstream/main`. |
| 14 | + |
| 15 | +## Architecture |
| 16 | + |
| 17 | +The entire mechanism lives in two declarative files — there is no runtime Python logic to read: |
| 18 | + |
| 19 | +- **`setup.cfg`** — the heart of the project. The `[setuptools_download]` section declares one `[trivy]` |
| 20 | + download entry per platform (Linux x86_64/aarch64/armv7l, macOS arm64/x86_64, Windows). Each entry pins a |
| 21 | + release `url`, a `sha256` checksum, and an `extract_path`. The `marker` lines select which binary installs |
| 22 | + on a given platform. The package version in `[metadata]` (e.g. `0.70.0.1`) encodes the wrapped Trivy |
| 23 | + version `0.70.0` plus a wrapper revision suffix. |
| 24 | +- **`setup.py`** — only customizes wheel building: a `bdist_wheel` subclass marks the wheel as non-pure |
| 25 | + (platform-specific) and rewrites `linux` platform tags to `manylinux2014` for PyPI compatibility. The |
| 26 | + `py2.py3` / `none` tag reflects that the wheel carries a binary, not Python code. |
| 27 | +- **`.pre-commit-hooks.yaml`** — defines the `trivy-fs` (filesystem vuln scan) and `trivy-config` (IaC |
| 28 | + misconfig scan) hooks consumers reference in their `.pre-commit-config.yaml`. |
| 29 | + |
| 30 | +## The one task that matters: bumping the Trivy version |
| 31 | + |
| 32 | +This repo's lifecycle is almost entirely "update to a new Trivy release" (see `CHANGELOG.md` history). To do it: |
| 33 | + |
| 34 | +1. In `setup.cfg`, update `version` under `[metadata]` to `<trivy-version>.<wrapper-rev>`. |
| 35 | +2. In **every** `[trivy]`/`[trivy.exe]` block, update both the `url` (release version) **and** the matching |
| 36 | + `sha256`. All 6 platform entries must point at the same Trivy release. Get checksums from the Trivy |
| 37 | + release `*.tar.gz`/`*.zip` assets — a stale or mismatched `sha256` makes install fail on that platform. |
| 38 | +3. Add a dated entry to `CHANGELOG.md` (Keep a Changelog format, semver). |
| 39 | + |
| 40 | +Publishing is automated: pushing a `v*` tag triggers `.github/workflows/publish.yml` to build and `twine |
| 41 | +upload` to PyPI. |
| 42 | + |
| 43 | +## Commands |
| 44 | + |
| 45 | +```bash |
| 46 | +# Run the full test matrix (installs the binary, runs pre-commit) |
| 47 | +tox |
| 48 | + |
| 49 | +# The "tests" — tox's [testenv] just verifies the downloaded binary runs: |
| 50 | +trivy --version |
| 51 | +trivy --help |
| 52 | + |
| 53 | +# Lint / format (also the pre-commit testenv) |
| 54 | +pre-commit run --all-files |
| 55 | + |
| 56 | +# Local install to test the download mechanism end-to-end |
| 57 | +pip install . |
| 58 | +``` |
| 59 | + |
| 60 | +There is no unit-test suite; `tox` validates that the platform binary downloads and executes, then runs |
| 61 | +pre-commit (flake8, autopep8, pyupgrade, reorder-python-imports, etc. — config in `.pre-commit-config.yaml`). |
| 62 | + |
| 63 | +## Conventions |
| 64 | + |
| 65 | +- Python ≥ 3.9; code style enforced entirely by pre-commit. New `.py` files must start with |
| 66 | + `from __future__ import annotations` (added automatically by `reorder-python-imports`). |
| 67 | +- This is a mirror — prefer keeping `setup.py`/wheel-tagging logic aligned with upstream `trivy-py` unless an |
| 68 | + eccenca-specific change is intended. |
0 commit comments