backend/core/error_docs_map.py

"""Error class → docs URL mapping for the in-app deeplink button.

Used by the React ErrorBoundary's "Open docs for this error" button (via the
TypeScript mirror at `frontend/src/utils/errorDocsMap.ts`) and by the Phase 5
bug-reporter for "this error has a docs page" links.

The 4-class taxonomy below is the contract — Phase 5 reporter consumes it,
the TS map mirrors it, and `test_error_docs_map.test_keys_match_taxonomy`
locks the key set. To add a new class:

  1. Pick a stable ALL_CAPS key (the API will live forever).
  2. Add the entry here.
  3. Mirror it in `frontend/src/utils/errorDocsMap.ts`.
  4. Update the `test_keys_match_taxonomy` set and the TS-side keys-sync test.
"""
from __future__ import annotations

from core import links

_BASE = links.PROJECT_REPO_BLOB_MAIN

ERROR_DOCS: dict[str, str] = {
    "GATEKEEPER_QUARANTINE":      f"{_BASE}/docs/install/macos.md#gatekeeper-quarantine",
    "APPIMAGE_WEBKIT_WHITESCREEN":f"{_BASE}/docs/install/linux.md#appimage-white-screen-on-fedora-44--ubuntu-2404",
    "PKG_RESOURCES_MISSING":      f"{_BASE}/docs/install/troubleshooting.md#pkg_resources-missing",
    "HF_AUTH_FAILED":             f"{_BASE}/docs/setup/huggingface-token.md",
}

DEFAULT_DOCS: str = f"{_BASE}/docs/install/troubleshooting.md"


def lookup(error_class: str | None) -> str:
    """Return the docs URL for `error_class`, or DEFAULT_DOCS when the
    class is None / unknown."""
    return ERROR_DOCS.get(error_class or "", DEFAULT_DOCS)