falcon

Rules / Correctness / unused-code

unused-code

cross-file/correctness/unused-code
recommendedcross-file
Same as check-unused-code · Dart Code Metrics
Cross-file rule. This rule 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, and expect it to do more work on large projects than a single-file rule.

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

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()}';
api.dartPublic class 'PublicUnused' is never referenced anywhere in the project; remove it
6// Never referenced anywhere else → dead public class.
7class PublicUnused {}
api.dartPublic declaration 'publicUnusedFn' is never referenced anywhere in the project; remove it
19// Never referenced elsewhere → dead public function.
20void publicUnusedFn() {}
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 {}

How to configure

Set the severity of unused-code in your falcon.json under the cross-file section:

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

Related