AI Features

Falcon includes AI-powered analysis capabilities to assess code quality, detect provenance, discover conventions, and predict risks.

1. AI Code Score

Run falcon score to get a comprehensive quality assessment of your project.

What it measures

The AI score evaluates 6 dimensions with the following weights:

• Maintainability (25%) — Code structure, modularity, and readability
• Testability (20%) — Test coverage and dependency injection
• Performance (15%) — Efficient patterns and potential bottlenecks
• Security (15%) — Sensitive data handling and vulnerability patterns
• Consistency (15%) — Naming, formatting, and architectural alignment
• Documentation (10%) — Comments, docstrings, and API clarity

Example command and output

$ falcon score .
Analyzing project...

AI Score: 82/100 (B)

Dimension breakdown:
  Maintainability  ████████████████░░░░  78%
  Testability      ██████████████████░░  85%
  Performance      █████████████████░░░  82%
  Security         ████████████████░░░░  80%
  Consistency      ███████████████████░  92%
  Documentation    ████████████░░░░░░░░  62%

Suggestions: 4 improvements found

Flags

• --badge — Output a README badge URL for your project
• --json — Output machine-readable JSON for CI pipelines

Grade scale

2. Code Provenance

Run falcon provenance to detect the origin of code in your project.

What it detects

• human-written — Manually authored code
• AI-generated — Code produced by LLMs (e.g., Copilot, ChatGPT)
• code-generated — Generated by tools (build_runner, codegen)
• unknown — Cannot be confidently classified

Heuristic signals

The detector looks for patterns such as:

• Repetitive structure and boilerplate typical of AI output
• Presence of codegen markers (// GENERATED CODE, etc.)
• Comment style and density
• Naming consistency and variation

Flags

• --verbose — Show per-file provenance details

Example output

$ falcon x provenance . --verbose
Provenance analysis:

  lib/main.dart           human-written
  lib/services/api.dart   AI-generated
  lib/models/user.g.dart  code-generated
  lib/widgets/home.dart   unknown

Summary: 45% human, 30% AI, 15% generated, 10% unknown

3. Convention Detection

Run falcon conventions to auto-detect patterns in your codebase.

What it detects

• Naming — File, class, and variable naming conventions
• Architecture — Project structure and layering
• State management — Which state solution you use
• Error handling — Try/catch patterns, Result types, etc.

Architecture patterns

• Clean Architecture (data/domain/presentation)
• Feature-First (features/ folder structure)
• MVC / MVVM

State management

• BLoC
• Riverpod
• Provider
• GetX
• setState

Example output

$ falcon x conventions .
Detected conventions:

  Architecture:  Feature-First (lib/features/*)
  State:         Riverpod
  Naming:        snake_case files, PascalCase classes
  Error handling: try/catch with rethrow

4. Drift Detection

Run falcon drift to find new code that deviates from established patterns.

What drift means

Drift occurs when newly added or changed code does not follow the conventions and patterns already established in the project. Falcon compares recent changes against the baseline to flag inconsistencies.

Flags

• --since HEAD~1 — Git-aware analysis; only analyze commits since the given ref

Example output

$ falcon x drift . --since HEAD~1
Drift analysis (since HEAD~1):

  lib/features/auth/login_bloc.dart
    - Uses setState instead of BLoC (project uses Riverpod)
    - Naming: login_bloc vs convention loginBloc

  lib/widgets/new_button.dart
    - Missing error boundary (project convention)

5. Risk Prediction

Run falcon predict to identify potential risks in your codebase.

Risk categories

• MemoryLeak — Unclosed streams, controllers, subscriptions
• CrashAtScale — Null safety, async gaps, platform channels
• StateCorruption — Mutable shared state, race conditions
• SecurityBreach — Hardcoded secrets, insecure storage
• PerformanceDegradation — Heavy work on main thread, large rebuilds
• DataLoss — Unhandled errors, missing persistence

Output format

Each risk shows probability, timeframe, and evidence.

Example output

$ falcon x predict .
Risk prediction:

  MemoryLeak (72%)
    Timeframe: Medium-term
    Evidence: StreamController in lib/services/socket.dart:45 not disposed

  CrashAtScale (58%)
    Timeframe: Short-term
    Evidence: Potential null in lib/screens/profile.dart:112

  SecurityBreach (41%)
    Timeframe: Long-term
    Evidence: API key in lib/config.dart:8

6. Auto Rule Discovery

Run falcon discover-rules to get proposed new rules based on patterns in your codebase.

How it works

Falcon analyzes your project for recurring patterns and anti-patterns, then proposes custom rules you can add to your configuration. Each rule includes a confidence score.

Example output

$ falcon x discover-rules .
Discovered rules:

  1. prefer_const_constructors_in_widgets (confidence: 0.92)
     "Use const constructors for stateless widgets when possible"
     Matches: 47 files

  2. no_print_in_production (confidence: 0.88)
     "Avoid print() in lib/; use debugPrint or logger"
     Matches: 12 files

  3. bloc_dispose_in_dispose (confidence: 0.85)
     "Close BLoC/Cubit in dispose()"
     Matches: 8 files