fcheck #

A command-line tool for analyzing the quality of Flutter and Dart projects. It provides comprehensive metrics including code statistics, comment ratios, and compliance with coding standards like the "one class per file" rule.

Features #

📊 Project Statistics: Total files, folders, lines of code, and comment ratios
📝 Comment Analysis: Measures code documentation levels
✅ Code Quality Checks: Validates compliance with "one class per file" rule
🎯 StatefulWidget Support: Special handling for Flutter StatefulWidget classes
🔍 Hardcoded String Detection: Flags user-facing strings; treated as errors when localization is enabled, otherwise shown as cautionary counts
🔧 Source Code Sorting: Ensures Flutter class members are properly organized
📁 Recursive Analysis: Scans entire project directory trees
🌐 Multiple Diagram Outputs: Generate SVG, Mermaid, PlantUML, and folder/hierarchical views of dependency graphs
🚀 Fast CLI: Command-line interface with simple usage

Installation #

From Source #

Clone the repository:

git clone https://github.com/vteam-com/fCheck.git
cd fcheck

Install dependencies:

dart pub get

Run the tool:

dart run bin/fcheck.dart --input /path/to/your/flutter/project

As a Global Tool #

# Activate as a global Dart package
dart pub global activate fcheck

# Run from anywhere using direct command
fcheck --input /path/to/your/project

# Or use positional arguments
fcheck /path/to/your/project

Usage #

Basic Usage #

# Analyze current directory
fcheck

# Analyze specific project (after global installation)
fcheck --input /path/to/project

# Use positional arguments
fcheck /path/to/project

# Use short options
fcheck -i /path/to/project

# Show fCheck version
fcheck --version
# or
fcheck -v

Note: Examples show global installation usage. When running from source, use dart run fcheck instead of fcheck.

SVG Generation Mode #

# Generate SVG dependency graph (after global installation)
fcheck --svg

# Generate SVG in specific project
fcheck --input /path/to/project --svg

# Use positional arguments
fcheck /path/to/project --svg

# Use short options
fcheck -i /path/to/project --svg

Folder-Based SVG Generation Mode #

# Generate folder-based SVG visualization (after global installation)
fcheck --svgfolder

# Generate folder-based SVG in specific project
fcheck --input /path/to/project --svgfolder

# Use positional arguments
fcheck /path/to/project --svgfolder

# Use short options
fcheck -i /path/to/project --svgfolder

Visualization Example:

Dependency Graph Visualization

The SVG visualization shows:

Layered Architecture: Files organized by dependency layers (Layer 1 = entry points, higher numbers = deeper dependencies)
Dependency Graph: Visual representation of file dependencies with directional edges
Metrics Badges: Each file shows incoming/outgoing dependency counts
Interactive Features: Hover over nodes/edges for detailed information

The visualization helps identify:

✅ Proper layering and separation of concerns
⚠️ Circular dependencies (handled via Tarjan's SCC algorithm)
📊 Architecture patterns and component relationships
🔍 Potential refactoring opportunities

Folder-Based Visualization Features:

Folder-Based Dependency Graph Visualization

The folder-based visualization provides:

Folder Containers: Files grouped by their containing folders
Folder-Level Metrics: Rollup incoming/outgoing dependency counts per folder
File-Level Details: Individual files shown within each folder with their own dependency badges
Interactive Tooltips: Hover over folder edges to see specific file dependencies between folders
Visual Hierarchy: Folders sorted by dependency activity (most connected folders first)

This visualization helps identify:

📁 Folder Coupling: Which folders have the most inter-dependencies
🔗 Architecture Patterns: Natural grouping and separation of concerns
🎯 Refactoring Opportunities: Folders that might benefit from consolidation or separation
📊 Component Relationships: How different modules/components interact

Mermaid Generation Mode #

# Generate Mermaid dependency graph (after global installation)
fcheck --mermaid

# Generate Mermaid file in a specific project
fcheck --input /path/to/project --mermaid

Outputs layers.mmd in the target directory for quick embedding in docs.

PlantUML Generation Mode #

# Generate PlantUML dependency graph (after global installation)
fcheck --plantuml

# Generate PlantUML file in a specific project
fcheck --input /path/to/project --plantuml

Outputs layers.puml in the target directory; render with your preferred PlantUML tool.

JSON Output Mode #

# Output all analysis results in structured JSON format
fcheck --json

# Output JSON in specific project
fcheck --input /path/to/project --json

# Use positional arguments
fcheck /path/to/project --json

Auto-Fix Mode #

# Automatically fix sorting issues (after global installation)
fcheck --fix

# Fix sorting issues in specific project
fcheck --input /path/to/project --fix

# Use positional arguments
fcheck /path/to/project --fix

# Use short options
fcheck -i /path/to/project -f

Example Output #

Analyzing project at: /path/to/project...
--- Stats ---
Folders: 15
Files: 89
Dart Files: 23
Lines of Code: 2456
Comment Lines: 312
Comment Ratio: 12.70%
----------------------
❌ 3 files violate the "one class per file" rule:
  - lib/widgets.dart (4 classes found)
  - lib/main.dart (2 classes found)
  - lib/models.dart (3 classes found)

⚠️ 6 potential hardcoded strings detected (project not localized)

✅ All Flutter classes have properly sorted members.

Quality Metrics #

Project Statistics #

Total Folders: Number of directories in the project
Total Files: Total number of files (all types)
Total Dart Files: Number of .dart files analyzed
Total Lines of Code: Sum of all lines in Dart files
Total Comment Lines: Lines containing comments
Comment Ratio: Percentage of lines that are comments

Code Quality Rules #

One Class Per File Rule

Public Classes: Maximum 1 public class per file (classes not starting with _)
StatefulWidget Files: Maximum 2 public classes per file (widget + state)
Private Classes: Unlimited (implementation details starting with _)
Violations: Files with too many public classes are flagged

Library Usage #

You can also use fcheck as a Dart library in your own tools:

import 'dart:io';
import 'package:fcheck/fcheck.dart';

void main() {
  final projectDir = Directory('/path/to/project');
  final engine = AnalyzeFolder(projectDir);
  final metrics = engine.analyze();

  // Access metrics programmatically
  print('Total files: ${metrics.totalFiles}');
  print('Comment ratio: ${(metrics.commentRatio * 100).toStringAsFixed(1)}%');

  // Print full report
  metrics.printReport();
}

Quality Standards #

Comment Ratio Guidelines #

Excellent: > 20%
Good: 10-20%
Needs Improvement: < 10%

Class Organization #

Compliant: Files with appropriate public class counts
StatefulWidget: Allowed 2 public classes (widget + State)
Private Classes: Unlimited (starting with _ are implementation details)
Non-compliant: Files with too many public classes

Member Sorting (Flutter Classes) #

Localization-Aware Hardcoded Strings #

When localization is enabled (presence of l10n.yaml, .arb files, or AppLocalizations usage): hardcoded strings are treated as errors and the report lists the first few findings (❌).
When localization is not detected: only the total count is shown as a caution (⚠️) without listing individual strings to reduce noise in non-localized projects.
Proper Order: Constructors → Fields → Getters/Setters → Methods → Lifecycle Methods
Lifecycle Methods: initState, dispose, didChangeDependencies, didUpdateWidget, build
Field Grouping: Related getters/setters are grouped with their fields
Validation: Checks if Flutter class members follow consistent organization patterns

Project Structure #

fcheck/
├── bin/
│   └── fcheck.dart          # CLI entry point
├── lib/
│   ├── fcheck.dart  # Public API (AnalyzeFolder engine)
│   └── src/
│       ├── graphs/          # Diagram generators
│       │   ├── export_mermaid.dart
│       │   ├── export_plantuml.dart
│       │   ├── export_svg.dart
│       │   ├── export_svg_folders.dart
│       │   ├── graph_format_utils.dart
│       │   └── svg_common.dart
│       ├── hardcoded_strings/
│       │   ├── hardcoded_string_analyzer.dart
│       │   ├── hardcoded_string_issue.dart
│       │   └── hardcoded_string_visitor.dart
│       ├── layers/
│       │   ├── layers_analyzer.dart
│       │   ├── layers_issue.dart
│       │   ├── layers_results.dart
│       │   └── layers_visitor.dart
│       ├── metrics/
│       │   ├── file_metrics.dart
│       │   └── project_metrics.dart
│       ├── models/
│       │   ├── class_visitor.dart
│       │   ├── file_utils.dart
│       │   ├── rect.dart
│       │   └── version.dart
│       └── sort/
│           ├── sort.dart
│           ├── sort_analyzer.dart
│           ├── sort_issue.dart
│           └── sort_members.dart
├── example/                 # Test example project
├── pubspec.yaml             # Package configuration
└── README.md                # This file

Development #

Running Tests #

dart test

Building #

dart pub get
dart compile exe bin/fcheck.dart

Testing with Example #

The project includes a test example you can analyze:

dart run fcheck --input example

Contributing #

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Run tests: dart test
Submit a pull request

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Requirements #

Dart SDK >= 3.0.0
Flutter projects (for Flutter-specific analysis features)

fcheck 0.5.0 fcheck: ^0.5.0 copied to clipboard

Metadata