Add annotation-no-unknown

docs/user-guide/rules/list.md

@@ -91,6 +91,10 @@ Within each cateogory, the rules are grouped by the [_thing_](http://apps.workfl
 - [`no-invalid-double-slash-comments`](../../../lib/rules/no-invalid-double-slash-comments/README.md): Disallow double-slash comments (`//...`) which are not supported by CSS.
 - [`no-invalid-position-at-import-rule`](../../../lib/rules/no-invalid-position-at-import-rule/README.md): Disallow invalid position `@import` rules within a stylesheet.
 
+### Annotation
+
+- [`annotation-no-unknown`](../../../lib/rules/annotation-no-unknown/README.md): Disallow unknown annotations.
+
 ## Enforce conventions
 
 ### Alpha-value

lib/reference/keywordSets.js

@@ -65,6 +65,8 @@ keywordSets.lengthUnits = new Set([
 
 keywordSets.units = uniteSets(keywordSets.nonLengthUnits, keywordSets.lengthUnits);
 
+keywordSets.annotations = new Set(['!important']);
+
 keywordSets.camelCaseFunctionNames = new Set([
 	'translateX',
 	'translateY',

lib/rules/annotation-no-unknown/README.md

@@ -0,0 +1,74 @@
+# annotation-no-unknown
+
+Disallow unknown annotations.
+
+<!-- prettier-ignore -->
+```css
+a { color: green !imprtant; }
+/**              ↑
+ * This annotation */
+```
+
+This rule considers solely the `!important` annotation per the [CSS Cascading and Inheritance spec](https://www.w3.org/TR/css-cascade-3/#importance).
+
+## Options
+
+### `true`
+
+The following patterns is considered a problem:
+
+<!-- prettier-ignore -->
+```css
+a {
+  color: green !imprtant;
+}
+```
+
+The following patterns are _not_ considered problems:
+
+<!-- prettier-ignore -->
+```css
+a {
+ color: green !important;
+}
+```
+
+<!-- prettier-ignore -->
+```css
+a {
+  color: green !IMPORTANT;
+}
+```
+
+<!-- prettier-ignore -->
+```css
+a {
+  color: green !ImPoRtAnT;
+}
+```
+
+## Optional secondary options
+
+### `ignoreAnnotations: ["/regex/", /regex/, "string"]`
+
+Given:
+
+```json
+["/^!my-/", "!custom"]
+```
+
+The following patterns are _not_ considered problems:
+
+<!-- prettier-ignore -->
+```css
+a {
+  color: green !custom;
+}
+```
+
+<!-- prettier-ignore -->
+```css
+a {
+  color: green !my-custom-annotation;
+}
+```

lib/rules/annotation-no-unknown/__tests__/index.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { messages, ruleName } = require('..');
+
+testRule({
+	ruleName,
+	config: [
+		true,
+		{
+			ignoreAnnotations: ['!custom', '/^!my-/'],
+		},
+	],
+
+	accept: [
+		{
+			code: 'a { color: green !important; }',
+		},
+		{
+			code: 'a { color: green !IMPORTANT; }',
+		},
+		{
+			code: 'a { color: green !ImPoRtAnT; }',
+		},
+		{
+			code: 'a { color: green !custom; }',
+		},
+		{
+			code: 'a { color: green !my-custom-annotation; }',
+		},
+	],
+
+	reject: [
+		{
+			code: 'a { color: green !imprtant }',
+			message: messages.rejected('!imprtant'),
+			line: 1,
+			column: 18,
+			endLine: 1,
+			endColumn: 27,
+		},
+		{
+			code: 'a { color: green !IMPRTANT }',
+			message: messages.rejected('!IMPRTANT'),
+			line: 1,
+			column: 18,
+			endLine: 1,
+			endColumn: 27,
+		},
+		{
+			code: 'a { color: green !ImPrTaNt }',
+			message: messages.rejected('!ImPrTaNt'),
+			line: 1,
+			column: 18,
+			endLine: 1,
+			endColumn: 27,
+		},
+	],
+});

lib/rules/annotation-no-unknown/index.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const valueParser = require('postcss-value-parser');
+const getDeclarationValue = require('../../utils/getDeclarationValue');
+
+const keywordSets = require('../../reference/keywordSets');
+const optionsMatches = require('../../utils/optionsMatches');
+const report = require('../../utils/report');
+const ruleMessages = require('../../utils/ruleMessages');
+const validateOptions = require('../../utils/validateOptions');
+const { isRegExp, isString } = require('../../utils/validateTypes');
+
+const ruleName = 'annotation-no-unknown';
+
+const messages = ruleMessages(ruleName, {
+	rejected: (annotation) => `Unexpected unknown annotation "${annotation}"`,
+});
+
+const meta = {
+	url: 'https://stylelint.io/user-guide/rules/list/annotation-no-unknown',
+};
+
+/** @type {import('stylelint').Rule} */
+const rule = (primary, secondaryOptions) => {
+	return (root, result) => {
+		const validOptions = validateOptions(
+			result,
+			ruleName,
+			{ actual: primary },
+			{
+				actual: secondaryOptions,
+				possible: {
+					ignoreAnnotations: [isString, isRegExp],
+				},
+				optional: true,
+			},
+		);
+
+		if (!validOptions) {
+			return;
+		}
+
+		root.walkDecls(checkStatement);
+
+		/**
+		 * @param {import('postcss').Declaration} decl
+		 */
+		function checkStatement(decl) {
+			if (!decl.value.includes('!')) return;
+
+			const parsedValue = valueParser(getDeclarationValue(decl));
+
+			parsedValue.walk((node) => {
+				if (!isAnnotation(node)) return;
+
+				const value = node.value;
+
+				if (optionsMatches(secondaryOptions, 'ignoreAnnotations', value)) {
+					return;
+				}
+
+				if (keywordSets.annotations.has(value.toLowerCase())) {
+					return;
+				}
+
+				report({
+					message: messages.rejected(value),
+					node: decl,
+					result,
+					ruleName,
+					word: value,
+				});
+			});
+		}
+
+		/**
+		 * @param {valueParser.Node} node
+		 */
+		function isAnnotation(node) {
+			return node.type === 'word' && node.value.startsWith('!');
+		}
+	};
+};
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+rule.meta = meta;
+module.exports = rule;

lib/rules/index.js

@@ -7,6 +7,7 @@ const importLazy = _importLazy(require);
 /** @type {typeof import('stylelint').rules} */
 const rules = {
 	'alpha-value-notation': importLazy('./alpha-value-notation'),
+	'annotation-no-unknown': importLazy('./annotation-no-unknown'),
 	'at-rule-allowed-list': importLazy('./at-rule-allowed-list'),
 	'at-rule-disallowed-list': importLazy('./at-rule-disallowed-list'),
 	'at-rule-empty-line-before': importLazy('./at-rule-empty-line-before'),