stylelint-config-validator
Validate Stylelint configuration files for correctness, deprecated rules, and best practices.
What it does
Checks .stylelintrc / .stylelintrc.json / .stylelintrc.yaml for:
- Rules — unknown rules, deprecated rules (70+ deprecated in Stylelint 16), null values, many disabled rules
- Config structure — unknown config keys, extends/plugins arrays, override validation
- Deprecated rules — blacklist→disallowed-list renames, removed formatting rules (use Prettier instead)
- Extends — duplicate entries, prettier config ordering (must be last)
- Plugins — duplicates, plugin-prefixed rules without declared plugins
- Overrides — missing files property, deprecated rules in overrides
Rules (20+)
| Category | Rules | Examples |
|---|---|---|
| Config structure (4) | Unknown keys, invalid types, no rules or extends, invalid defaultSeverity | customConfig: true → unknown key |
| Rules validation (5) | Deprecated rules (70+), unknown rules, null values, disabled rule ratio | indentation: 2 → deprecated in v16 |
| Extends (3) | Duplicate entries, non-array type, prettier ordering | prettier before standard → wrong order |
| Plugins (3) | Duplicate plugins, non-array type, plugin rules without plugins | scss/no-dollar-variables without plugin |
| Overrides (3) | Non-array type, missing files, deprecated rules in overrides | Override without files property |
| Ignore files (1) | Catch-all patterns | ignoreFiles: "*" matches everything |
Output formats
- text — human-readable with severity icons (❌ ⚠️ ℹ️)
- json — structured with summary counts
- summary — one-line PASS/WARN/FAIL
Exit codes
0— no errors1— errors found (or--strictwith any issue)2— file not found or parse error
Commands
lint / validate
Full config validation.
python3 scripts/stylelint_validator.py lint .stylelintrc.json
python3 scripts/stylelint_validator.py validate --format json .stylelintrcrules
Check rules only (deprecated, unknown, conflicts).
python3 scripts/stylelint_validator.py rules .stylelintrc.jsondeprecated
List only deprecated rules in the config.
python3 scripts/stylelint_validator.py deprecated .stylelintrc.jsonOptions
| Option | Values | Default | Description |
|---|---|---|---|
--format | text, json, summary | text | Output format |
--min-severity | error, warning, info | info | Filter by minimum severity |
--strict | flag | off | Exit 1 on any issue |
Requirements
- Python 3.8+
- No external dependencies (pure stdlib)
Examples
# Quick check
python3 scripts/stylelint_validator.py lint .stylelintrc.json
# CI pipeline
python3 scripts/stylelint_validator.py lint --strict --format summary .stylelintrc
# Find deprecated rules to upgrade
python3 scripts/stylelint_validator.py deprecated .stylelintrc.json
# JSON output for tooling
python3 scripts/stylelint_validator.py validate --format json .stylelintrc.yaml