eslint/eslint
github.com/eslint/eslint ↗ · 2259 files · 15.8 MB
ESLint Website | Configure ESLint | Rules | Contribute to ESLint | Report Bugs | Code of Conduct | X | Discord | Mastodon | Bluesky ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.
Overview
ESLint is a configurable source-code analyzer for developers, editors, and build pipelines, exposed through a Node.js CLI and programmatic APIs. It parses JavaScript into an AST, runs selected rules, reports diagnostics, and can produce or write automatic fixes. This checkout uses flat configuration, supports custom languages, parsers, processors, rules, and formatters, and includes optional worker-thread execution and persistent lint-result caching. This brief reflects bounded source inspection at commit bc51eee6e3e816622b2dd1bc08acb9cfb2d3a6a7; tests and CI were inspected, not executed.
System map
The npm package provides both an executable and reusable analysis classes. CLI orchestration, asynchronous file/configuration work, synchronous verification, and JavaScript language support have distinct owners. Persistence consists of local cache and suppression files rather than an application database. Browser packaging and documentation builds are separate from the Node.js runtime.
- package.json publishes eslint 10.11.0 as CommonJS, maps the executable to bin/eslint.js, and exposes lib/api.js with TypeScript declarations.
- lib/api.js exports ESLint, Linter, RuleTester, SourceCode, and async loadESLint(), which returns the ESLint constructor.
- bin/eslint.js bootstraps execution and sets process.exitCode; cli.execute() interprets arguments and returns status without directly exiting.
- ESLint constructs a Linter, result cache, optional suppression service, and ConfigLoader; architecture documentation reserves asynchronous file operations for the file-oriented layer.
- Flat configuration imports are handled by ConfigLoader, while Config resolves plugin languages/processors and validates language options and rules.
- Local persistence uses file-entry-cache through LintResultCache and a JSON suppression file through SuppressionsService.
- webpack.config.js packages Linter as a UMD library with Babel and Node polyfills; docs/package.json separately builds Sass, PostCSS, Eleventy pages, and optimized images.
- Repository scripts route lint/test/release tasks through Makefile.js; eslint-config-eslint separately exports base, cjs, and formatting configurations, and version-data changes trigger a Netlify rebuild workflow.
Feature catalog
The primary interfaces lint paths or supplied text and return diagnostics with configurable severity. Users can apply fixes, choose report formats, inspect effective configuration, and manage suppression allowances. Optional caching and concurrency change execution strategy. Separate convenience flags delegate setup, MCP serving, and interactive configuration inspection to external packages.
- lintFiles() accepts file/directory/glob inputs; empty inputs default to '.', unless passOnNoPatterns requests an empty result.
- The CLI supports stdin with --stdin-filename; lintText() matches configuration using a resolved filename or __placeholder__.js and optionally reports ignored input.
- --fix and --fix-dry-run both enable fix generation, but only --fix invokes outputFixes(); --fix-type restricts fixes and stdin requires dry-run mode.
- Reports support built-in, npm, or file-path formatters and an optional output file; formatter calls receive cwd, result metadata, and lazily computed rule metadata.
- --quiet filters displayed warnings; --max-warnings can still require warning rules to execute and causes failure when the threshold is exceeded.
- --print-config calculates and prints one file's configuration; --help, --version, and --env-info return informational output through early CLI branches.
- Bulk suppression commands create allowances for all or selected rules, prune obsolete allowances, and normally reject leftover unused suppressions with exit status 2.
- Optional cache strategies are metadata/content and concurrency can choose worker execution; --init, --mcp, and --inspect-config delegate to @eslint/config, @eslint/mcp, and @eslint/config-inspector respectively.
Data flow
CLI arguments become constructor options and appended configuration overrides. File discovery resolves physical paths, while text linting uses a filename for configuration matching. Parsing produces language-owned source representations that rules turn into diagnostics and fix ranges. Results then pass through persistence, suppression, formatting, and exit-status decisions.
- translateOptions() turns globals, parser selection, CLI rules, plugins, and extensions into overrideConfig; fix/dry-run, ignores, cache, flags, and statistics become ESLint options.
- findFiles() resolves inputs against cwd, stats direct paths, loads configuration for explicit files, groups directory/glob searches, and deduplicates the resulting paths.
- ConfigLoader caches lookup promises by starting directory and configuration-array promises by config path, then replaces promises with resolved values for synchronous cached access.
- ParserService.parseSync() calls language.parse(), rejects promise results, creates SourceCode on success, and converts parse failures into severity-2 fatal diagnostics.
- JavaScript parsing requests locations, ranges, tokens, comments, visitor keys, and scope information; parseForESLint() can additionally return parser services and its own scope manager.
- runRules() derives severity/options and FileContext, registers rule selectors, traverses SourceCode synchronously, and forwards context.report() calls into FileReport.
- verifyText() converts verifyAndFix() output into LintResult with messages, suppressed messages, counts, optional fixed output, original source for unresolved problems, and optional timing statistics.
- Workers claim file indices through Atomics.add(), return indexed results through parentPort, and the controller restores input ordering before storing cache entries.
Behavior traces
The traced flows include startup, physical-file linting, stdin analysis, automatic fixing, cache reuse, and suppression persistence. Their execution order separates analysis from source writes. Configuration selection occurs before verification, and CLI suppressions occur after optional fix writes. These are source-derived walkthroughs, not observed executions.
- Startup: enableCompileCache() and optional debug initialization → main() installs fatal handlers → optional readStdin() → cli.execute() → process.exitCode assignment unless a fatal handler already set status 2.
- File action: cli.execute() constructs ESLint directly or through fromOptionsModule() → lintFiles() → findFiles() → selected single-thread/worker path → cache reconcile() → report processing.
- Single-thread verification: lintFilesWithoutMultithreading() retrieves cached configs → lintFile() checks matching config/cache → readAndVerifyFile() reads UTF-8 → verifyText() → Linter.verifyAndFix().
- Rule execution: verify() normalizes flat config → _verifyWithFlatConfigArray() selects a matching config → processor or no-processor branch → ParserService.parseSync() → runRules() → applyDisableDirectives().
- Stdin action: readStdin() accumulates UTF-8 → cli.execute() detects string input → lintText() resolves configuration by virtual filename → verifyText() generates results → printResults(); --fix is rejected for this branch.
- Fix action: verifyAndFix() repeats verify() → SourceCodeFixer.applyFixes(), stops on no fixes, bounded passes, fatal parse failure, or a two-state cycle, then re-verifies final changed text; CLI --fix subsequently calls outputFixes().
- Cache persistence: getCachedLintResults() checks file/config validity and hydrates source; cached diagnostics are reprocessed when fixing; setCachedLintResults() skips results with output; lintFiles() calls reconcile() to persist entries.
- Suppression persistence: after linting and optional outputFixes(), CLI constructs SuppressionsService → suppress()/prune() → load()/save() → applySuppressions() → counts/formatting → status 2 for unused allowances unless explicitly permitted.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is established here. The inspected suite uses Mocha-style tests, RuleTester, Chai or Node assertions, Sinon, and Proxyquire. CI defines Node, operating-system, browser, type, documentation, and ecosystem checks. Inspection is bounded, and identified limits apply to the specific tests or workflows cited.
- The configured unit runner is Mocha under c8 with --forbid-only; inspected CLI tests use Chai, Node assertions, Sinon, and Proxyquire, while ESLint-class tests also use filesystem fixtures.
- The full test target checks rule files, runs unit tests, fuzzes 150 cases with fuzzBrokenAutofixes false, and checks licenses; coverage thresholds are 99% statements/functions/lines and 98% branches.
- Inspected CLI cases assert stdin lint failure status 1, empty stdin success without log output, and unsupported-option status 2.
- RuleTester no-undef cases cover explicit globals, global comments, CommonJS require, typeof exemptions, and later syntax; Linter cases assert ECMAScript-version-dependent global availability.
- Inspected persistence tests assert ESLint/Node versions participate in cache hashing and suppression loading handles valid JSON, missing files, and malformed JSON; suppression readFile calls are stubbed in these cases.
- ESLint constructor tests assert numeric/auto concurrency rejects uncloneable function/plugin options with ESLINT_UNCLONEABLE_OPTIONS and recommends options modules.
- Main CI defines Linux Node 20/22/24/26 runs, minimum Node 20.19.0, Windows/macOS LTS runs, fuzzing and EMFILE checks; Cypress selects only tests/lib/linter/linter.js with a built-bundle alias, so that browser job does not select CLI/file-engine tests.
- CI also defines type/compiler compatibility checks, external-consumer type tests, docs builds/link validation, and ecosystem plugin tests; the ecosystem matrix explicitly disables typescript-eslint pending test updates.
Risk map
These observations identify execution and persistence boundaries requiring care; they are not confirmed vulnerabilities. Configuration and extension modules execute within the host process, and convenience commands can invoke external package tooling. Filesystem destinations are resolved from caller-controlled paths rather than constrained to a repository root. Fixing, caching, suppressions, and concurrency have conditions that can materially change results or side effects.
- Configuration discovery searches upward from target directories and imports executable modules; explicit config paths resolve against cwd, so config loading can cross the repository boundary.
- CLI parser/plugin selection and formatter loading import caller-selected modules; imported code therefore participates in the host runtime rather than a separate analysis sandbox.
- --init and --mcp synchronously spawn npm/npx with inherited stdio and propagate status/signals; --inspect-config similarly invokes npx. These paths delegate package acquisition/execution to external tools.
- outputFixes() writes any result containing string output and an absolute filePath; report output resolves against process.cwd() and creates parent directories. Neither shown writer enforces a repository-root boundary.
- lintFiles() can delete the resolved cache file when caching is disabled; getCacheFile() accepts absolute or cwd-relative destinations, making cacheLocation relevant even outside cache-enabled runs.
- Autofix convergence is bounded and detects return to text from two iterations earlier; fix-range application rejects conflicts. The implementation does not establish general convergence or semantic equivalence of rule-provided fixes.
- Suppression loading performs JSON.parse() without shape validation in load(), and save() directly overwrites the file. Hypothesis: malformed-but-valid JSON or interrupted/concurrent writes merit focused robustness checks; these were not demonstrated failures. (inferred)
- The low-overhead visitor branch tags listener functions with rule IDs and falls back to wrappers when functions are shared across rules; changes here must preserve attribution for shared visitors, timing, and statistics.
Extension points
Extension is centered on flat configuration and explicit plugin objects. Rules, languages, processors, and parsers connect at different stages of verification. Formatters extend the output boundary, while configuration helpers and feature flags provide additional integration surfaces. Built-in rules are registered lazily and follow the same metadata/create contract used by rule tests.
- New built-in rules enter the alphabetized LazyLoadingRuleMap in lib/rules/index.js; defaultConfig exposes that map through a proxy under the internal '@' plugin.
- Rule modules provide create(context) and metadata; runRules() rejects missing create(), requires meta.fixable for emitted fixes, and requires meta.hasSuggestions for suggestions.
- Plugin rule IDs resolve through config.plugins[pluginName].rules[ruleName]; CLI --plugin normalizes package names and registers default exports under shorthand names.
- Language plugins register under plugins[namespace].languages[name]; Config merges defaults, validates languageOptions, and optionally normalizes them before parsing.
- Custom JavaScript parsers may implement parseForESLint() or parse(); enhanced parser results can supply services, visitor keys, and scopeManager.
- Processors can be plugin-qualified names or objects; verification uses preprocess/postprocess and disables fixes unless supportsAutofix is true.
- Custom formatters are dynamically imported functions from paths or eslint-formatter packages; their wrapper sorts results and supplies contextual/rule metadata.
- eslint/config re-exports defineConfig(), globalIgnores(), and includeIgnoreFile(); behavior experiments register in activeFlags/inactiveFlags, including unstable_native_nodejs_ts_config.
Contributor handoff
Begin with the actual implementation and nearby tests, then use architecture documentation to preserve ownership boundaries. Tests and CI were inspected, not executed; this brief provides no passing checks or exhaustive coverage assessment. Rule changes couple source, tests, documentation, and generated metadata. Pay particular attention to virtual filenames, executable configuration, cache side effects, suppression counters, and worker option transport.
- Read AGENTS.md, package.json, architecture documentation, and the affected implementation/test first; keep synchronous verification and rules free of asynchronous work, filesystem access, and console output.
- Do not treat AGENTS.md's ownership shorthand as a substitute for source: bin/eslint.js sets process.exitCode and spawns tools, while lib/cli.js itself writes reports and orchestrates suppression files.
- For a rule change, maintain its source/test/docs trio, register new rules alphabetically, use messageId and metadata schemas, and place reusable AST helpers at module scope.
- Rule edits trigger tooling for all/recommended configurations and rule type headers; rule-doc edits trigger example checks and further-reading data regeneration. Avoid hand-editing these derived outputs.
- When test execution is authorized, start with the affected file through npm run test:cli, then choose relevant lint, rule-example, type, or browser checks; full npm test adds coverage, fuzzing, consistency, and license checks.
- Verification expectations here come from inspected definitions, not executed results: c8 thresholds are configured, and the browser suite selects the Linter test file rather than the entire Node suite.
- Concurrency edits must preserve cloneability/options-module transport, atomic file assignment, ordered indexed results, worker-error cancellation, and cache updates in the controlling thread.
- GitHub issues, PRs, and comments require AI disclosure using the actual producing model; AGENTS.md also limits AI-generated PR consideration to accepted issues and expects human responses to maintainer feedback.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 1456 | 96% |
| Markdown | 422 | docs/config |
| JSON | 92 | docs/config |
| YAML | 54 | docs/config |
| HTML | 38 | docs/config |
| Sass | 35 | 2% |
| TypeScript | 22 | 1% |
| Shell | 1 | 0% |
Start reading here
Probable source entrypoint: lib/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (395 files) packages/ (23 files)
Repository structure
| Top-level path | Files |
|---|---|
tests/ | 1138 |
docs/ | 604 |
lib/ | 395 |
tools/ | 24 |
packages/ | 23 |
.github/ | 22 |
messages/ | 18 |
templates/ | 5 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.mddocs/README.mddocs/src/about/index.mddocs/src/contribute/ai-policy.mddocs/src/contribute/architecture/index.mddocs/src/contribute/code-conventions.mddocs/src/contribute/code-of-conduct.mddocs/src/contribute/core-rules.md
Package
package.json — eslint v10.11.0, 80 declared dependencies.
@arethetypeswrong/cli@babel/core@babel/preset-env@cypress/webpack-preprocessor@eslint-community/eslint-utils@eslint-community/regexpp@eslint/config-array@eslint/config-helpers@eslint/core@eslint/eslintrc@eslint/json@eslint/plugin-kit
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/update-readme.yml— GitHub Actions workflow.github/workflows/codeql-analysis.yml— GitHub Actions workflow.github/workflows/rebuild-docs-sites.yml— GitHub Actions workflow.github/workflows/stale.yml— GitHub Actions workflow.github/workflows/ecosystem-tests.yml— GitHub Actions workflow.github/workflows/ecosystem-updates.yml— GitHub Actions workflow.github/workflows/pr-labeler.yml— GitHub Actions workflow.github/workflows/docs-ci.yml— GitHub Actions workflow
Structural health signals
Average score 7/10 across 96 analyzed source files; 15 hotspots surfaced.
docs/src/assets/js/css-vars-ponyfill@2.js— 1493 lines, score 4 (Large file, Deep nesting)lib/rules/no-extra-parens.js— 1669 lines, score 5.5 (Large file, Deep nesting)docs/.eleventy.js— 589 lines, score 5.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
bc51eee6e3e82026-10-02 — fix: `prefer-arrow-callback` false positive in conditional test (#21373)bbff86c415212026-10-02 — fix: skip lines with multiple comments in `max-lines-per-function` (#21332)152067f0f81f2026-10-01 — chore: update ecosystem plugins (#21362)b56d58e0b1f32026-10-01 — chore: update github/codeql-action action to v4.38.2 (#21376)67eb586e2eda2026-10-01 — docs: Update README