Purl to v3

[spatten]

Overview

This PR backports the purl module (PURL → Locator conversion) from the v4 line to v3. The v4 line is being retired: its only active consumer is ficus, and purl conversion (#36) is the only v4-specific functionality ficus uses. This backport is the last piece ficus needs to migrate (fossas/ficus#180), after which nothing depends on v4.

This releases as v5.0.0 on main. It's purely additive over v3, but backwards-incompatible with v4, so we'll bump the main version to v5.

This is a direct copy of v4's locator/src/purl.rs and its 16 ecosystem submodules, with Ecosystem renamed to Fetcher (v3's name for the same concept):

• Each submodule differs from the version on v4 by 3 lines: the import, the builder call, and the revision line (below).
• purl.rs: ecosystem() is renamed fetcher() with a one-to-one variant mapping, plus the shared revision helper and its regression tests.
• The v4 purl test suite is ported along with the code.

You can see that in this diff:

git fetch origin v4-maintenance purl-to-v3
diff <(git show origin/v4-maintenance:locator/src/purl.rs) <(git show origin/purl-to-v3:src/purl.rs)

Almost all of the changes are renaming Ecosystem -> Fetcher.

There is one largish behaviour change. v4 builds revisions with a fallible parse that returns None for empty input. v3 has no fallible parse, and its infallible Revision::from would instead produce Some(Opaque("")).

For example, pkg:apk/alpine/curl has no version and no arch qualifier, so the apk/deb/rpm revision (built by joining whichever of arch/version are present with #) comes out as the empty string:

pkg:apk/alpine/curl  →  apk+curl#alpine   (v4, Core, and this PR)
                     →  apk+curl#alpine$  (naive port: trailing $, doesn't round-trip through Locator::parse)

A purl whose version is only whitespace (pkg:npm/foobar@%20, version = " ") has the same problem.

To handle this, every conversion routes through one shared helper — revision() in src/purl.rs — which trims and maps empty to None, reproducing v4's observable behaviour. This also matches Core, whose Locator class coerces an empty revision to null.

Risks

v-prefixed revisions This is a pre-existing difference between the v3 and v4 branches. v4 strips a leading v before comparing revisions, so v1.2.3 == 1.2.3. v3 classifies v1.2.3 as Opaque, which never equals Semver(1.2.3) — v3 equality is effectively string equality for v-prefixed versions.

Rendered locator strings are identical on both branches; the difference is only observable in in-memory comparison (Eq/Ord/Hash). For example, these two locators are the same key in a v4 HashMap<Locator, _> but different keys in v3:

git+github.com/foo/bar$v1.2.3
git+github.com/foo/bar$1.2.3

This stays as-is, for two reasons: v3's string-equality semantics match how Core compares locators, and v-stripping is unsafe exactly where prefixes occur — for git and go, v2 and 2 can be different refs. Consumers migrating off v4 inherit strict string equality.

Fetcher JSON names

Equivalence testing caught Maven/SourceForge/StackOverflow serializing to JSON as their snake_case variant names ("maven", "source_forge", "stack_overflow") instead of their locator-string names ("mvn", "sourceforge", "stackoverflow"). They had #[serde(alias)] — which only affects deserialization — where they needed rename.

This PR renames them. The old spellings remain as deserialization aliases so existing payloads still parse, and a regression test pins every Fetcher's serde name to its strum name.

This is a safe change because Sparkle never serializes a Fetcher and already parses both spellings; ficus's serialized output becomes identical to what it emits on v4 today.

Testing plan

To test, run against something that Vendetta finds vendored deps in. I used the deps directory of github.com/redis/redis. The test passes if the v3 and v4 versions give the same result.

export FOSSA_API_TOKEN=<token>
cd ~/fossa/ficus
git checkout main && cargo build --release && cp target/release/ficus /tmp/ficus-v4
git checkout scott/locator-purl-to-v3 && cargo build --release && cp target/release/ficus /tmp/ficus-v3

git clone --depth 1 https://github.com/redis/redis /tmp/redis && cd /tmp/redis/deps

/tmp/ficus-v4 analyze --strategy vendetta --locator 'custom+equiv-test$v4' > /tmp/v4.ndjson 2> /tmp/v4.log
/tmp/ficus-v3 analyze --strategy vendetta --locator 'custom+equiv-test$v3' > /tmp/v3.ndjson 2> /tmp/v3.log

jq -c 'select(.observation.strategy=="vendetta" and .observation.kind=="finding") | .observation.payload' /tmp/v4.ndjson | sort > /tmp/v4-findings.txt
jq -c 'select(.observation.strategy=="vendetta" and .observation.kind=="finding") | .observation.payload' /tmp/v3.ndjson | sort > /tmp/v3-findings.txt

There should be no difference between the results for v4 and v3, so /tmp/v4-findings.txt and /tmp/v3-findings.txt should be exactly the same.

Metrics

Not applicable — this is a library change with no runtime surface of its own; consumers pin tags.

References

• Add PURL support #36: original purl support on the v4 line
• fossas/ficus#180: the ficus migration that consumes this backport
• Ficus's usage of this API: ficus/src/strategy/vendetta/solver.rs (parse_locator)

Checklist

• I added tests for this PR's change (the v4 purl test suite is ported alongside the module).

[nficca]

👌