# Biome Migration Guide

> **Note:** This guide is intended for the migration period (Jan 2026 - Q2 2026).  
> Once Biome is fully adopted and the team is familiar with the tooling, consider:
> - Moving this to `docs/archive/` or `.github/` for historical reference
> - Removing if all team members are in agreement and rules are finalized
> - Archiving after A11y rules are enabled and warnings are addressed

## Quick Reference - Your New Workflow

### Main Commands (Same as Before!)

```bash
# Check for issues
pnpm lint:js

# Auto-fix issues (shows all output)
pnpm lint:fix

# Auto-fix issues (quiet - summary only)
pnpm lint:fix:quiet

# Full lint (CSS + JS)
pnpm lint

# Run tests (includes lint check)
pnpm test
```

### Direct Biome Commands

```bash
# Check specific files
npx biome check src/components/my-component.js

# Fix specific files
npx biome check --write src/components/my-component.js

# Format only (no linting)
npx biome format --write src/

# CI mode (warnings become errors)
npx biome ci src/

# Silent mode (no output unless errors)
npx biome check --silent src/
```

## What Changed

### package.json Scripts

**BEFORE (ESLint):**
```json
"lint:js": "eslint --ext .js,.ts,.tsx,.jsx $npm_package_config_jslintables"
"lint:js:fix": "eslint --ext .js,.ts,.tsx,.jsx --max-warnings=0 --fix $npm_package_config_jslintables"
```

**NOW (Biome):**
```json
"lint:js": "biome check $npm_package_config_jslintables"
"lint:js:fix": "biome check --write $npm_package_config_jslintables"
"lint:fix:quiet": "biome check --write --reporter=summary $npm_package_config_jslintables"
```

### New Files Added

- `biome.json` - Biome configuration
- `@biomejs/biome` in package.json devDependencies
- 1,153 files reformatted across codebase

### Can Remove Later (After Testing)

- `.eslintrc.yml` - Old ESLint config
- `@orchard/eslint-config-frontend-ts` - Old ESLint preset
- ESLint VSCode extension

## Performance Improvements

| Tool | Time | Speed |
|------|------|-------|
| ESLint | ~30-40s | Baseline |
| Biome | ~0.3-0.5s | **100x faster** |

## IDE Setup (VSCode)

### 1. Install Biome Extension
- Install: [Biome VSCode Extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
- Disable/remove ESLint extension to avoid conflicts

### 2. Configure Settings

Add to `.vscode/settings.json`:
```json
{
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}
```

## Configuration (biome.json)

### Current Rules Disabled (Permissive First Pass)

**Accessibility (8 rules):**
- `useFocusableInteractive` - Interactive elements need tabIndex
- `useSemanticElements` - Use `<hr>` instead of `role="separator"`
- `useAriaPropsForRole` - Missing ARIA attributes
- `noStaticElementInteractions` - Static elements with onClick
- `useKeyWithClickEvents` - onClick without keyboard handlers
- `noLabelWithoutControl` - Labels without associated inputs
- `noSvgWithoutTitle` - SVGs need alt text
- `useKeyWithMouseEvents` - Mouse events need keyboard equivalents

**Test Quality:**
- `noDuplicateTestHooks` - Multiple beforeEach/afterEach
- `noExportsInTest` - Exports from test files
- `noThenProperty` - Custom `.then` on objects
- `noGlobalAssign` - Reassigning globals (test mocking)

**Code Quality:**
- `noUselessFragments` - Empty `<></>` fragments
- `useIterableCallbackReturn` - forEach returning values
- `noControlCharactersInRegex` - Special chars in regex

**Performance (as warnings):**
- `noAccumulatingSpread` - Spread in reduce (O(n²))
- `noUnsafeOptionalChaining` - Unsafe optional chaining with destructuring

**Downgraded to Warnings (from errors):**
- `noEmptyPattern` - Empty object destructuring pattern (1 file - needs refactor)
- `useValidAnchor` - Anchor used as button (1 file - needs CSS review before fix)

### Enabling Rules Incrementally

To enable a rule, change it in `biome.json`:
```json
{
  "linter": {
    "rules": {
      "a11y": {
        "useKeyWithClickEvents": "warn"  // Change from "off" to "warn"
      }
    }
  }
}
```

Then fix violations:
```bash
pnpm lint:fix  # Auto-fix what's possible
pnpm lint      # Check remaining issues
```

## Common Workflows

### Before Committing
```bash
pnpm lint:fix:quiet         # Auto-fix with clean output
pnpm lint                    # Verify clean
pnpm test                    # Full test suite
```

### Working on Feature Branch
```bash
# Format as you work (VSCode extension does this automatically)

# Before pushing:
pnpm lint:fix:quiet
git add -A
git commit -m "feat: my feature"
```

### Fixing Specific Component
```bash
npx biome check --write src/components/my-component/
```

### Checking What Would Change
```bash
# Dry run - shows what would be fixed without writing
npx biome check src/components/my-component/
```

## Migration Stats

### What Was Fixed

- **1,153 files** modified
- **1,120+ files** with code improvements
- **Import organization** - All imports sorted alphabetically
- **Formatting** - Standardized to 4-space indent, single quotes, trailing commas
- **Line length** - Enforced 120 character max

### Current Status

- All tests pass
- **0 errors** (fixed 2, downgraded 2 to warnings)
- ⚠️ 142 warnings (includes 2 downgraded from errors)
- 17 info messages (code smell suggestions)

## Differences from ESLint

| Feature | ESLint | Biome |
|---------|--------|-------|
| **Speed** | Slow (~30s) | Fast (~0.3s) |
| **Formatter** | Separate (Prettier) | Built-in |
| **Config** | `.eslintrc.yml` | `biome.json` |
| **Import sorting** | Plugin needed | Built-in |
| **Language** | JavaScript | Rust (native) |
| **Dependencies** | 40+ packages | 1 package |

## Troubleshooting

### "React is not defined" errors in tests
- Fixed: `noUnusedImports` disabled to preserve React imports for React 16

### Tests failing after formatting
- Run: `npm run test:unit:update` to update snapshots

### VSCode not formatting on save
- Install Biome extension
- Set as default formatter in settings
- Restart VSCode

### CI/CD failing
- Update Jenkinsfile to use `biome` instead of `eslint`
- Use `npx biome ci src/` for strict CI mode

### Want to see all issues (including warnings)
```bash
npx biome check --verbose src/
```

### Want to suppress warnings
```bash
npx biome check --max-diagnostics=0 src/
```

## Next Steps

> **Lifecycle Note:** Review this guide quarterly. Consider archiving when:
> - All immediate/short-term tasks are completed
> - Team is comfortable with Biome workflow
> - No one references this guide for >1 month
> - Disabled rules are either enabled or documented in biome.json

### Immediate (Done)
- [x] Install Biome
- [x] Configure permissive rules
- [x] Auto-fix 1,120+ files
- [x] Update package.json scripts
- [x] Verify tests pass
- [x] Fix 2 critical errors (constructor return, Intl shadowing)
- [x] Downgrade 2 errors to warnings (empty pattern, anchor semantics)

### Short Term (This Sprint)
- [ ] Fix empty pattern in project-landing-graphic.js (verify no props passed)
- [ ] Fix useValidAnchor in apply-to-all.js (requires CSS review)
- [ ] Install Biome VSCode extension
- [ ] Update `.vscode/settings.json`
- [ ] Update CI/CD pipeline (Jenkinsfile)
- [ ] Team training/demo

### Medium Term (Next Sprint)
- [ ] Enable 1-2 A11y rules
- [ ] Fix violations as you touch files
- [ ] Remove ESLint dependencies

### Long Term (Future Sprints)
- [ ] Enable all A11y rules
- [ ] Address performance warnings
- [ ] Strict mode for new code

## Resources

- [Biome Official Docs](https://biomejs.dev)
- [Biome vs ESLint](https://biomejs.dev/guides/migrate-eslint/)
- [Biome Configuration Reference](https://biomejs.dev/reference/configuration/)
- [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
- Project Config: `biome.json` in repo root

## Questions?

Common issues and solutions documented above. For team-specific questions:
1. Check this guide
2. Review `biome.json` comments
3. Run `npx biome --help`
4. Check Biome docs

---

**Summary:** Your commands haven't changed (`pnpm lint`, `pnpm lint:fix`, `pnpm test`) - they just run 10x faster now!

Migration completed: January 8, 2026