Contribuer

Miravo est open source et accueille les contributions.

Prérequis

• Bun (dernière version)
• Git

Installation

git clone https://github.com/amine-amaach/miravo.git
cd miravo
bun install

Structure du monorepo

miravo/
  packages/
    cli/            # Point d'entrée CLI (Commander.js)
    core/           # Moteur, scheduler, générateurs, twin runtime
    shared/         # Schémas Zod, types, constantes
    content/        # Modèles et templates intégrés
    console/        # Tableau de bord web (React + shadcn/ui + Vite)
    protocols/
      mqtt/         # Adaptateur MQTT (aedes intégré + mqtt.js externe)
      opcua/        # Adaptateur OPC UA (node-opcua)
    web/            # Site de documentation (Astro + Starlight)
  tests/fixtures/   # Templates de stress
  scripts/          # Scripts de build et release

Les packages utilisent "workspace:*" pour les dépendances inter-packages.

Commandes de développement

Exécuter le CLI en mode dev :

bun run dev

Exécuter tous les tests :

bun run test

Exécuter les tests d’un package spécifique :

bun run test --cwd packages/core

Vérification de types (requis — Bun ne vérifie pas les types) :

bun run typecheck

Lint :

bun run lint

Lint et correction automatique :

bun run lint:fix

Formatage :

bun run format

Vérification de types

Bun transpile TypeScript mais ne vérifie pas les types. Exécutez toujours :

bun run typecheck

Cela exécute tsc -b (mode build) qui suit les références de projet. N’utilisez pas tsc --noEmit — cela ne vérifie rien avec la config racine du monorepo.

Conventions de test

• Fichiers de test : *.test.ts colocalisés à côté des fichiers source
• Import depuis bun:test : import { describe, test, expect } from "bun:test"
• Les tests doivent asserter des valeurs spécifiques, pas seulement que le code s’exécute sans erreur
• Ne jamais modifier un test qui échoue pour le faire passer — corriger l’implémentation
• Ne jamais mocker ce qui est testé

Exécuter un fichier de test unique :

bun run test packages/core/src/scheduler.test.ts

Lint

Miravo utilise Biome pour le lint et le formatage (pas ESLint/Prettier) :

Vérifier :

bun run lint

Correction automatique :

bun run lint:fix

Formater tous les fichiers :

bun run format

Style de code

• ES modules uniquement (import/export)
• Utiliser import type { X } pour les imports de types uniquement
• Préférer les APIs Bun à Node.js (Bun.write() plutôt que writeFile)
• Pas de any — utiliser unknown et réduire avec Zod ou des gardes de type
• Préférer interface à type pour les formes d’objets
• Les schémas Zod sont la source de vérité unique — dériver les types avec z.infer<>

Définition de “terminé”

Une tâche est complète quand :

bun run typecheck && bun run test && bun run lint

Les trois doivent passer sans échec.

Nommage des branches

• feat/ — Nouvelles fonctionnalités
• fix/ — Corrections de bugs
• refactor/ — Restructuration de code
• docs/ — Modifications de documentation

Messages de commit

Utilisez les commits conventionnels :

feat: add transport-delay generator
fix: correct lifecycle stage transition timing
refactor: extract generator input resolution
docs: update MQTT adapter reference