feat(index): MetadataIndex interface, types, and MockIndex

[jonyoder]

What

RFD 0001 Phase 3.1 — the architectural seam between the resolver and storage, per RFD §6 with the interface decisions settled in §16.

Tracked as rstudio/package-manager#18646.

The settled decisions, as specified

Decision (§16)	Implementation
DistFile.Location semantics	Scheme-prefixed string; the interface treats it as opaque and the consumer parses the scheme
PackageMetadata.Origin	string
DistFile.UploadTime	time.Time
Files() platform filtering	Returns all wheels; the consumer decides compatibility
Interface naming	MetadataIndex

Two distinctions that are load-bearing

Collapsing either produces a silently wrong resolution rather than an error, so both are enforced and tested:

• ErrPackageNotFound vs an empty version list. An unknown name is probably a typo; a known name with no acceptable version is a constraint conflict. A resolver must report them differently, so a known-but-empty package is ([], nil).
• ErrMetadataUnavailable vs ErrPackageNotFound. Treating an sdist-only release whose metadata needs a build as "not found" would let the resolver quietly select an older version and call it a success.

Three judgment calls the RFD does not settle

1. PackageName is a distinct type, normalized at construction. This is correctness, not style: if Flask and flask reach the solver as separate identities, it builds two nodes for one package and can report a conflict that does not exist.

Normalization delegates to go-python-packaging's extras.Normalize, which implements exactly the PEP 503 algorithm — PEP 685 extra names and PEP 503 project names are the same transformation, and that function's own doc describes it as mirroring canonicalize_name for both. Reusing it beats a second copy that can drift from the first. The name reads oddly at this call site, so I filed rstudio/package-manager#19425 to add a PEP 503-named entry point upstream, and the code comment points there.

2. DistFile.Yanked / YankedReason go slightly beyond §16's four decisions. PEP 592 makes yanking a per-file property, and §6 assigns yanked policy to FilteredIndex — that policy needs the fact carried somewhere, and this is the only per-file type. Flagging it explicitly since it is an addition rather than a settled decision.

3. DistFile.RequiresPython is per-file and distinct from PackageMetadata.RequiresPython. A release can ship one wheel for older interpreters and another for newer ones, so the file-level constraint is what decides whether a particular file is usable.

Also: DistKindUnknown is the zero value on purpose, so a DistFile built by an incomplete implementation is obviously incomplete rather than silently claiming to be an installable wheel.

MockIndex

A non-test file, because candidate, provider, and resolver tests all need an index to drive and Go cannot share _test.go helpers across packages. It pulls in no test-only dependency, so this costs nothing at build time.

• Concurrency-safe, per the interface contract, so a resolver that looks ahead in parallel can be tested against it.
• Returns copies. A resolver is entitled to sort what it is handed; leaking internal slices would let one test corrupt the fixture for the assertions after it.
• AddFiles registers the version. Otherwise a files-only setup surfaces as ErrPackageNotFound, which looks like a bug in the code under test rather than in its setup.
• Versions returns reverse insertion order — deterministic, but deliberately unsorted. The interface promises no ordering, and a mock returning sorted versions would let an ordering assumption pass here and then fail against a real index. A shuffle would achieve the same at the cost of flaky tests.

Testing

• 98.1% statement coverage on index/; -race clean; gofmt -l . silent; golangci-lint run ./... at CI's pinned v2.11.2 → 0 issues from the module root.
• Mutation tested rather than assumed effective. Removing the metadata slice copy fails TestMockIndexReturnsCopies; skipping name normalization fails three tests including TestMockIndexNormalizesNames. Both mutations were reverted and the tree confirmed free of residue.
• Tests cover the two error distinctions, context cancellation on all three methods, PEP 503 name equivalence across five spellings, and that bad test setup panics loudly rather than leaving a silently empty index.

Dependencies

Pins go-python-packaging v0.2.0 — the first release carrying the PEP 440/508 conformance work and the local-label ordering fix. go-version comes in as an indirect.

Not in this PR

RSFIndex and CachedJSONIndex are #18647. OfflineIndex, DBIndex, FilteredIndex, and MultiIndex are named in index/doc.go with their intended scope but are not in the initial release.

🤖 Generated with Claude Code