# Compacteurs et filtres personnalisés

> Écrivez un filtre TOML qui resserre la sortie de vos propres commandes, installez-le avec tokenade add-compactor et partagez des filtres de projet sans risque.

Source: https://tokenade.net/fr/docs/custom-compactors · Updated: 2026-10-07

Quand Tokenade ne compacte une commande que de façon générique (un outil interne, un outil de build peu répandu), vous pouvez lui apprendre ce qui compte dans cette sortie avec un filtre TOML déclaratif. Pas de code : vous décrivez la commande visée et ce qu'il faut retirer ou garder, et Tokenade valide le fichier avant de s'en servir.

## Installer un filtre en une commande

```bash
tokenade add-compactor --file mytool.toml
```

Le fichier est d'abord validé : chaque regex est compilée et chaque cas `[[tests]]` est exécuté. Au moindre échec, rien n'est installé. Sinon, le filtre est écrit dans `~/.tokenade/filters/<name>.toml` et s'applique aux commandes correspondantes dès l'exécution suivante. Ses économies apparaissent dans `tokenade gain` et le tableau de bord sous son `name`.

Autres formes :

```bash
tokenade add-compactor < mytool.toml        # lit le TOML sur l'entrée standard
tokenade add-compactor --list               # liste les compacteurs installés
tokenade add-compactor --from sample.txt --command "mytool status"
```

`--from` génère un filtre de départ à partir d'une vraie sortie capturée et affiche le TOML. Ce brouillon porte `draft = true`, et l'installation est refusée tant que vous ne l'avez pas relu et n'avez pas retiré cette ligne.

## Un exemple complet

```toml
name = "mytool-status"
match_command = "^mytool\\s+status"
strip_ansi = true
strip_lines_matching = ["^DEBUG", "^\\s*$"]
match_output = [{ pattern = "All systems go", summary = "mytool: ok" }]
head_lines = 40
tail_lines = 5
on_empty = "mytool: ok"

[[tests]]
input = "DEBUG boot\nAll systems go\n"
expect_contains = "mytool: ok"
```

## Champs

| Champ | Obligatoire | Rôle |
|---|---|---|
| `name` | oui | Libellé dans les rapports et nom du fichier. |
| `match_command` | oui | Regex testée sur la ligne de commande entière. Quand plusieurs filtres correspondent, celui qui couvre la portion **la plus longue** l'emporte. |
| `priority` | non (défaut `0`) | Départage uniquement des correspondances de même longueur ; la plus haute gagne. Ne passe jamais devant une correspondance plus longue. |
| `draft` | non | Posé par `--from`. Retirez-le pour installer. |

Deux gabarits se développent dans `match_command` : `{{runner}}` devient `(npx|bunx|pnpm dlx|yarn dlx)` et `{{py-runner}}` devient `(poetry run|uv run|python -m)`. Un `{{token}}` inconnu est une erreur bloquante.

Les champs inconnus sont refusés : une coquille comme `expect` au lieu de `expect_contains` fait échouer la validation au lieu de sauter votre test en silence.

## Opérations

Elles s'appliquent dans cet ordre ; il en faut au moins une.

1. `match_output` : liste de `{ pattern, summary }`. Si `pattern` correspond n'importe où, **toute** la sortie est remplacée par la ligne `summary` (un build propre devient `build: ok`).
2. `strip_ansi` : `true` retire les séquences de couleur ANSI.
3. `replace` : liste de substitutions regex `{ from, to }` ; `to` peut utiliser `\1`.
4. `strip_lines_matching` : liste de regex ; chaque ligne qui correspond est retirée.
5. `on_empty` : si les étapes précédentes n'ont rien laissé, cette ligne unique est émise à la place.
6. `head_lines` / `tail_lines` : garde les N premières et M dernières lignes ; le milieu devient un marqueur `… [K lines omitted]`, et la ligne de résultat finale survit.
7. `max_lines` : plafond strict du nombre de lignes gardées, avec une étiquette `… [K more]`.

Pour une sortie qui passe par des phases (compilation, puis tests, puis échecs), le format accepte aussi des entrées `[[phases]]` avec une regex `keep` optionnelle (lignes gardées pendant la phase ; toutes si elle est absente) et une regex `until` optionnelle (passe à la phase suivante). La dernière phase n'a pas besoin de `until`.

## Auto-tests

Chaque bloc `[[tests]]` contient un `input` et soit `expect_contains`, soit `expect_equals`. Ils conditionnent l'installation : un filtre dont le test échoue n'est pas écrit. Prévoyez-en au moins un par sortie réelle qui vous importe.

## Filtres de projet et confiance

Un dépôt peut livrer des filtres dans `.tokenade/filters/*.toml`. Tokenade examine deux emplacements, dans cet ordre :

1. `.tokenade/filters/` dans le dossier courant (couche projet)
2. `~/.tokenade/filters/` (vos propres filtres, toujours approuvés)

Si les deux définissent le même `name`, le fichier du projet gagne et le global est masqué.

Un filtre de projet est du code que vous n'avez pas écrit : il pourrait transformer une suite de tests en échec en « tous les tests passent ». Les filtres de projet ne font donc **rien** tant que vous ne les avez pas approuvés :

```bash
tokenade trust-filters --list   # montre les filtres non approuvés, n'approuve rien
tokenade trust-filters          # approuve les filtres de projet de ce dossier
```

La confiance porte sur le **contenu** du fichier et est enregistrée dans `~/.tokenade/trusted-filters.json`. Modifier un fichier approuvé annule l'approbation : relancez `tokenade trust-filters` après avoir relu le changement.

Un fichier de filtre de plus de 256 Kio est refusé sans être lu.

## Vérifier ce qui est chargé

`tokenade healthcheck` affiche deux lignes pour les filtres :

- `project-filters` : compacteurs de projet en attente d'approbation (information, pas un échec).
- `filter-syntax` : fichiers de compacteur illisibles, qui ne s'appliquent donc jamais (échec). Le détail donne la raison exacte. Corrigez le fichier ou supprimez-le.

Pour essayer un filtre sur une sortie enregistrée sans relancer la commande, passez-la à `tokenade filter <cmd…>`, qui filtre l'entrée standard comme si elle venait de cette commande. Voir [wrap, raw et filter](https://tokenade.net/fr/docs/wrap-raw-filter).

Pour comprendre pourquoi un filtrage propre à chaque commande est rentable, lisez [Filtrer la sortie des commandes](https://tokenade.net/fr/articles/output-filtering-command-logs).

## Voir aussi

- [Compaction des sorties et réserve](https://tokenade.net/fr/docs/compaction)
- [wrap, raw et filter](https://tokenade.net/fr/docs/wrap-raw-filter)
- [Fichiers et chemins](https://tokenade.net/fr/docs/files-and-paths)
- [Dépannage](https://tokenade.net/fr/docs/troubleshooting)
