@stylistic/stylelint-plugin 6.0.0-alpha.0

Release v6.0.0-alpha.0

on Node.js NPM

Changed

Namespaces for custom syntaxes

The rules under their core names no longer read an SCSS or Less stylesheet, or a styled template: such a file now gets one warning naming the namespace that holds the same rules with the same options and documentation, and nothing else of it is checked. Where the namespace's copy of the rule is configured over the file, in an overrides block or through a preset, that copy reads it and the core name says nothing. An option a namespace's syntax cannot carry is refused there instead: Less refuses an at-rule name in upper case, so upper is an invalid option of @stylistic/less/at-rule-name-case, since a stylistic fix must never leave a file its compiler refuses.
Rename the rules in the overrides block that sets customSyntax — @stylistic/scss/indentation in place of @stylistic/indentation, and less or styled in place of scss for the other two. Nothing else in the configuration changes, and a namespace reads plain CSS exactly as the core does. A configuration that names no syntax anywhere is unaffected: such a file is parsed as CSS, which is the family the core's copies read, and it is read by them under the same names and with the same warnings as before.
The core is now written for plain CSS alone, so a construct only a preprocessor spells is read as the CSS it is: a Sass module (ns.$a), a placeholder selector (%a), a nested property (font: { … }), a comment opened by a double slash, an at-rule carrying neither block nor parameters, and a value opening with @. A plain CSS file spelling any of those may meet warnings it used to escape.
The new defineStylistic and defineStylisticOverride functions (see below) name the syntax once for the whole block, so the rules stay under their short names and you write no namespace at all.
A rule listed under two of these names over one stylesheet is now read once, by the copy of the stylesheet's own family — the core's over plain CSS, the namespace's over its syntax — and the other copies yield without a word; where the family's copy is not configured, the first listed copy whose namespace accepts the stylesheet reads it. A configuration listing the core and a namespace over the same files used to run every rule twice there and report every problem twice.

Expanding the scope of the rules

• The named-grid-areas-alignment rule now applies to the grid-template and grid properties too, and not only to grid-template-areas (see #45). Where your code spells those shorthands, the rule may start asking for corrections or writing them under --fix. For finer control use its new option (see below).

Independence from the order of the rules

Many rules now read the settings of other rules and what they will write in the same text, so what --fix leaves no longer depends on where the configuration lists a rule (see #352, #354, #355, #477, #502). A rule writing a line break, for one, asks the linebreaks rule which break to write, wherever that rule is listed. Where a neighbor's write changes whether the rule's own option asks anything at all, the text is read as the whole fix leaves it, and a file that needed a second --fix run rests on one. Expect some new autocorrections in your code.

End-of-line characters

The plugin now reads a line break the way PostCSS and Stylelint do: a line feed, alone or behind the carriage return of a Windows pair. A bare carriage return and a form feed are plain whitespace, so a file broken with either is one line to every rule about breaks, empty lines and multi-line lists, and no rule reports a position your editor cannot show. The linebreaks rule still tells \n from \r\n.

Passing over @charset

The at-rule-name-case, at-rule-name-space-after, at-rule-name-newline-after, at-rule-semicolon-space-before and string-quotes rules no longer warn about a @charset or write into it, in any spelling: the encoding declaration is a byte sequence the browser reads before parsing rather than an at-rule, and every other spelling of it is ignored. Stylelint's at-charset-rule-no-invalid rule judges the spelling instead, so a CSS file holding a @charset now gets one warning asking you to enable that rule where your configuration leaves it off. The unicode-bom rule under "always" now warns about the option itself over a CSS file whose first node is a @charset, since the mark would keep the declaration from working; set "never" or leave the rule unset for such files.

Conflicting settings

The plugin now refuses a configuration holding two settings that conflict with each other, such as value-list-comma-newline-after: "always-multi-line" beside value-list-comma-space-after: "always": the run stops with a configuration error naming both settings and what to change (see #743). Where your configuration holds such a pair, change one of the two as the message says, or turn one of them off. The types of defineStylistic refuse such a pair in the editor.

Added

New rules

• The aspect-ratio-notation rule, which specifies how the value of aspect-ratio is written (see #18).
• The declaration-block-single-line-max-declarations rule, which limits the number of declarations within a single-line declaration block (see #639). Stylelint 18 removes the rule of its own, and this one takes the same option, so a configuration moves it by renaming it to @stylistic/declaration-block-single-line-max-declarations. It reads more than Stylelint's did — the single-line block of an at-rule as well (see #640) — and it is autofixable, which Stylelint's never was (see #641).
• The value-slash-newline-before and value-slash-newline-after rules, which require a newline or disallow whitespace on either side of the same solidus (see #622).
• The value-slash-space-before, value-slash-space-after, media-feature-slash-space-before and media-feature-slash-space-after rules, which require a single space or disallow whitespace on either side of the solidus of a value or of a media feature's ratio (see #548).

New options

• The block-closing-brace-empty-line-before rule now takes a last-nested value in its except option (see #60), which reverses the primary option where a chain of nested blocks ends — at a block nested in another one and holding no block of its own — so that under "never" the empty line before such a brace is asked for, and under "always-multi-line" it is not.
• The max-line-length rule now has an additional tabSize option (see #10), which measures a tab to the next tab stop of that width, so a file indented with tabs is as long as the editor's ruler shows.
• The named-grid-areas-alignment rule now has an additional alignColumns option (see #45), which lays the line names and the sizes of a grid-template or grid shorthand out as columns of a table.

New autofixes

• The at-rule-name-newline-after rule is now autofixable (see #696). Expect --fix to write the newlines the rule used to only ask for. Where your configuration also lists at-rule-name-space-after under always, the two ask for different things in the same place, and the plugin now refuses the pair as conflicting settings. A @charset is reported but left as written, since breaking its head can leave the stylesheet declaring no encoding.
• The at-rule-semicolon-space-before rule is now autofixable (see #697). Expect --fix to write the whitespace the rule used to only ask for.
• The block-closing-brace-space-after rule is now autofixable (see #698). Expect --fix to write the whitespace the rule used to only ask for.
• The media-query-list-comma-newline-before rule is now autofixable (see #699). Expect --fix to write the newlines the rule used to only ask for. Where your configuration also lists media-query-list-comma-space-before asking for something else of that same run — media-query-list-comma-newline-before: "always-multi-line" beside media-query-list-comma-space-before: "never", for one — the plugin now refuses the pair as conflicting settings.
• The unicode-bom rule is now autofixable (see #700). Expect --fix to write or take off the byte order mark the rule used to only ask for.
• The value-list-comma-newline-before rule is now autofixable (see #701). Expect --fix to write the newlines the rule used to only ask for. Where your configuration also lists value-list-comma-space-before asking for something else of that same run — value-list-comma-newline-before: "always-multi-line" beside value-list-comma-space-before: "never", for one — the plugin now refuses the pair as conflicting settings.

New features

• The plugin now ships a recommended preset (see #745): "extends": ["@stylistic/stylelint-plugin/recommended"] sets every rule of the plugin that has an answer the same for every project, for plain CSS and, over .scss and .less files, for SCSS and Less; a setting of your own in rules wins over it. It names no parser, so a project installs none, and an .scss or a .less file is read by the copies of its syntax as soon as the project names that syntax with one overrides entry of its own, and is read as CSS by the @stylistic/ names until then, as before. The table it is built out of is exported as configs.recommendedRules beside the preset, for a configuration that projects it under the styled namespace or changes one setting under every name at once.
• The package now exports the defineStylistic and defineStylisticOverride functions for a JavaScript configuration (see #624). You name the rules by their short names and the syntax once for the whole block: an editor completes the names and the options, and the compiler refuses a rule, an option, a key or a syntax the plugin does not take.
• The plugin now ships a type declaration for what it exports, so a TypeScript configuration or a script importing the package reads the plugin list as Plugin[] rather than as any. Nothing about configuring the plugin changes.
• The plugin now says so when it is listed in extends instead of plugins (see #14). Such a configuration used to fail with every @stylistic/ rule of it reported as unknown; the run now stops with a configuration error naming the preset to extend instead, or the field to move the package to.
  By the way, the documentation now lives at stylelint-stylistic.github.io.

Fixed

The rules below used to pass some code over in silence. They now warn on it, so code that used to be clean may need corrections.

• The declaration-block-semicolon-newline-after, declaration-block-semicolon-newline-before, declaration-block-semicolon-space-after and declaration-block-semicolon-space-before rules now check the declarations of an inline style attribute (see #49).
• The declaration-colon-space-after rule now looks for the whitespace after the colon where a custom property whose value holds a comment actually keeps it (see #109) (@VChet).
• The indentation rule now reports every mis-indented line of an at-rule's parameters holding comments, at the line and column the file spells (see #65).
• The indentation rule now corrects every mis-indented line of an at-rule, and not only one of them (see #64).
• The max-empty-lines rule now counts the empty lines inside a Sass nested property written with a value, and puts every warning behind such a property, an end-of-line comment or a Less mixin call's !important on the line and column the file spells (see #583).
  And also a huge number of false negatives and other bugs found by tools and agents, which may likewise require you to fix the code.