Suppressing findings

// bonsai-lint-ignore: hand-tuned state machine, splitting it hurts more than it helps
function parse(string $input): Ast { /* ... */ }

Works above the declaration, inside the docblock, or trailing the signature line, in every supported language. In Python it goes in a # comment above the def or its decorators: a docstring is a string inside the body, not a comment, so it cannot carry a marker. It works for a bound function too, such as const handler = () => {}, Python’s handler = lambda e: …, a Java field Runnable handler = () -> {}, $handler = function () {} or Go’s var handler = func() {}, even when a call wraps it, as in const useCart = defineStore('cart', () => {}). A marker after a closing brace on its own line belongs to nobody. A marker without a reason is refused, reported on stderr, and the finding stands. Suppression hides a finding but never changes a score, and --all always shows the real number.

A <toplevel> finding is reported on line 1, so its marker goes in the comment block at the top of the file: on the first line of a script, behind a shebang if there is one; in Python, behind a shebang or coding line and above the module docstring; just above or trailing the package line in Java or Go; or trailing <?php, or in the file’s docblock, in PHP. One comment silences one unit, so a marker directly above the first function is that function’s; write it on the package or <?php line to address the file instead.