refactor(v2): give the metadata provider taxonomy one home

[sdornan]

Description

The v2 frontend declared the "general catalogs vs specialised sources vs hash proxies" provider taxonomy four separate times, each hand-maintained with its own shape:

Surface	What it declared
useScanProviders/index.ts	GENERAL_PROVIDER_KEYS / SPECIFIC_PROVIDER_KEYS (module-private key sets)
Auth/SetupStepMetadata.vue	catalogs / specialised / proxies (key, name, logo, locale keys, requiresKey, disabled)
Settings/MetadataSources.vue	catalogs / specialised / proxies (name, subtitle, value, logo, website, docsUrl, ...)
Scan/ScanInfoDialog.vue	generalProviders / specificProviders / proxies (id, name, logo, locale keys)

This cost real bugs. When Steam was added in #4241 it landed in the specialised group in three surfaces while the composable treated it as general; two were fixed in 3064de63b and the third only turned up later in 0560c974c, because the first sweep found two of the three stragglers. An unclassified provider is worse than misclassified: it silently disappears from the scan selects entirely.

What changed

• New frontend/src/v2/utils/metadataProviderGroups.ts holds the one map from provider slug (the same slug the backend MetadataSource enum and the heartbeat store use) to "catalog" | "specialised" | "proxy", plus the shared section order and the MetadataProviderKey type.
• All four surfaces read from it. The three view surfaces now derive their sections by filtering one flat provider list, instead of declaring three lists, so a provider physically cannot be filed differently per surface. That also collapses three near-identical markup blocks per surface into one loop: net -244 lines across the four files.
• The row key field is now typed key: MetadataProviderKey in all three components (was key: string / value / id), so an unknown provider slug is a compile error.
• HASH_MATCHER_KEYS and the HashMatcherKey union in the composable are derived from the proxy group, so a third proxy becomes a compile error at the switch rather than a silent miss.
• Per-surface presentation data (logos, setup.* / settings.* locale keys, websites, docs URLs, heartbeat wiring, section icons) deliberately stayed where it is used. Only the grouping moved.

Rendered providers, their order and every per-provider field value are unchanged (verified by diffing the extracted entries before/after). Rows and sections gained data-provider / data-group attributes as the test hook; no CSS keys off them.

Tests

frontend/src/v2/utils/metadataProviderGroups.test.ts is the contract test the taxonomy had been missing (only MetadataSources.vue had any grouping coverage before):

• every provider the heartbeat exposes is classified, and every provider in the ROM-match registry is classified;
• the scan selects split all 12 providers by the taxonomy (gamelist / libretro included);
• the three reference surfaces render identical provider-to-group maps, read off the mounted DOM rather than matched on display names (the old approach had to special-case "SteamGridDB" containing "Steam");
• the section order partitions the taxonomy.

I mutation-tested both guards: dropping sgdb from ScanInfoDialog fails the cross-surface assertion, and adding an unclassified steam to the heartbeat store fails the classification assertion. Those are the two exact failure modes from #4241.

gamelist and libretro are still absent from the three reference surfaces (they would need new locale keys, logos and website/docs entries). Out of scope here; the taxonomy classifies them, so the scan selects behave as before.

Verification

npm run typecheck clean, npm run test 746 passing / 68 files (was 741), trunk fmt && trunk check clean. Note the suite needs the .nvmrc Node 24 — under Node 26 every test file fails in vitest.setup.ts because Node's gated built-in localStorage collides with happy-dom's. That is pre-existing on master, not from this change.

I have not opened the setup wizard / settings / scan dialog in a browser in both themes. The change preserves rendering and the new test asserts the rendered grouping for all three surfaces, but a visual pass before merge is worthwhile.

AI assistance

This PR was written primarily by Claude Code (Opus 5), including the code, tests and this description, under my review and direction.

Checklist
^{Please check all that apply.}

• I've tested the changes locally
• I've updated relevant comments
• I've assigned reviewers for this PR
• I've added unit tests that cover the changes

Screenshots (if applicable)

None. Pure refactor with no intended visual change.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

The PR centralizes v2 metadata-provider grouping into one typed taxonomy and updates scan selection, setup, settings, and scan-reference surfaces to derive their sections from it.

• Adds a shared provider-group map, group order, key types, and lookup helpers.
• Refactors three provider views to filter flat presentation lists through the shared taxonomy.
• Derives scan provider and proxy classification from the taxonomy and adds cross-surface contract tests.

Confidence Score: 4/5

The PR appears safe to merge, with one non-blocking gap in the intended compile-time protection for adding future proxy providers.

Current provider membership, rendering, selection behavior, and payload construction remain equivalent, but a future proxy can widen the derived key type without forcing the hard-coded hash-matcher branches to be updated.

Files Needing Attention: frontend/src/v2/utils/metadataProviderGroups.ts, frontend/src/v2/composables/useScanProviders/index.ts

Important Files Changed

Filename	Overview
frontend/src/v2/utils/metadataProviderGroups.ts	Introduces the canonical provider taxonomy and derived types, though the advertised compile-time exhaustiveness for future proxies is not realized by consumers.
frontend/src/v2/composables/useScanProviders/index.ts	Replaces duplicate provider sets with taxonomy lookups while preserving current selection and payload behavior; proxy handling remains hard-coded for two providers.
frontend/src/v2/components/Auth/SetupStepMetadata.vue	Consolidates three explicit provider sections into taxonomy-derived groups while preserving provider data, ordering, probing, and status rendering.
frontend/src/v2/components/Scan/ScanInfoDialog.vue	Derives provider reference sections from the shared taxonomy with the existing provider content and order preserved.
frontend/src/v2/views/Settings/MetadataSources.vue	Refactors metadata-source cards into taxonomy-derived sections while retaining status, links, heartbeat wiring, and presentation fields.
frontend/src/v2/utils/metadataProviderGroups.test.ts	Adds classification, partitioning, scan-select, and rendered cross-surface consistency coverage.

Prompt To Fix All With AI

### Issue 1
frontend/src/v2/utils/metadataProviderGroups.ts:27-34
**Proxy exhaustiveness is not enforced**

Adding another `proxy` widens `MetadataProviderKeyIn<"proxy">`, but the hash-matcher branches treat every non-Hasheous key as Playmatch and payload construction still handles only the current two providers. Type checking therefore does not force those branches to be updated, allowing a future proxy to share Playmatch state or be omitted from scan payloads.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "refactor(v2): give the metadata provider..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This pull request centralizes the v2 metadata-provider taxonomy and updates all related surfaces to derive their groupings from it.

Changes:

• Adds shared provider groups, ordering, and typed keys.
• Refactors scan, setup, settings, and scan-info surfaces.
• Adds classification and cross-surface contract tests.

Review findings:

• useScanProviders/index.ts: Moderate (3 votes) — hash-matcher handling is not exhaustive for new proxy providers.
• metadataProviderGroups.ts: Moderate (3 votes) — inherited properties may be accepted as provider keys.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Summary
frontend/src/v2/views/Settings/MetadataSources.vue	Derives settings sections from the shared taxonomy.
frontend/src/v2/utils/metadataProviderGroups.ts	Defines shared taxonomy utilities.
frontend/src/v2/utils/metadataProviderGroups.test.ts	Tests classification and cross-surface consistency.
frontend/src/v2/composables/useScanProviders/index.ts	Uses taxonomy-driven scan filtering and hash matching.
frontend/src/v2/components/Scan/ScanInfoDialog.vue	Derives provider sections from the shared taxonomy.
frontend/src/v2/components/Auth/SetupStepMetadata.vue	Derives setup sections from the shared taxonomy.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.