Skip to content
Docs
Main site, archipelago.banuacoder.com
Back to archipelago.banuacoder.com

DevTools

affected Enterprise ​

Tier
Enterpriseversion 1.0.7
Command
archipelago generate affected
Generates
  • devtools/scripts/affected
Depends on
monorepo_toolkitgenerate these first

Git-based affected package detection for CI/CD pipelines. Adds the affected command (list/format/fix-check/analyze/test/golden/license/build/devtool/run) to the base monorepo_toolkit, so CI only builds and tests packages that actually changed.

What it is / when to use it ​

affected is a devtools CLI script, not a Flutter feature — it has no DI, no FeatureSDK, and generates no app UI. It adds an AffectedCommand (10 subcommands) to monorepo_toolkit's command_runner.dart, backed by an AffectedService that diffs git history and walks the workspace's package dependency graph to compute which packages are affected by a change (including transitive dependents).

Use it once your monorepo's CI is slow enough that testing/building every package on every PR is wasteful — it's the brick that turns flutter test across 60+ packages into flutter test across only the 3 that changed (plus their dependents).

Requires the base monorepo_toolkit brick to be generated first (it patches monorepo_toolkit's own command_runner.dart).

Variables ​

VariableTypeDefaultDescription
appNamestringMyAppThe name of your application
isForMonorepobooleantrueWhether this is being generated as part of a monorepo

Usage ​

Interactive ​

bash
archipelago generate affected

Non-interactive (CI) ​

bash
archipelago generate affected --config my_config.json

Config Template ​

json
{
  "@appName": "The name of your application",
  "appName": "MyApp",
  "@isForMonorepo": "Whether this is being generated as part of a monorepo",
  "isForMonorepo": true
}

Generated Structure ​

text
devtools/
└── scripts/
    └── affected/
        ├── ci-affected-matrix.yml.example     # Example GitHub Actions workflow
        ├── lib/
        │   ├── affected.dart                  # Barrel export, no bin/ entrypoint
        │   └── src/
        │       ├── commands/
        │       │   ├── affected_command.dart  # Parent command, registers the 10 subcommands below
        │       │   ├── analyze_command.dart
        │       │   ├── build_command.dart
        │       │   ├── devtool_command.dart
        │       │   ├── fix_check_command.dart
        │       │   ├── format_command.dart
        │       │   ├── golden_command.dart
        │       │   ├── license_command.dart
        │       │   ├── list_command.dart
        │       │   ├── run_command.dart
        │       │   └── test_command.dart
        │       ├── models/
        │       │   └── affected_config.dart
        │       └── services/
        │           └── affected_service.dart
        └── pubspec.yaml

CLI Usage ​

The package ships no bin/ entrypoint — it's a library consumed exclusively through monorepo_toolkit's command runner:

bash
# List packages affected by uncommitted/committed changes vs. a base ref
dart run monorepo_toolkit affected list --base main --json

# Run tests only for affected packages, with CI sharding
dart run monorepo_toolkit affected test --base origin/main --shard-index 0 --total-shards 4

# Run an arbitrary shell command across every affected package
dart run monorepo_toolkit affected run -- "flutter test --coverage"

list supports --base/-b (defaults to main), --format pretty|plain, and --json/-j for a JSON array suitable for a GitHub Actions matrix. run requires a command after -- and defaults --fail-fast to true.

Example CI workflow ​

The brick ships ci-affected-matrix.yml.example — a ready-to-copy GitHub Actions workflow with a detect job (affected list --json → dynamic matrix), a sharded test job, and a finalize job. Known issue: as shipped, that example invokes dart run devtools/scripts/affected list --json ... directly against the affected package path — since affected has no bin/ entrypoint, that specific line does not run as-is. Use dart run monorepo_toolkit affected list --json ... instead when copying the example (see Limitations below).

How It Works ​

The post-generation hook:

  1. Adds the affected package to the workspace pubspec.yaml
  2. Adds the dependency to monorepo_toolkit's pubspec.yaml
  3. Injects AffectedCommand into command_runner.dart at the // --- Pro Commands --- marker

Dependencies ​

  • monorepo_toolkit — must be generated first; this brick only patches an existing command_runner.dart.
  • shared_scripts — provides MonorepoFinder, CliLogger.

Limitations / Known Issues ​

  • The bundled ci-affected-matrix.yml.example references dart run devtools/scripts/affected ..., a direct path invocation that fails because the affected package has no bin/ entrypoint (only lib/affected.dart, a barrel export). The correct invocation is always through monorepo_toolkit: dart run monorepo_toolkit affected ....

Changelog ​

Run archipelago brick info affected to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.