pkgbuild: remove pypi field over purl; add purl version support

* We now support pypi PURLs, so no need to have our own separate pypi
  type anymore.
* PURLs now support versions, which take precedence over the pkgver
  if specified.

Author: lazka

web/dev/pkgbuild.md

@@ -28,12 +28,15 @@ For `msys2_references` the following keys are recognized:
 * `cygwin-mingw64` -
   the cygwin package name for all packages starting with "mingw64-x86_64-",
   minus that prefix: https://cygwin.com/packages/src_package_list.html
-* `pypi` - the PyPI project name (case-insensitive): https://pypi.org/search/
 * `gentoo` - the full Gentoo package name e.g. `dev-python/pyasn1`
 * `internal` - special key, which if it exists marks the package as internal and doesn't link it to any external sources
-* `purl` - a [package URL](https://github.com/package-url/purl-spec) e.g. `pkg:cargo/ripgrep` (only cargo supported atm)
-  Multiple PURLs supported.
-* `cpe` - a [CPE](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) prefix, either in the 2.2 format (`cpe: cpe:/a:gnu:gcc`) or the 2.3 format (`cpe:2.3:a:gnu:gcc`). `target_sw` etc are currently not supported. Multiple CPEs supported.
+* `purl` - a [package URL](https://github.com/package-url/purl-spec). Multiple PURLs supported. Versions are optionally supported, and useful in case the upstream version is different from the package version. Some common PURL types:
+  * [pypi](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#pypi) - example: `pkg:pypi/jinja2` or `pkg:pypi/@3.1.5` - make sure to [normalize](https://packaging.python.org/en/latest/specifications/name-normalization) the package name
+  * [cargo](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#cargo) - example: `pkg:cargo/ripgrep` or `pkg:cargo/[email protected]`
+  * [gem](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#gem) - example: `pkg:gem/asciidoctor`
+  * [github](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#github) - example: `pkg:github/curl/curl` or `pkg:github/curl/curl@curl-8_12_1`
+  * ...
+* `cpe` - a [CPE](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) prefix, either in the 2.2 format (`cpe: cpe:/a:gnu:gcc`) or the 2.3 format (`cpe:2.3:a:gnu:gcc`). `version`, `target_sw` etc are currently not supported. Multiple CPEs supported.
 
 Defining a key without a value means there is no mapping and the package shouldn't be linked.
 
@@ -44,3 +47,8 @@ The following datatypes are supported:
 * **mapping:** Mappings of strings to optional other strings, separated by `":"`, values are
   stripped: `msys2_myvar=("example1: value1" "example2")` 🠆 `{"myvar": {"example1": ["value1"], "example2": [null]}}`
 * **boolean:** either `true` or `false`: `msys2_myvar=true` 🠆 `{"myvar": true}`
+
+## Changelog
+
+**2025-02-17:** Added support for the `version` component in `purl` entries, for example `purl: pkg:pypi/[email protected]`.
+**2025-02-17:** Removed support for `pypi` in `msys2_references`, use `purl` with the `pypi` type instead, for example `purl: pkg:pypi/jinja2` instead of `pypi: jinja2`.

web/dev/vulnerabilities.md

@@ -14,7 +14,7 @@ graph LR;
 
 The following metadata is used to generate the SBOM file, so that CVEs etc. can be matched to our packages:
 
-In the `msys2_references` field in each `PKGBUILD` file the `cpe` key, the `purl` and the `pypi` keys are used to match to CVEs.
+In the `msys2_references` field in each `PKGBUILD` file the `cpe` and `purl` entries are used to match to CVEs.
 The more references the better. Language ecosystem specific references such as pypi and cargo are preferred. For more information about the fields see [PKGBUILD](./pkgbuild.md).
 
 Example:
@@ -23,11 +23,20 @@ Example:
 msys2_references=(
   "cpe: cpe:/a:python-cryptography_project:python-cryptography"
   "cpe: cpe:2.3:a:cryptography_project:cryptography"
-  "pypi: cryptography"
   "purl: pkg:pypi/cryptography"
 )
 ```
 
+In case the version format of the referenced ecosystem is different from the PKGBUILD version, you can specify the version in the `purl` field:
+
+```bash
+pkgver=1.0dev1
+_pypiver=1.0.dev1
+msys2_references=(
+  "purl: pkg:pypi/example@${_pypiver}"
+)
+```
+
 If a discovered vulnerability doesn't affect our users in the first place (it's
 Unix only for example), or is already fixed (missing or wrong version
 information attached to the vulnerability info), or we have backported a fix for