stylelint/stylelint
github.com/stylelint/stylelint ↗ · 1125 files · 3.7 MB
Stylelint A mighty CSS linter that helps you avoid errors and enforce conventions.
Overview
Stylelint is a configurable CSS linter for stylesheet authors and tooling developers, distributed as a Node.js package with a CLI, asynchronous JavaScript API, and PostCSS plugin. Its core converts stylesheets into PostCSS trees, runs explicitly configured rules, and returns diagnostics, optional edits, or rewritten files. Lazy rule loading, per-file configuration overrides, custom syntaxes, plugin rules, reference stylesheets, and experimental count-based suppressions make it adaptable to larger projects. This brief describes source inspected at commit bc06c7cdb1413de3d8dc939b33af138ab7e59df1; it does not establish runtime correctness.
System map
The runtime is a Node.js library and CLI centered on a shared PostCSS linting pipeline. Configuration discovery, rule execution, formatting, and persistence have separate modules, while each linter instance owns several caches. npm scripts define development checks, and GitHub workflows handle CI, preview packages, and releases.
- The npm package exports lib/index.mjs and TypeScript declarations, installs bin/stylelint.mjs as the stylelint command, and requires Node.js >=20.19.0.
- bin/stylelint.mjs forwards process.argv.slice(2) to cli; lib/index.mjs augments the PostCSS plugin creator with lint, resolveConfig, registries, plugin creation, utilities, and reference data.
- standalone orchestrates inputs and outputs; lintSource resolves configuration and parsing; lintPostcssResult loads and invokes configured rules on PostCSS roots.
- createStylelint constructs cosmiconfig explorers, four in-memory Maps, and a FileCache; production discovery uses the global search strategy, while NODE_ENV=test sets a stop directory.
- Core rules and built-in formatters are loaded through asynchronous getters; rule import promises are retained in a module-level Map.
- Runtime integrations include PostCSS, cosmiconfig, globby, file-entry-cache, CSS parsers, and write-file-atomic; npm's version-3 lockfile records the package dependency graph.
- npm scripts provide benchmarks, formatting, ESLint, Markdown linting, TypeScript checking, Jest, and node:test; TypeScript checks JavaScript strictly with no emit and excludes test files.
- CI delegates matrix tests to a pinned reusable workflow; preview publishing uses pkg.pr.new; release-PR and release workflows delegate to pinned workflows with write permissions.
Feature catalog
Users can lint files, glob patterns, or supplied code and configure which rules run. Diagnostics support severity controls, custom messages, multiple formats, inline disabling, autofixes, and edit information. Custom syntaxes, reference files, configuration inheritance, and suppressions extend the basic CSS workflow.
- The CLI accepts file paths and globs or reads stdin when no positional input exists; the Node API requires either files or a code string, rejecting simultaneous or missing inputs.
- Configured rules cover error prevention and conventions; color-no-invalid-hex checks declaration values while skipping URL functions, and color-hex-length supports short/long notation with autofixing.
- Configuration supports extends and matching per-file overrides; extended rule settings are replaced as complete values, and the original config is merged last.
- Custom syntaxes enable other styling languages and embedded containers; the loader accepts module names or syntax objects and supplies PostCSS.stringify for parser-only modules.
- Output formats include compact, json, string, tap, unix, and verbose; custom formatters receive results and aggregate metadata, and --output-file writes a report with terminal control characters removed.
- Users can control severity, messages, URLs, quiet reporting, and inline disables; lintSource additionally runs needless, invalid-scope, descriptionless, and unscoped-disable reporting after rules.
- Autofixing offers strict and lax parsing modes; computeEditInfo returns replacement ranges and text when fixing is disabled, respecting disableFix and inline disable ranges.
- Reference files are resolved as globs and parsed with optional custom syntax/loaders; experimental bulk suppressions persist error counts per file and rule, with stdin suppression rejected by the CLI.
Data flow
Input paths are normalized and filtered before stylesheet reads. Per-file configuration controls parsing, reference loading, rule execution, and diagnostic transformation. PostCSS results own execution metadata, while standalone turns those results into reports and optional disk writes.
- standalone resolves relative codeFilename against cwd; file inputs escape existing literal paths, add default node_modules exclusions, expand globs to absolute paths, and apply ignore-file patterns.
- getConfigForFile prefers options.config, then configFile, then searchPath discovery with a cwd fallback; augmented configuration is cached per target path.
- augmentConfigFull applies basic augmentation, plugins, processors, reference-file resolution, custom syntax, rule normalization, and language-option validation in that order.
- getPostcssResult selects supplied code or UTF-8 file contents, parses through PostCSS, and caches results by normalized path; lax mode selects postcss-safe-parser.
- Reference stylesheets are independently read and processed with optional loaders; Document nodes are flattened into roots, then attached to result.stylelint alongside the lexer and rule metadata.
- report resolves severity and custom messages, filters quiet warnings, applies eligible fixes, records disabled warnings, and otherwise emits PostCSS warnings with locations and optional edit data.
- createPartialStylelintResult separates deprecations, invalid options, and parse errors from ordinary warnings; prepareReturnValue derives errored/maxWarningsExceeded and calls the selected formatter.
- String input returns fixed CSS as result.code; file input conditionally writes changed CSS atomically, applies result processors and suppressions, reconciles caching, and then formats aggregate output.
Behavior traces
The inspected traces cover CLI initialization, file linting, stdin linting, fixing, suppression persistence, configuration printing, and PostCSS integration. These paths converge at lintSource but have different output and persistence behavior. Conditions such as ignored inputs, cache hits, syntax errors, and conflicting flags materially change the sequence.
- CLI startup runs bin → cli → buildCLI/meow; help and version return early, while custom formatter loading and typed option translation precede selecting files or stdin.
- File linting runs standalone → getFileIgnorer/createStylelint → globby/filterFilePaths → lintSource → getConfigForFile/getPostcssResult → lintPostcssResult; unmatched and fully ignored inputs have separate errors unless allowEmptyInput is enabled.
- For color-no-invalid-hex, lintPostcssResult resolves the rule, supplies normalized settings, and invokes its root callback; that callback validates options, walks declarations/value tokens, calculates offsets, and calls report for invalid hex words.
- Stdin runs getStdin → standalone's code branch → lintSource → createPartialStylelintResult → result processors → prepareReturnValue; fixed code goes to stdout, reports to stderr, and lint errors or excess warnings set the lint-problem exit code.
- A color-hex-length fix flows from its report fix object → isFixApplied → callback mutation of the declaration → root serialization; standalone writes only changed, nonignored file results when its fix argument is truthy.
- Suppression persistence runs standalone path resolution → SuppressionsService.suppress → load → countProblemsByRule → applySuppressions → prune → save; standalone reloads the JSON and applies suppressions before final formatting.
- --print-config runs printConfig → resolveConfig → createStylelint/getConfigForFile → JSON serialization omitting private properties; printConfig rejects stdin, multiple paths, and dynamic glob patterns.
- PostCSS integration runs stylelint(options) → createStylelint → Once(root, helpers) → lintSource with existingPostcssResult; supplied trees bypass getPostcssResult parsing and rules run against each root of a Document.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is asserted. The repository combines Jest rule schemas, integration tests, snapshot system tests, and selected node:test suites. The inspected tests demonstrate substantial behavioral specifications, but this bounded review does not establish exhaustive coverage or identify every untested branch.
- package.json configures Jest with jest-preset-stylelint, a Node environment, lib/system-tests/.changeset roots, V8 coverage, and global 90% thresholds; these are configured targets, not observed results.
- jest.setup.mjs exposes testRule and testRuleConfigs against the public lint API; setupAfterEnv clears emitted-warning state after each test.
- The inspected color-no-invalid-hex rule tests specify accepted alpha hex forms, quoted strings, URL fragments, and rejected hex values with exact start/end positions.
- standalone-fix tests specify fixed string output, config-enabled fixing, ignored inputs, and inline-disable behavior; edit-information tests specify replacement text/ranges and disableFix handling.
- standalone-cache tests inspect persisted cache entries, changed-file selection, config invalidation, and exclusion of error/warning files; their setup and cleanup perform filesystem mutations.
- CLI tests specify flag parsing; suppression tests mock process streams and check conflicting flags/stdin rejection; plugin tests exercise relative and absolute modules through PostCSS.
- System case 001 snapshots both filesystem and string-input APIs; snapshot preparation normalizes sources and removes private PostCSS results. The contributor guide explicitly describes system tests as real-use-case checks rather than comprehensive coverage.
- CI declares Node 20/22/24/26 across three OS families, a separate Node-24 coverage job, and an explicitly enabled Yarn PnP run; the default-gated PnP suite packages and installs dependencies, so ordinary Jest coverage does not imply it ran.
Risk map
The main sensitive boundaries are executable extensions, arbitrary configured filesystem paths, cache invalidation, and privileged workflow automation. Several source details warrant focused regression checks, particularly custom cwd handling and shared mutable state. Observations below describe behavior or explicitly labeled hypotheses; they are not confirmed vulnerabilities.
- Plugin, processor, syntax, loader, and formatter paths load JavaScript into the current Node process; dynamicImport directly invokes import rather than providing an execution sandbox.
- Module resolution tries the configuration directory, cwd, and global node_modules; config explorers use global search strategy, so resolution can cross the project directory boundary.
- Caller-controlled paths reach stylesheet/reference reads and fix/report writes; report output recursively creates parent directories, while FileCache can remove and recreate its configured cache file after a load failure.
- Hypothesis: heterogeneous per-file configurations need careful cache regression coverage because FileCache.calcHashOfConfig retains only its first hash, although lintSource calls it with each file's resolved config. (inferred)
- Suppression file location is resolved against standalone's cwd, but suppression entry keys are calculated using process.cwd(); persistence uses plain writeFile, and suppression matches counts rather than individual diagnostic identities.
- computeEditInfo invokes fix.apply and mutates nodes even without config.fix; it suppresses overlapping edits and records a narrowed replacement, making rule order and mutation behavior material to editor integration.
- Rule callbacks share PostCSS roots/results and are collected into promises; deprecated context.fix remains supported but is disabled for rules affected by inline disable ranges.
- The privileged workflow_run comment job consumes downloaded preview artifact metadata; postCustomComment takes output.number as its target and constructs comments from package URLs. The inspected workflow has a repository guard but no success-condition guard.
Extension points
Stylelint exposes extension interfaces for rules, syntaxes, configuration, reporting, and reference loading. Core rules and formatters use explicit registries, while configured plugin definitions are normalized into lookup tables. Most extension behavior converges on PostCSS roots and the shared reporting utility.
- New core rules plug into ruleNames in lib/rules/index.mjs; enumerable getters resolve each rule's index.mjs through a cached import promise.
- createPlugin returns {ruleName, rule}; plugin augmentation accepts a single definition or array, requires names containing '/', and installs functions into config._pluginFunctions.
- Rule factories receive primary settings, secondary options, and context, returning callbacks invoked with root and result; promise aggregation accommodates asynchronous callbacks.
- Public plugin utilities include report, ruleMessages, validateOptions, and checkAgainstRule; report integrates severity, disable ranges, fix callbacks, and edit information.
- Custom syntaxes can supply parse/stringify objects or modules; extension-language configs can select syntax through overrides and disable incompatible core rules.
- Custom formatters implement formatter(results, returnValue); API selection accepts functions/promises or existing file paths, and the CLI separately imports --custom-formatter modules.
- Configured processors are factories returning name and postprocess; augmentation validates both fields, stores callbacks by name, and standalone invokes them on each converted result and its root.
- referenceFiles entries accept files, customSyntax, and loader; loaders can be imported modules or supplied PostCSS plugins and are installed into a dedicated reference-file processor.
Contributor handoff
Start with the public API and the narrow rule or integration path being changed. Preserve configuration precedence, diagnostic locations, disable behavior, and the distinction between string output and file persistence. Tests and CI were inspected, not executed; future verification must report actual outcomes and respect the current read-only restriction.
- Read package.json and the npm lockfile before planning checks; npm test invokes pretest linting, then Jest and node:test, whereas test-only targets Jest with lifecycle scripts disabled.
- For runtime changes, begin with index, standalone, lintSource, and lintPostcssResult; preserve the callable PostCSS export and its explicit module.exports interoperability binding.
- Rule edits should remain standard-CSS focused and use validateOptions, syntax/type guards, and report; contributor guidance requires accepted/rejected cases and varied locations, including multiple warnings.
- Maintain .mjs/JSDoc conventions and strict no-emit checking; EditorConfig uses tabs generally and two-space indentation for package.json, Markdown, CSS, and YAML.
- Configuration edits require examining getConfigForFile and augmentConfig: cache keys include target paths, inheritance replaces whole rule settings, and overrides merge in matching order.
- Fix-related edits must cover string-input output, atomic file writes, disable ranges, and edit-information mutation; existing tests specify config-enabled fixes and disableFix behavior.
- When execution is authorized, the existing test-only script supports a narrow Jest test-file check before broader verification; npm test adds linting and node:test, while the Yarn PnP suite requires explicit enabling and performs packaging/install operations.
- This handoff records inspected test and CI specifications, not executed results; distinguish configured coverage thresholds and declared matrix jobs from observed passes, and do not treat snapshot system cases as exhaustive coverage.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 760 | 99% |
| Markdown | 183 | docs/config |
| CSS | 60 | docs/config |
| JSON | 50 | docs/config |
| YAML | 16 | docs/config |
| HTML | 6 | docs/config |
| Sass | 6 | 1% |
| TypeScript | 2 | 0% |
Start reading here
Probable source entrypoint: lib/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (999 files)
Source layout — lib/
| Path | Files |
|---|---|
lib/formatters/ | 17 |
lib/utils/ | 204 |
lib/assignDisabledRanges.mjs | 1 |
lib/augmentConfig.mjs | 1 |
lib/constants.mjs | 1 |
lib/createPartialStylelintResult.mjs | 1 |
lib/getPostcssResult.mjs | 1 |
lib/lintPostcssResult.mjs | 1 |
lib/needlessDisables.mjs | 1 |
lib/normalizeAllRuleSettings.mjs | 1 |
lib/postcssPlugin.mjs | 1 |
lib/prepareReturnValue.mjs | 1 |
lib/printConfig.mjs | 1 |
lib/reportUnknownRuleNames.mjs | 1 |
Repository structure
| Top-level path | Files |
|---|---|
lib/ | 999 |
system-tests/ | 41 |
docs/ | 27 |
.github/ | 12 |
scripts/ | 12 |
identity/ | 6 |
.changeset/ | 5 |
types/ | 2 |
Docs found: CONTRIBUTING.mdREADME.mddocs/about/governance.mddocs/about/semantic-versioning.mddocs/about/vision.mddocs/contributor-guide/benchmarks.mddocs/contributor-guide/rules.mddocs/contributor-guide/system-tests.mddocs/developer-guide/formatters.mddocs/developer-guide/plugins.md
Package
package.json — stylelint v17.16.0, 74 declared dependencies.
@changesets/cli@changesets/get-github-info@csstools/css-calc@csstools/css-parser-algorithms@csstools/css-syntax-patches-for-csstree@csstools/css-tokenizer@csstools/media-query-list-parser@csstools/selector-resolve-nested@csstools/selector-specificity@jest/globals@stylelint/prettier-config@stylelint/remark-preset
CI & config entrypoints
README.md— Repository readme.github/workflows/update-pkg.pr.new-comment.yml— GitHub Actions workflow.github/workflows/close-unknown-effort-prs.yml— GitHub Actions workflow.github/workflows/release.yml— GitHub Actions workflow.github/workflows/comment-on-old-issues.yml— GitHub Actions workflow.github/workflows/publish-to-pkg.pr.new.yml— GitHub Actions workflow.github/workflows/release-pr.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflowpackage.json— npm scripts: benchmark, benchmark-rule, changeset, format, generate-example-output, lint, lint:formatting, lint:js
Structural health signals
Average score 7.2/10 across 2 analyzed source files; 1 hotspot surfaced.
types/stylelint/index.d.ts— 1698 lines, score 6.2 (Large file, Long function/block)types/stylelint/type-test.ts— 181 lines, score 8.1 (High churn, No adjacent test signal)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
bc06c7cdb1412026-10-01 — Release 17.16.0 (#9551)f4fb76f709c52026-09-08 — Set `target-branch` to `v18` in Dependabot config (#9488)20194788a3932026-09-07 — Fix `property-layout-mappings` and `unit-layout-mappings` false negatives for uppercase property names and units (#9485)e8757103c6622026-09-07 — Fix `value-keyword-layout-mappings` false positives for `caption-side` (#9483)0547bff875de2026-09-04 — Release 17.15.0 (#9484)