techdebt_sherpa 0.4.0

CLI for technical debt observability and hotspot analysis in Dart and Flutter repositories.

techdebt_sherpa

Flutter Sherpa Suite — Professional Engineering Toolkit for Flutter Teams

The Flutter Sherpa Suite is a collection of focused, production-grade engineering tools for Dart and Flutter projects. Each Sherpa solves a distinct problem in the software lifecycle — from architecture and versioning to technical debt, migrations, and risk analysis.

techdebt_sherpa provides transparent technical debt and hotspot analysis for Dart and Flutter repositories.

Installation

dart pub global activate techdebt_sherpa
techdebt_sherpa --help

Quick Start

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

Canonical report files written by scan:

• reports/techdebt_sherpa.json
• reports/techdebt_sherpa.md

Optional dep_sherpa integration

techdebt_sherpa can optionally consume a dep_sherpa_report.json file and turn dep_sherpa Darwin iOS/macOS Swift Package Manager readiness findings into platform_migration_debt.

This feature does not run dep_sherpa automatically and does not perform SPM analysis itself. It only reads the additive Darwin readiness fields already reported by dep_sherpa.

Example workflow:

# Run dep_sherpa first and write reports/dep/dep_sherpa.json.
dart run dep_sherpa scan --format json --out reports/dep

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

When platform migration findings exist, JSON output includes debt_findings entries and Markdown output includes a Platform Migration Debt section. No Xcode, CocoaPods, Swift Package Manager, or macOS is required for this static workflow. dep_sherpa remains the source of truth for Darwin readiness, and techdebt_sherpa uses that data as platform migration debt.

Commands

techdebt_sherpa scan [options]
techdebt_sherpa rank [options]
techdebt_sherpa diff --left <report.json> --right <report.json> [options]
techdebt_sherpa diff <left-report.json> <right-report.json> [options]
techdebt_sherpa snapshot [options]
techdebt_sherpa trend [options]
techdebt_sherpa explain [options]

Diff examples:

techdebt_sherpa diff --left reports/old/techdebt_sherpa.json --right reports/new/techdebt_sherpa.json --format json
techdebt_sherpa diff reports/old/techdebt_sherpa.json reports/new/techdebt_sherpa.json --format json

Documentation

• Configuration Reference
• Troubleshooting
• Scoring Model
• Pub Score Playbook

Part of the Flutter Sherpa Suite

• arch_sherpa - Architectural validation and structure enforcement
• dep_sherpa - Dependency risk intelligence and observability
• semver_sherpa - Semantic versioning and changelog automation
• techdebt_sherpa - Technical debt observatory and hotspot detection

Support the Project

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

License

MIT. See LICENSE.