ranska-pixel_palette_art/CLAUDE.md

Pixel Palette Art - Guide pour Claude

Vue d'ensemble

Extension ComfyUI (custom nodes) pour la manipulation de palettes de couleurs pixel art. Auteur : Ranska | Version : 0.0.4 | Licence : open source

Commandes essentielles

# Tests BDD (OBLIGATOIRE avant tout PR)
mamba spec/ --enable-coverage --format=documentation

# Tests rapides (pendant le dev)
mamba spec/ --format=documentation

# Tests d'un module spécifique
mamba spec/pixel_palette_spec.py --enable-coverage

# Installation des dépendances de dev
pip install -r requirements-dev.txt

Architecture

pixel_palette_art/
├── lib/                         # Logique metier (TESTE)
│   ├── pixel_color.py           # Dataclass PixelColor (r,g,b,name,color_space)
│   ├── pixel_palette.py         # Dataclass PixelPalette (colors, parsing, export)
│   ├── color/                   # Systeme d'espaces colorimétriques
│   │   ├── color_space_registry.py   # Registry central (singleton)
│   │   ├── color_space_context.py    # Context manager temporaire
│   │   └── color_spaces/             # Implémentations par espace
│   │       ├── rgb/  (mixer + exporter)
│   │       └── hsv/  (mixer)
│   ├── palette/                 # Systeme d'export de palettes
│   │   ├── exporter_context.py       # Context manager d'export
│   │   └── exporters/                # Formats : gimp, hex, rgb
│   │       ├── exporter_registry.py
│   │       └── base_exporter.py      # ABC
│   └── parsers/                 # Systeme de parsing de palettes
│       ├── parser_registry.py
│       ├── base_parser.py            # ABC
│       ├── gimp_parser.py
│       ├── generic_parser.py
│       └── adobe_aco_parser.py
├── nodes/                       # Interface ComfyUI (NON TESTE - wrappers)
│   ├── gimp_palette_loader_node.py
│   ├── palette_formatter_node.py
│   ├── color_formatter_node.py
│   ├── create_color_from_rgb_node.py
│   ├── color_preview_node.py
│   ├── mix_colors_node.py
│   ├── pixel_palette_extractor_node.py
│   └── palette/
│       └── replace_color_at_node.py
├── spec/                        # Tests BDD (Mamba + expects)
└── __init__.py                  # Enregistrement ComfyUI

Principes fondamentaux

Separation lib/ vs nodes/

• lib/ = logique metier pure, 100% testable, aucune dépendance ComfyUI
• nodes/ = adaptateurs fins vers ComfyUI, NON testés (wrappers d'intégration)
• Toute nouvelle logique va dans lib/, le node ne fait que l'appeler

Pattern Registry (coeur du projet)

Trois registries indépendants, tous extensibles :

1. ColorSpaceRegistry - espaces colorimétriques (rgb, hsv, futur: hsl, lab...)
2. ExporterRegistry - formats d'export palette (gimp, hex, rgb)
3. ParserRegistry - formats de parsing palette (gimp, generic, adobe_aco)

Chaque composant s'auto-enregistre a l'import. Voir docs/architecture-registries.md.

Auto-enregistrement

Les mixers, exporters et parsers se déclarent eux-memes via les __init__.py de leur module. Ajouter un nouveau format = créer la classe + l'importer dans le __init__.py du module.

Règles STRICTES pour les commits (PRIORITÉ MAXIMALE)

• JAMAIS de Co-Authored-By dans les messages de commit
• JAMAIS de mention "Generated with", "Generated by", "Made with" ou similaire
• JAMAIS de référence a un outil IA/assistant dans les commits ou commentaires de code
• Les messages de commit doivent etre rédigés comme si un humain les avait écrits directement

Conventions de code

Tests (Mamba/BDD)

• Framework : mamba (équivalent Python de RSpec)
• Assertions : expects (matchers fluides)
• Structure : description > context > it (comme RSpec)
• Convention de nommage des fichiers : *_spec.py
• Les specs mirrorent la structure de lib/ dans spec/
• Toujours lancer avec --enable-coverage avant un PR

Style

• Commentaires et docstrings en francais
• Noms de classes/variables en anglais
• Dataclasses pour les modeles de données
• Context managers pour les operations temporaires
• ABC (Abstract Base Class) pour les interfaces

Git Flow (IMPORTANT)

• Branche principale de travail : develop
• master = releases uniquement (tags), ne jamais PR directement vers master
• Workflow obligatoire pour chaque feature/fix :
  1. git pull origin develop (toujours partir de develop a jour)
  2. git checkout -b feature/<nom> (creer une branche feature)
  3. Travailler, commiter sur la branche feature
  4. git push -u origin feature/<nom>
  5. Creer la PR vers develop (jamais vers master)
  6. Apres merge, supprimer la branche feature
• Releases : merge develop → master et tag uniquement quand le nombre d'ajouts est significatif (pas a chaque petit commit)
• Lefthook : pre-commit lance mamba spec/ automatiquement
• CI : GitHub Actions sur push/PR (Python 3.10/3.11/3.12)
• Tests verts obligatoires avant PR
• Conventions PR : voir docs/pr-conventions.md

Types ComfyUI custom

• PIXEL_COLOR : instance PixelColor (r, g, b, name, color_space)
• PIXEL_PALETTE : instance PixelPalette (colors[], metadata)

Ajouter un nouvel espace de couleur

1. Créer lib/color/color_spaces/<nom>/ avec __init__.py
2. Implémenter le mixer (methode mix_with(color_a, color_b, ratio))
3. Optionnel : implémenter l'exporter
4. Auto-register dans le mixer : ColorSpaceRegistry.register('<nom>', mixer_class=<Class>)
5. Importer dans lib/color/color_spaces/__init__.py
6. Écrire les specs dans spec/color/color_spaces/<nom>/

Ajouter un nouveau format d'export/parsing

1. Créer la classe héritant de BaseExporter ou BaseParser
2. L'enregistrer dans le __init__.py du module correspondant
3. Écrire les specs

Documentation détaillée

• docs/architecture-registries.md - Pattern Registry en détail
• docs/color-spaces.md - Système d'espaces colorimétriques
• docs/testing.md - Guide des tests BDD avec Mamba
• docs/nodes-comfyui.md - Référence des nodes ComfyUI
• docs/data-models.md - Modeles de données PixelColor et PixelPalette