Standards de code

Ce guide documente les conventions appliquées à tout le monorepo. Le CI les vérifie — autant les respecter dès le premier commit.

Python (Backend)

Style et formatage

# Vérifier
cd services/core
uv run ruff check .
uv run ruff format --check .

# Corriger
uv run ruff check --fix .
uv run ruff format .

Conventions Python

• PEP 8 respecté via Ruff.
• Type hints obligatoires sur les signatures publiques.
• Imports : triés par Ruff (stdlib → third-party → local).
• Async-first : les repositories et use cases sont async. Utiliser await, pas de .result().
• Pas de print() : utiliser le port LoggerPort ou structlog.
• Logging Windows-safe : ne jamais inclure de caractères non-ASCII dans les messages de log (émojis, accents). Windows PowerShell corrompt la sortie.

Architecture hexagonale stricte

Violation typique à éviter : un use case qui importe SQLAlchemy directement.

TypeScript/JavaScript (Frontend)

Style et formatage

# Depuis la racine
pnpm lint          # Vérifier
pnpm lint:fix      # Corriger
pnpm format:check  # Vérifier le formatage
pnpm format        # Formater

Conventions TypeScript

• prefer-const : toujours const sauf si réassignation nécessaire.
• no-var : interdit.
• no-explicit-any : warning (éviter au maximum).
• Pas de @ts-ignore sauf justification en commentaire.
• Nommage :
  • Composants React : PascalCase (FlowEditor.tsx)
  • Hooks : camelCase avec préfixe use (useFlowStore.ts)
  • Utilitaires : camelCase (formatDate.ts)
  • Types/interfaces : PascalCase (FlowNode, RunStatus)
  • Constantes : UPPER_SNAKE_CASE (MAX_RETRIES)

Structure des composants React

features/
└── flows/
    ├── components/     # Composants UI spécifiques au domaine
    ├── hooks/          # Hooks custom
    ├── types/          # Types spécifiques
    └── utils/          # Utilitaires

Les composants UI partagés (boutons, modals, etc.) sont dans components/ui/ et suivent les patterns shadcn/ui + Radix UI.

Git

Commits

Commits conventionnels (commitlint enforced) :

type(scope): description courte

# Types autorisés
feat:     Nouvelle fonctionnalité
fix:      Correction de bug
docs:     Documentation uniquement
style:    Formatage, pas de changement de logique
refactor: Refactoring sans changement de fonctionnalité
perf:     Amélioration de performance
test:     Ajout ou correction de tests
build:    Système de build ou dépendances
ci:       Configuration CI/CD
chore:    Maintenance, nettoyage

Exemples :

feat(flows): add flow duplication endpoint
fix(agent): handle empty prompt gracefully
docs(api): update channel binding schema
test(core): add integration tests for run SSE

Branches

Avant chaque PR

# 1. Linting
pnpm lint
cd services/core && uv run ruff check . && cd ../..

# 2. Formatage
pnpm format:check
cd services/core && uv run ruff format --check . && cd ../..

# 3. Tests
pnpm test
cd services/core && uv run pytest && cd ../..

# 4. Type-check
pnpm type-check

Fichiers d'environnement

• Ne jamais committer de fichiers .env contenant des secrets.
• Utiliser .env.example comme template (sans valeurs sensibles).
• Les clés de chiffrement (ENCRYPTION_KEY) et les clés API LLM ne doivent jamais apparaître dans le code ou les logs.

Pour aller plus loin

• Guide de test — Conventions de test détaillées
• Architecture backend — Règles de dépendance entre couches