flutter_shipcheck 0.1.1

Offline release-readiness audits for Flutter apps, with explainable Android and iOS diagnostics and CI-friendly reports.

Flutter Shipcheck

Find release configuration problems before your Flutter app reaches the stores.

Shipcheck inspects a Flutter application's source configuration and explains what needs attention: the evidence, its impact, and the next action. It runs locally, without building the app, accessing credentials, uploading source, or calling a service.

$ flutter_shipcheck
Flutter Shipcheck 0.1.0
Source configuration audit · android, ios

Android
  [BLOCKER] ANDROID_RELEASE_SIGNING: The release build type explicitly selects the debug signing configuration.
    android/app/build.gradle.kts:32
    Fix: Create a release/upload signing configuration and assign it to buildTypes.release.

1 blockers · 2 warnings · 0 informational · 13 passed · 18 skipped
9 checks lack sufficient evidence. Use --verbose for details or --require-complete to gate CI.

Excerpt from the Flutter 3.44 template fixture. Full reports include explanations and official references. A passed check verifies its stated source assertion, not store acceptance. Skips expose missing evidence instead of manufacturing a clean bill of health.

Install and run

Requires Dart 3.8 or later. Flutter includes Dart; Shipcheck itself is a pure Dart package. Inspecting iOS source works on Linux and Windows too—Xcode is not required.

Add the published package to your Flutter application:

flutter pub add --dev flutter_shipcheck
dart run flutter_shipcheck
dart run flutter_shipcheck --verbose

Or install the standalone command:

dart pub global activate flutter_shipcheck

# From a Flutter application root:
flutter_shipcheck

Put the Pub cache's bin directory on PATH if needed, or use dart pub global run flutter_shipcheck.

To develop Shipcheck from a checkout:

dart pub get
dart run flutter_shipcheck /path/to/flutter-app

Normal audits are offline; initial package installation may require the package registry.

What 0.1 checks

The initial release has 34 independently testable rules, deliberately limited to evidence available in source configuration.

Area	Examples
Flutter	Application pubspec, release version/build defaults, missing asset and font references, resolution-only image variants
Android	Literal application ID, debug release signing, explicit debug/test flags, SDK ordering, configurable target SDK floor, version-code bounds
Android manifests	XML structure, exported components, cleartext declarations, network exceptions, App Links declarations, Firebase package consistency
iOS	Selected application target/configuration, Info.plist structure, bundle/version declarations, deployment-target syntax, permission description types
iOS distribution	ATS exceptions, source entitlements, associated-domain syntax, privacy manifest value shapes, named icon files, URL schemes, Firebase bundle consistency

Run flutter_shipcheck --list-rules or read the rule catalog and detection boundaries. Each finding includes a stable ID, severity, confidence, evidence path, explanation, suggested action, and official documentation. Source contents and signing credentials are not printed.

CI and reports

flutter_shipcheck --strict
flutter_shipcheck --platform android --format json > shipcheck.json
flutter_shipcheck --format sarif > shipcheck.sarif
flutter_shipcheck --require-complete --verbose

Exit	Meaning
0	No findings violating the selected policy. Skips can still exist.
1	Blockers, warnings with --strict, or unavailable checks with --require-complete.
2	Invalid arguments/configuration, inaccessible root, or unexpected rule failure.

JSON schema version 1 includes every assertion, rule metadata and coverage counts. SARIF 2.1.0 includes actionable findings and preserves passed/skipped coverage in run properties. Both are deterministic and use relative paths. See report contracts and GitHub Actions examples.

Configuration is optional

Create flutter_shipcheck.yaml in the audited application root only when needed:

platforms: [android, ios]
strict: true
ignore:
  - IOS_ATS # Intentional exception reviewed by the team.
severity:
  FLUTTER_BUILD_NUMBER: info # CI supplies --build-number.
exclude:
  - assets/generated/**
# minimum_target_sdk: 35 # Set YOUR distribution policy; not a universal default.
# ios_target: Runner
# ios_configuration: Release-production

Unknown keys, invalid types and misspelled rule IDs fail visibly. Ignored rules appear as suppressed; excluded inputs create unavailable checks. All configuration options and precedence.

Boundaries that keep the results trustworthy

Shipcheck inspects source declarations. It does not execute Gradle, Xcode, Dart code or Flutter builds. In 0.1:

• Android inspection targets conventional android/app projects. Product flavors, custom source sets and release manifest overlays can make dependent checks unavailable. Gradle expressions such as flutter.targetSdkVersion are not assigned guessed values.
• iOS selects a unique application target and an exact configuration, defaulting to Release. It parses the Xcode object graph, excludes test targets, and resolves direct build settings. External xcconfig files, generated plists and binary plists are not evaluated.
• A missing app privacy manifest is an evidence gap, not proof of a policy violation. Shape checks do not establish required-reason API coverage or reason eligibility. Dependencies and built bundles still need validation.
• Icon checks establish that named files exist. They do not assess artwork, image dimensions, transparency, launch screens or every required store slot.
• Firebase checks compare identifiers. Names such as dev or staging never establish environment intent. Build-time file selection is not verified.
• Signing selection is not signing verification. Certificates, keystores, provisioning, uploaded version history, hosted link association files and changing store deadlines remain outside the core audit.

Missing or unsupported evidence is visible with --verbose. Architecture and limitations explains the exact inspection boundary.

Contribute a trustworthy rule

Start with a reproducible release failure and an official reference. Add a focused rule with valid, invalid, malformed and ambiguity fixtures, then document the assertion it can actually make. See CONTRIBUTING.md.

dart pub get
dart format --output=none --set-exit-if-changed lib bin test example tool
dart analyze --fatal-infos
dart test

CI checks the supported Dart floor and current stable SDK, plus Linux, macOS and Windows. A template-derived regression fixture accompanies synthetic fixtures for controlled edge cases.

Shipcheck complements flutter analyze, flutter test, release builds and store validation. It is an independent project, unaffiliated with Flutter, Google or Apple.

MIT licensed. Flutter-derived test fixtures retain their separate BSD license.