[WIP] aksel stylelint (#1973)

* working stylelint config + test rule

this commit is a good "base" for developing future stylelint rules

* merge ideas (sortof)

* delete test-rule + add URL to readme section

* flatten json object

* bundle token files at build time

* update lock file deps

* package distribution & version in error message

* rule for internal tokens

* rule for class name override

* remove config props

* fix: emit multiple errors for nodes in postcss-value-parser

* adjust error messages

* some tests

* final tests

* refactor

* no more regex

* update README.md

* update README.md (again)

* readme

* readme and usage example for aksel-design-token-exists

* move README of rule into top-level README

* update README

* update README

* move sources into /src, bookkeeping

* add aksel-stylelint to changeset.fixed

* set exports correctly (exposes ./recommended)

* bookkeeping, cleanup, refactor, remove test files

* Update README.md

* changeset

* fix urls

* update test for aksel-design-token-exists to cover all token files

* add more granular error catching

* cleanup, improve error message

* update tests + fix code that broke tests

* add rule: deprecate classes

* adjust aksel-design-token-exists

* adjust test for no-deprecated-classes

* refactor design-token-exists

* update README

* 📝 update README

* update readme

* refactor: split rules into smaller rules

* fix tests (deduplicate from refactor), fix plugin too

* fix meta name / ruleName -> ruleNamePackage refactor

* set internal dependencies (build time)

* set internal dependencies (build time)

* when building stylelint, always pull latest css & token files

* new lock

* test cache-busting

* ignore some lint rules

* deduplicate rulename

* bring back caching in ci.yml

* 📝 Oppdatert Package.json docs

* more helpful error messages

* 📝 Updated readme

* 📝 Updated prefixes for rules in readme

* 📝 Formateringsfeil i readme

* refactor ruleNames (shorter and better!)

* update one more rule name (I forgor)

* refactor names again (must have namespace)

* 🐛 Fikset intern bruk av lint-regler

* ⬆️ yarn lock sync

---------

Co-authored-by: Halvor Haugan <[email protected]>
Co-authored-by: Ken <[email protected]>
Co-authored-by: Ken <[email protected]>

.changeset/config.json

@@ -13,7 +13,8 @@
       "@navikt/ds-codemod",
       "@navikt/aksel-icons",
       "@navikt/aksel",
-      "@navikt/ds-icons"
+      "@navikt/ds-icons",
+      "@navikt/aksel-stylelint"
     ]
   ],
   "linked": [],

.changeset/shy-days-walk.md

@@ -0,0 +1,5 @@
+---
+"@navikt/aksel-stylelint": minor
+---
+
+add stylelint plugin

@navikt/aksel-stylelint/.gitignore

@@ -0,0 +1 @@
+/dist

@navikt/aksel-stylelint/README.md

@@ -0,0 +1,173 @@
+# Aksel stylelint rules & plugins
+
+This stylelint plugin is useful when working with the [Aksel design system](https://aksel.nav.no/).
+
+It is designed to be useful for both _internal_ and _external_ developers, so _everyone_ should install this 🙌.
+
+> **Warning**
+> The version of this plugin **_MUST MATCH_** the version of the other design system packages used in your project for the linting to make sense!
+> Otherwise you are very likely to get _incorrect_ errors that tell you to use the wrong token names.
+
+# Install
+
+```bash
+yarn add -D @navikt/aksel-stylelint
+npm install -D @navikt/aksel-stylelint
+```
+
+### How to configure
+
+It should be sufficient for most cases to extend the recommended defaults.
+
+```js
+  "stylelint": {
+    "extends": [
+        ...
+        "@navikt/aksel-stylelint/recommended"
+    ],
+    ...
+  }
+```
+
+## aksel/design-token-exists
+
+Makes sure all referenced CSS-variables with prefix `--a-` or `--ac-` exists in Aksels token-collection. As a side-effect Aksel reserves these prefixes for its design-tokens.
+
+❌ Incorrect:
+
+```css
+html {
+    --a-my-own-color-bg-hover: #f2f2f2;
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+    background-color: var(--a-my-own-color-bg-hover);
+                          ^^^^^^^^^^^^^^^^^^^^^^^^^
+}
+```
+
+✅ Correct:
+
+```css
+html {
+  background-color: var(--custom-tag-surface-default);
+}
+```
+
+## aksel/design-token-no-global-override
+
+Makes sure you don't override global level tokens with `--a-`-prefix. Global/Semantic tokens are supposed to be used as is, and not overridden. That is unless you are theming your solution to match a different sub-brands or brands. In those cases we encourage to make all the changes in a single 'config'-file, then disable the rule for that file only.
+
+❌ Incorrect:
+
+```css
+div {
+    --a-surface-default: #f2f2f2;
+    ^^^^^^^^^^^^^^^^^^^
+}
+```
+
+✅ Correct:
+
+```css
+div {
+  background-color: var(--a-surface-default);
+}
+```
+
+## aksel/design-token-no-component-reference
+
+Makes sure you don't reference component level tokens with `--ac-`-prefix. Component level tokens are only supposed to be overridden, not referenced.
+This is since they are by default not defined, leading to unknown side-effects when referenced incorrectly.
+
+❌ Incorrect:
+
+```css
+html {
+    stroke: var(--ac-button-loader-stroke);
+                ^^^^^^^^^^^^^^^^^^^^^^^^^
+}
+```
+
+✅ Correct:
+
+```css
+html {
+  --ac-button-loader-stroke: lawngreen;
+}
+```
+
+## aksel/no-internal-tokens
+
+Disallows use or override of internal Aksel design tokens. Internal tokens are not supposed to be used outside the design system, and may be changed or removed without warning. Be aware that the rule simply checks the prefix of the token, and not if it actually exists in the design system. Even if it doesn't exist, using design system prefixes should be avoided.
+
+❌ Incorrect:
+
+```css
+a {
+  --__ac-some-property: pink;
+} ^^^^^^^^^^^^^^^^^^^^
+```
+
+```css
+a {
+  color: var(--__ac-some-property);
+}            ^^^^^^^^^^^^^^^^^^^^
+```
+
+✅ Correct:
+
+```css
+a {
+  --some-property: pink;
+}
+```
+
+```css
+a {
+  color: var(--some-property);
+}
+```
+
+## aksel/no-class-override
+
+Warns when trying to override design system styling by using class selectors that starts with "navds-" or "navdsi-". Overriding styles in the design system is discouraged. We want to have consistent look and feel across applications. Even if it seems to work fine now, it might break on subsequent updates in the design system.
+
+❌ Incorrect:
+
+```css
+.navds-button {
+^^^^^^^^^^^^^
+}
+```
+
+```css
+.some-class .navdsi-header {
+}           ^^^^^^^^^^^^^^
+```
+
+✅ Correct:
+
+```css
+.some-class {
+}
+```
+
+## aksel/no-deprecated-classes
+
+Warns when you try to use deprecated class names.
+
+❌ Incorrect:
+
+```css
+.navdsi-deprecated-example {
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+}
+```
+
+✅ Correct:
+
+```css
+.guaranteed-not-deprecated {
+}
+```
+
+🐛 Found a bug? https://github.com/navikt/aksel/issues

@navikt/aksel-stylelint/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@navikt/aksel-stylelint",
+  "version": "3.3.1",
+  "author": "Aksel | NAV",
+  "homepage": "https://aksel.nav.no/grunnleggende/kode/stylelint",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/navikt/aksel.git",
+    "directory": "@navikt/aksel-stylelint"
+  },
+  "keywords": [
+    "aksel",
+    "stylelint",
+    "config",
+    "linting"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "exports": {
+    "./recommended": "./dist/recommended.js"
+  },
+  "files": [
+    "./dist"
+  ],
+  "scripts": {
+    "test": "jest",
+    "copy-internal-tokens": "node -e \"require('fs').copyFileSync('../internal/css/tokens.json','dist/internal-tokens.json')\"",
+    "copy-css": "node -e \"require('fs').copyFileSync('../core/css/dist/index.css','dist/index.css')\"",
+    "copy-tokens": "node -e \"require('fs').copyFileSync('../core/css/tokens.json','dist/tokens.json')\"",
+    "copy": "yarn copy-internal-tokens && yarn copy-css && yarn copy-tokens",
+    "build": "tsc -p . && concurrently \"yarn:copy-*\"",
+    "watch:lint": "tsc --watch -p .",
+    "dev": "yarn watch:lint"
+  },
+  "devDependencies": {
+    "@navikt/ds-css": "^3.3.1",
+    "@navikt/ds-tokens": "^3.3.1",
+    "@types/jest": "^29.0.0",
+    "concurrently": "7.2.1",
+    "copyfiles": "2.4.1",
+    "jest": "^29.0.0",
+    "jest-preset-stylelint": "^6.1.0",
+    "stylelint": "^14.8.5",
+    "typescript": "^4.8.0"
+  },
+  "jest": {
+    "preset": "jest-preset-stylelint",
+    "testMatch": [
+      "**/*.test.ts"
+    ],
+    "transform": {
+      "^.+\\.ts?$": "ts-jest"
+    }
+  }
+}

@navikt/aksel-stylelint/src/deprecations.ts

@@ -0,0 +1,8 @@
+type DeprecatedList = { classes: string[]; message: string }[];
+
+export const deprecations: DeprecatedList = [
+  {
+    classes: ["navdsi-deprecated-example", "navdsi-other-deprecated-example"],
+    message: "Removed in vX.X.X, see documentation [link] for more information",
+  },
+];

@navikt/aksel-stylelint/src/index.ts

@@ -0,0 +1,8 @@
+import { createPlugin } from "stylelint";
+import { rules } from "./rules";
+
+const rulesPlugins = Object.keys(rules).map((ruleName) => {
+  return createPlugin(`${ruleName}`, rules[ruleName]);
+});
+
+export default rulesPlugins;

@navikt/aksel-stylelint/src/recommended.ts

@@ -0,0 +1,11 @@
+module.exports = {
+  plugins: ["."],
+  rules: {
+    "aksel/design-token-exists": true,
+    "aksel/no-internal-tokens": true,
+    "aksel/no-class-override": [true, { severity: "warning" }],
+    "aksel/no-deprecated-classes": true,
+    "aksel/design-token-no-global-override": true,
+    "aksel/design-token-no-component-reference": true,
+  },
+};

@navikt/aksel-stylelint/src/rules/aksel-design-token-exists/index.test.ts

@@ -0,0 +1,94 @@
+import { getTestRule } from "jest-preset-stylelint";
+import rule, { messages } from ".";
+
+getTestRule()({
+  plugins: ["./dist/index.js"],
+  ruleName: rule.ruleName,
+  config: true,
+
+  accept: [
+    {
+      code: ".foo { --ac-accordion-header-bg-hover: 1px; --ac-header-bg: red; }",
+      description: "existing '--ac-' tokens overridden",
+    },
+    {
+      code: ".foo { --my-custom-color: var(--a-orange-800); }",
+      description: "existing '--a-' token referenced",
+    },
+  ],
+
+  reject: [
+    {
+      code: ".foo { --a-does-not-exist: 1px }",
+      description: "attempt to override nonexistent '--a-' token",
+      warnings: [
+        {
+          message: messages.propNotExist({ prop: "--a-does-not-exist" }),
+          line: 1,
+          endLine: 1,
+          column: 8,
+          endColumn: 26,
+        },
+      ],
+    },
+    {
+      code: ".foo \n { \n --ac-does-not-exist: 1px; \n }",
+      description: "attempt to override nonexistent '--ac-' token",
+      message: messages.propNotExist({ prop: "--ac-does-not-exist" }),
+      line: 3,
+      endLine: 3,
+      column: 2,
+      endColumn: 21,
+    },
+
+    {
+      code: ".foo { color: var(--a-bar) }",
+      description: "attempt to use nonexistent token",
+      message: messages.valueNotExist({ prop: "color" }, "--a-bar"),
+      line: 1,
+      endLine: 1,
+      column: 19,
+      endColumn: 26,
+    },
+    {
+      code: ".foo { width: var(--ac-bar, --a-baz) }",
+      description: "attempt to use two nonexistent tokens in one var()",
+      warnings: [
+        {
+          message: messages.valueNotExist({ prop: "width" }, "--ac-bar"),
+          line: 1,
+          endLine: 1,
+          column: 19,
+          endColumn: 27,
+        },
+        {
+          message: messages.valueNotExist({ prop: "width" }, "--a-baz"),
+          line: 1,
+          endLine: 1,
+          column: 29,
+          endColumn: 36,
+        },
+      ],
+    },
+    {
+      code: ".foo { padding: var(--a-bar) var(--a-baz); }",
+      description: "attempt to use two nonexistent tokens as separate vars",
+      warnings: [
+        {
+          message: messages.valueNotExist({ prop: "padding" }, "--a-bar"),
+          line: 1,
+          endLine: 1,
+          column: 21,
+          endColumn: 28,
+        },
+        {
+          message: messages.valueNotExist({ prop: "padding" }, "--a-baz"),
+          line: 1,
+          endLine: 1,
+          column: 34,
+          endColumn: 41,
+        },
+      ],
+    },
+  ],
+});