scale_guard 0.6.0 copy "scale_guard: ^0.6.0" to clipboard
scale_guard: ^0.6.0 copied to clipboard

Published 10 days ago
SDKDartFlutter
PlatformAndroidiOSLinuxmacOSWindows
→

Metadata

Deterministic CLI for detecting architectural scale risks in Flutter projects.

More...

pub package pub points License: Apache-2.0

Flutter ScaleGuard

Flutter ScaleGuard #

Architecture health check for Flutter apps.

Flutter ScaleGuard is a deterministic CLI tool that detects architectural risks in Flutter projects before they become expensive to fix.

Instead of focusing on style or formatting, ScaleGuard analyzes structural architecture patterns such as:

  • cross-feature coupling
  • layer boundary violations
  • service locator abuse
  • module hotspots
  • configuration risks

It helps teams detect architecture erosion early, before it slows development.

Quick Start #

Install the CLI:

dart pub global activate scale_guard

Run a scan in your Flutter project:

scale_guard scan .

Example Output #

Flutter ScaleGuard v0.6.0
Project: ./my_flutter_app
Scan Path: ./my_flutter_app

Architecture Score: 69/100
Risk Level: Medium

Summary:
This codebase shows early-stage coupling patterns that may reduce feature isolation as the team scales.

Dominant Risk Category: Coupling Risk (69% of total penalty)
Most Expensive Risk: Feature Module Imports Another Feature (reduces isolation and scaling flexibility) (-15.0) [Coupling Risk] [rule: cross_feature_coupling]
Hotspot (source): lib/features/user_profile (42 findings)
Examples:
  lib/features/user_profile/domain/usecase.dart lib/features/dashboard/repo.dart
  (+39 more)

---

Top Fix Priorities:

1. lib/features/user_profile
   - 42 findings
   - dominant: cross_feature_coupling
   - Avoid direct feature-to-feature imports.

2. lib/features/dashboard
   - 28 findings
   - dominant: cross_feature_coupling
   - Avoid direct feature-to-feature imports.


Hotspots:

lib/features/user_profile (42 findings)
  - cross_feature_coupling: 38
  - service_locator_abuse: 4

lib/features/dashboard (28 findings)
  - cross_feature_coupling: 22
  - hardcoded_scale_risks: 6

---

Findings by Category:

Coupling Risk
  - Feature Module Imports Another Feature (91 across 31 files)
  Features importing each other directly increases coupling and reduces scalability.
  Suggestion: Avoid direct feature-to-feature imports. Move shared contracts into a shared domain layer or introduce an abstraction.

  - Global Dependency Access Across Boundaries (34 across 15 files)
  Global dependency access hides dependencies and reduces architectural clarity.
  Suggestion: Limit service locator usage to composition roots. Inject dependencies explicitly into classes.

---

Tip:
Use ScaleGuard in CI to prevent architecture drift:
scale_guard scan . --fail-under 70

CI / Guardrail Usage #

ScaleGuard can be used to prevent architectural regressions in CI pipelines.

Example:

scale_guard scan . --fail-under 70

If the architecture score drops below the threshold, the command exits with a failure code.

This allows teams to enforce architecture quality gates automatically.

Installation #

Global install via Dart:

dart pub global activate scale_guard

Or run directly from the repository:

dart run bin/scale_guard.dart scan .

Usage #

Basic scan:

scale_guard scan .

JSON output:

scale_guard scan . --json

Fail if architecture score is too low:

scale_guard scan . --fail-under 70

Output #

ScaleGuard produces a structured report in this order:

Architecture Score #

Numeric score from 0–100. Higher score means lower architectural risk.

Risk Level #

Risk classification based on score:

Score Risk Level
80–100 Low
55–79 Medium
0–54 High

Summary #

A short summary of the dominant risk category and its impact.

Dominant Risk Category #

The architecture problem contributing most to the score penalty.

Most Expensive Risk #

The single rule responsible for the largest score reduction, with optional hotspot (source/target) and example findings.

Top Fix Priorities #

The top 3 modules (by finding count) with the most issues. For each, the report shows the path, total findings, the dominant rule, and a short actionable hint so you know where to start fixing.

Hotspots #

Modules grouped by path, with total findings and a per-rule breakdown. Shows where violations concentrate so you can focus refactoring effort.

Findings by Category #

Findings grouped by risk category. For each rule, the report includes:

  • Count and file spread
  • A description of the problem
  • A suggestion on how to fix it

CI Tip #

A short tip at the end of the report on using ScaleGuard in CI to prevent architecture drift.

Exit Codes #

Code Meaning
0 Scan succeeded (and passed fail-under if set via --fail-under or scaleguard.yaml)
1 High risk (scan succeeded but risk level is High)
2 Scan succeeded but fail-under threshold not met (CLI or config)
64 Invalid usage / invalid project path (e.g., not a directory)

Configuration (optional) #

Add an optional scaleguard.yaml file in the project root. Partial config is fine; missing keys use defaults. See scaleguard.yaml.example for a commented template.

Precedence: scaleguard.yaml is primary. Legacy risk_scanner.yaml remains supported. If both files exist, only scaleguard.yaml is loaded; risk_scanner.yaml is ignored and a warning is printed to stderr.

Fail-under: Set a minimum architecture score under score.fail_under (integer 0–100). The CLI flag --fail-under overrides the file when you pass it (same range).

Disabled rules: Under rules, set a rule id to false. Disabled rules are not run and are omitted from JSON ruleResults.

# Minimal example (all optional)
feature_roots:
  - lib/features

ignore:
  - lib/generated/**
  - lib/l10n/**

rules:
  god_files: false
  service_locator_abuse: true

thresholds:
  god_file_medium_loc: 500
  god_file_high_loc: 900

score:
  fail_under: 75
  • ignore — Appended to built-in default ignore patterns (deduplicated).
  • rules — Map of rule id → true / false. Omitted rules stay enabled.

Ignore pattern semantics #

Paths are project-relative (forward slashes), matching how files are indexed under lib/.

  • Literal pattern — Does not contain *. Matches if the path contains the pattern as a substring or ends with it (same idea as older ignored_patterns entries like .g.dart or /build/).
  • Glob pattern — Contains *. Matching uses only glob rules (no extra substring pass for that entry):
    • ** matches zero or more path segments (between /).
    • * matches zero or more characters inside one segment (does not cross /).

Examples: lib/generated/**, lib/l10n/**, **/*.g.dart.

risk_scanner.yaml (legacy) #

You can still use risk_scanner.yaml alone. Keys include feature_roots, layer_mappings, ignored_patterns, god_file_medium_loc, god_file_high_loc, and others (see risk_scanner.yaml.example). ignored_patterns replaces the entire default ignore list when this file is loaded (unlike ignore in scaleguard.yaml, which merges with defaults).

Programmatic API #

  • ScannerConfig.load(projectPath) — Unchanged; warnings from parsing are discarded.
  • ScannerConfig.loadWithDiagnostics(projectPath) — Returns ({ScannerConfig config, List<String> warnings}) for the same merge rules as the CLI.

Rules #

ScaleGuard detects the following architecture risks. In the report, each rule includes a description (what’s wrong) and a suggestion (how to fix it).

Cross Feature Coupling #

Feature modules importing other feature modules. Suggestion: move shared contracts into a shared domain layer or introduce an abstraction.

Layer Violations #

Invalid dependencies between architecture layers (e.g. presentation → data). Suggestion: ensure domain does not depend on data or presentation; move implementations behind interfaces.

God Files #

Files exceeding defined size thresholds. Suggestion: split into smaller focused components and separate responsibilities by layer or feature.

Hardcoded Scale Risks #

Configuration values embedded directly in code. Suggestion: move configuration to environment-based or external config files.

Service Locator Abuse #

Global dependency access patterns. Suggestion: limit usage to composition roots and inject dependencies explicitly.

Shared Boundary Leakage #

Shared modules importing feature modules. Suggestion: keep shared modules independent of features; depend on abstractions.

Direct route usage instead of centralized navigation. Suggestion: use a central router or navigation service.

Design Principles #

ScaleGuard is intentionally designed to be:

Deterministic
Same code always produces the same result.

Fast
Scans large Flutter projects in seconds.

Opinionated
Focused specifically on architectural scale risks.

CLI-first
Simple tooling that integrates easily into CI pipelines.

When to Use ScaleGuard #

ScaleGuard is useful when:

  • preparing a Flutter app for scale
  • auditing an existing codebase
  • reviewing architecture health during development
  • preventing architecture decay in CI
  • identifying refactoring hotspots

Author #

Pavel Koifman

Mobile Strategy & Architecture for Founders

Creator of ScaleGuard – Flutter architecture health check.

License #

Apache License 2.0.

See the LICENSE file for details.

← Metadata

2
likes
150
points
214
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Metadata

Deterministic CLI for detecting architectural scale risks in Flutter projects.

Repository (GitHub)
View/report issues

Topics

#flutter #architecture #cli #static-analysis #code-quality

License

MIT (license)

Dependencies

args, yaml

More

Packages that depend on scale_guard

Back