Doc développeur

Architecture interne et contribution au projet Catnip. Section technique destinée à l'implémentation du runtime et des outils. Le cap est simple : comprendre le moteur, puis le faire aller plus vite.

Vue d'ensemble

Catnip transforme du texte en résultat en plusieurs étapes, un peu comme une chaîne d'assemblage : on lit, on simplifie, on optimise, puis on exécute.

Mermaid diagram dev__index--m001 Mermaid diagram dev__index--m001

L'architecture est hybride Rust + Python : Rust gère le "gros œuvre" (performance et sécurité), Python expose une API simple côté application.

Transparence : les preuves Coq du repo ne couvrent ni Tree-sitter ni Cranelift.

Détails de chaque étape : voir Architecture.

Composants principaux

Composant Rôle Implémentation Opcodes
Parser Analyse syntaxique Tree-sitter Rust -
Transformer Parse tree → IR (Intermediate Repr.) Rust IROpCode
Semantic Analyse et optimisation IR → Op Rust OpCode
CFG Control Flow Graph pour analyse Rust (dominance, loops) -
Compiler Op → Bytecode (mode VM uniquement) Rust -
VM Exécution bytecode stack-based Rust (NaN-boxing, JIT) -
Registry Dispatch direct des opérations (mode AST) Rust -
Scope Gestion des variables O(1) Rust -
Context Environnement d'exécution, pragmas Python -

Documents de cette section

  • ARCHITECTURE - Pipeline complet, parsing, analyse sémantique, scopes
  • VM - Machine virtuelle Rust, NaN-boxing, modes d'exécution
  • ND_VM_ARCHITECTURE - Opérations ND dans le VM (\~~, ~>, ~[])
  • JIT - Compilation Just-In-Time trace-based, Cranelift backend, hot detection
  • OPTIMIZATIONS - Passes d'optimisation, niveaux, quand les activer
  • CACHE - Système de cache multi-niveaux, backends intégrés, protocole custom
  • TEST_STRATEGY - Répartition Rust/Python, parité VM/AST, anti-doublons
  • BENCHMARKING - Méthodologie de mesure et comparaison de performances
  • EXTENDING - Ajouter opcodes, opérations, extensions
  • CONSTANTS - Configuration par défaut (prompts, couleurs, seuils JIT, etc.)
  • COQ_PROOFS - Preuves Coq : périmètre, vérification (make proof), modules de preuve

Où trouver le code

catnip/             # module Python
catnip_rs/          # coeur Rust
catnip_grammar/     # Grammaire Tree-sitter
catnip_repl/        # REPL
catnip_tools/       # outils format, linter
catnip_mcp/         # serveur mcp

Workflow de développement

# Après modification de fichiers Rust
uv pip install -e .

# Tests rapides Rust (~5s)
make rust-test-fast

# Tests complets Python (~25s)
make test

# Après modification de grammar.js
make grammar-deps

Pipeline composable : chaque étape prépare la suivante.