App Management

Falcon goes beyond static analysis — it manages your Flutter app. The falcon x manage command provides a unified dashboard covering project health, dependencies, architecture, maintenance, and build optimization.

Run everything at once

falcon x manage all /path/to/flutter/app

Project Health Dashboard

A unified 0-100 health score combining 6 weighted dimensions into a single number.

$ falcon x manage health .

  falcon x manage Project Health — my_app
  ═══════════════════════════════════════

  Overall Health: 72/100 (Grade: C)

    Code Quality       72/100 ██████████████░░░░░░ (30%)
    Security          100/100 ████████████████████ (20%)
    Performance        85/100 █████████████████░░░ (15%)
    Maintainability    60/100 ████████████░░░░░░░░ (15%)
    Test Coverage      45/100 █████████░░░░░░░░░░░ (10%)
    Dependencies       90/100 ██████████████████░░ (10%)

  ▸ Stats
    Files: 120 | Lines: 15000 | Issues: 230 (5 errors, 225 warnings)

  ▸ Action Items (by priority)
    1. [Error Handling] Score 45/100 — empty catches, unawaited futures
       Run: falcon check --preset ai-generated
    2. [Test Coverage] 8 test files for 120 source files
       Run: falcon x test-gen --write

Dimension Weights

Dimension	Weight	What it Measures
Code Quality	30%	AI Code Score (error handling, type safety, security, etc.)
Security	20%	Vulnerability scan results (insecure storage, HTTP, injection)
Performance	15%	DevTools-style analysis (rebuilds, memory, rendering)
Maintainability	15%	Long functions, nesting, unused code
Test Coverage	10%	Ratio of test files to source files
Dependencies	10%	Unused, outdated, or insecure dependencies

Use --json to get machine-readable output for CI pipelines:

falcon x manage health . --json

Dependency Manager

Analyzes pubspec.yaml and all Dart imports to find dependency health issues.

$ falcon x manage deps .

  falcon x manage Dependency Manager

  Total dependencies: 50 (49 direct, 1 dev)

  ⚠ Unused dependencies:
    ✗ flutter_animate — not imported in any file
    ✗ sqflite — not imported in any file
    ✗ path_provider — not imported in any file

  ▸ Issues:
    ⚠ [path-dep] 'my_package' uses path dependency — ensure CI can resolve it
    · [override] dependency_overrides found — not for production

Issues Detected

Issue Type	Description
`unused`	Dependency declared in pubspec.yaml but never imported
`permissive`	No version constraint (using `any`) — pin with `^x.y.z`
`pinned`	Exact version pin may prevent updates
`git-dep`	Git dependency — less stable than published packages
`path-dep`	Local path dependency — ensure CI can resolve
`override`	`dependency_overrides` found — should be temporary

Architecture Governor

Detects your architecture pattern, enforces layer boundaries, and finds complexity hotspots.

$ falcon x manage arch .

  falcon x manage Architecture Governor

  Pattern:         Clean Architecture
  Compliance:      92%
  Violations:      3
  Modules:         45

  ▸ Violations:
    ✗ lib/domain/user_repo.dart — Domain layer imports from data layer
    ✗ lib/data/api_service.dart — Data layer imports from presentation

  ▸ Complexity Hotspots:
    ⚠ lib/pages/settings.dart — 1271 lines — split into smaller files
    ⚠ lib/pages/profile.dart — 810 lines — split into smaller files

  ▸ Suggestions:
    → 5 files exceed 500 lines — break into focused modules
    → Enforce with: falcon x check-layers in CI

Supported Architecture Patterns

Pattern	Detection Signal	Layer Enforcement
Clean Architecture	`domain/`, `data/`, `presentation/` dirs	Domain cannot import data/presentation; Data cannot import presentation
Feature-First	`features/` dir	Features cannot cross-import; use `core/` or `shared/`
MVC/MVVM	`models/`, `views/` dirs	Basic separation checks
Flat/Custom	No recognized pattern	Suggests adopting Clean Architecture

Maintenance Advisor

Identifies cleanup tasks, calculates tech debt score, and shows what can be auto-fixed.

$ falcon x manage maint .

  falcon x manage Maintenance Advisor

  Tech Debt Score: 55/100
  Cleanup tasks:   7 (1 auto-fixable, 6 manual)
  Est. savings:    ~3740 lines removable

  · [Dead Code] 216 unused declarations can be removed
     Run: falcon x check-unused-code
  · [Unused Files] 10 files not imported anywhere
     Run: falcon x check-unused-files
  · [Empty Catch Blocks] 12 silently swallowing errors
     Run: falcon check --preset ai-generated
  ⚡ [Trailing Commas] 467 missing — auto-fixable
     Run: falcon fix

Cleanup Categories

Category	Auto-fixable	Impact
Dead Code	No	Reduces codebase size, improves readability
Unused Files	No	Removes confusion, speeds up builds
Unused Dependencies	No	Reduces app size, fewer vulnerabilities
Stale Generated Files	No	Prevents build errors from orphaned .g.dart
Long Functions	No	Improves testability and readability
Empty Catch Blocks	No	Prevents silent production failures
Print Statements	No	Use logging framework instead
Trailing Commas	Yes	Better git diffs, consistent formatting

Build Optimizer

Analyzes assets, build configuration, and provides optimization recommendations.

$ falcon x manage build .

  falcon x manage Build Optimizer

  Assets: 45 files (2400 KB total, 30 images, 4 fonts)
  Platforms: 3

  ▸ Large assets:
    · assets/images/hero.png (850KB)
    · assets/images/background.png (620KB)

  ▸ Recommendations:
    → [Assets] 'hero.png' is 850KB — compress or use lower resolution
    → [Build Config] Enable tree-shaking for icons (~1MB savings)
    → [Code Size] 200+ Dart files — consider deferred imports

Running All Analyses

Use falcon x manage all to run health, deps, arch, maint, and build analyses in sequence:

$ falcon x manage all /path/to/app

This gives you a complete picture of your Flutter app's state in a single command.

CI Integration

Add health checks to your CI pipeline:

# .github/workflows/falcon.yml
name: Falcon Health Check
on: [pull_request]
jobs:
  health:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo install --git https://github.com/viveky259259/falcon
      - run: falcon x manage health . --json > health.json
      - run: falcon review . --format gh

Tip

Combine falcon x manage health with falcon x enterprise check to enforce minimum health scores as a CI gate.