0029: Maintaining the Vendored Paragon Icon Allow-List
######################################################

Status
******

**Draft**

Context
*******

`ADR 0017`_ §4 requires schema validation to reject ``icon`` values that are not
valid names exported by ``@openedx/paragon/icons``. Categories, permissions,
roles, and role extensions each carry an optional Paragon icon name (for example
``BookOpen`` or ``RemoveRedEye``), and those names are used by frontends to
render the schema.

``openedx-authz`` is a Python backend with no Node or Paragon dependency, so the
JavaScript icon package cannot be imported at validation time. There is no
Python-side source of truth for the set of valid icon names, and the set changes
whenever Paragon adds, renames, or removes an icon.

Paragon publishes its icons as component exports from ``@openedx/paragon/icons``.
The built export barrel (``icons/es5/index.js`` in a published release) lists
every icon as ``export { default as <IconName> } from "./<file>";``, which is a
stable, machine-readable source for the name set.

Decision
********

We vendor the icon-name allow-list as a generated Python module,
``openedx_authz/engine/schema/paragon_icons.py``, exposing
``PARAGON_ICON_NAMES: frozenset[str]``. The schema validator imports this
frozenset and rejects any ``icon`` value that is not a member (ADR 0017 §4).

The list is generated by ``scripts/generate_paragon_icons.py``, run via
``make paragon_icons``. The script fetches the icon export barrel for a pinned
Paragon version from the public npm CDN, parses the exported names, and writes
the vendored module. The generated file is committed to the repository so that
validation is deterministic and needs no network access at runtime.

**Pinned version.** The generator pins the Paragon version to match the
``@openedx/paragon`` major that ``frontend-app-admin-console`` declares on its
``master`` branch (currently ``^23``, generated from ``23.21.3``). That MFE is
the primary consumer that renders these icons, so aligning the allow-list with
the version it ships keeps validation honest: an icon that validates here is one
the console can actually render.

**Update process.** Regenerate the list whenever
``frontend-app-admin-console`` changes its ``@openedx/paragon`` version:

1. Update ``PARAGON_VERSION`` in ``scripts/generate_paragon_icons.py`` to the
   new pinned release.
2. Run ``make paragon_icons`` to rewrite ``paragon_icons.py``.
3. Commit the regenerated file together with the version bump.

``make paragon_icons_check`` regenerates the list into memory and fails if the
committed file is stale; wire it into CI to catch a forgotten refresh after a
version bump.

**Deprecation.** When Paragon renames or removes an icon, the change lands in the
allow-list at the next regeneration. Any schema ``icon`` value that no longer
exists then fails validation as an error, following the same deprecation path as
other consumers of ``@openedx/paragon/icons`` (ADR 0017 §4).

Consequences
************

* Icon validation is deterministic, offline, and requires no Node dependency in
  the Python backend.
* The allow-list can drift from the latest Paragon release between refreshes.
  This is intentional: it tracks the version the console consumes, not the newest
  published icons, and the ``paragon_icons_check`` target surfaces staleness.
* Bumping the console's Paragon version is now a two-repo change: someone must
  refresh the vendored list here so newly available icons validate and removed
  icons are rejected.
* ``paragon_icons.py`` is a generated artifact; it must not be edited by hand.

References
**********

* `ADR 0017`_
* `Paragon icons`_
* `frontend-app-admin-console`_

.. _ADR 0017: 0017-static-authorization-schema.rst
.. _Paragon icons: https://paragon-openedx.netlify.app/components/icon/
.. _frontend-app-admin-console: https://github.com/openedx/frontend-app-admin-console
