# Plán refaktoringu a optimalizace

Tento dokument obsahuje seznam navrhovaných vylepšení pro knihovnu `color-hash`, která zvýší její výkon, čistotu kódu a uživatelský komfort. Úkoly jsou rozděleny do dvou hlavních fází podle dopadu na zpětnou kompatibilitu.

---

## 🟢 Fáze 1: Jarní úklid a optimalizace (Aktuální release - Minor/Patch)
*Tyto změny neporušují veřejné API, nemění vygenerované barvy u stávajících hashů a lze je vydat ihned.*

### 🚀 Výkon (Performance)
- [ ] **Optimalizace `hue_to_rgb`**:
    - Prověřit možnost nahrazení série `if` podmínek matematickým vzorcem nebo efektivnějším větvením. Tato funkce se volá 3x pro každou barvu.
    - *Přínos:* Mikro-optimalizace jádra výpočtu.
- [ ] **Matematické modulo v `hue_to_rgb`**:
    - Nahradit if-větvení pro ořez hodnoty (`t < 0`, `t > 1`) čistou operací modulo `t = t % 1.0` (po ověření matematické správnosti).
    - *Přínos:* Zjednodušení a zpřehlednění výpočtu.

### 🧹 Čistota kódu (Code Quality)
- [ ] **Modernizace `all()` v `color_hash`**:
    - Nahradit `all([x for x in ...])` za `all(x for x in ...)` (odstranění list comprehension).
    - *Důvod:* V moderním Pythonu (3.11+) je generátorová verze idiomatická a šetrnější k paměti.
- [ ] **Extrakce konstant**:
    - Definovat hodnoty jako `1/3`, `2/3`, `1/6` jako globální konstanty v modulu.
    - *Důvod:* Vyhnutí se opakované definici floatů v lokálním scope funkcí při každém volání.
- [ ] **Modernizace formátování stringů (f-strings)**:
    - Nahradit `"{:02x}{:02x}{:02x}".format(*rgb)` ve funkci `rgb2hex` moderními f-stringy (např. `f"#{rgb[0]:02x}{rgb[1]:02x}{rgb[2]:02x}"`).
    - *Důvod:* Čistší a idiomatický zápis s drobným nárůstem výkonu oproti staré syntaxi `.format(...)`.
- [ ] **Zpřesnění typových anotací**:
    - Použít interně definovaný (a nesprávně opomíjený) alias `IntOrFloat` (nebo `Sequence[float] | float`) u parametrů `lightness` a `saturation` místo pouhého `Sequence[float]`, jelikož kód v reálu akceptuje i jednoduchá čísla. Zároveň zvážit `typing.Final` pro konstanty `MIN_HUE` a `MAX_HUE`.
    - *Důvod:* Zlepšení přesnosti analýzy pro lintery a lepší DX pro uživatele.

### ⚙️ CI/CD a Konfigurace projektu
- [ ] **Aktualizace `target-version` linterů (Ruff)**:
    - V `pyproject.toml` je nastaven `target-version = "py37"`, ale knihovna už nyní z logiky věci vyžaduje Python `3.8+` (`requires-python = ">=3.8,<3.16"`).
    - *Přínos:* Linter může začít vynucovat modernější a efektivnější syntax (např. některé union typy).
- [ ] **Statická analýza typů (Mypy / Pyright)**:
    - Knihovna obsahuje soubor `py.typed` a exportuje tak své typové anotace uživatelům. Chybí však automatická kontrola těchto typů (Mypy) v Github metrikách, testovací CI matrixi nebo alespoň v `.pre-commit-config.yaml`.
    - *Přínos:* Zamezení zanesení chybné typové anotace (falešná varování u uživatelů knihovny).
- [ ] **Automatizace testů přes GitHub Actions**:
    - `hatch` matice je hezky nastavena pro lokální testy (Python 3.8 - 3.15), ale schází složka `.github/workflows` pro spouštění automatické CI pipeline pro pull requesty a komity.
    - *Přínos:* Zvýšení jistoty, že nový commit neporuší kompatibilitu s nějakou konkrétní starší verzí Pythonu.

---

## 🛑 Fáze 2: Velké strukturální změny (Release 3.0.0 - Major/Breaking Changes)
*Tyto úpravy zasahují do veřejného chování, způsobů interakce s instancemi nebo mění výstupy stávajících hasů. Musí být vydány v hlavní verzi.*

### 🛠️ Architektura a API
- [ ] **Ošetření mutability a `cached_property` (Architektura / Immutability)**:
    - Zamezit případné mutaci instance (např. vnější změna vlastnosti `self.hsl`), aby kód byl bezpečný, a následně nasadit `functools.cached_property` pro atributy `rgb` a `hex`. 
    - *Přínos:* Výrazné zrychlení při opakovaném čtení.
    - *Řešení & Dopad:* Přesunout inicializaci a vlastnosti za data properties (`@property` nad reálným skrytým polem jako `_hsl`). Objekt `ColorHash` bude defacto read-only, což může rozbít kód uživatelům provádějícím mutace instancí. Proto jde o breaking change vhodnou pro sekci s 3.0.0.
- [ ] **Standardizace rozsahu Hue**:
    - Zvážit přechod z `% 359` na `% 360` (s dělením `/ 359`), aby byl pokryt celý kruh $360^\circ$.
    - *Dopad:* Tato změna generuje jiné barvy než starší verze knihovny pro identické vstupy! (Nevyhnutná breaking change).
- [ ] **Zavedení plné imutability přes `__slots__`**:
    - Přidat `__slots__` do třídy `ColorHash` pro snížení paměťové náročnosti při vytváření tisíců instancí.
    - *Dopad:* Znemožní uživatelům dynamicky přiřazovat vlastní atributy, je to zásahem do standardního chování Python objektů.
- [ ] **Validace parametrů v `ColorHash.__init__`**:
    - Přesunout validaci `lightness` a `saturation` z funkce `color_hash` přímo do inicializace třídy.
    - *Dopad:* Menší úprava workflow uvnitř. Zařazeno do 3.0 pro bezpečnost (změní, kde přesně je výjimka vyvolána a může změnit standalone chování funkce `color_hash()`).
- [ ] **Volitelná injekce Hashovací funkce (Nová Feature)**:
    - Zvážit přidání `hash_func` callable argumentu coby alternativy k hard-coded hashovací funkci `binascii.crc32`.
    - *Přínos:* Poskytnutí obrovské flexibility pro advanced scénáře (např. potřeba masově cachovat větší vstupy či kryptograficky silný hash se stejným Color algoritmem). Změní signatury metod.
