Řešení potíží

Čistý výsledek, který čistý být nemá, hláška o pravidlech, která se neustálí, editor, který po uložení vrací, co DressCode opravil: ke každé takové situaci tu najdete příčinu a nápravu.

Proč je čisto, i když nemá být

Běh skončil s OK a vy víte, že by neměl. Odpověď najdete v hlavičce a ve shrnutí:

• OK 36 violations in the baseline: porušení tam jsou, ale baseline je zná. Vygenerujte ji znovu, nebo ji z konfigurace odeberte.
• Soubor není v rozsahu kontroly. Hlavička říká, kolik souborů se kontroluje. Ve výchozím stavu jsou vyloučené vendor, node_modules, temp, tmp, log a všechny adresáře i soubory začínající tečkou, k tomu excludePaths z konfigurace i z pluginů. Pozor: vyloučené cesty se jen sčítají, a co jednou vyloučíte, žádná vrstva zpátky nezahrne.
• Rozhodnutí se neuplatní. dresscode config vypíše u každého rozhodnutí hodnotu, vrstvu, která ji nastavila, a u toho, které se neuplatní, proč: no effect: php, když potřebuje novější PHP, než je cílová verze, no effect: types, když potřebuje typy, které konfigurace nemá, a podobně. Rozhodnutí, které nenastaví standard, sada ani konfigurace, je keep a nevyžaduje nic; dresscode explain <cesta> řekne, jaké hodnoty bere a co mu dávají standardy.
• Pravidlo se vynechalo kvůli verzi PHP. Pravidlo pro novější syntaxi se pod cílovou verzí projektu samo vypne, a pokud jeho rozhodnutí jmenuje vaše konfigurace, běh o tom napíše varování. Cílovou verzi ukazuje hlavička jako Target PHP 8.2 from `composer.json`. Když tam stojí PHP 8.0 by default, `composer.json` names no PHP version in `require`, přestože composer.json máte, DressCode z jeho require.php nejnižší verzi nevyčetl. Čte jakýkoli zápis omezení, kterému rozumí Composer, jenže omezení bez spodní meze (<8.4, *) nejnižší verzi neurčuje a z neplatného zápisu DressCode raději nehádá. Verzi pak nastavte klíčem targets: {php: '8.2'}.
• Oprava je riziková. Shrnutí říká třeba 1 risky fix waits, the type is unknown: set `typeAnalysis: phpstan`: jde o rizikovou opravu (risky fix), která by mohla změnit chování kódu, a tak ji fix jen ohlásil. Věta ve shrnutí říká, co by opravu rozhodlo, a odkaz za ní vede na návod. Kde chybí typy, zapněte typeAnalysis: phpstan; u rozhodnutí jako hygiene.is_null nebo hygiene.aliasFunctions, jejichž oprava stojí na tom, že je funkce globální, řekněte DressCode, co je ve vašich jmenných prostorech, a s klíčem nameResolution: certain tyhle opravy rizikové nejsou vůbec. Kde oprava mění chování ze své podstaty, rozhodujete vy: jednu po druhé s fix --ask-risky, cestou rozhodnutí v seznamu fixRisky, nebo přepínačem --fix-risky pro jeden běh. Proč je konkrétní místo rizikové, ukáže výpis na řádku pod porušením. Která rozhodnutí s rizikovými opravami jste přijali, ukáže dresscode config poznámkou risky fixes accepted.
• Pravidlo jen varuje. Klíč severity ho změkčil na warning (tak to mají file.longLines standardy psr12 a perCs), takže porušení hlásí se značkou warning a exit kód nemění; práh nastavíte přepínačem --max-warnings. dresscode config takové rozhodnutí označí poznámkou only warns.
• Cache. Soubor se stejnou cestou, stejným obsahem a stejnou konfigurací se přeskočí. Konfigurace, baseline i soubory vlastních pravidel projektu jsou součástí klíče, takže jejich změna cache zneplatní sama. Výjimkou je pravidlo sestavené továrnou, která čte ještě jiný soubor než konfiguraci: jeho změnu cache nepozná, a tam pomůže --no-cache.
• Potlačení v kódu. dresscode:ignore i phpcs:ignore platí i pro opravu a dresscode:disable bez enable platí až do konce souboru. Rozhodnutí se v komentáři píše celou cestou jako v konfiguraci, mistakes.strictArgument, případně jen sekcí, která potlačí všechno pod sebou; jiný zápis, třeba strict-calls, DressCode nepozná a komentář nic nepotlačí.

Hlášky, které stojí za vysvětlení

No `dresscode.neon` or `dresscode.php` found in `/var/www/shop` or above it, so there is no dress code to check against. Run `dresscode init` to have one made to measure from the code, or name a standard with `--use`. DressCode sám žádný styl nenosí, a tak bez konfigurace nic nekontroluje ani neopravuje. Konfiguraci změří z kódu příkaz dresscode init; na zkoušku stačí zvolit standard přepínačem --use, třeba --use perCs.

No paths given and none configured. Bez konfiguračního souboru musíte cesty zadat na příkazové řádce; se souborem stačí klíč paths.

Key `no_unused_imports` is unknown. It is the name of a rule of another tool, covered by `imports.unused`; `dresscode migrate config` translates a configuration of another tool. Do konfigurace i na příkazovou řádku patří cesty rozhodnutí DressCode; jména jiných nástrojů platí jen v potlačovacích komentářích. Cizí jméno hláška rovnou přeloží, celý cizí konfigurační soubor převede příkaz migrate config. Když klíč přišel z přepínače --set, začíná hláška slovy The command line:.

Key `imports.unsed` is unknown; write `imports.unused`. Překlep v cestě; hláška nabídne nejbližší známou. Když cesta patří do sekce pluginu, třeba acme.debugCalls, a hláška ji nezná, není plugin v klíči use, ani třídou, ani jménem balíčku, který ho přináší.

Package `acme/code-style` brings the plugin `Acme\CodeStyle\Plugin`, which loads only where `use` names the package or the plugin; skipped. Nainstalovaný balíček nese plugin, ale projekt ho nepustil dovnitř. Plugin přináší kód, který běží při každé kontrole, a tak se načte, jen když jméno balíčku nebo třídu pluginu napíšete do klíče use; viz Pluginy.

Name `types` is both a section of decisions and the preset `dresscode/types`; write `types.*` for the section or `dresscode/types` for the preset. Jméno v --only, fixRisky nebo severity je zároveň sekcí i sadou a DressCode neví, kterou myslíte. Napište, co chcete: types.* pro sekci, dresscode/types pro sadu. Jiné sekce se se sadami nepletou: sady cleanup a correctness mají své sekce pojmenované hygiene a mistakes.

Rule `Acme\CodeStyle\NoDebugCallsRule` declares no decision. Pravidlo z klíče rules nebo z pluginu nevrací z getDecisions() žádné rozhodnutí. Každé porušení se hlásí pod rozhodnutím, a tak pravidlo aspoň jedno mít musí; viz Pravidlo do detailu.

Decision `classes.overridingMethod.signature` needs the types of the code; set `typeAnalysis: phpstan` in the configuration and install `phpstan/phpstan` beside DressCode. Rozhodnutí, jehož pravidlo se ptá na typy, jste napsali v konfiguraci, ale ta žádné typy nemá. Ze standardu nebo ze sady by se takové rozhodnutí tiše neuplatnilo, jenže o rozhodnutí v konfiguraci jste požádali výslovně, a tak je to chyba konfigurace s exit kódem 3. Nastavte typeAnalysis: phpstan, jak radí hláška, nebo rozhodnutí z konfigurace odeberte; viz Typy z PHPStanu.

Key `file.lineLength` does not take `abc`; write a count from `1` or `none`. Hodnota mimo obor, který rozhodnutí bere; hláška řekne, co bere. Celý obor i s významem každého slova vypíše dresscode explain file.lineLength.

Rules `Acme\CodeStyle\OneRule` and `Acme\CodeStyle\TwoRule` do not converge in `src/Cart.php`. Dvě pravidla se přetahují: jedno kód změní, druhé ho vrátí zpátky, a strom se tak dostal do stavu, ve kterém už jednou byl. Jádro to pozná, soubor ohlásí jako selhání (exit kód 2) a nic do něj nezapíše. Vestavěná pravidla se nekříží, takže hláška ukazuje na vlastní pravidlo nebo na plugin a jmenuje obě strany sporu. Pod ní bývá rozdíl mezi oběma stavy, ze kterého je vidět, o co se pravidla přou. Než to vyřešíte, nechte rozhodnutí jednoho z nich na keep. Kdyby hláška jmenovala dvě vestavěná pravidla, je to chyba DressCode; nahlaste ji i s tím rozdílem.

The file changed while it was being fixed, so it was not written; run `fix` again. Soubor mezitím uložil editor nebo jiný nástroj. DressCode těsně před zápisem ověří, že soubor pořád obsahuje text, který opravoval, a když ne, nic nezapíše, aby vaše změny nepřepsal. Soubor se ohlásí jako selhání (exit kód 2); stačí fix pustit znovu.

Rule `Acme\CodeStyle\NoDebugCallsRule` is faulty: it changed the file without reporting a violation. (nebo after a suppressed report) znamená, že pravidlo porušilo kontrakt: každá změna stromu musí následovat až po volání report(), které vrátilo true. U vestavěných pravidel to hlídá RuleTester, u vlastního pravidla je to chyba v něm. Přepínač --strict-rules z takového varování udělá chybu, aby neproklouzlo testy.

Chyba konfigurace o dvou pravidlech, která chtějí rozhodovat o téže mezeře. Dvě pravidla pro bílé znaky si nárokují totéž místo; jádro to odmítne, protože jinak by výsledek závisel na pořadí. Pevné nároky porovná hned u prvního zpracovaného souboru, a když pravidlo o svém nároku rozhoduje až podle kódu, ohlásí spor v místě, kde se oba nároky sejdou. Stát se to může jen s pravidlem z pluginu nebo s vlastním pravidlem projektu.

Soubor se syntaktickou chybou se vypíše s číslem řádku a exit kód je 1, stejně jako u porušení. DressCode ho neopravuje, ale ani mlčky nepřeskočí: na kódu, který PHP nepřijme, se styl měřit nedá.

Warning: 3 entries of the baseline no longer match a violation; regenerate it with `dresscode baseline`. znamená, že porušení, které baseline zná, v kódu už není: opravil ho někdo ručně, nebo fix, jakmile se stalo opravitelným. Nic se neděje, jen baseline přestala odpovídat skutečnosti; vygenerujte ji znovu. Hlásí se jen položky souborů, které běh zpracoval, a při --only jen položky rozhodnutí, která běžela, takže kontrola části projektu neoznačí za zastaralé to, na co se vůbec neptala.

Baseline file `/var/www/shop/dresscode-baseline.neon` is not of the version this DressCode writes; generate it again with `dresscode baseline`. Soubor baseline nemá na začátku version: 2, takže nemá tvar, který DressCode čte, a běh skončí s exit kódem 3. Starý soubor smažte, pusťte fix a dresscode baseline ho zapíše znovu.

Editor a konfigurace

Když editor soubor opravený příkazem dresscode fix při uložení přeformátuje zpátky, přetahují se o něj dva formátovače: DressCode a vestavěný formátovač editoru. Vypněte vestavěné formátování PHP v PhpStormu nebo výchozí formátovač pro PHP ve VS Code, případně aspoň formátování při uložení.

Když DressCode hlásí, že konfiguraci nenašel, ačkoli ji projekt má, zkontrolujte, odkud ho spouštíte. Konfiguraci hledá od pracovního adresáře směrem nahoru, ne od kontrolovaných souborů, takže spuštěný mimo projekt ji nenajde. Pomůže spustit ho z kořene projektu, nebo cestu ke konfiguraci předat přepínačem --config.

Konce řádků

Hláška Expected LF line endings, CRLF found. znamená, že konfigurace nebo preset předepisuje pevný konec řádku (file.lineEnding: LF) a soubor má jiný; nález je jeden na celý soubor. Projekt, který chce konce řádků nechat tak, jak jsou, a jen je uvnitř souboru sjednotit, nastaví file.lineEnding: majority, a tak to má i všech pět standardů. Projekt na Windows, kde konce řádků převádí Git, má převod nechat na Gitu a zůstat u majority: soubor v pracovním stromu má CRLF a DressCode ho tak nechá.