copilot-instructions.md

Overview

This repository is a Racket package called Resyntax, which is a refactoring and static analysis tool for Racket code. It analyzes code using "refactoring rules" written in a domain-specific sublanguage of Racket and implemented using Racket's macro system. Resyntax then uses these rules to suggest ways people can improve their Racket code. See the Resyntax documentation and Racket website for more information.

Adding New Refactoring Rules

When trying to add a new refactoring rule to Resyntax's default recommendations, pay special attention to the sections in the Resyntax documentation on what makes a good refactoring rule and on how to test refactoring rules. Additionally, consider running Resyntax itself on the files you touch before opening a pull request: this can help you improve your code and ensure it follows Racket's best practices. Check the documentation on the Resyntax command line tool for more information on how to run it. Beware that Resyntax is not a raco command. Run it using resyntax fix or resyntax analyze, not raco resyntax fix or raco resyntax analyze.

If you want to experiment with new refactoring rules you've created, consider doing so by cloning the DrRacket, Herbie, or Typed Racket repositories and running Resyntax on them. These repositories contain a lot of Racket code and are good candidates for testing new refactoring rules.

Pull Request Style Conventions

When creating a pull request, avoid being overly verbose in the pull request description. Keep descriptions to a single paragraph. If you need to include example code, limit it to one or two small blocks. Do not write lengthy, detailed explanations or documentation in the PR description. Avoid mentioning things that are obvious from the code changes themselves, such as lists of files changed. Reserve the PR description for only the most essential information, and err on the side of omission. There is nothing wrong with a pull request description that is just a single sentence and a mention of what issue number is being addressed.

Code Coverage

When writing tests, you can use the raco cover command to check the code coverage of your test cases. The command raco cover path/to/file.rkt will generate an HTML report showing what code is covered by running the indicated files. To check coverage for the whole repository, you can run this command:

raco cover --suppress-log-execution --package resyntax

The --suppress-log-execution flag is necessary to avoid a bug in raco cover related to Racket's logging system. The raco cover tool has a few other sharp edges like this; see its documentation for more details.

Pull requests should aim for high code coverage, and an integration with Coveralls is set up to help track coverage over time. You can view the Coveralls report for the entire repository at this link.