notjack.space / racket-skills
AI agent skill files related to programming with Racket
fork atom
racket-skills / resyntax / SKILL.md
at main 5.3 kB view raw view code
notjack.space Add Resyntax skill
3cbd70f1

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.

# 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.

# 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.

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:

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:

raco test path/to/file.rkt

Step 4: Review the diff#

Check what Resyntax actually changed:

git diff

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

Useful options#

Limiting scope#

# 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#

# 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:

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:

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

Output formats for resyntax fix#

# 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.