dep_sherpa

Flutter Sherpa Suite — Professional Engineering Toolkit for Flutter Teams

dep_sherpa is a production-grade dependency risk intelligence CLI for Dart and Flutter projects. It analyzes direct and transitive packages, combines local dependency graph data with optional online package metadata, and produces transparent risk reports that help teams decide where dependency health is drifting.

Problem Statement

Dependency management is usually reduced to "outdated or not." That misses the real engineering risk:

• a package can be current but abandoned
• a package can be popular but introduce an oversized transitive graph
• a package can be owned by your own organization and still have hard compatibility risks
• a project can look healthy while dependency risk quietly accumulates across dozens of packages

dep_sherpa answers:

• Which dependencies are high risk?
• Which may be abandoned or poorly maintained?
• Which introduce excessive transitive dependencies?
• Which are significantly behind the latest version?
• What is the overall dependency risk of this project?

Installation

dart pub global activate dep_sherpa

Or run from source:

dart run bin/dep_sherpa.dart scan

Usage

dep_sherpa scan --format both --out dep_sherpa_reports
dart run dep_sherpa scan --format json --out reports/dep
dep_sherpa rank --top 10 --format table
dep_sherpa graph --format json
dep_sherpa diff --left reports/old/dep_sherpa.json --right reports/new/dep_sherpa.json --format json
dep_sherpa diff reports/old/dep_sherpa.json reports/new/dep_sherpa.json --format json
dep_sherpa explain --dependency http

Canonical report files written by scan:

• dep_sherpa_reports/dep_sherpa.json
• dep_sherpa_reports/dep_sherpa.md

Suite report example:

dart run dep_sherpa scan --format json --out reports/dep

Commands

• dep_sherpa scan Analyzes the current project and writes Markdown and/or JSON reports.
• dep_sherpa rank Displays the highest-risk dependencies.
• dep_sherpa graph Shows dependency depth, transitive count, and central nodes.
• dep_sherpa diff Compares two JSON reports and prints JSON score deltas. Use either --left/--right or the positional alias dep_sherpa diff old.json new.json.
• dep_sherpa explain Prints the scoring model and resolved configuration.

Exit Codes

• 0: success
• 1: usage error
• 2: analysis failure
• 3: high-risk threshold exceeded

Documentation

• Scoring Model
• Configuration Reference
• Report Schema
• Troubleshooting
• Publish Playbook

How The Risk Model Works

dep_sherpa computes risk components in the range [0, 1] and then blends them into a normalized score out of 100.

• Version lag risk Uses weighted major/minor/patch deltas and an exponential lag curve.
• Maintenance risk Combines days since last publish and release frequency over the last 12 months.
• Adoption risk Uses pub.dev popularity and likes.
• Quality risk Uses pub points.
• Bus factor proxy Uses contributor count.
• Transitive impact Uses maximum dependency depth and transitive dependency count.

Each report includes:

• raw signals
• individual risk components
• base weights
• trust factor
• adjusted weights
• base score
• final score
• classification
• Sherpa policy status
• hard risk triggers

Flutter and Dart SDK-provided packages are identified separately from hosted packages using local source metadata from pubspec.lock. They remain visible in reports with source: sdk, but they are not evaluated with hosted pub.dev maintenance, adoption, quality, discontinued, or latest-version signals when those signals do not apply. This prevents false positives for SDK packages such as flutter and sky_engine.

Sherpa Suite Section

Sherpa packages must never be penalized for early-stage signals like low popularity, low likes, or a small contributor base when the package is clearly within the same trusted context.

dep_sherpa implements that through a context-aware trust model:

• same pub.dev publisher
• same GitHub organization
• explicit user configuration

No hardcoded allowlist is used. Hard risks remain active even for trusted packages:

• discontinued package
• incompatible SDK constraints
• transitive explosion
• excessive graph depth
• major version lag beyond the threshold

Configuration Guide

Create dep_sherpa.yaml at the project root:

risk_weights:
  lag: 0.22
  maintenance: 0.20
  adoption: 0.16
  quality: 0.12
  bus_factor: 0.12
  transitive: 0.18

attenuation:
  maintenance: 0.4
  adoption: 0.7
  quality: 0.2
  bus_factor: 0.7

project:
  publisher: carlosf.dev
  github_org: CarlosFAdev

manual_trust:
  dep_sherpa: 1.0

hard_risk_thresholds:
  high_risk_score: 60
  critical_risk_score: 80
  transitive_explosion: 150
  excessive_depth: 10
  major_lag: 2

network:
  enabled: true
  offline: false
  timeout_seconds: 5
  use_cache: true
  cache_ttl_hours: 24
  github_token_env: GITHUB_TOKEN

platforms:
  darwin:
    enabled: true
    analyze_ios: true
    analyze_macos: true
    analyze_add_to_app: true
    spm:
      mode: advisory
      minimum_flutter_for_plugin_spm: "3.41.0"
      warn_when_cocoapods_only: true
      warn_when_mixed_without_validation: true
      require_privacy_manifest_resource_mapping: true
    cocoapods:
      require_backwards_compatibility: true
    enforcement:
      fail_on_blocked: true
      fail_on_error_findings: true
      fail_on_warning_findings: false
      max_blocked: 0
      max_partial: null
      include_info_findings: false

iOS/macOS Swift Package Manager readiness

dep_sherpa can statically inspect Flutter projects and plugins for CocoaPods and Swift Package Manager readiness on iOS and macOS. This helps Flutter teams prepare for the CocoaPods to Swift Package Manager transition without changing the analyzed project.

The analysis is local and static. It reads pubspec.yaml plus local ios/, macos/, and darwin/ files. It does not compile native projects and does not require Xcode, CocoaPods, Swift Package Manager, macOS, or network access. For local path Flutter plugin dependencies, dependency entries can carry their own platformCompatibility.darwin state instead of inheriting the root project state.

Darwin readiness is enabled by default in advisory mode. Advisory findings are reported in JSON and Markdown, but they do not change dependency scores, classifications, hard risk triggers, or exit codes.

Run a scan with both report formats:

dep_sherpa scan --format both --out dep_sherpa_reports

Suite workflow:

dart run dep_sherpa scan --format json --out reports/dep
dart run techdebt_sherpa scan --format json --out reports/tech --dep-sherpa-report reports/dep/dep_sherpa.json

dep_sherpa remains the source of truth for Darwin readiness. techdebt_sherpa consumes the generated report when you want readiness gaps represented as platform migration debt.

Use platforms.darwin.spm.mode: off to disable the analysis. strict and ci are enforcement-oriented modes for teams that want pipeline checks. In those modes, configured Darwin readiness violations can fail scan with exit code 3, using hard trigger style identifiers such as darwin_spm_blocked, without changing dependency scores. Individual warning categories can be suppressed through platforms.darwin.spm, platforms.darwin.cocoapods, and platforms.darwin.enforcement options.

Example Output

score  class     package
 77.6  high      alpha
 41.3  moderate  beta
 34.7  moderate  sherpa_core

Offline And Caching

• Network access is optional.
• Requests use timeouts and fail gracefully.
• Cached pub.dev and GitHub responses are stored in .dep_sherpa/cache.
• Offline mode can be enabled through configuration.

Part Of The Flutter Sherpa Suite

Existing Sherpa repositories:

• arch_sherpa
• dep_sherpa
• semver_sherpa
• techdebt_sherpa

Support

• Buy Me a Coffee: https://buymeacoffee.com/carlosfdev
• Patreon: https://patreon.com/CarlosF_dev