PostCSS Config Validator

Validate .postcssrc, .postcssrc.json, postcss.config.js, postcss.config.ts, and package.json#postcss for deprecated plugins, ordering issues, Tailwind integration problems, parser misconfiguration, and best practices. JS/TS configs are detected but cannot be statically validated. Supports text, JSON, and summary output formats with CI-friendly exit codes.

Commands

# Full validation (all 22+ rules)
python3 scripts/postcss_config_validator.py validate .postcssrc

# Quick structure-only check
python3 scripts/postcss_config_validator.py check .postcssrc.json

# Explain config in human-readable form
python3 scripts/postcss_config_validator.py explain package.json

# Suggest improvements
python3 scripts/postcss_config_validator.py suggest .postcssrc

# JSON output (CI-friendly)
python3 scripts/postcss_config_validator.py validate .postcssrc --format json

# Summary only (pass/fail + counts)
python3 scripts/postcss_config_validator.py validate .postcssrc --format summary

# Strict mode (warnings and infos become errors)
python3 scripts/postcss_config_validator.py validate .postcssrc --strict

Rules (22+)

#	ID	Category	Severity	Rule
1	S1	Structure	Error	File not found or unreadable
2	S2	Structure	Error	Empty config file
3	S3	Structure	Error	Invalid JSON syntax
4	S4	Structure	Warning	Unknown top-level keys (valid: plugins, parser, syntax, stringifier, map, from, to)
5	S5	Structure	Info	JS/TS config detected — cannot statically validate
6	P1	Plugins	Warning	Empty plugins object/array
7	P2	Plugins	Warning	Deprecated plugin (autoprefixer-core, postcss-cssnext, lost, postcss-sprites)
8	P3	Plugins	Warning	Duplicate plugins
9	P4	Plugins	Info	Plugin ordering issues (autoprefixer after preset-env, cssnano last)
10	P5	Plugins	Info	postcss-import should be first plugin
11	P6	Plugins	Info	Unknown/uncommon plugin name (not in top 50 list)
12	T1	Tailwind	Info	tailwindcss without nesting plugin
13	T2	Tailwind	Warning	tailwindcss after autoprefixer (wrong order)
14	T3	Tailwind	Info	postcss-preset-env with tailwindcss (potential conflict)
15	X1	Syntax/Parser	Warning	Both parser and syntax specified
16	X2	Syntax/Parser	Info	Unknown parser value
17	X3	Syntax/Parser	Info	Parser set but no matching preprocessor plugin
18	M1	Source Maps	Info	Source maps disabled (map: false)
19	M2	Source Maps	Info	Inline source maps enabled (map.inline: true)
20	B1	Best Practices	Warning	No plugins configured
21	B2	Best Practices	Info	Using postcss-preset-env AND individual feature plugins it includes
22	B3	Best Practices	Info	Very large number of plugins (>15)

Output Formats

• text (default): Human-readable with severity icons
• json: Machine-parseable JSON with findings array and summary
• summary: Pass/fail with error/warning/info counts

Exit Codes

• 0: No errors (warnings/infos only or clean)
• 1: One or more errors found
• 2: File not found or invalid input

Requirements

• Python 3.8+
• No external dependencies (pure stdlib)