example/README.md

SmartPub Examples #

This directory contains example usage scenarios and demonstrations of SmartPub functionality.

Files #

usage_scenarios_demo.dart #

Interactive demonstration of common SmartPub usage patterns. Run this to see examples of:

• Basic dependency analysis
• Dry-run previews
• Automatic fixes
• Interactive mode
• CI/CD integration
• Backup restoration
• Error handling

Usage:

dart run example/usage_scenarios_demo.dart

automatic_fix_demo.dart #

Demonstrates the automatic fix functionality with various dependency scenarios.

ci_integration_demo.dart #

Shows how to integrate SmartPub into CI/CD pipelines with proper exit codes and machine-readable output.

interactive_prompts_demo.dart #

Demonstrates interactive mode features and user confirmation workflows.

output_formatter_demo.dart #

Shows different output formatting options (colored, CI-friendly, etc.).

Common Usage Patterns #

1. Basic Analysis #

# Analyze current project
smartpub

# Analyze specific project
smartpub --project-path /path/to/project

2. Preview Changes #

# See what would be changed without modifying files
smartpub --dry-run

# Interactive preview
smartpub --interactive --dry-run

3. Apply Fixes #

# Automatically fix all issues
smartpub --fix

# Interactive fixes (confirm each change)
smartpub --interactive --fix

# Fix without colors (for logging)
smartpub --fix --no-color

4. CI/CD Integration #

# Check for issues in CI (exit code 1 if issues found)
smartpub --ci

# Combine with other tools
smartpub --ci && echo "Dependencies are clean" || echo "Issues found"

5. Backup and Restore #

# Restore from backup if needed
smartpub --restore

# Check if backup exists
ls pubspec.yaml.bak

Exit Codes #

• 0: Success (no issues found or operation completed successfully)
• 1: Issues found (in CI mode) or error occurred

Output Formats #

Standard Output (Colored) #

• ✅ Green for success/used packages
• ⚠️ Yellow for warnings/miscategorized packages
• ❌ Red for errors/unused packages
• 🔄 Blue for actions/moves

CI Mode Output #

• Machine-readable key-value format
• No colors or emojis
• Structured sections for parsing

Interactive Mode #

• Step-by-step prompts
• Clear explanations for each change
• Confirmation dialogs

Integration Examples #

GitHub Actions #

- name: Check dependencies
  run: dart run smartpub --ci

GitLab CI #

dependency_check:
  script:
    - dart run smartpub --ci
  allow_failure: false

Pre-commit Hook #

#!/bin/sh
dart run smartpub --ci || exit 1

Troubleshooting #

Common Issues #

1. "No pubspec.yaml found"

   • Ensure you're in a Dart/Flutter project root
   • Use --project-path to specify correct directory

2. "Permission denied"

   • Check file permissions on pubspec.yaml
   • Ensure write access for --fix operations

3. "Conflicting flags"

   • Don't combine --dry-run with --fix
   • Don't combine --restore with other modification flags

Getting Help #

smartpub --help