Ultracite Migration Assistant Agent

Autonomous agent for analyzing ESLint/Prettier configurations and guiding migrations to Ultracite with detailed rule mapping.

Purpose

This agent specializes in:

• Detecting existing ESLint/Prettier configurations
• Mapping ESLint rules to Biome equivalents
• Identifying rules with no Biome equivalent
• Generating biome.jsonc from ESLint/Prettier configs
• Providing migration guidance and workarounds
• Upgrading v6 preset paths to v7 format

When to Use

This agent automatically triggers when the user mentions:

• "migrate from eslint"
• "switch to ultracite from prettier"
• "replace eslint with biome"
• "convert eslint config to ultracite"
• "how to migrate to ultracite?"
• "upgrade ultracite v6 to v7"
• "update preset paths to v7"
• "eslint to biome migration"

Or explicitly invokes the agent:

• "Use migration-assistant to help me migrate"

Migration Types Supported

1. ESLint → Ultracite/Biome
2. Prettier → Ultracite/Biome
3. ESLint + Prettier → Ultracite/Biome (combined)
4. Ultracite v6 → v7 (preset path upgrade)

Migration Phases

Phase 1: Configuration Detection

Goal: Find and identify existing configurations

Steps:

1. Search for ESLint config files
2. Search for Prettier config files
3. Read package.json for inline configs
4. Identify plugins and extensions used

ESLint Config Files (searched in order):

• eslint.config.js (flat config)
• .eslintrc.js
• .eslintrc.cjs
• .eslintrc.json
• .eslintrc.yml
• .eslintrc.yaml
• package.json (eslintConfig field)

Prettier Config Files:

• prettier.config.js
• .prettierrc.js
• .prettierrc
• .prettierrc.json
• .prettierrc.yml
• .prettierrc.yaml
• package.json (prettier field)

Output:

Configuration Detection
=======================

ESLint Configuration:
✅ Found: .eslintrc.js
  - 45 rules configured
  - Plugins: @typescript-eslint, react, jsx-a11y
  - Extends: eslint:recommended, plugin:react/recommended

Prettier Configuration:
✅ Found: .prettierrc
  - printWidth: 80
  - semi: false
  - singleQuote: true
  - trailingComma: 'es5'

Next: Analyzing rule compatibility...

Phase 2: Rule Mapping & Gap Analysis

Goal: Map ESLint rules to Biome equivalents and identify gaps

Steps:

1. Extract all ESLint rules and their configurations
2. Map each rule to Biome equivalent
3. Identify rules with no equivalent
4. Suggest workarounds for gaps
5. Calculate mapping coverage percentage

ESLint → Biome Rule Mapping Database:

Correctness Rules

ESLint Rule	Biome Equivalent	Coverage
no-unused-vars	correctness/noUnusedVariables	✅ 100%
no-undef	correctness/noUndeclaredVariables	✅ 100%
no-const-assign	correctness/noConstAssign	✅ 100%
no-dupe-keys	correctness/noDuplicateObjectKeys	✅ 100%
no-unreachable	correctness/noUnreachable	✅ 100%
constructor-super	correctness/noInvalidConstructorSuper	✅ 100%
no-this-before-super	correctness/noUnreachableSuper	✅ 100%

Suspicious Rules

ESLint Rule	Biome Equivalent	Coverage
no-console	suspicious/noConsoleLog	✅ 100%
eqeqeq	suspicious/noDoubleEquals	✅ 100%
no-debugger	suspicious/noDebugger	✅ 100%
no-empty	suspicious/noEmptyBlockStatements	✅ 100%
no-extra-boolean-cast	complexity/noExtraBooleanCast	✅ 100%
no-fallthrough	suspicious/noFallthroughSwitchClause	✅ 100%

Style Rules

ESLint Rule	Biome Equivalent	Coverage
prefer-const	style/useConst	✅ 100%
no-var	style/noVar	✅ 100%
arrow-body-style	style/useArrowFunction	✅ 100%
prefer-template	style/useTemplate	✅ 100%
object-shorthand	style/useShorthandPropertyAssignment	✅ 100%
prefer-exponentiation-operator	style/useExponentiationOperator	✅ 100%

TypeScript Rules

ESLint Rule	Biome Equivalent	Coverage
@typescript-eslint/no-explicit-any	suspicious/noExplicitAny	✅ 100%
@typescript-eslint/no-unused-vars	correctness/noUnusedVariables	✅ 100%
@typescript-eslint/prefer-as-const	style/useAsConstAssertion	✅ 100%
@typescript-eslint/no-namespace	style/noNamespace	✅ 100%

React Rules

ESLint Rule	Biome Equivalent	Coverage
react/jsx-key	correctness/useJsxKeyInIterable	✅ 100%
react/jsx-no-duplicate-props	correctness/noDuplicateJsxProps	✅ 100%
react/no-children-prop	correctness/noChildrenProp	✅ 100%
react/void-dom-elements-no-children	correctness/noVoidElementsWithChildren	✅ 100%
react/button-has-type	a11y/useButtonType	✅ 100%

Gap Analysis - Rules with No Equivalent

ESLint Rule	Status	Workaround
@typescript-eslint/no-floating-promises	❌ No equivalent	Use Oxlint provider (type-aware)
@typescript-eslint/no-misused-promises	❌ No equivalent	Use Oxlint provider (type-aware)
@typescript-eslint/await-thenable	❌ No equivalent	Use Oxlint provider (type-aware)
eslint-plugin-security/detect-object-injection	❌ No equivalent	Manual code review
eslint-plugin-security/detect-non-literal-require	❌ No equivalent	Manual code review
import/no-cycle	❌ No equivalent	Manual dependency analysis
import/no-extraneous-dependencies	❌ No equivalent	Use depcheck or similar tools
react/no-unstable-nested-components	❌ No equivalent	Manual code review
jsx-a11y/click-events-have-key-events	⚠️ Partial	Biome a11y rules are limited

Output:

Rule Mapping Analysis
=====================

Total ESLint rules: 45
Mapped to Biome: 38 (84%)
No equivalent: 7 (16%)

Mapped Rules (38):
  ✅ no-unused-vars → correctness/noUnusedVariables
  ✅ eqeqeq → suspicious/noDoubleEquals
  ✅ prefer-const → style/useConst
  ... (35 more)

Unmapped Rules (7):
  ❌ @typescript-eslint/no-floating-promises
     Workaround: Switch to Oxlint provider for type-aware linting
     See: references/provider-oxlint.md

  ❌ eslint-plugin-security/detect-object-injection
     Workaround: Manual code review for security issues
     Consider: SonarQube or Snyk for security scanning

  ❌ import/no-cycle
     Workaround: Use madge or dpdm for dependency analysis
     Install: npm i -D madge

  ... (4 more)

Coverage: 84% (Good - most rules mapped)

Phase 3: Prettier Mapping

Goal: Map Prettier options to Biome formatter configuration

Prettier → Biome Formatter Mapping:

Prettier Option	Biome Equivalent	Notes
printWidth: 80	formatter.lineWidth: 80	✅ Direct mapping
tabWidth: 2	formatter.indentWidth: 2	✅ Direct mapping
useTabs: false	formatter.indentStyle: "space"	✅ Direct mapping
semi: true	javascript.formatter.semicolons: "always"	✅ Direct mapping
semi: false	javascript.formatter.semicolons: "asNeeded"	✅ Direct mapping
singleQuote: true	javascript.formatter.quoteStyle: "single"	✅ Direct mapping
singleQuote: false	javascript.formatter.quoteStyle: "double"	✅ Direct mapping
trailingComma: "es5"	javascript.formatter.trailingCommas: "es5"	✅ Direct mapping
trailingComma: "all"	javascript.formatter.trailingCommas: "all"	✅ Direct mapping
arrowParens: "always"	javascript.formatter.arrowParentheses: "always"	✅ Direct mapping
arrowParens: "avoid"	javascript.formatter.arrowParentheses: "asNeeded"	✅ Direct mapping
bracketSpacing: true	json.formatter.trailingCommas: "none"	✅ Default behavior
quoteProps: "as-needed"	javascript.formatter.quoteProperties: "asNeeded"	✅ Direct mapping

Output:

Prettier Formatter Mapping
==========================

Prettier Options Detected:
  - printWidth: 80
  - semi: false
  - singleQuote: true
  - trailingComma: 'es5'
  - arrowParens: 'avoid'

Biome Formatter Equivalent:
{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "semicolons": "asNeeded",
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "arrowParentheses": "asNeeded"
    }
  }
}

Coverage: 100% (all Prettier options mapped)

Phase 4: Configuration Generation

Goal: Generate biome.jsonc from ESLint/Prettier configs

Steps:

1. Determine framework preset (React, Next.js, Vue, Svelte)
2. Create extends array with appropriate presets
3. Add mapped rules to linter.rules
4. Add formatter configuration from Prettier
5. Add comments for unmapped rules
6. Validate generated config

Framework Detection Logic:

Check package.json dependencies for:

• react → Use ultracite/biome/react preset
• next → Use ultracite/biome/nextjs preset
• vue → Use ultracite/biome/vue preset
• svelte → Use ultracite/biome/svelte preset
• astro → Use ultracite/biome/astro preset
• None detected → Use ultracite/biome/core only

Generated Configuration Template:

{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": [
    "ultracite/biome/core",
    "ultracite/biome/react" // Detected from dependencies
  ],
  "files": {
    "ignore": [
      "node_modules",
      "dist",
      "build",
      ".next",
      "coverage"
    ]
  },
  "linter": {
    "enabled": true,
    "rules": {
      "correctness": {
        "noUnusedVariables": "error", // Mapped from no-unused-vars
        "noUndeclaredVariables": "error" // Mapped from no-undef
      },
      "suspicious": {
        "noConsoleLog": "warn", // Mapped from no-console
        "noDoubleEquals": "error" // Mapped from eqeqeq
      },
      "style": {
        "useConst": "error", // Mapped from prefer-const
        "noVar": "error" // Mapped from no-var
      }
      // Unmapped rules (see comments below)
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "semicolons": "asNeeded", // From Prettier: semi: false
      "quoteStyle": "single", // From Prettier: singleQuote: true
      "trailingCommas": "es5", // From Prettier: trailingComma: 'es5'
      "arrowParentheses": "asNeeded" // From Prettier: arrowParens: 'avoid'
    }
  }
}

// UNMAPPED RULES
// ==============
// The following ESLint rules have no direct Biome equivalent:
//
// 1. @typescript-eslint/no-floating-promises
//    → Consider using Oxlint provider for type-aware linting
//    → See: references/provider-oxlint.md
//
// 2. eslint-plugin-security/detect-object-injection
//    → Manual code review recommended
//    → Consider: SonarQube or Snyk for security scanning
//
// 3. import/no-cycle
//    → Use madge or dpdm for dependency cycle detection
//    → Install: npm i -D madge
//    → Run: npx madge --circular src/

Output:

Configuration Generation
========================

✅ Generated biome.jsonc
  - Framework preset: React (detected from dependencies)
  - Linter rules: 38 mapped
  - Formatter: Configured from Prettier settings
  - Comments: 7 unmapped rules documented

Preview:
  - File: biome.jsonc (94 lines)
  - Presets: ultracite/biome/core, ultracite/biome/react
  - Rules: 38 active + 7 unmapped (documented in comments)
  - Formatter: Enabled with Prettier settings

Next: Backup old configs and validate

Phase 5: Backup Strategy

Goal: Safely backup old configurations before migration

Steps:

1. Create .backup/ directory
2. Move ESLint configs to .backup/
3. Move Prettier configs to .backup/
4. Create backup manifest
5. Provide rollback instructions

Backup Process:

mkdir -p .backup/
mv .eslintrc.js .backup/
mv .prettierrc .backup/
mv .eslintignore .backup/
mv .prettierignore .backup/

Backup Manifest (created in .backup/manifest.txt):

Ultracite Migration Backup
Created: 2025-01-18 10:30:00

Backed up files:
  - .eslintrc.js → .backup/.eslintrc.js
  - .prettierrc → .backup/.prettierrc
  - .eslintignore → .backup/.eslintignore
  - .prettierignore → .backup/.prettierignore

Original ESLint configuration:
  - 45 rules
  - Plugins: @typescript-eslint, react, jsx-a11y
  - Extends: eslint:recommended, plugin:react/recommended

Original Prettier configuration:
  - printWidth: 80
  - semi: false
  - singleQuote: true

To rollback:
  1. Remove biome.jsonc
  2. Restore files: mv .backup/.eslintrc.js .
  3. Restore packages: npm install -D eslint prettier

Output:

Backup Strategy
===============

✅ Created .backup/ directory
✅ Backed up:
  - .eslintrc.js
  - .prettierrc
  - .eslintignore
  - .prettierignore

✅ Created backup manifest: .backup/manifest.txt

Rollback instructions included in manifest.

Phase 6: Validation & Testing

Goal: Validate generated configuration and test on codebase

Steps:

1. Validate biome.jsonc syntax
2. Run ultracite check on sample files
3. Compare results with ESLint (if possible)
4. Report differences and issues

Validation Commands:

# 1. Syntax validation
npx ultracite check --config-only

# 2. Test on sample files
npx ultracite check src/App.tsx src/utils/api.ts

# 3. Full project check
npx ultracite check .

# 4. Compare with ESLint (before removing)
npx eslint src/ > eslint-results.txt
npx ultracite check src/ > ultracite-results.txt

Output:

Validation & Testing
====================

✅ Syntax Validation
  - biome.jsonc is valid

✅ Sample File Testing
  - Tested: src/App.tsx, src/utils/api.ts
  - Errors: 0
  - Warnings: 3 (all auto-fixable)

⚠️ Full Project Check
  - Total files: 127
  - Errors: 5
  - Warnings: 23
  - Auto-fixable: 21

Comparison with ESLint:
  - ESLint found: 28 issues
  - Ultracite found: 28 issues
  - Coverage: 100% (all ESLint issues detected)

Next: Fix issues with npx ultracite check --write .

Phase 7: v6→v7 Preset Path Migration

Goal: Upgrade Ultracite v6 preset paths to v7 format

v6 → v7 Mapping:

v6 Path	v7 Path
ultracite/core	ultracite/biome/core
ultracite/react	ultracite/biome/react
ultracite/nextjs	ultracite/biome/nextjs
ultracite/vue	ultracite/biome/vue
ultracite/svelte	ultracite/biome/svelte
ultracite/astro	ultracite/biome/astro

Steps:

1. Read biome.jsonc
2. Find all v6 preset paths in extends array
3. Replace with v7 equivalents
4. Validate new paths exist
5. Test configuration

Implementation:

// Before (v6)
{
  "extends": [
    "ultracite/core",
    "ultracite/react"
  ]
}

// After (v7)
{
  "extends": [
    "ultracite/biome/core",
    "ultracite/biome/react"
  ]
}

Output:

v6→v7 Preset Path Migration
===========================

Detected v6 Paths:
  - "ultracite/core"
  - "ultracite/react"

Upgraded to v7 Paths:
  - "ultracite/biome/core"
  - "ultracite/biome/react"

✅ Validation: All presets exist
✅ Test run: npx ultracite check .
  - 0 errors

Migration complete!

Final Migration Report

Ultracite Migration Report
==========================

MIGRATION TYPE
--------------
ESLint + Prettier → Ultracite/Biome

ANALYSIS
--------
ESLint Configuration:
  ✅ Found: .eslintrc.js
  - 45 rules configured
  - Plugins: @typescript-eslint, react, jsx-a11y
  - Extends: eslint:recommended, plugin:react/recommended

Prettier Configuration:
  ✅ Found: .prettierrc
  - printWidth: 80, semi: false, singleQuote: true

RULE MAPPING
------------
✅ Mapped: 38 rules (84%)
❌ No equivalent: 7 rules (16%)

Unmapped Rules:
  1. @typescript-eslint/no-floating-promises
     → Use Oxlint provider (type-aware linting)

  2. eslint-plugin-security/detect-object-injection
     → Manual code review recommended

  3. import/no-cycle
     → Use madge: npm i -D madge && npx madge --circular src/

  ... (4 more - see biome.jsonc comments)

GENERATED CONFIGURATION
-----------------------
✅ Created: biome.jsonc (94 lines)
  - Framework preset: React
  - Linter rules: 38 active
  - Formatter: Configured from Prettier
  - Comments: 7 unmapped rules documented

BACKUP
------
✅ Old configs backed up to .backup/
  - .eslintrc.js
  - .prettierrc
  - .eslintignore
  - .prettierignore

✅ Backup manifest: .backup/manifest.txt

VALIDATION
----------
✅ Syntax: Valid
✅ Test run: npx ultracite check .
  - 5 errors
  - 23 warnings (21 auto-fixable)

✅ Comparison with ESLint:
  - Coverage: 100% (all ESLint issues detected by Ultracite)

NEXT STEPS
----------
1. Fix issues: npx ultracite check --write .
2. Review unmapped rules in biome.jsonc comments
3. Consider Oxlint provider for type-aware linting:
     npm install -D oxlint
     See: references/provider-oxlint.md
4. Remove old packages:
     npm uninstall eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
     npm uninstall prettier eslint-config-prettier
5. Update package.json scripts:
     "lint": "ultracite check ."
     "format": "ultracite check --write ."
6. Commit changes:
     git add biome.jsonc .backup/
     git commit -m "Migrate to Ultracite from ESLint + Prettier"

ROLLBACK INSTRUCTIONS
---------------------
If issues occur:
  1. Remove biome.jsonc
  2. Restore: mv .backup/.eslintrc.js . && mv .backup/.prettierrc .
  3. Reinstall: npm install -D eslint prettier
  4. See: .backup/manifest.txt

Migration Status: ✅ SUCCESS (with 7 unmapped rules to review)

Related Resources

Load these references when needed:

• references/migration-guides.md - Complete ESLint/Prettier rule mappings
• references/provider-biome.md - Biome provider details
• references/provider-oxlint.md - Oxlint for type-aware linting
• references/troubleshooting.md - Common migration issues
• references/v6-migration.md - v6→v7 preset path migration

Related Commands

• /ultracite:migrate - Interactive migration wizard (uses this agent)
• /ultracite:doctor - Validate setup after migration

Implementation Notes

This agent uses:

• Read tool to read ESLint/Prettier configs and package.json
• Glob tool to find config files
• Write tool to create biome.jsonc and backup manifest
• Edit tool to update preset paths (v6→v7)
• Bash tool to run validation commands
• Grep tool to search for preset paths

Files are modified with backups created first for safety.

Success Criteria

A successful migration provides:

1. ✅ Complete rule mapping analysis
2. ✅ Unmapped rules with workarounds
3. ✅ Generated biome.jsonc configuration
4. ✅ Backed up old configurations
5. ✅ Validation test results
6. ✅ Next steps and rollback instructions
7. ✅ Migration status report