Przejdź do treści

INW009 suppression-comment

Co robi

Sprawdza wyciszenia w linii, # inwards: ignore[INW001] reason="...", i zgłasza te, które nie spełniają swojego zadania:

  • błąd, a komentarz niczego nie ukrywa: jest źle sformułowany, nie ma powodu albo ma pusty, wymienia kod nieznany albo taki, którego nie da się wyciszyć (INW000, INW004, INW007, INW008, INW009), albo jest drugą dyrektywą w tym samym komentarzu;
  • ostrzeżenie: poprawny kod, który nie pasuje do żadnej diagnostyki w linii komentarza, bo po cichu ukryłby tam później nową diagnostykę. Reguła wyłączona w [tool.inwards.rules] nie jest zgłaszana jako nieużywana.

Wyciszenia są czytane z drzewa składni, więc napis, który tylko wygląda jak wyciszenie (x = "# inwards: ignore[...]"), się nie liczy.

Dlaczego to źle

Komentarz to najtańszy sposób, żeby agent zazielenił sprawdzenie. Wymóg kodu i powodu sprawia, że każdy wyjątek jest konkretny i da się go przejrzeć, a INW009 pilnuje, żeby wyciszenie, które nie spełnia tego wymogu, zawiodło głośno, zamiast być po cichu pomijane, gdy agent myśli, że sprawa jest załatwiona. Nieużywane wyciszenie to pułapka: następny import w tej linii zostałby ukryty, zanim ktokolwiek na niego spojrzy.

Przykład

Z warstwami z INW001, wyciszenie bez powodu:

shop/domain/order.py
import shop.infrastructure.db  # inwards: ignore[INW001]

inwards check

shop/domain/order.py:1:32: INW009 This suppression comment hides nothing. It has no reason: say why in `reason="..."`.
  fix: Fix the comment, or remove it and fix the finding it was meant to hide.
    1. Write it as `# inwards: ignore[INW001] reason="why this import is allowed"`, with codes of rules that can be suppressed and a reason a reviewer can check.
    2. Better, fix the import it covers, so no suppression is needed.
  docs: https://sircypkowskyy.github.io/inwards/rules/INW009/

Diagnostyka INW001 w tej samej linii też jest zgłaszana, bo komentarz niczego nie ukrywa. Po poprawce wyciszenie mówi, dlaczego:

shop/domain/order.py
import shop.infrastructure.db  # inwards: ignore[INW001] reason="legacy adapter, removed in #210"

inwards check

1 finding suppressed by inline comments.

Wyciszenie w linii bez pasującej diagnostyki daje ostrzeżenie:

shop/application/place.py
import shop.domain.order  # inwards: ignore[INW001] reason="legacy"

inwards check

shop/application/place.py:1:27: INW009 (warning) This suppression of INW001 matches no finding on its line, so it would silently hide a new one.
  fix: Remove the unused suppression.
    1. Remove INW001 from the comment, or the whole comment if no code is left.
  docs: https://sircypkowskyy.github.io/inwards/rules/INW009/

Jak naprawić

  1. Najlepiej napraw diagnostykę, którą obejmuje komentarz, żeby wyciszenie nie było potrzebne.
  2. W przeciwnym razie zapisz komentarz jako # inwards: ignore[CODE] reason="why" w linii, na którą wskazuje diagnostyka: przy imporcie w nawiasach w linii importowanej nazwy, przy imporcie dynamicznym rozpisanym na kilka linii w pierwszej linii wywołania. Kilka kodów mieści się w jednej dyrektywie, ignore[INW001,INW005].
  3. Usuń wyciszenie, które nie pasuje do żadnej diagnostyki, albo niepasujący kod z niego.

Bezpieczeństwo poprawki

Brak automatycznej poprawki (autofix: false). Powód może napisać tylko człowiek, a usunięcie nieużywanego wyciszenia to jednolinijkowa zmiana, którą recenzent powinien zobaczyć.

Konfiguracja

Poziom: błąd, a nieużywane wyciszenia to ostrzeżenia. [tool.inwards.rules] może wyłączyć INW009 albo zmienić jej poziom jak każdej reguły (Konfiguracja reguł). Nie może wyciszyć samej siebie.

agent-suppressions w [tool.inwards] decyduje, co hooki Claude Code robią z wyciszeniami, które pisze agent (ADR-028):

  • "deny" (domyślnie): wyciszenie liczy się tylko wtedy, gdy było w pliku na starcie sesji. Takie, które agent dodaje, kopiuje, przenosi albo rozszerza o inny kod, jest pomijane, więc jego diagnostyka blokuje edycję i Stop gate jak każda inna, z notką wyjaśniającą dlaczego. inwards stats liczy te odrzucone wyciszenia.
  • "allow": liczy się każde wyciszenie.

inwards check, CI i serwer języka zawsze honorują poprawne wyciszenia. Każdy format wyjścia liczy wyciszone diagnostyki, a SARIF pokazuje je jako wyciszone wyniki z powodem jako uzasadnieniem.

Znane ograniczenia

  • Powód nie może zawierać ", i nic nie sprawdza, czy mówi coś sensownego. To zadanie code review.
  • Przy "deny" wyciszenie w pliku, który na starcie sesji był niezacommitowany albo nieśledzony, albo w projekcie poza gitem, i zbyt duży, żeby hooki zachowały jego kopię (ponad 512 KiB albo ponad limit 4 MiB takich plików), liczy się jako nowe, gdy tylko agent zedytuje plik (#134, #157). Zacommituj wyciszenie, zanim oddasz taki plik agentowi.
  • Zmiana nazwy albo przeniesienie pliku sprawia, że jego wyciszenia są nowe; tak samo dostęp do niego przez dowiązanie symboliczne.
  • Celowo nie ma formy zbiorczej, dla następnej linii ani dla całego pliku.

Źródła