# Migration Guide: v4 to v5

**For developers:** Canonical v4→v5 migration guide. Moved from `bugs/history/migration/` during history integration; init CLI and README reference this guide.

saropa_lints v5 migrates from `custom_lint` to the native Dart analyzer plugin system introduced in Dart 3.10.

## Automatic Migration (Recommended)

Run the init command — it auto-detects v4 `custom_lint:` config and converts it:

```bash
dart run saropa_lints:init --tier recommended
```

This will:
- Extract your v4 rule settings and preserve them as user customizations
- Remove the `custom_lint:` section from `analysis_options.yaml`
- Remove `- custom_lint` from `analyzer: plugins:`
- Warn you to remove `custom_lint` from `pubspec.yaml`

To also convert ignore comments in your `.dart` files:

```bash
dart run saropa_lints:init --tier recommended --fix-ignores
```

After running, remove `custom_lint` from `pubspec.yaml` and run `dart pub get`.

---

## Manual Migration (Reference)

The steps below are handled automatically by `dart run saropa_lints:init`. They are kept here for reference only.

## Why Migrate?

- **Quick fixes work in IDE** - the old system never delivered fix requests to custom_lint plugins
- **`dart analyze` integration** - no more `dart run custom_lint`
- **`dart fix --apply` support** - automated fixes work natively
- **Better IDE performance** - no separate isolate overhead

## Step 1: Update Dependencies

In your `pubspec.yaml`:

```yaml
# BEFORE (v4):
dev_dependencies:
  saropa_lints: ^4.15.0
  custom_lint: ^0.7.0

# AFTER (v5):
dev_dependencies:
  saropa_lints: ^5.0.0
```

Remove `custom_lint` from your dependencies. The native plugin system is built into the Dart SDK.

## Step 2: Update analysis_options.yaml

### Option A: Use a Tier Preset (Recommended)

Replace the old `custom_lint:` section with a tier include:

```yaml
# BEFORE (v4):
include: package:saropa_lints/tiers/recommended.yaml
custom_lint:
  rules:
    avoid_debug_print: true

# AFTER (v5):
include: package:saropa_lints/tiers/recommended.yaml
```

Available presets:
- `package:saropa_lints/tiers/essential.yaml` - Critical rules (~50)
- `package:saropa_lints/tiers/recommended.yaml` - Default tier (~150)
- `package:saropa_lints/tiers/professional.yaml` - Enterprise (~250)
- `package:saropa_lints/tiers/comprehensive.yaml` - Thorough (~400)
- `package:saropa_lints/tiers/pedantic.yaml` - All rules

### Option B: Use the Init Command

Regenerate your configuration:

```bash
dart run saropa_lints:init --tier comprehensive
```

This generates explicit `plugins: saropa_lints: diagnostics:` entries for all rules.

### Option C: Manual Configuration

Replace the `custom_lint:` section with `plugins:`:

```yaml
# BEFORE (v4):
custom_lint:
  enable_all_lint_rules: false
  rules:
    - avoid_debug_print: true
    - require_dispose: true
    - no_magic_number: false

# AFTER (v5):
plugins:
  saropa_lints:
    diagnostics:
      avoid_debug_print: true
      require_dispose: true
      no_magic_number: false
```

Key format changes:
- `custom_lint:` -> `plugins: saropa_lints:`
- `rules:` -> `diagnostics:`
- `- rule_name: true` -> `rule_name: true` (no list prefix)
- Remove `enable_all_lint_rules` (lint rules are disabled by default in v5)
- Severity overrides: `rule_name: warning` / `rule_name: error` / `rule_name: info`

## Step 3: Update Ignore Comments

```dart
// BEFORE (v4):
// ignore: avoid_debug_print

// AFTER (v5):
// ignore: saropa_lints/avoid_debug_print
```

The native system namespaces diagnostics with the plugin name.

## Step 4: Run Analysis

```bash
# BEFORE (v4):
dart run custom_lint

# AFTER (v5):
dart analyze
```

## Step 5: Custom Settings (Optional)

Per-project settings in `analysis_options_custom.yaml` continue to work:

```yaml
# Severity overrides
severities:
  avoid_debug_print: ERROR
  no_magic_number: false

# Baseline suppression
baseline:
  paths:
    - "lib/legacy/"

# Output control
max_issues: 500
output: both
```

## Breaking Changes

| Change | v4 | v5 |
|--------|-----|-----|
| Plugin system | `custom_lint` | Native analyzer plugin |
| Configuration | `custom_lint: rules:` | `plugins: saropa_lints: diagnostics:` |
| Run command | `dart run custom_lint` | `dart analyze` |
| Fix command | Not supported | `dart fix --apply` |
| Ignore format | `// ignore: rule_name` | `// ignore: saropa_lints/rule_name` |
| Rule defaults | All enabled | All disabled (must opt-in) |
| Dependencies | `custom_lint: ^0.7.0` | None (built-in) |

## Dart SDK 3.0 removed APIs (legacy codebases)

If you still have pre–Dart 3 snippets (or branches) that reference removed or deprecated SDK APIs, the **Recommended** tier includes migration rules in `lib/src/rules/config/dart_sdk_3_removal_rules.dart`: legacy **`dart:core`** (`List()`, `CastError`, annotations, etc.), **`dart:collection`** (`HasNextIterator`), **`dart:developer`** (`UserTag.MAX_USER_TAGS`, removed metrics types), and **`dart:io`** (`NetworkInterface.listSupported`). They use `requiredPatterns` for file-level skipping and element resolution to avoid flagging **your own** types named like the old SDK symbols. Override entries live under **Migration (Dart SDK 3.0 removals)** in [example/analysis_options_template.yaml](../../example/analysis_options_template.yaml).

## Troubleshooting

### Rules not appearing?

1. Ensure `saropa_lints: ^5.0.0` is in `dev_dependencies`
2. Ensure rules are enabled in `diagnostics:` section (they're disabled by default)
3. Restart the IDE after changing `analysis_options.yaml`

### Quick fixes not appearing?

1. Ensure you're using Dart SDK 3.10+
2. Restart the analysis server: Cmd/Ctrl+Shift+P -> "Dart: Restart Analysis Server"

### Old `custom_lint` errors?

Remove `custom_lint` from your `pubspec.yaml` and delete `lib/custom_lint_client.dart` if it exists.
