Filtres TOML

Où les filtres se chargent

Boost fusionne les filtres de plusieurs emplacements et applique chaque filtre sélectionné par la commande ou la sortie. Les fichiers d'un dossier se chargent dans un ordre déterministe.

1. Filtres intégrés livrés avec Boost (make, terraform, shellcheck, …)
2. ~/.boost/filters/*.toml (dossier global, un filtre par fichier)
3. .boost/filters/*.toml dans le projet — cwd, puis racine git, puis $GITHUB_WORKSPACE

Project discovery loads only .boost/filters/*.toml — it does not read, create, or require a repo-level .boost/config.toml. Filters committed at the repo root apply from subdirectories. If the same name appears in more than one project dir, cwd wins. Enable/disable still uses ~/.boost/config.toml.

Les sources sont fusionnées, pas remplacées. Un filtre projet ne remplace pas un filtre intégré du même nom — les deux se chargent (nom + source), et chaque filtre dont match_command ou match_output_select correspond s'applique dans l'ordre (builtin → global → project). Pour remplacer un intégré, désactivez-le avec boost filters disable et publiez le vôtre.

Create a project filter

Ship team filters in .boost/filters/ at the repo root. Anyone who clones the repo — and runs Boost from a subdirectory or CI — gets the same compression automatically.

1. mkdir -p .boost/filters
2. Add one .toml file per filter. The name comes from [filters.<name>]. Use match_command plus a distinctive match_output_select so the filter selects on the agent pipe path.
3. Commit the file with the repo.
4. From a subdirectory, run boost filters show — the filter should appear with SOURCE=project.

schema_version = 1

[filters.acme-cli]
description = "Keep errors and warnings from the internal acme-cli"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:\S*/)?acme-cli\b'
match_output_select = [
  '(?m)^acme-cli v',
]
strip_ansi = true
keep_lines_matching = [
  '^acme-cli v',
  '^Error:',
  '^Warning:',
  '^✗',
]
on_empty = "acme-cli: ok"

Confirm it loaded

# From any subdirectory of the repo:
boost filters show | grep acme-cli
# → enabled   project     acme-cli   toml:project:acme-cli

After boost init, agent shell commands are piped through Boost automatically. No repo-level .boost/config.toml is required for project filters; enable/disable still uses ~/.boost/config.toml. For a fuller end-to-end example with before/after output, see the deploy script section below.

Disposition des dossiers (un filtre par fichier)

Les filtres personnalisés vivent dans des fichiers à un seul filtre : chaque fichier contient un bloc [filters.<name>] et des exemples [[tests.<name>]].

~/.boost/filters/                 # global (this machine)
  my-personal.toml

<repo>/.boost/filters/            # project (commit with the team)
  acme-cli.toml
  deploy.toml

Les filtres dans ~/.boost/filters/ sont pris en charge au prochain processus boost sans recompilation.

Sélecteurs et champs courants

Chaque filtre a besoin d'au moins un sélecteur. Ces champs apparaissent dans presque tous les exemples ; le glossaire complet est en bas de page.

Variante regex

Tous les motifs utilisent le paquet regexp de Go (syntaxe RE2), pas PCRE. Pas de backreferences ni de lookbehind. Les ancres multilignes ^/$ nécessitent (?m). Voir regexp/syntax.

Exemple : script de déploiement personnalisé

Votre équipe exécute ./scripts/deploy.sh via Boost. Le hook n'envoie que la sortie, donc match_output_select est nécessaire en plus de match_command.

schema_version = 1

[filters.deploy]
description = "Keep failures from deploy.sh"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:bash\s+)?(?:\S*/)?deploy\.sh\b'
# The hook pipes output to boost, so select by a distinctive output signature.
# (?m) makes ^ and $ match each line, not only the full output boundaries.
match_output_select = [
  '(?m)^Starting deployment$\n^Environment: ',
]
strip_ansi = true
keep_lines_matching = [
  '^Starting deployment$',
  '^Environment: ',
  '^\[(WARN|ERROR)\]',
  '^ERROR DETAILS:$',
  'failed readiness probe',
  '^File:$',
  '^deploy/check_health\.go:\d+$',
  '^Reason:$',
  '^connection refused',
  '^Rollback started\.\.\.$',
  '^Deployment FAILED$',
]

[[tests.deploy]]
name = "keeps failures, drops info chatter"
input = """
Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""
expected = """
Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""

Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging

Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging

Tests inline

Chaque bloc [[tests.<name>]] est un fixture de régression : name, input et expected. expect_match_output optionnel vérifie la sélection via match_output_select.

Comment les exécuter

Il n'y a pas encore de boost filters test. Vérifiez les filtres personnalisés en envoyant un échantillon via boost. Les fixtures intégrés tournent avec go test :

# Spot-check a custom filter: pipe sample output through boost
printf '%s\n' 'Starting deployment' 'Environment: staging' '[INFO] noise' | boost

# Built-in [[tests.*]] fixtures run in the Boost repo / CI:
go test ./internal/tomlfilter/ -run TestInlineTestDefs

Exemple : réduire le bruit make

Les filtres intégrés utilisent le même schéma. Ceci reflète le filtre make livré : supprime les lignes d'entrée/sortie de répertoire et les lignes vides.

schema_version = 1

[filters.make]
match_command = "^make\\b"
match_output_select = [
  "^make\\[\\d+\\]:",
  "^gcc ",
]
strip_lines_matching = [
  "^make\\[\\d+\\]:",
  "^\\s*$",
  "^Nothing to be done",
]
on_empty = "make: ok"

make[1]: Entering directory '/home/user/app'
gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

make[1]: Leaving directory '/home/user/app'

gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

Exemple : court-circuit sur lint propre

Utilisez match_output pour renvoyer un résumé d'une ligne quand l'outil a réussi silencieusement.

schema_version = 1

[filters.eslint-quiet]
match_command = "^eslint\\b"
match_output_select = [
  "problems",
]
match_output = [
  { pattern = "0 problems", message = "eslint: ok" },
]

Désactiver un filtre

Préférez la CLI :

boost filters show                 # inventory with enabled/disabled status
boost filters show --enabled       # enabled filters only
boost filters disable git-status   # bare name or toml:builtin:git-status
boost filters enable git-status

Ou éditez ~/.boost/config.toml directement — listez les noms sous [filters] disabled. Après retrieve_disable_threshold événements retrieve (défaut 3), boost retrieve ajoute automatiquement les noms rollback. Mettez 0 pour désactiver l'auto-disable.

[filters]
disabled = ["git-status", "make"]
retrieve_disable_threshold = 3

Champs de filtre

Mettez schema_version = 1 en tête de chaque fichier. Étapes : strip ANSI → replace → match_output → strip/keep → dedupe → collapse → head/tail → on_empty. Référence complète dans docs/TOML_FILTERS.md.