@codacy/tools-biome-2

Table of Contents

• Overview
• Updating patterns
• Updating the Biome version
• Development
• Notes for maintainers

Overview

JavaScript/TypeScript/CSS/JSON linter using the Biome binary. Biome is a fast web toolchain written in Rust that provides linting, formatting, and import sorting. Uses the CLI execution strategy. The binary comes from the @biomejs/biome npm package, which is an on-demand payload rather than a dependency: install runs npm ci against the committed payload/package-lock.json, so npm picks the right platform binary (including musl) on the machine that runs it.

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

Pattern IDs follow the format Biome_lint_suspicious_noDoubleEquals, Biome_lint_correctness_noUnusedVariables, etc.

Updating the Biome version

1. Update preferredVersion in src/metadata.ts
2. Update the @biomejs/biome version in devDependencies of package.json
3. Run pnpm install to get the new binary
4. Run pnpm generate-payloads biome-2 from the repo root to re-pin payload/package.json and regenerate its lockfile
5. Run pnpm prefetch — Biome adds new rules frequently
6. Run pnpm test to verify compatibility
7. If the major version changes, create a new adapter package (biome-3/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests (the payload is a devDependency, so no install is needed)

Notes for maintainers

• Preset mappings (src/pattern-mappings.json): tags only — Biome's pattern IDs are lint/<group>/<rule> and carry no framework in the path, so the tag is the only signal. drizzle-orm and turborepo were added for the three nursery rules that name those tools. The test- and a11y-tagged rules are deliberately left universal: they only match test or JSX syntax, so they are inert rather than noisy in a repo that has neither.

• Biome is a standalone Rust binary distributed via the @biomejs/biome npm package with platform-specific optionalDependencies (@biomejs/cli-darwin-arm64, @biomejs/cli-linux-x64, etc.).

• The adapter resolves the binary from @biomejs/biome/bin/biome (a JS wrapper) and invokes it via node.

• JSON output via biome lint --reporter=json — the JSON is emitted to stdout, while stderr contains an unstable API warning (filtered by the adapter).

• Exit code 0 = clean, 1 = issues found (normal), 2+ = error.

• --config-path accepts a directory path (biome looks for biome.json inside it).

• Critical gotcha: The generated biome.json must be written to a temp directory outside the repository. Biome 2.x treats any biome.json inside the repo hierarchy as a nested root configuration and errors out with "Found a nested root configuration" if there is already an implicit root at the repo level. Writing to os.tmpdir() avoids this.

• When patterns are specified, a biome.json config is generated with recommended: false and only the requested rules enabled.

• Config file search order: biome.json, biome.jsonc, .biome.json, .biome.jsonc.

• Biome reports 1-based line and column numbers — no conversion needed.

• File paths in JSON output are relative to the working directory.