Potlačení a baseline
********************

.[perex]
Jak vypnout pravidlo na jednom řádku, v bloku nebo v celém souboru, proč potlačení zastaví i opravu, a jak nasadit DressCode na velký projekt bez obřího commitu díky baseline.


Čtyři úrovně
============

Výjimky z pravidel osobně nemám rád a v kódu je nepíšu; když už, tak v konfiguraci pro celou cestu. Ale jsou místa, kde pravidlo prostě nemá pravdu, a pak je dobré mít přesný nástroj a ne kladivo. DressCode má čtyři, od nejužšího po nejširší:

| úroveň | jak | kde |
|---|---|---|
| jeden řádek nebo příkaz | `// dresscode:ignore` | v kódu |
| blok | `dresscode:disable` a `dresscode:enable` | v kódu |
| soubor | `dresscode:ignore-file` | v kódu |
| cesta | `excludeRulePaths`, `excludePaths` | v konfiguraci |

A vedle nich **baseline**, která není výjimka z pravidla, ale z času: zapíše porušení, která v projektu jsou dnes, a hlásí jen nová.

Ať zvolíte cokoli, platí jedna věc: **potlačené porušení se neopraví.** Pravidlo smí měnit kód jen poté, co ho ohlásilo a hlášení prošlo, a hlídá to engine, ne autor pravidla. Potlačení tedy není jen ticho ve výpisu, je to skutečné vypnutí.


Na řádku
========

Komentář `dresscode:ignore` na konci řádku potlačí porušení na tomto řádku. Bez jména potlačí všechna pravidla, se jménem jen to jedno; víc jmen oddělte čárkou:

```php
$isEmpty = $value == null; // dresscode:ignore dresscode/strict-comparison
```

Komentář na vlastním řádku platí pro příkaz, který začíná na řádku pod ním, i když se ten příkaz táhne přes víc řádků:

```php
// dresscode:ignore dresscode/multi-line-array
$matrix = [[1, 0, 0],
	[0, 1, 0],
	[0, 0, 1]];
```

Funguje `//`, `#` i `/* */`. Jméno pravidla je to z výpisu; místo něj DressCode přijme i jméno pravidla PHP CS Fixeru nebo PHP_CodeSniffer, které jeho pravidlo pokrývá, a stejně tak rozumí komentářům `phpcs:ignore`, `phpcs:disable`, `phpcs:enable`, `phpcs:ignoreFile` a anotaci `@phpcsSuppress`. Kdo přechází z jiného nástroje, nemusí do kódu sahat; přepis na nová jména udělá [`dresscode migrate-suppressions` |migration#3. Přepište komentáře].


V bloku
=======

```php
// dresscode:disable dresscode/line-length
$data = ['alpha' => 1, 'beta' => 2, 'gamma' => 3, 'delta' => 4, 'epsilon' => 5, 'zeta' => 6, 'eta' => 7];
$more = ['theta' => 8, 'iota' => 9, 'kappa' => 10, 'lambda' => 11, 'mu' => 12, 'nu' => 13, 'xi' => 14];
// dresscode:enable
```

`disable` bez jména vypne všechna pravidla až po `enable`; bez `enable` až do konce souboru.


V souboru
=========

```php
<?php // dresscode:ignore-file
```

Komentář kdekoli v souboru vypne pro něj všechna pravidla. Hodí se pro generovaný kód, který leží mezi ručně psaným; když generovaných souborů je víc, je čistší je vyloučit cestou nebo podle obsahu (`skipWhen` v [konfiguraci |configuration#Cesty]).


Pro cestu
=========

Výjimka, která platí pro celý adresář, patří do konfigurace, ne do stovky souborů:

```neon
excludeRulePaths:
	dresscode/strict-comparison: [legacy]
	dresscode/line-length: [tests/fixtures]
```

Soubor pak zkontroluje zbytek pravidel. Celé cesty vynechá `excludePaths`; obojí je popsané v [Konfiguraci |configuration#Cesty].


Baseline
========

Na projektu s tisíci porušeními má první `fix` podobu jednoho obřího commitu. Někdy je to přesně to, co chcete udělat a mít za sebou. Někdy ne: kód se právě reviduje na jiné větvi, tým na to nemá týden, nebo chcete pravidlo zapnout jen pro nový kód. Pro ty případy je baseline.

```shell
vendor/bin/dresscode check --generate-baseline
```

/--pre .[terminal]
Baseline with 1408 violations written to dresscode-baseline.neon.
Name it in the configuration to make it apply.
\--

Soubor vznikne vedle konfigurace a má její formát (`.neon` vedle `dresscode.neon`, `.php` vedle `dresscode.php`). Platí od chvíle, kdy ho konfigurace pojmenuje:

```neon
baseline: dresscode-baseline.neon
```

Uvnitř je pro každý soubor seznam porušení s pravidlem, zprávou a otiskem:

```neon
files:
	src/Cart.php:
		-
			rule: dresscode/strict-comparison
			message: 'The == comparison must be written ''==='''
			fingerprint: a91a46b053d6d827
```

Otisk se počítá z pravidla, zprávy a obsahu řádku, ne z jeho čísla, takže baseline přežije úpravy jinde v souboru. Porušení z baseline se nehlásí ani neopravují a shrnutí běhu je přizná, aby nikdo nežil v omylu, že je čisto:

/--pre .[terminal]
OK  1408 violations in the baseline in 214 files
\--

Když porušení z baseline zmizí, protože ho někdo opravil, běh upozorní, že položka už ničemu neodpovídá, a stačí baseline vygenerovat znovu. Baseline se má zmenšovat; jakmile je prázdná, řádek z konfigurace smažte a soubor s ním.