Eslint Flat Config Validator

Validate ESLint v9+ flat config files (JSON-exported) for structural correctness, language options, rules configuration, plugin hygiene, file patterns, and best practices. Use when auditing ESLint projects, enforcing config standards in CI, or reviewing eslint.config.js changes.

Validate ESLint v9+ flat configuration files exported as JSON for structural correctness, language options, rules configuration, plugin setup, file/ignore patterns, and best practices. Uses pure Python 3 stdlib (json, argparse, re, os, sys) -- no external dependencies.

Since ESLint flat configs are JS/MJS/CJS (eslint.config.js), the validator works with JSON-exported snapshots. Export your config first:

node -e "import('./eslint.config.js').then(m => console.log(JSON.stringify(m.default)))" > eslint.config.json

Then validate the JSON output.

Commands

validate -- Comprehensive validation with all rules and summary

python3 scripts/eslint_flat_config_validator.py validate eslint.config.json
python3 scripts/eslint_flat_config_validator.py validate eslint.config.json --strict
python3 scripts/eslint_flat_config_validator.py validate eslint.config.json --format json

lint -- Run all rules

python3 scripts/eslint_flat_config_validator.py lint eslint.config.json
python3 scripts/eslint_flat_config_validator.py lint eslint.config.json --format summary

rules -- Check rules configuration

python3 scripts/eslint_flat_config_validator.py rules eslint.config.json
python3 scripts/eslint_flat_config_validator.py rules eslint.config.json --format json

plugins -- Check plugin configuration

python3 scripts/eslint_flat_config_validator.py plugins eslint.config.json
python3 scripts/eslint_flat_config_validator.py plugins eslint.config.json --format json

Flags

Flag	Description
--strict	Treat warnings as errors -- exit code 1 (CI-friendly)
--format text	Human-readable output (default)
--format json	Machine-readable JSON
--format summary	Compact summary with counts

Validation Rules (25)

Structure (5)

Rule	Severity	Description
S1	error	File not found or unreadable
S2	error	Empty config (empty array or no objects)
S3	error	JSON syntax errors
S4	error	Not an array (flat config must be an array of config objects)
S5	warning	Unknown top-level keys in config objects (valid: files, ignores, languageOptions, linterOptions, plugins, processor, rules, settings, name)

Language Options (5)

Rule	Severity	Description
L1	error	Invalid ecmaVersion (must be number >= 3 or "latest")
L2	error	Invalid sourceType (must be "module", "script", or "commonjs")
L3	warning	Invalid parser value (should be object with parse/parseForESTree, warn if string)
L4	error	globals with invalid values (only "readonly"/"writable"/"off" or true/false/"readable")
L5	info	Missing ecmaVersion (defaults to "latest" in ESLint v9)

Rules (5)

Rule	Severity	Description
R1	error	Unknown severity (must be "off"/0, "warn"/1, "error"/2)
R2	warning	Rules with deprecated names
R3	warning	Conflicting rules (e.g., indent + @typescript-eslint/indent)
R4	info	Empty rules object
R5	error	Rule config not array or severity (must be severity or [severity, ...options])

Plugins (3)

Rule	Severity	Description
P1	info	Empty plugins object
P2	error	Plugin value not object (plugin values should be plugin objects)
P3	warning	Duplicate plugin key across config objects

Files/Ignores (4)

Rule	Severity	Description
F1	info	Missing files pattern in non-global config (config without files/ignores applies globally)
F2	error	Invalid glob patterns (empty string)
F3	error	files as string instead of array
F4	error	ignores as string instead of array

Best Practices (3)

Rule	Severity	Description
X1	warning	No rules defined in any config object
X2	warning	Many config objects (>20) suggest consolidation
X3	info	Missing "name" property (recommended in v9 for debugging)

Exit Codes

Code	Meaning
0	No errors (warnings allowed unless --strict)
1	Errors found (or warnings in --strict mode)
2	File not found / parse error

CI Integration

# GitHub Actions
- name: Validate ESLint flat config
  run: |
    node -e "import('./eslint.config.js').then(m => console.log(JSON.stringify(m.default)))" > /tmp/eslint.config.json
    python3 scripts/eslint_flat_config_validator.py validate /tmp/eslint.config.json --strict --format json

Example Output

eslint.config validate — eslint.config.json
============================================
[ERROR  ] S5: Unknown top-level key in config object #2: 'env'
         'env' is not valid in flat config. Valid keys: files, ignores, languageOptions, linterOptions, plugins, processor, rules, settings, name
[ERROR  ] R1: Invalid rule severity for 'no-unused-vars': 'on'
         Severity must be 'off'/0, 'warn'/1, or 'error'/2.
[WARNING] R2: Deprecated rule 'no-buffer-constructor' in config object #1
         This rule was deprecated in ESLint v7. Remove it or replace with the recommended alternative.
[WARNING] X1: No rules defined in any config object
         At least one config object should define rules for ESLint to enforce anything.
[INFO   ] X3: Config object #3 missing 'name' property
         Adding a name helps identify config objects in ESLint's debug output and error messages.

Result: INVALID
Summary: 2 error(s), 2 warning(s), 1 info