flutter_audit 1.0.0

A static analysis CLI for Flutter projects. Scans for missing const, undisposed controllers, missing SafeArea, hardcoded values, API issues, and security risks.

Flutter Audit

A static analysis CLI for Flutter projects. Scans your codebase and reports findings across 7 categories — performance, memory, UI, API hygiene, security, architecture, and code quality — in a single command.

$ flutter_audit scan .

What it catches

21 rules, organized by category:

Category	Rules
Performance	missing_const, avoid_foreach, prefer_listview_builder
Memory	dispose_controllers, cancel_subscriptions, close_sinks
Security	hardcoded_secret, insecure_http, unsafe_storage
API hygiene	print_in_production, missing_try_catch, hardcoded_url
Architecture	huge_build_method, deep_widget_nesting, business_logic_in_widget
UI quality	missing_key_in_list, avoid_inline_text_style, hardcoded_size
Code quality	empty_catch, todo_comment, long_method

Each rule emits findings at one of four severities: critical (−10), error (−5), warning (−2), info (−1).

Install

dart pub global activate flutter_audit

Or for local development:

git clone <repo>
cd flutter_audit
dart pub get
dart run bin/flutter_audit.dart scan /path/to/your/flutter/project

Usage

# Audit the current directory (pretty terminal output)
flutter_audit scan .

# Audit a specific path
flutter_audit scan ~/projects/my_app

# JSON for CI/CD pipelines
flutter_audit scan . --output=json --report-file=audit.json

# Styled HTML report
flutter_audit scan . --output=html --report-file=audit.html

# Fail the CI build if any error/critical issue is found
flutter_audit scan . --fail-on-error

How scoring works

Each category starts at 100 and loses points per finding based on severity:

Severity	Penalty
info	−1
warning	−2
error	−5
critical	−10

category_score = max(0, 100 − Σ penalties) — never goes below zero.

The overall score is a weighted average across categories (weights in lib/models/audit_score.dart):

Category	Weight	Why
memory	1.5	crashes
security	1.5	breaches
performance	1.2	user-visible
api	1.2	user-visible network
architecture	1.0	baseline
ui	0.8	cosmetic
quality	0.8	cosmetic

overall = round( Σ(score × weight) / Σ(weights) )

Grade labels: EXCELLENT ≥ 90 · GOOD 80–89 · FAIR 70–79 · NEEDS WORK 50–69 · POOR < 50.

Output formats

--output=terminal (default) prints category scores, counts per category, and the top 5 highest-severity issues.

--output=json emits a machine-readable report including every finding with file path, line, snippet, severity, and suggested fix.

--output=html renders a self-contained HTML dashboard (no JS dependency) with score cards, full findings tables, and a "fix first" section.

Examples

Two scan-target projects in example/ demonstrate clean and dirty codebases:

# Should print: OVERALL : 100 / 100  EXCELLENT
dart run bin/flutter_audit.dart scan example/clean_project

# Should print findings in every category and OVERALL : 70 / 100  FAIR
dart run bin/flutter_audit.dart scan example/issues_project

See example/README.md for details.

Project structure

lib/
├── core/        Scanner, Parser, Rules Engine, Score Calculator
├── rules/       21 pluggable audit rules (one per file)
├── models/      Data classes (Issue, Report, Severity, AuditScore)
├── output/      Terminal, JSON, and HTML reporters
└── commands/    CLI subcommands

Adding a new rule

1. Create lib/rules/your_rule.dart extending AuditRule (see lib/rules/base_rule.dart for the interface).
2. Set category to one of: performance, memory, security, api, architecture, ui, quality.
3. Set defaultSeverity (info / warning / error / critical).
4. Implement check(ParsedFile file) → List<Issue>.
5. Register it in lib/commands/scan_command.dart's defaultRules().

No changes to the score calculator, reporters, or CLI needed — they're already wired for all 7 categories and 4 severities.

License

MIT