---
name: resyntax
description: "Use this skill whenever running Resyntax to analyze or refactor Racket code. Triggers include: any mention of 'resyntax', 'refactoring' in a Racket context, requests to find idiomatic improvements in Racket code, or requests to clean up or modernize Racket code. Also use when the user asks to run linting or style checks on Racket files."
---

# Resyntax

## Overview

Resyntax is a refactoring tool for Racket. It analyzes Racket code and suggests
idiomatic improvements, powered by `syntax-parse`-based refactoring rules. Use
it to find and automatically apply refactorings such as removing legacy API
calls, simplifying expressions, and modernizing code style.

Resyntax has two modes: **analyze** (report suggestions) and **fix** (apply
changes to files directly).

---

## Running Resyntax

Resyntax is a *launcher*, not a `raco` command. Run it as `resyntax`, NOT
`raco resyntax`.

```sh
# Analyze a single file (report suggestions without modifying anything)
resyntax analyze --file path/to/file.rkt

# Analyze all files in a directory
resyntax analyze --directory path/to/project/

# Analyze an installed package
resyntax analyze --package my-package

# Analyze only files changed relative to a Git branch
resyntax analyze --local-git-repository . origin/main
```

### Applying fixes

Use `resyntax fix` to apply suggested changes directly to files. **Always prefer
`resyntax fix` over manually reproducing suggestions.** This ensures changes are
exactly what Resyntax intended and makes auditing easier.

```sh
# Fix a single file
resyntax fix --file path/to/file.rkt

# Fix all files in a directory
resyntax fix --directory path/to/project/

# Fix an installed package
resyntax fix --package my-package

# Fix only files changed relative to a Git branch
resyntax fix --local-git-repository . origin/main
```

---

## Workflow: Using Resyntax to refactor code

Follow this workflow when using Resyntax to improve code quality:

### Step 1: Analyze to find suggestions

Run `resyntax analyze` first to see what Resyntax would change, without
modifying any files. Review the output to understand the suggestions.

```sh
resyntax analyze --file path/to/file.rkt
```

Output looks like:

```
resyntax: path/to/file.rkt:43:5 [rule-name]

  Description of the suggested change.

  43 (original-code ...)

  43 (suggested-replacement ...)
```

Each suggestion includes:
- The file, line, and column
- The rule name in brackets (e.g. `[syntax-protect-migration]`)
- A description of why the change is suggested
- The original code and the replacement

### Step 2: Apply fixes with `resyntax fix`

Once you've reviewed the suggestions and they look appropriate, use
`resyntax fix` to apply them:

```sh
resyntax fix --file path/to/file.rkt
```

Resyntax modifies files in place. It may run multiple passes, since applying one
fix can unlock further fixes.

### Step 3: Run tests to verify

Always run the project's tests after applying fixes:

```sh
raco test path/to/file.rkt
```

### Step 4: Review the diff

Check what Resyntax actually changed:

```sh
git diff
```

This lets you (and reviewers) confirm the changes are correct before committing.

---

## Useful options

### Limiting scope

```sh
# Apply at most N fixes
resyntax fix --file foo.rkt --max-fixes 5

# Modify at most N files
resyntax fix --directory src/ --max-modified-files 3

# Modify at most N lines total
resyntax fix --directory src/ --max-modified-lines 50
```

### Targeting specific rules

```sh
# Only analyze with a specific refactoring rule
resyntax analyze --file foo.rkt --refactoring-rule if-else-false-to-and

# Only fix with a specific refactoring rule
resyntax fix --file foo.rkt --refactoring-rule syntax-protect-migration
```

### Timeouts

The default analyzer timeout is 10 seconds per analyzer per file. Increase it
for files that are slow to expand:

```sh
resyntax analyze --file foo.rkt --analyzer-timeout 30000
```

### Git integration

The `--local-git-repository` option is useful for analyzing only files that have
been modified in a branch:

```sh
resyntax analyze --local-git-repository /path/to/repo origin/main
```

### Output formats for `resyntax fix`

```sh
# Output a commit message summarizing fixes to stdout
resyntax fix --file foo.rkt --output-as-commit-message

# Output results as JSON
resyntax fix --file foo.rkt --output-as-json

# Create individual Git commits for each fix
resyntax fix --directory src/ --create-multiple-commits
```

---

## Important: always use `resyntax fix`, not manual edits

When applying Resyntax suggestions, **always use `resyntax fix`** to apply
changes rather than manually editing files to match the suggestion output. This
is important because:

1. It guarantees the applied change exactly matches what Resyntax computed.
2. It eliminates the risk of introducing typos or subtle differences when
   reproducing suggestions by hand.
3. It makes code review easier — reviewers can trust that the diff came from the
   tool itself.

The only reason to manually edit would be if `resyntax fix` fails on a specific
file (e.g., due to expansion errors) but `resyntax analyze` was able to show the
suggestion. In that case, note in the commit message that the change was applied
manually based on a Resyntax suggestion.