Lint Fix

Fix violations of rule $0 on files matching $1.

Arguments

• $0 — Rule name (e.g., use-semantic-token, no-core-import)
• $1 — File or glob pattern (e.g., static/app/components/, static/app/views/alerts/)

Step 1: Understand the Rule

Before fixing violations, know what the fix looks like. Load references/fix-patterns.md for per-rule fix details:

For use-semantic-token violations, you MUST load references/token-taxonomy.md to know which token category to use for each CSS property.

Step 2: Assess Scale

Count violations before choosing a strategy:

pnpm exec eslint --rule '@sentry/scraps/$0: error' "$1" 2>&1 | tail -5

The last line shows the count (e.g., "42 problems (42 errors, 0 warnings)").

Tip: Running eslint on all of static/app/ can take 2+ minutes. Narrow scope to a subdirectory first.

Step 3: Choose Strategy

Auto-fixable rule (any scale)

pnpm exec eslint --fix --rule '@sentry/scraps/$0: error' "$1"

Always review the diff after --fix before committing. If the rule is partially auto-fixable, run --fix first, then manually fix remaining violations.

Under 100 violations — manual agent fix

1. Run eslint on target path 2. Fix violations 5-10 files at a time 3. Re-run after each batch to verify 4. Repeat until clean

100-500 violations — batched fix

1. Split target into subdirectories (e.g., static/app/views/, static/app/components/) 2. Fix one subdirectory at a time 3. Commit after each batch for reviewable PRs 4. Re-run count after each batch to track progress

500+ violations — codemod or staged rollout

• Mechanical transforms: write a temporary jscodeshift codemod or a targeted script using @typescript-eslint/typescript-estree
• Import-path rules: --fix usually handles these at any scale
• Complex transforms: enable the rule as warn first, fix in batches across multiple PRs

Fix Workflow (tight loop)

1. Run: pnpm exec eslint --rule '@sentry/scraps/$0: error' "$1" 2. Fix violations in reported files 3. Re-run on changed files to verify 4. Expand scope, repeat

Coordinating Large Changes

• Split PRs to ~50 changed files based on ownership rules in @.github/CODEOWNERS.
• PR title convention: fix(lint): enforce @sentry/scraps/$0 for <codeowner>
• If the rule is new and not yet in eslint.config.ts, fix all violations first, then enable the rule in a follow-up PR
• Run pre-commit on changed files before committing:

  .venv/bin/prek run -q --files <file1> [file2 ...]

Verification

After all fixes:

pnpm exec eslint --rule '@sentry/scraps/$0: error' static/app/ 2>&1 | tail -5

Should report 0 problems.

Fix Patterns per Rule

Load this reference when fixing violations of a specific @sentry/scraps rule.

no-core-import

Has autofix: Yes — use --fix.

Transformation: sentry/components/core/<component>[/subpath] → @sentry/scraps/<component>

Edge cases handled by autofix:

• Deep paths collapse to the first component segment
• Type-only imports preserved
• Mixed named imports (value + type) preserved
• Multiple imports from different core paths fixed independently

Edge cases to verify after autofix:

• Files with multiple sentry/components/core/* imports that resolve to the same @sentry/scraps/* path — check for duplicate import statements that need manual merging

no-token-import

Has autofix: No.

What the rule enforces: Imports from utils/theme/scraps are only allowed in the designated theme directory.

Manual fix: Move the token usage to a component that accesses tokens via theme.tokens.* through useTheme() or styled-component theme callback, rather than importing raw token values directly.

use-semantic-token

Has autofix: No.

What the rule enforces: Theme tokens (theme.tokens.*) must only be used with CSS properties that match the token's semantic category.

Manual fix: Replace the token with one from the correct category for the CSS property being used. Consult token-taxonomy.md for the full mapping.

Example fixes:

Pattern: Keep the same specificity level (.primary, .secondary, etc.) — just change the category prefix.

restrict-jsx-slot-children

Has autofix: No.

What the rule enforces: Only specific components (from specific imports) may appear as children in configured JSX slot props.

Manual fix: Replace the disallowed JSX element with one from the allowed set. The error message tells you which components are allowed and from which import source:

<div> is not allowed in 'menuHeaderTrailingItems'. Use: MenuComponents.HeaderButton, MenuComponents.CTAButton from '@sentry/scraps/compactSelect', or Flex, Stack, Grid, Container from '@sentry/scraps/layout'.

Use the suggested components. If you need custom behavior, wrap your content in an allowed layout component.

Token Taxonomy

Load this reference when manually fixing use-semantic-token violations.

Source of truth: static/eslint/eslintPluginScraps/src/config/tokenRules.ts

Token Categories and Allowed CSS Properties

Quick Lookup: CSS Property → Correct Category

Keyword Matching Strategy

Token paths like theme.tokens.interactive.chonky.neutral.content are matched by keyword:

1. Split the path into segments 2. Find which category keyword appears deepest (last) in the path 3. That category's rule applies

Example: interactive.background.content → content wins (deeper than background).

Fix Pattern

When fixing a violation, keep the same specificity suffix and change only the category:

// Before (wrong: border token used for color)
color: ${p => p.theme.tokens.border.primary};

// After (correct: content token for color)
color: ${p => p.theme.tokens.content.primary};

If unsure which specific token name exists, check the theme definition or use your IDE's autocomplete on theme.tokens.<category>..