pokerogue/docs/linting.md

Linting & Formatting

Writing clean, readable code is important, and linters and formatters are an integral part of ensuring code quality and readability.
It is for this reason we are using Biome, an opinionated linter/formatter (akin to Prettier) with a heavy focus on speed and performance.

Installation

You probably installed Biome already without noticing it - it's included inside package.json and should've been downloaded when you ran pnpm install after cloning the repo. If you haven't done that yet, go do that first.

Using Biome

For the most part, Biome attempts to stay "out of your hair", letting you write code while enforcing a consistent formatting standard and only notifying for errors it can't automatically fix.
On the other hand, if Biome complains about a piece of code, there's probably a good reason why. Disable comments should be used sparingly or when readabilty demands it - your first instinct should be to fix the code in question, not disable the rule.

Editor Integration

Biome has integrations with many popular code editors. See these pages for information about enabling Biome in your editor of choice.

Automated Runs

Generally speaking, most users shouldn't need to run Biome directly; in addition to editor integration, a pre-commit hook will automatically format and lint all staged files before each commit.

![WARNING] You will not be able to commit code if any staged files contain error-level linting problems.
If you, for whatever reason, absolutely need to bypass Lefthook for a given commit, pass the --no-verify flag to git commit.

We also have a Github Action to verify code quality each time a PR is updated, preventing bad code from inadvertently making its way upstream.
These are effectively the same commands as run by Lefthook, merely on a project-wide scale.

Running Biome via CLI

To run Biome on your files manually, you have 2 main options:

1. Run the scripts included in package.json (pnpm biome and pnpm biome:all).
   These have sensible defaults for command-line options, but do not allow altering certain flags (as some cannot be specified twice in the same command)

2. Execute the Biome executable manually from the command line like so:

   pnpm exec biome check --[flags]
   

   This allows customizing non-overridable flags like --diagnostic-level on a more granular level, but requires slightly more verbosity and specifying more options.

A full list of flags and options can be found on their website, but here's a few useful ones to keep in mind:

• --write will cause Biome to write all "safe" fixes and formatting changes directly to your files (rather than just complaining and erroring out).
• --changed and --staged will limit checking to all changed or staged files respectively. Biome sources this info from the relevant version control system (in this case git).
• diagnostic-level=XXX will only show diagnostics with at least the given severity level (info/warn/error). Useful to only focus on errors causing a failed workflow run or similar.

Linting Rules

We primarily use Biome's recommended ruleset for linting JS/TS files, with some customizations to better suit our project's needs.
A complete list of rules can be found in the biome.jsonc file in the project root. Most rules are accompanied by comments explaining the reasons for their inclusion/exclusion.

Important

Certain lint rules may be marked as info or warn to allow for gradual refactoring without blocking development. Do not write new code that triggers these rules!

Any questions about linting rules can be brought up in the #dev-corner channel in the community Discord.