Documentation Développeur

Architecture interne et contribution au projet Catnip.

Si tu lis ceci, tu es déjà dans le circuit, branché au flux.

Vue d'ensemble

Catnip utilise une architecture pipeline à plusieurs étapes pour transformer du code source en résultats exécutables :

Source text
    ↓
Parser (Tree-sitter)
    ↓
Parse Tree (CST)
    ↓
Transformer (72 modules Rust)
    ↓
IR (Intermediate Representation avec IROpCode)
    ↓
Semantic Analyzer + 6 passes d'optimisation
    ↓
Op (Optimized AST avec OpCode final)
    ↓
┌─────────────────┐
│  Mode VM (on)   │──→ Compiler Bytecode → VM Stack-based → Result
├─────────────────┤
│ Mode AST (off)  │──→ Registry Direct Execution → Result
└─────────────────┘

L'architecture repose sur une stratégie hybride Rust + Python : les composants bas niveau sont en Rust (via PyO3), l'API de haut niveau reste en Python.

Étapes détaillées :

Parsing : Tree-sitter génère un CST (Concrete Syntax Tree) depuis le texte source
Transformation : 72 transformateurs Rust convertissent le CST en IR avec IROpCode (56 opcodes)
Analyse sémantique : 6 passes d'optimisation transforment l'IR en Op final avec OpCode optimisé
Compilation (mode VM) : Le compiler bytecode génère des instructions VM (65 opcodes) pour la stack machine
Exécution :
VM mode : Stack-based bytecode VM avec NaN-boxing et JIT Cranelift
AST mode : Dispatch direct via Registry (52 opérations)

Composants principaux

Composant	Rôle	Implémentation	Opcodes
Parser	Analyse syntaxique Tree-sitter	Rust	-
Transformer	Parse tree → IR (Intermediate Repr.)	Rust (72 transformateurs)	IROpCode 56
Semantic	Analyse et optimisation IR → Op	Rust (6 passes)	OpCode 56
CFG	Control Flow Graph pour analyse	Rust (dominance, loops)	-
Compiler	Op → Bytecode (mode VM uniquement)	Rust	VMOpCode 68
VM	Exécution bytecode stack-based	Rust (NaN-boxing, JIT)	-
Registry	Dispatch direct des opérations (mode AST)	Rust (52 opérations)	-
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
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.)

Où trouver le code

catnip/
├── __init__.py          # Classe principale Catnip
├── context.py           # Contexte d'exécution
├── nodes.py             # Nœuds AST (Ref, patterns, signaux)
├── semantic/            # Wrappers Python pour semantic Rust
├── transformer/         # Wrappers Python pour transformer Rust
└── vm/                  # Bridge Python pour VM Rust

catnip_rs/
├── grammar/             # Grammaire Tree-sitter (grammar.js)
└── src/
    ├── core/            # Scope, Op, Registry
    ├── ir/              # OpCodes IR
    ├── parser/          # Transformateurs (72 modules)
    ├── semantic/        # Analyzer + 6 passes d'optimisation
    ├── cfg/             # Control Flow Graph (dominance, loops)
    ├── vm/              # VM bytecode (compiler, frame, value)
    ├── jit/             # JIT Cranelift
    ├── cache/           # Cache system (backends, memoization)
    ├── config/          # ConfigManager (TOML, XDG)
    └── pragma/          # Directives de compilation

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 simple et composable, dans l'esprit Unix. Chaque étape fait une chose et la fait bien. Sauf que chaque étape dépend de la précédente, ce qui est moins Unix mais plus pratique pour interpréter du code.