Příkazová řádka
***************

.[perex]
Příkazy check, fix, rules, import a migrate-suppressions se všemi volbami, formáty výstupu pro terminál, CI a hooky, exit kódy, cache a paralelní běh.


Příkazy
=======

```shell
vendor/bin/dresscode check [cesty...]
vendor/bin/dresscode fix [cesty...]
vendor/bin/dresscode rules
vendor/bin/dresscode import <soubor>
vendor/bin/dresscode migrate-suppressions [cesty...]
vendor/bin/dresscode lsp
```

- `check` ohlásí porušení a nic nezapíše.
- `fix` opraví, co pravidla umějí, a ohlásí zbytek. Soubor se zapíše jen tehdy, když se změnil a výsledek znovu parsuje stejně; soubor se syntaktickou chybou nebo se selhavším pravidlem zůstane netknutý.
- `rules` vypíše všechna známá pravidla: hvězdičku u zapnutých v aktuální konfiguraci, fázi, popis a jména pravidel jiných nástrojů, která pokrývají. Hodí se k hledání, jak se co jmenuje.
- `import` přeloží konfiguraci PHP CS Fixeru nebo PHP_CodeSniffer, viz [Přechod |migration#2. Přeložte konfiguraci].
- `migrate-suppressions` přepíše komentáře `phpcs:*` na `dresscode:*`, viz [tamtéž |migration#3. Přepište komentáře].
- `lsp` spustí jazykový server pro [editory |editors].

Cesty jsou soubory nebo adresáře relativně k aktuálnímu adresáři a mají přednost před `paths` z konfigurace; bez cest i bez konfigurace příkaz skončí chybou, protože nechce hádat, co kontrolovat.


Volby
=====

| volba | význam |
|---|---|
| `-c`, `--config <soubor>` | konfigurační soubor místo nejbližšího `dresscode.neon` nebo `dresscode.php` |
| `-f`, `--format <název>` | formát výstupu, níže |
| `--diff` | u `check` ukáže, co by `fix` změnil, jako unifikovaný diff; u `fix` diff toho, co změnil |
| `--preset <název>` | přidá preset; lze opakovat |
| `--rule <název>=on` nebo `=off` | zapne nebo vypne pravidlo pro tento běh; lze opakovat |
| `--stdin <cesta>` | čte kód ze standardního vstupu, jako by to byl soubor na dané cestě; `fix` vypíše opravený kód na standardní výstup |
| `--generate-baseline` | zapíše nalezená porušení do [baseline |suppressing#baseline] místo hlášení; jen `check` |
| `--no-cache` | zpracuje každý soubor, i ten, o kterém je známo, že je čistý |
| `--jobs <n>` | počet pracovních procesů; `1` běží v jednom procesu |
| `--strict-rules` | pravidlo, které poruší svůj kontrakt, je chyba, ne varování; pro vývoj vlastních pravidel |
| `--no-color` | výstup bez barev |
| `--version`, `--help` | verze, nápověda |


Formáty výstupu
===============

Formát je celá smlouva výstupu, ne přepínač, který mění jiný formát.

`console` je výchozí na terminálu: hlavička s konfigurací, cílovou verzí PHP a rozsahem, pak soubory s porušeními (řádek, sloupec, zpráva, pravidlo) a shrnutí. Barvy se vypnou samy, když výstup není terminál.

`github` se zvolí sám, když běh je krokem GitHub Actions: každé porušení je anotace, která se ukáže přímo v diffu pull requestu.

`bare` je pro hooky a nástroje, které výstup čtou: bez hlavičky a shrnutí, jen porušení, která zůstala na uživateli, ve stejném rozvržení jako `console`, a u každého přepsaného souboru řádek `rewritten`. Čistý běh nevypíše nic.

/--pre .[terminal]
src/Cart.php  rewritten

src/Order.php
  error  12:1  The line is 133 characters long, the limit is 120  line-length
\--

`json` je strojově čitelný a stabilní: pole `files` s porušeními (pravidlo, zpráva, řádek, sloupec, závažnost, zda je opravitelné, otisk), `summary` s počty a `warnings`.

`checkstyle` je XML, kterému rozumí Jenkins, `cs2pr` a další nástroje CI.


Exit kódy
=========

| kód | význam |
|---|---|
| `0` | čisto; u `fix` také tehdy, když všechno opravil |
| `1` | zůstala porušení, nebo soubor nejde parsovat |
| `2` | selhání: špatná konfigurace, neznámé pravidlo, pravidlo, které vyhodilo výjimku nebo se s jiným zacyklilo |

Selhání jednoho souboru nezastaví běh: soubor se ohlásí jako selhavší, nic se do něj nezapíše a ostatní se zpracují dál.


Cache a paralelní běh
=====================

DressCode si pamatuje otisk obsahu každého souboru, který vyšel čistý, spolu s otiskem konfigurace, cílové verze PHP a verzí nainstalovaných balíčků. Soubor se stejným obsahem pod stejnou konfigurací příště přeskočí; jakmile se změní cokoli z toho, zpracuje ho znovu. Cache leží v systémovém dočasném adresáři, nebo tam, kam ukáže `cacheDir` v konfiguraci; `--no-cache` ji pro jeden běh obejde.

Soubory, které cache nepokryje, se rozdělí mezi pracovní procesy. Výchozí počet je počet procesorů, nejvýš jeden proces na čtyři soubory, protože start procesu něco stojí; `--jobs 1` běží bez procesů, což se hodí při ladění vlastního pravidla, a `--jobs 8` na serveru s mnoha jádry, kde by výchozí odhad byl nižší.


Standardní vstup
================

`--stdin` je rozhraní pro editory a hooky: obsah přijde na standardním vstupu, cesta říká, které pravidlo pro něj platí (výjimky pro cesty se vyhodnotí proti ní), a `fix` vrátí opravený kód na standardní výstup místo zápisu:

```shell
git show :src/Cart.php | vendor/bin/dresscode check --stdin src/Cart.php
```

Cache se u standardního vstupu nepoužívá.