falconGitHub

maximum-nesting-level

Same as maximum_nesting_level in Pyramid Lint

Path
lint/complexity/maximum-nesting-level
Default
Off, opt in
Origin
Pyramid Lint
Rule
266 of 512

Flags a function whose control-flow nesting runs deeper than the configured level.

Deeply nested blocks push logic to the right and make control flow hard to follow; early returns, guard clauses, and extracted helpers flatten it. The rule measures the deepest nesting of control structures — if, for, while, do, switch, and try — within a function body. A plain block does not add a level, else if chains stay at the same level, and a nested local function or closure restarts the count. Their deepest level still contributes to the enclosing declaration's maximum. Operator bodies are included; the rule reports at the declaration when depth exceeds the threshold.

Options

max-nesting (integer, default: 5) — flag when the nesting depth exceeds this.

Invalid

example.dartdart
// Each function nests control structures deeper than the configured
// max_nesting of 2 (deepest point reaches nesting level 3).

void ifForIf(bool a, bool b, List<int> xs) {
  if (a) {
    for (final x in xs) {
      if (b) {
        print(x);
      }
    }
  }
}

void whileIfWhile(int n) {
  while (n > 0) {
    if (n.isEven) {
      while (n > 10) {
        n -= 1;
      }
    }
    n -= 1;
  }
}

void switchInLoop(List<int> codes) {
  for (final code in codes) {
    if (code > 0) {
      switch (code) {
        case 1:
          print('one');
        default:
          print('other');
      }
    }
  }
}

void tryInside(bool a, bool b) {
  if (a) {
    if (b) {
      try {
        print('run');
      } catch (e) {
        print(e);
      }
    }
  }
}

void deepLoops(List<List<int>> grid) {
  for (final row in grid) {
    for (final cell in row) {
      if (cell > 0) {
        print(cell);
      }
    }
  }
}

class Grid {
  void render(List<List<int>> rows) {
    for (final row in rows) {
      for (final cell in row) {
        while (cell > 0) {
          print(cell);
          break;
        }
      }
    }
  }
}

// A label on the outer loop must not hide the nesting it wraps.
void labeledDeep(List<int> xs, bool a, bool b) {
  outer:
  for (final x in xs) {
    if (a) {
      if (b) {
        print(x);
        break outer;
      }
    }
  }
}

// Control flow inside a closure argument counts like a local function does.
void closureDeep(List<int> xs) {
  run(() {
    for (final x in xs) {
      if (x > 0) {
        while (x > 10) {
          print(x);
          break;
        }
      }
    }
  });
}
Function has a nesting level of 3 (max 2).
3
4void ifForIf(bool a, bool b, List<int> xs) {
Function has a nesting level of 3 (max 2).
13
14void whileIfWhile(int n) {
Function has a nesting level of 3 (max 2).
24
25void switchInLoop(List<int> codes) {
Function has a nesting level of 3 (max 2).
37
38void tryInside(bool a, bool b) {
Function has a nesting level of 3 (max 2).
49
50void deepLoops(List<List<int>> grid) {
Function has a nesting level of 3 (max 2).
60class Grid {
61 void render(List<List<int>> rows) {
Function has a nesting level of 3 (max 2).
73// A label on the outer loop must not hide the nesting it wraps.
74void labeledDeep(List<int> xs, bool a, bool b) {
Function has a nesting level of 3 (max 2).
86// Control flow inside a closure argument counts like a local function does.
87void closureDeep(List<int> xs) {

Valid

example.dartdart
// Each function keeps control-structure nesting at or below the
// max_nesting of 2, so none trigger the rule.

void singleIf(bool a) {
  if (a) {
    print('yes');
  }
}

void loopThenIf(List<int> xs) {
  for (final x in xs) {
    print(x);
  }
  if (xs.isEmpty) {
    print('empty');
  }
}

void ifInLoop(List<int> xs, bool flag) {
  for (final x in xs) {
    if (flag) {
      print(x);
    }
  }
}

void guardedWhile(int n) {
  while (n > 0) {
    n -= 1;
  }
}

void tryOnce(bool a) {
  if (a) {
    try {
      print('run');
    } catch (e) {
      print(e);
    }
  }
}

class Printer {
  void printAll(List<int> xs) {
    for (final x in xs) {
      print(x);
    }
  }
}

// Labeled loop whose nesting stays within the limit.
void labeledShallow(List<int> xs, bool a) {
  loop:
  for (final x in xs) {
    if (a) {
      print(x);
      break loop;
    }
  }
}

// Closure whose nesting stays within the limit.
void closureShallow(List<int> xs) {
  run(() {
    for (final x in xs) {
      print(x);
    }
  });
}

Configure maximum-nesting-level

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson
{
  "linter": {
    "rules": {
      "complexity": {
        "maximum-nesting-level": "error"
      }
    }
  }
}

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

example.dartdart
// falcon-ignore lint/complexity/maximum-nesting-level: <reason>