@jhae/stylelint-config-verifier 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jan Hähne | https://github.com/jhae-de
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+![Version](https://img.shields.io/npm/v/%40jhae/stylelint-config-verifier?label=Version)
+![License](https://img.shields.io/github/license/jhae-de/stylelint-config-verifier?label=License&color=lightgrey)
+![Tests](https://img.shields.io/github/actions/workflow/status/jhae-de/stylelint-config-verifier/analyze.yaml?label=Tests)
+![Coverage](https://img.shields.io/codecov/c/github/jhae-de/stylelint-config-verifier/main?label=Coverage)
+
+# Stylelint Config Verifier
+
+Does your [Stylelint](https://github.com/stylelint/stylelint) configuration meet your expectations? Easily test
+individual rules with [Jest](https://github.com/jestjs/jest) using code snippets and ensure that errors and warnings are
+being reported correctly.
+
+## Installation
+
+Using npm:
+
+```shell
+npm install --save-dev @jhae/stylelint-config-verifier
+```
+
+## Usage
+
+### With inline code
+
+Example Stylelint configuration file:
+
+```yaml
+rules:
+  at-rule-disallowed-list:
+    - debug
+    - import
+```
+
+Verifying the `at-rule-disallowed-list` rule configuration:
+
+```javascript
+import { ConfigVerifier } from '@jhae/stylelint-config-verifier';
+
+new ConfigVerifier().verify(
+  // Pass the name of the rule.
+  'at-rule-disallowed-list',
+
+  // Describe one or more test cases.
+  {
+    // Give the test case a name.
+    name: 'Disallow @debug rule',
+
+    // Place the code to be tested against the configuration file here.
+    code: '@debug "";',
+
+    // Define the expectation.
+    expect: {
+      // Whether Stylelint should report an error or not.
+      errored: true,
+
+      // The messages that Stylelint should report.
+      messages: ['Unexpected at-rule "debug"'],
+
+      // The severities that Stylelint should report for each message.
+      severities: ['error'],
+    },
+  },
+  {
+    name: 'Disallow @import rule',
+    code: `
+      @import "test-1.css";
+      @import "test-2.css";
+    `,
+    expect: {
+      errored: true,
+      messages: ['Unexpected at-rule "import"', 'Unexpected at-rule "import"'],
+      severities: ['error', 'error'],
+    },
+  },
+  {
+    // The expectation can be omitted if Stylelint should not report errors.
+    name: 'Allow @use rule',
+    code: '@use "test.scss";',
+  },
+);
+```
+
+The verification result:
+
+```shell
+Rule 'at-rule-disallowed-list'
+  ✓ Disallow @debug rule (1 ms)
+  ✓ Disallow @import rule (1 ms)
+  ✓ Allow @use rule (1 ms)
+```
+
+### With a file
+
+It is also possible to pass a file to the test case. This is useful for testing overrides, for example.
+
+Example Stylelint configuration file:
+
+```yaml
+rules:
+  at-rule-disallowed-list:
+    - import
+
+overrides:
+  - files:
+      - '*.css'
+      - '**/*.css'
+    rules:
+      at-rule-disallowed-list: null
+```
+
+The CSS file, for example `at-rule-disallowed-list.css`:
+
+```css
+@import 'test.css';
+```
+
+Verifying the `at-rule-disallowed-list` rule configuration:
+
+```javascript
+import { ConfigVerifier } from '@jhae/stylelint-config-verifier';
+
+new ConfigVerifier().verify('at-rule-disallowed-list', {
+  name: 'Allow @import rule in CSS files',
+
+  // Pass the file instead of inline code.
+  file: 'at-rule-disallowed-list.css',
+});
+```
+
+### Specifying the Stylelint configuration file
+
+By default, the config verifier looks for a `.stylelintrc.yaml` configuration file. If a different location or file name
+is used, the path to it can be specified as a constructor argument.
+
+```javascript
+import { ConfigVerifier } from '@jhae/stylelint-config-verifier';
+
+new ConfigVerifier('path/to/stylelint.config.js').verify();
+```
+
+### Importing into CommonJS
+
+```javascript
+const { ConfigVerifier } = require('@jhae/stylelint-config-verifier');
+
+new ConfigVerifier().verify();
+```
+
+---
+
+Check out the [Standard SCSS Stylelint Config](https://github.com/jhae-de/stylelint-config-standard-scss) tests for more
+examples.

package/dist/cjs/config-verifier.class.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigVerifier = void 0;
+const stylelint_1 = __importDefault(require("stylelint"));
+/**
+ * ConfigVerifier class
+ */
+class ConfigVerifier {
+    configFile;
+    /**
+     * The default test case expectation
+     *
+     * This expectation occurs if Stylelint reports no problems and is used if no expectation was defined in a test case.
+     *
+     * @type {TestCaseExpectation}
+     *
+     * @internal
+     */
+    defaultExpectation = {
+        errored: false,
+        messages: [],
+        severities: [],
+    };
+    /**
+     * Creates and initializes an object instance of the class.
+     *
+     * @param {string} configFile The path to the Stylelint config file whose rules should be verified
+     */
+    constructor(configFile = '.stylelintrc.yaml') {
+        this.configFile = configFile;
+    }
+    /**
+     * Verifies a rule configuration.
+     *
+     * @param {string} ruleName The name of the rule
+     * @param {TestCase[]} testCases The test cases
+     */
+    verify(ruleName, ...testCases) {
+        describe(`Rule '${ruleName}'`, () => {
+            test.each(testCases)('$name', async (testCase) => {
+                const warnings = this.getWarnings(ruleName, await this.getLinterResult(testCase));
+                const { expect: expectation = this.defaultExpectation } = testCase;
+                expect(this.getErrored(warnings)).toBe(expectation.errored);
+                expect(this.getMessages(warnings)).toStrictEqual(expectation.messages.map((message) => `${message} (${ruleName})`));
+                expect(this.getSeverities(warnings)).toStrictEqual(expectation.severities);
+            });
+        });
+    }
+    /**
+     * Runs Stylelint for the given test case and returns a Promise that resolves to the linter result.
+     *
+     * @internal
+     *
+     * @param {TestCase} testCase The test case
+     *
+     * @return {Promise<LinterResult>}
+     */
+    getLinterResult({ file, code }) {
+        if ([file, code].filter((value) => value === undefined).length !== 1) {
+            throw new Error('Though both "file" and "code" are optional, you must have one and cannot have both.');
+        }
+        return stylelint_1.default.lint({
+            configFile: this.configFile,
+            files: file,
+            code,
+        });
+    }
+    /**
+     * Returns the warnings for a rule from the given linter result.
+     *
+     * @internal
+     *
+     * @param {string} ruleName The name of the rule
+     * @param {LinterResult} linterResult The linter result
+     *
+     * @return {Warning[]}
+     */
+    getWarnings(ruleName, { results: lintResults }) {
+        return lintResults
+            .map(({ warnings }) => warnings)
+            .reduce((previous, current) => previous.concat(current), [])
+            .filter((warning) => warning.rule === ruleName);
+    }
+    /**
+     * Returns true if the given lint warnings contain an error, otherwise false.
+     *
+     * @internal
+     *
+     * @param {Warning[]} warnings The lint warnings
+     *
+     * @return {boolean}
+     */
+    getErrored(warnings) {
+        return this.getSeverities(warnings).some((severity) => severity === 'error');
+    }
+    /**
+     * Returns the messages of the given lint warnings.
+     *
+     * @internal
+     *
+     * @param {Warning[]} warnings The lint warnings
+     *
+     * @return {string[]}
+     */
+    getMessages(warnings) {
+        return warnings.map(({ text }) => text);
+    }
+    /**
+     * Returns the severities of the given lint warnings.
+     *
+     * @internal
+     *
+     * @param {Warning[]} warnings The lint warnings
+     *
+     * @return {Severity[]}
+     */
+    getSeverities(warnings) {
+        return warnings.map(({ severity }) => severity);
+    }
+}
+exports.ConfigVerifier = ConfigVerifier;

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/esm/config-verifier.class.js

@@ -0,0 +1,117 @@
+import stylelint from 'stylelint';
+/**
+ * ConfigVerifier class
+ */
+export class ConfigVerifier {
+    configFile;
+    /**
+     * The default test case expectation
+     *
+     * This expectation occurs if Stylelint reports no problems and is used if no expectation was defined in a test case.
+     *
+     * @type {TestCaseExpectation}
+     *
+     * @internal
+     */
+    defaultExpectation = {
+        errored: false,
+        messages: [],
+        severities: [],
+    };
+    /**
+     * Creates and initializes an object instance of the class.
+     *
+     * @param {string} configFile The path to the Stylelint config file whose rules should be verified
+     */
+    constructor(configFile = '.stylelintrc.yaml') {
+        this.configFile = configFile;
+    }
+    /**
+     * Verifies a rule configuration.
+     *
+     * @param {string} ruleName The name of the rule
+     * @param {TestCase[]} testCases The test cases
+     */
+    verify(ruleName, ...testCases) {
+        describe(`Rule '${ruleName}'`, () => {
+            test.each(testCases)('$name', async (testCase) => {
+                const warnings = this.getWarnings(ruleName, await this.getLinterResult(testCase));
+                const { expect: expectation = this.defaultExpectation } = testCase;
+                expect(this.getErrored(warnings)).toBe(expectation.errored);
+                expect(this.getMessages(warnings)).toStrictEqual(expectation.messages.map((message) => `${message} (${ruleName})`));
+                expect(this.getSeverities(warnings)).toStrictEqual(expectation.severities);
+            });
+        });
+    }
+    /**
+     * Runs Stylelint for the given test case and returns a Promise that resolves to the linter result.
+     *
+     * @internal
+     *
+     * @param {TestCase} testCase The test case
+     *
+     * @return {Promise<LinterResult>}
+     */
+    getLinterResult({ file, code }) {
+        if ([file, code].filter((value) => value === undefined).length !== 1) {
+            throw new Error('Though both "file" and "code" are optional, you must have one and cannot have both.');
+        }
+        return stylelint.lint({
+            configFile: this.configFile,
+            files: file,
+            code,
+        });
+    }
+    /**
+     * Returns the warnings for a rule from the given linter result.
+     *
+     * @internal
+     *
+     * @param {string} ruleName The name of the rule
+     * @param {LinterResult} linterResult The linter result
+     *
+     * @return {Warning[]}
+     */
+    getWarnings(ruleName, { results: lintResults }) {
+        return lintResults
+            .map(({ warnings }) => warnings)
+            .reduce((previous, current) => previous.concat(current), [])
+            .filter((warning) => warning.rule === ruleName);
+    }
+    /**
+     * Returns true if the given lint warnings contain an error, otherwise false.
+     *
+     * @internal
+     *
+     * @param {Warning[]} warnings The lint warnings
+     *
+     * @return {boolean}
+     */
+    getErrored(warnings) {
+        return this.getSeverities(warnings).some((severity) => severity === 'error');
+    }
+    /**
+     * Returns the messages of the given lint warnings.
+     *
+     * @internal
+     *
+     * @param {Warning[]} warnings The lint warnings
+     *
+     * @return {string[]}
+     */
+    getMessages(warnings) {
+        return warnings.map(({ text }) => text);
+    }
+    /**
+     * Returns the severities of the given lint warnings.
+     *
+     * @internal
+     *
+     * @param {Warning[]} warnings The lint warnings
+     *
+     * @return {Severity[]}
+     */
+    getSeverities(warnings) {
+        return warnings.map(({ severity }) => severity);
+    }
+}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@jhae/stylelint-config-verifier",
+  "description": "A Stylelint configuration tester for Jest that helps you verify your defined rules.",
+  "version": "1.0.0",
+  "main": "./dist/cjs/config-verifier.class.js",
+  "module": "./dist/esm/config-verifier.class.js",
+  "exports": {
+    "types": "./types/config-verifier.class.d.ts",
+    "require": "./dist/cjs/config-verifier.class.js",
+    "default": "./dist/esm/config-verifier.class.js"
+  },
+  "author": {
+    "name": "JHAE",
+    "url": "https://github.com/jhae-de"
+  },
+  "repository": {
+    "url": "https://github.com/jhae-de/stylelint-config-verifier.git",
+    "type": "git"
+  },
+  "homepage": "https://github.com/jhae-de/stylelint-config-verifier",
+  "license": "MIT",
+  "scripts": {
+    "build": "rm -rf ./dist && npm run-script build:cjs && npm run-script build:esm",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:types": "rm -rf ./types && tsc --project tsconfig.types.json",
+    "lint": "npm run-script lint:prettier && npm run-script lint:eslint",
+    "lint:eslint": "eslint .",
+    "lint:prettier": "prettier . --check",
+    "postbuild": "./bin/post-build.sh",
+    "test": "jest",
+    "test:coverage": "npm run-script test -- --coverage",
+    "test:watch": "npm run-script test -- --watchAll",
+    "test:watch:coverage": "npm run-script test:watch -- --coverage"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15",
+    "@types/jest": "^29.5",
+    "eslint": "^9.15",
+    "eslint-config-prettier": "^9.1",
+    "eslint-plugin-prettier": "^5.2",
+    "globals": "^15.12",
+    "prettier": "^3.3",
+    "ts-jest": "^29.2",
+    "typescript": "^5.7",
+    "typescript-eslint": "^8.15"
+  },
+  "peerDependencies": {
+    "jest": "^29.0",
+    "stylelint": "^16.0"
+  },
+  "keywords": [
+    "config",
+    "configuration",
+    "jest",
+    "rule",
+    "rules",
+    "stylelint",
+    "stylelint-scss",
+    "stylelintrc",
+    "test",
+    "ts-jest",
+    "verify"
+  ]
+}

package/types/config-verifier.class.d.ts

@@ -0,0 +1,21 @@
+import type { TestCase } from './type';
+
+/**
+ * ConfigVerifier class
+ */
+export declare class ConfigVerifier {
+  /**
+   * Creates and initializes an object instance of the class.
+   *
+   * @param {string} configFile The path to the Stylelint config file whose rules should be verified
+   */
+  constructor(configFile?: string);
+
+  /**
+   * Verifies a rule configuration.
+   *
+   * @param {string} ruleName The name of the rule
+   * @param {TestCase[]} testCases The test cases
+   */
+  verify(ruleName: string, ...testCases: TestCase[]): void;
+}

package/types/type/index.d.ts

@@ -0,0 +1,2 @@
+export type { TestCaseExpectation } from './test-case-expectation.type';
+export type { TestCase } from './test-case.type';

package/types/type/test-case-expectation.type.d.ts

@@ -0,0 +1,7 @@
+import type { Severity } from 'stylelint';
+
+export type TestCaseExpectation = {
+  errored: boolean;
+  messages: string[];
+  severities: Severity[];
+};

package/types/type/test-case.type.d.ts

@@ -0,0 +1,8 @@
+import type { TestCaseExpectation } from './index';
+
+export type TestCase = {
+  name: string;
+  file?: string;
+  code?: string;
+  expect?: TestCaseExpectation;
+};