falconGitHub

unused-code

Same as check-unused-code in Dart Code Metrics

Path
cross-file/correctness/unused-code
Default
Off, opt in
Origin
Dart Code Metrics
Rule
479 of 512
cross-file

Cross-file rule. It runs in falcon's whole-project pass, analyzing relationships across every file rather than one file at a time. Configure it under the top-level cross-file key.

Report public top-level declarations that nothing references.

Flags a public top-level declaration in lib/ — a class, mixin, enum, typedef, extension type, function, or variable — whose name appears nowhere else in the project, neither in another file nor elsewhere in its own file. An unreferenced public API is usually dead code that outlived its callers, but removing something still in use is worse than missing one, so the rule is tuned to avoid false positives: it exempts main, annotated declarations, members of re-exported files, and unnamed extensions, treats any same-name identifier anywhere as usage, and skips files that failed to parse. Private (_-prefixed) declarations are out of scope. This is a cross-file rule: it runs in the cross-file pass over the whole analyzed file set and is configured under the top-level cross-file section rather than linter.

Invalid

bad/api.dartdart
// Public API surface exercising unused-code.

// Referenced from main.dart → live.
class PublicUsed {}

// Never referenced anywhere else → dead public class.
class PublicUnused {}

// Private: never a candidate, regardless of usage.
class _PrivateClass {}

// Annotated declarations are exempt (annotations often imply framework use).
@Deprecated('legacy')
class AnnotatedUnused {}

// Referenced from main.dart → live.
void usedFn() {}

// Never referenced elsewhere → dead public function.
void publicUnusedFn() {}

// Referenced within THIS file (by _useLocal) → used, not dead. dcl counts
// same-file references as usage, so this must NOT be flagged.
class OnlyLocal {}

// Never referenced anywhere, including its own file → dead public class.
class NeverReferenced {}

void _useLocal() {
  OnlyLocal();
  _PrivateClass();
}

// Referenced only from a string interpolation in THIS file → still used. The
// lexer folds interpolated identifiers into the string token, so the rule must
// look inside `${...}`; otherwise this is a false positive.
class InterpolatedOnly {}

String _describe() => 'value: ${InterpolatedOnly()}';
bad/api.dartPublic class `PublicUnused` is never referenced anywhere in the project; remove it.
6// Never referenced anywhere else → dead public class.
7class PublicUnused {}
bad/api.dartPublic declaration `publicUnusedFn` is never referenced anywhere in the project; remove it.
19// Never referenced elsewhere → dead public function.
20void publicUnusedFn() {}
bad/api.dartPublic class `NeverReferenced` is never referenced anywhere in the project; remove it.
26// Never referenced anywhere, including its own file → dead public class.
27class NeverReferenced {}

Configure unused-code

Set its severity in falcon.json under the cross-file section. See the configuration guide.

falcon.jsonjson
{
  "cross-file": {
    "rules": {
      "correctness": {
        "unused-code": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore cross-file/correctness/unused-code: <reason>