Tracking: build and classify purls through one validated utils::purl API #748

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: discussion #560 register.

Kind: tracking. Source: review 6.4, 7.3; register C20.

Problem (verified on 045d7ec)

utils/purl.rs has two builder families:

• Unvalidated: build_gem_purl … build_cargo_purl. There are 7 of them, plain format!, with 21 production callers.
• Validated: npm_purl … maven_purl. They return None for unsafe coordinates; lockfile discovery and the lock inventory use them.

On top of these, 42 production format!("pkg:…") sites outside utils/purl.rs build purls by hand. The review counted 48; corrected here. The largest groups:

• vex/product.rs: 13 sites, including versionless purls
• vendor/path.rs::leaf_to_purl: 10
• vendor/lock_inventory/recover.rs: 6
• vex/discover/mod.rs: 5, with their own PyPI/composer/nuget canonicalization in discover/mod.rs L1455-L1468
• hosted/engine.rs:622

There are also 24 inline starts_with("pkg:<type>/") checks beside Ecosystem::from_purl.

Drift already present. The families disagree on canonicalization:

• composer_purl lowercases, while build_composer_purl, leaf_to_purl and recover.rs don't.
• pypi_purl canonicalizes the name, while leaf_to_purl, recover.rs and the hosted skip purl (hosted/engine.rs:622) don't. vex::discover re-canonicalizes afterwards.
• vlt.rs:290 alone percent-encodes the npm scope @.

Every consumer that compares purls therefore needs purl_eq/normalize_purl to paper over the differences.

Target design

• utils::purl exposes one validated constructor per ecosystem (or Purl::new(Ecosystem, ns, name, version) -> Option<String>) that owns name canonicalization (PyPI PEP 503, composer and nuget lowercase), plus one versionless base_purl. build_* becomes private or is deleted.
• Type checks go through Ecosystem::from_purl.

Checklist (one PR each, in order)

• Route purl ecosystem checks through Ecosystem::from_purl instead of 24 inline starts_with("pkg:<type>/") tests #747: purl type checks through Ecosystem::from_purl (mechanical; can start now).
• Vendored ledger keys (vendor/{gem,maven_repo,nuget_feed,composer_lock}.rs) and redirect/golang_local.rs move to the validated builders. An unsafe coordinate becomes a refusal instead of a ledger key. Owner: ecosystems area.
• vendor/path.rs::leaf_to_purl and lock_inventory/recover.rs build through the validated builders, canonicalizing PyPI and composer once. Delete the re-canonicalization in vex::discover.
• vex/product.rs versionless/product purls through one base_purl builder.
• Delete the build_* family and purl_name_version, which only has a test caller.

Dependencies

• Children 2–4 touch the ecosystem area (audit-ecosystems), so coordinate with E-rows on vendor/ and vex/.
• Related: Move the crawler coordinate guards and composer's leading-v rule into utils and delete the copies #630 (crawler coordinate guards into formats).

Consolidated work — backlog review, 2026-10-08

The following standalone issues are now tracked here. Their closure consolidates scheduling; it does not mean their implementation is complete. Original reports and discussion remain linked below.

#630: Move the crawler coordinate guards and composer's leading-v rule into utils and delete the copies

• Track the remaining scope from Move the crawler coordinate guards and composer's leading-v rule into utils and delete the copies #630 in this issue. Coordinate/purl helper consolidation belongs under the existing validated-purl tracker.