ESLint Flat Config Validator

Validate ESLint v9+ flat config files (JSON-exported) for structural correctness, language options, rules configuration, plugin hygiene, file patterns, and b...

Security Scan

The skill is internally consistent: it validates ESLint v9+ flat configs by reading a JSON snapshot and contains only a local Python validator; nothing requested or installed appears disproportionate to its stated purpose.

Purpose & Capability

Name/description match the included Python validator. The skill requires no extra binaries, env vars, or unrelated permissions; the provided script and SKILL.md behavior are coherent with an ESLint flat-config validator.

Instruction Scope

SKILL.md instructs users to export their eslint.config.js to JSON using a Node import, then run the included Python script to validate that JSON. The Python script appears to only read the provided JSON and run static checks (no network, subprocess, or extraneous file reads). Caveat: the node export command will execute the user's eslint.config.js (this is necessary to obtain the config object) so that step can run arbitrary JS present in the config file; this is expected but worth noting.

Install Mechanism

No install spec (instruction-only). The package includes a single Python script that uses only the stdlib; there are no downloads, external package installs, or archive extraction instructions.

Credentials

The skill requests no credentials or env vars and the validator script doesn't appear to read environment secrets. The only proportionality concern is that exporting the config via the recommended node import will execute eslint.config.js — that execution could access env vars or perform side effects if the config contains code. This is an inherent consequence of evaluating JS config files, not a behavior introduced by the skill itself.

Persistence & Privilege

The skill is not always:true, does not persist or modify other agent/system settings, and does not request elevated privileges or long-lived presence.

Assessment

This skill is coherent and appears to do what it says: it validates a JSON-exported ESLint flat config using a bundled Python script. Before running it: 1) inspect or trust the eslint.config.js you will import — the node export command executes that file and could run arbitrary JS (access env vars, network, or perform side effects) if the config contains such code; 2) if the config is untrusted, export it in an isolated environment (ephemeral container, CI runner, or VM) before validating; 3) you can also manually produce the JSON snapshot and pass it to the Python script to avoid re-executing project code; 4) optionally review the included Python script (it's standard-library-only) if you want to audit exactly what checks are performed.

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