Compacteurs et filtres personnalisés

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

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 :

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

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.

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).
strip_ansi : true retire les séquences de couleur ANSI.
replace : liste de substitutions regex { from, to } ; to peut utiliser \1.
strip_lines_matching : liste de regex ; chaque ligne qui correspond est retirée.
on_empty : si les étapes précédentes n'ont rien laissé, cette ligne unique est émise à la place.
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.
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 :

.tokenade/filters/ dans le dossier courant (couche projet)
~/.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 :

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.

Pour comprendre pourquoi un filtrage propre à chaque commande est rentable, lisez Filtrer la sortie des commandes.