[simonchrz]

Supersedes #519, which @andrew wrote and said we could take over. His commit is kept as the first commit, rebased onto main; the second is mine. Part of #501.

As in #519, the npm metadata rewrite moves out of internal/handler into internal/metadata/npm, and the JSON scanner into internal/jsonscan, shared by npm and Composer. The rewrite takes everything as explicit inputs (proxy URL, cooldown policy, the time cooldown is evaluated at, denied versions, pushed versions) and reports what it did through callbacks the handler logs. It doesn't depend on handler.Proxy, so it pulls in no SQL drivers, cloud SDKs, metrics, HTTP or logging. Fetching, storage, the rewrite cache and HTTP responses stay in the handler.

Main changed a lot of this code after #519 branched. Where each change went:

• Logging rewritten tarball URLs once per document (Log rewritten npm tarball URLs once per document #538): now in the package. OnTarballRewrite(version, old, new) became OnTarballsRewritten(count), called at most once per document. The handler still logs one rewrote tarball URLs debug line with the count.
• Abbreviated packuments under cooldown (Fix npm search routing and abbreviated packuments under cooldown #567): detecting the abbreviated format is now npm.Abbreviated. packumentAccept, packumentValidator and the errAbbreviatedPackument they return stay in the handler, since they use the proxy's config and metadata cache.
• Failing closed (mustFilterMetadata, 09e41d0), the stale warning on filtered version metadata (994a936), the cooldown rewrite cache with its one-minute TTL (f4cab2d), storedRewrite/storedRewriteVariant (Cache Helm and PyPI metadata rewrites #600), stale fallback (Flag stale Composer and Chef metadata #541), metrics (Separate artifact and metadata cache metrics on /metrics and the analytics page #463, Count cached metadata against max_size and evict it LRU #507), the tarball and cooldown download checks (Don't fetch npm tarballs whose packument can't be read #582, 224bce8), npm search routing and debug-level request logs: all depend on the DB, cache, metrics or HTTP, so they stay in the handler as main has them. The cached rewrite now calls into the package.
• Composer (Resolve Composer downloads from the cached metadata #494, Serve cached Composer releases without a metadata lookup #568, Mirror Composer releases #594): it only uses the scanner, so it now calls jsonscan.

Changes from #519:

• The tarball callback reports a count instead of one call per version (see above).
• npm.Abbreviated is new.
• imports_test.go in internal/metadata/npm runs go list -deps and fails on any non-standard import outside an allowlist (semver, cooldown, purl, vers, packageurl-go, internal/jsonscan, internal/packageurl), or on net, net/http, log/slog or database/sql. database/sql/driver comes in through semver, as it already did in Extract portable npm metadata transformations #519. It's only interfaces, with no driver.
• jsonscan has a package comment.

Cooldown is checked with Evaluate at one EvaluatedAt per rewrite instead of IsAllowed per version, as in #519. The handler passes time.Now(), so results are the same unless a rewrite runs across a cooldown boundary.

Portability: GOOS=wasip1 GOARCH=wasm go build ./internal/metadata/npm ./internal/jsonscan works, and both packages' tests pass when compiled for wasip1 and run under Node's WASI. The imports test skips there because it has no go tool. I didn't try TinyGo.

Benchmarks (M5 Pro, internal/handler, main vs this branch, test binaries run alternately, n=12, benchstat):

	main	branch
NPMRewriteMetadata	45.20 ms	44.26 ms	~ (p=0.068)
NPMVersionTarball	16.74 ms	16.60 ms	~ (p=0.29)
ComposerRewriteMetadata	9.80 ms	9.75 ms	~ (p=0.89)
ComposerFindDownloadURL	3.43 ms	3.54 ms	+3% (p=0.02)

Bytes and allocations per op are unchanged. A first, non-alternating run had ComposerFindDownloadURL at −7.5% and NPMVersionTarball at +6%, so I read these differences as noise. The scanner code is the same apart from the renames.

The npm rewrite unit tests moved to internal/metadata/npm with the code. The handler tests stay, adjusted to the new names. go test ./..., go test -race on handler, metadata and jsonscan, and golangci-lint pass.