Suppressions

falcon.json turns rules on or off across your project. To silence one occurrence, use // falcon-ignore lint/<group>/<rule>: <reason>. The reason is mandatory.

For turning rules off wholesale, per group, or per path, see configuration.md; for the rule ids and groups you name in a directive, see the rules index.

Syntax

// falcon-ignore <section>/<group>/<rule>: <reason>
// falcon-ignore-all <section>/<group>/<rule>: <reason>

Each directive names exactly one rule by its full path and ends with a non-empty reason after the colon:

<section>: lint for a normal per-file rule, cross-file for a whole-project rule. The pre-1.0 spelling project is still accepted as a deprecated alias for cross-file.
<group>: the rule's category: a11y, complexity, correctness, performance, security, style, or suspicious.
<rule>: the rule id, kebab-case (e.g. avoid-dynamic). Registered legacy snake_case ids still resolve as aliases.

// falcon-ignore lint/suspicious/avoid-dynamic: interop boundary
// falcon-ignore cross-file/correctness/unused-files: generated entrypoint

Note: falcon does not read Dart's own // ignore: / // ignore_for_file: comments. Those still control the Dart analyzer's lints and have no effect on falcon. Suppress a falcon diagnostic only with // falcon-ignore.

Both // line comments and /// doc comments carry directives. A directive inside a /* block comment */ or a string literal is not treated as a suppression:

var note = '// falcon-ignore lint/suspicious/avoid-dynamic: x'; // string, ignored
/* falcon-ignore lint/suspicious/avoid-dynamic: x */            // block, ignored

Inline suppression (one line)

A // falcon-ignore directive suppresses a single line. Placement decides which line:

Trailing: a comment after code on the same line suppresses that line:

dynamic payload = decode(bytes); // falcon-ignore lint/suspicious/avoid-dynamic: interop boundary

Leading: a comment alone on its own line suppresses the next line of code:

// falcon-ignore lint/suspicious/avoid-dynamic: interop boundary
dynamic payload = decode(bytes);

Stacking multiple rules

One comment carries one rule. To suppress several rules on the same code line, stack the leading comments directly above it. Consecutive suppression-only lines all apply to the next line of code:

// falcon-ignore lint/suspicious/avoid-dynamic: interop boundary
// falcon-ignore lint/style/prefer-const-constructors: perf-tested
final widget = build(dynamicValue);

File-level suppression (`falcon-ignore-all`)

// falcon-ignore-all suppresses a rule everywhere in the file. It may sit anywhere, but conventionally goes at the top:

// falcon-ignore-all lint/suspicious/avoid-dynamic: generated file

dynamic a = 1;
dynamic b = 2;   // both suppressed

This is the inline equivalent of turning the rule off for one file via an overrides entry in falcon.json. Use overrides when you want the same exclusion across many files by path.

Cross-file rules are suppressed the same way, with the cross-file section:

// falcon-ignore-all cross-file/correctness/unused-code: public API surface

The reason is required

Every directive must end with a non-empty reason after the colon. A directive with no reason does not suppress; instead falcon reports a malformed-suppression warning pointing at the comment:

dynamic x = 1; // falcon-ignore lint/suspicious/avoid-dynamic
//             ^ no reason → not suppressed, malformed-suppression reported

The same warning catches these mistakes:

the path is malformed (not <section>/<group>/<rule>, or an unknown section):
```
// falcon-ignore avoid-dynamic: x   → malformed path
```

the rule is named under the wrong group or section; the message tells you the correct path:

// falcon-ignore lint/style/avoid-dynamic: x
//   avoid-dynamic is in `suspicious`, so the message says:
//   "suppression path is lint/suspicious/avoid-dynamic"

// falcon-ignore-all lint/correctness/unused-files: x
//   unused-files is a cross-file rule, so the message says:
//   "suppression path is cross-file/correctness/unused-files"

the rule name is unknown (catching typos):

// falcon-ignore lint/suspicious/not-a-rule: x   → unknown rule 'not-a-rule'

Caution: malformed-suppression is an internal diagnostic. It is not a configurable rule: it does not appear in falcon.json, and it cannot itself be suppressed. Fix the directive instead.