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
dep_sherpa rank --top 10 --format table
dep_sherpa graph --format json
dep_sherpa diff --left old.json --right new.json
dep_sherpa explain --dependency http

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 score deltas.
• 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

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

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

Libraries

adapters/filesystem

Filesystem adapter interfaces and local disk implementation.

adapters/http_client

HTTP adapter interfaces and dart:io implementation.

adapters/process_runner

Process execution abstractions used by dep_sherpa.

cli/command_runner

Command-line entrypoint and command wiring for dep_sherpa.

dep_sherpa

Public exports for the dep_sherpa package.

domain/dependency

Dependency domain models used by dep_sherpa.

domain/report

Report models produced by dep_sherpa scans.

domain/risk_score

Risk scoring models for dependency analysis.

services/cache_service

Filesystem-backed caching for remote metadata responses.

services/config_service

Configuration models and parsing for dep_sherpa.yaml.

services/deps_service

Dependency graph inspection and lockfile parsing.

services/github_service

GitHub metadata enrichment services for dependency analysis.

services/graph_service

Dependency graph analysis and summarization.

services/pub_api_service

pub.dev metadata enrichment services for dependencies.

services/pubspec_service

Project manifest loading for dep_sherpa.

services/scan_service

Scanning and report rendering for dep_sherpa.

services/scoring_service

Dependency risk scoring and trust adjustment.