Add a garbage collection mechanism to the CLI

[charliermarsh]

Summary

Detects unused cache entries, which can come in a few forms:

1. Directories that are out-dated via our versioning scheme.
2. Old source distribution builds (i.e., we have a more recent version).
3. Old wheels (stored in archive-v0, but not symlinked-to from anywhere in the cache).

Closes #1059.

[charliermarsh]

This phase is pretty bad (tightly coupled to the cache, but awkwardly so in that it doesn't read the manifest files that point to the latest entry, it just looks for the most recent directory and deletes all the others).

[BurntSushi]

Is there a reason to not read the manifest files?

I think being tightly coupled here is okay, since this is the puffin-cache crate after-all. :)

(I do think our cache representation is a little leaky, but that's a problem for another day.)

[charliermarsh]

One reason is that the manifest files and readers are all in puffin-distribution (which depends on cache crate), but this code is in the cache crate itself :(

It might be necessary though. Removing the "wrong" directories here will break the cache, which is really bad.

[charliermarsh]

I'll also add some tests for this. Parts of it are really tedious to test, but it's probably important.

[BurntSushi]

Nice!

I can see how testing this would be annoying. Maybe one way is to just explicitly build cache directories and then run prune and assert the expected result. But then your tests are tightly coupled with the cache representation.

[BurntSushi]

Is there a reason to not read the manifest files?

I think being tightly coupled here is okay, since this is the puffin-cache crate after-all. :)

(I do think our cache representation is a little leaky, but that's a problem for another day.)

[charliermarsh]

I'm merging this for now without "Old source distribution builds (i.e., we have a more recent version)." That's more complex, and was delaying it, but this is already useful.

[charliermarsh]

I'm not sure why CI / check system | python3.13 on windows (pull_request) is now failing, but it shouldn't be related to this PR. I'll follow-up separately.