@codacy/tools-eslint-9

Table of Contents

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

Overview

JavaScript/TypeScript linter using ESLint 9 with the flat config format. Uses the Library execution strategy — calls the ESLint API directly rather than spawning a subprocess.

Updating patterns

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

# Commit the result
git add src/patterns.json

Pattern IDs use the codacy-eslint9 encoding: _ → __, / → _. Examples:

• ESLint9_no-unused-vars (core rule)
• ESLint9_@typescript-eslint_no-unused-vars (scoped plugin)
• ESLint9_react_jsx-no-target-blank (non-scoped plugin)

Updating the ESLint version

1. Update eslint and related packages in devDependencies of package.json, and preferredVersion in src/metadata.ts
2. Run pnpm install
3. Run pnpm generate-payloads eslint-9 from the repo root to re-pin payload/package.json and regenerate its lockfile
4. Run pnpm prefetch to check for new/removed rules
5. Run pnpm test to verify compatibility
6. If the major version changes, create a new adapter package (eslint-10/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests

Notes for maintainers

• Preset mappings (src/pattern-mappings.json): prefixes only. SonarJS's four React rules and @stylistic's JSX rules live under ESLint9_sonarjs_ / ESLint9_@stylistic_ beside those plugins' framework-agnostic rules, so the react key names them explicitly (ESLint9_@stylistic_jsx- plus the four SonarJS ids). Codacy tags them reactjs, but gating on the tag is wrong here: the same tag sits on rules that are not React rules, and because filterAutoPatterns ORs matched keys, a tag also drags in rules prefix-owned by other keys entirely (i18next/no-literal-string, perfectionist/sort-jsx-props — the latter duplicating @stylistic/jsx-sort-props). Measured on an ordinary React login form, tag gating produced 15 findings from rules the project had no reason to enable. Same reasoning for the Vue SFC custom-block rules under jsonc/yml.

  There is no webdriverio key, even though plugin-registry.ts still loads eslint-plugin-wdio and ESLint 8's mapping still gates on ESLint8_wdio_. Codacy dropped the wdio ruleset from ESLint 9's catalog, so ESLint9_wdio_ matches nothing upstream and the key was gating patterns that can no longer be selected. mapping-drift.test.ts will only catch this once pnpm prefetch refreshes patterns.json — the committed mirror still lists the three rules. Do not re-add the key without checking the tool's live pattern list first.

• ESLint 9 uses the flat config format exclusively. The adapter generates flat config arrays when building from Codacy patterns.

• Pattern IDs use the same encoding as the codacy-eslint9 wrapper: _ → __ then / → _ (encode), reverse for decode. This means _ in rule names is escaped as __.

• The blacklist.ts file contains 30+ rules known to crash ESLint or produce severe false positives, sourced from the codacy-eslint9 wrapper. The isBlacklisted() function also checks regex patterns (e.g. unused-imports/*-ts).

• The plugin-registry.ts handles lazy loading of all 68 ESLint plugin packages. Plugins are only loaded when rules from that plugin are in the active pattern selection.

• The config-builder.ts generates flat config objects from Codacy patterns, grouping rules by plugin and setting up appropriate parsers. TypeScript files get @typescript-eslint/parser; Vue/Svelte/JSONC/YML files get appropriate file globs.

• When no config or patterns are provided, the adapter falls back to @eslint/js recommended config.

• checkAvailability imports the ESLint class and returns ESLint.version.

• The tool is an npm payload, not a dependency: it is resolved at run time (a Codacy-managed install under ~/.codacy/tools/<id>/, a CODACY_TOOL_ROOT_<ID> root, or this package's own node_modules in the monorepo) and install runs npm ci against the committed payload/package-lock.json. See src/payload.ts.

• Peer dependency warnings from plugins not yet updated for ESLint 9 are expected and match the codacy-eslint9 wrapper behavior.