widget_analyser 0.2.0

Offline Flutter widget analyzer: complexity, nesting, and quality reports (console, JSON, HTML) with optional CI gates.

example/README.md

widget_analyser – example usage

This directory shows how to integrate widget_analyser into a Flutter project.

Files

File	Purpose
analysis_options.yaml	Fully annotated config with every supported key. Copy or merge the widget_analyser section into your project's own analysis_options.yaml.

Quick start

1. Add the dev dependency to your Flutter project's pubspec.yaml:

   dart pub add --dev widget_analyser
   dart pub get
   

2. Copy the config (or merge the widget_analyser section) into your project's analysis_options.yaml.

3. Run the analyser:

   # Console report (default)
   dart run widget_analyser lib
   
   # HTML report written to build/reports/widget_analysis.html
   dart run widget_analyser lib --reporter html --output-dir build/reports
   
   # JSON for tooling, progress to stderr, only JSON on stdout
   dart run widget_analyser lib --reporter json --quiet
   

Output formats

Flag	Output
(none)	Coloured console table, medium and low widgets only
--reporter html --output-dir <dir>	Interactive HTML report with sortable columns and filters
--reporter json	Machine-readable JSON on stdout
--reporter json --output-dir <dir>	widget_analysis.json written to the specified directory

CI integration

Add a step to your GitHub Actions workflow:

- name: Analyse widgets
  run: dart run widget_analyser lib --show-similarity --quiet

Exit code 1 means at least one widget was graded low. Exit code 0 means all widgets are medium or high. Exit code 2 means an error occurred.

To fail the CI job only on errors (not on low-quality widgets):

set +e
dart run widget_analyser lib --reporter html --output-dir build/reports --quiet
status=$?
set -e
[ "$status" -gt 1 ] && exit "$status"

Configuration tips

• Tight thresholds for a design system: Lower cyclomatic-complexity to 6 and number-of-parameters to 4.
• Ignore generated files: The default exclude list already covers *.g.dart and *.freezed.dart. If you set your own exclude, re-add those patterns.
• Distance-style similarity: Use similarity-threshold: 0.2 instead of 0.8 — both mean "report pairs that are at least 80% similar".