flutter_dev_intelligence 1.2.0

Offline-first diagnostic toolkit that analyzes Flutter and Dart build logs, identifies root causes, separates cascading failures, and generates evidence-backed debugging reports.

Flutter Dev Intelligence

Flutter Dev Intelligence is an offline-first diagnostic toolkit that analyzes Flutter and Dart build logs, identifies likely root causes, separates cascading failures, extracts evidence, and generates actionable debugging reports.

---

Key Features

• 🎯 Primary Root-Cause Prioritization: Distinguishes the primary root cause from downstream cascading failures (such as BUILD FAILED or :compileDebugJavaWithJavac FAILED).
• 🔎 Evidence-Backed Findings: Every finding includes exact log references, context lines, and defensible confidence levels.
• 🔒 Offline & Local-First: Performs 100% deterministic analysis locally. Automatically redacts secrets, tokens, private keys, and user home directory paths.
• 📦 Zero Heavy Dependencies: Lightweight design without heavy AST parsers or network dependencies.
• 📄 Multi-Format Output: Renders scannable reports in Terminal (with color/ASCII options), JSON (machine-readable), and Markdown (ideal for GitHub Actions and issue comments).

---

Quick Start

Installation

Add flutter_dev_intelligence to your pubspec.yaml or run:

flutter pub add flutter_dev_intelligence

CLI Usage

Analyze a build log file:

dart run flutter_dev_intelligence build-doctor --log path/to/build.log

Analyze build log from standard input pipe (ideal for CI pipelines):

flutter build apk 2>&1 | dart run flutter_dev_intelligence build-doctor --stdin

Generate a JSON report for CI artifact archiving:

dart run flutter_dev_intelligence build-doctor --log build.log --format json --output report.json

Generate Markdown summary for GitHub PR / Issue comments:

dart run flutter_dev_intelligence build-doctor --log build.log --format markdown

---

UI Doctor (Static UI/UX & Code Health Inspector)

UI Doctor statically inspects Flutter source code and asset declarations to detect potential code smells, maintainability concerns, asset errors, and accessibility issues.

Disclaimer: UI Doctor performs offline static heuristic analysis. Its findings are recommendations based on source code patterns and project structure. Findings should be reviewed in the context of your application and are not guarantees of runtime performance problems.

UI Doctor Features

• 📁 Asset Validation: Missing asset files, path letter-case mismatches, oversized asset files.
• 🧹 Code Health: Production debugPrint/print statement detection (ignoring kDebugMode condition guards).
• 📐 Maintainability: Large build() methods and oversized widget class detection.
• ⚡ Performance Heuristics: shrinkWrap: true usages inside scrollable parent containers.
• ♿ Accessibility: Image widgets missing semanticLabel descriptions or excludeFromSemantics flags.
• 🎯 Baseline & Regression Detection: Save baseline snapshots (--generate-baseline) and enforce "no new issues" in CI quality gates (--baseline, --fail-on-new).
• ⚙️ Configurable: Configurable via .flutter_dev_intelligence.yaml.

UI Doctor Commands

# Analyze Flutter UI and code-health patterns
dart run flutter_dev_intelligence ui-doctor

# Inspect a specific scope (assets, accessibility, performance, maintainability)
dart run flutter_dev_intelligence ui-doctor --scope accessibility

# Output machine-readable JSON for CI or tooling
dart run flutter_dev_intelligence ui-doctor --format json --output ui-report.json

# Generate a baseline snapshot
dart run flutter_dev_intelligence ui-doctor --generate-baseline

# Compare against baseline and fail CI only if new findings are introduced
dart run flutter_dev_intelligence ui-doctor --baseline --fail-on-new

---

Supported Diagnostic Categories

Category	Description	Example Rule IDs
Pub & Dependency	Version solving failures, SDK mismatches, incompatible constraints	PUB_VERSION_SOLVING_FAILED, DART_SDK_CONSTRAINT_MISMATCH
Dart Compiler	Unresolved imports, undefined identifiers, type mismatches, missing generated files	DART_UNRESOLVED_IMPORT, DART_MISSING_GENERATED_FILE
Android & Gradle	Maven dependency resolution failures, SDK missing, Java/Gradle version mismatches	GRADLE_DEPENDENCY_RESOLUTION_FAILED, JAVA_AGP_INCOMPATIBILITY
iOS & CocoaPods	Pod spec resolution errors, deployment target conflicts, signing issues	COCOAPODS_RESOLUTION_FAILED, IOS_DEPLOYMENT_TARGET_TOO_LOW

---

Dart API Usage

You can also use flutter_dev_intelligence programmatically inside Dart or Flutter tools:

import 'package:flutter_dev_intelligence/flutter_dev_intelligence.dart';

void main() async {
  final logContent = await File('build.log').readAsString();

  final report = await BuildDoctor.analyzeLog(
    logContent,
    projectName: 'my_flutter_app',
  );

  print('Total Findings: ${report.findings.length}');
  print('Primary Root Causes: ${report.primaryFindings.length}');

  for (final primary in report.primaryFindings) {
    print('Primary Cause: ${primary.title} [${primary.id}]');
    print('Likely Cause:  ${primary.likelyCause}');
  }
}

---

Development & Testing

Run analysis and test suite:

flutter analyze
flutter test

Dry-run package publication:

dart pub publish --dry-run

---

License

MIT License. See LICENSE for details.