Merge pull request #40 from adorade/develop

Prepare release v3.0.0

.eslintrc.cjs

@@ -1,11 +1,11 @@
 /*!
- * Gulp Stylelint (v2.2.0): .eslintrc.cjs
+ * Gulp Stylelint (v3.0.0): .eslintrc.cjs
  * Copyright (c) 2023-24 Adorade (https://github.com/adorade/gulp-stylelint-esm)
  * License under MIT
  * ========================================================================== */
 
 module.exports = {
-  parser: "@babel/eslint-parser",
+  parser: '@babel/eslint-parser',
   env: {
     node: true,
     es6: true
@@ -23,10 +23,24 @@ module.exports = {
   overrides: [
     {
       files: [
-        "test/*.test.js"
+        'src/*.mjs',
+        'test/*.test.js'
+      ],
+      rules: {
+        '@stylistic/js/semi': ['error', 'always'],
+      }
+    },
+    {
+      files: [
+        'test/*.test.js',
+        'test/*.spec.js',
+        'bin/*.spec.js'
       ],
       env: {
         jest: true
+      },
+      rules: {
+        '@stylistic/js/arrow-parens': ['error', 'always'],
       }
     }
   ]

.gitignore

@@ -2,6 +2,7 @@
 # Folders to ignore
 node_modules
 archive
+bin
 
 # To do Tasks
 .todo

README.md

@@ -34,19 +34,17 @@ import gStylelintEsm from 'gulp-stylelint-esm';
 
 function lintCssTask() {
   return src('src/**/*.css')
-    .pipe(gStylelintEsm({
-      reporters: [
-        { formatter: 'string', console: true }
-      ]
-    }));
+    .pipe(gStylelintEsm());
 }
 ```
 
 ## Formatters
 
 Below is the list of currently available **stylelint formatters**. Some of them are bundled with stylelint by default and exposed on `gStylelintEsm.formatters` object. Others need to be installed. You can [write a custom formatter](http://stylelint.io/developer-guide/formatters/) to tailor the reporting to your needs.
 
-Formatters bundled with stylelint: `"compact"`, `"github"`, `"json"`, `"string (default)"`, `"tap"`, `"unix"`, `"verbose"`.
+Formatters bundled with stylelint: `"compact", "github", "json", "string", "tap", "unix", "verbose"`.
+
+The plugin comes with a built-in formatter called `"stylish"`, which is set as the **default**.
 
 ## Options
 
@@ -66,69 +64,75 @@ import { myStylelintFormatter } from 'my-stylelint-formatter';
 function lintCssTask() {
   return src('src/**/*.css')
     .pipe(gStylelintEsm({
-      failAfterError: true,
-      reportOutputDir: 'reports/lint',
+      failAfterError: true, // true (default) | false
+      fix: false,           // false (default) | true
       reporters: [
-        { formatter: 'verbose', console: true },
+        { formatter: 'stylish', console: true }, // default
         { formatter: 'json', save: 'report.json' },
         { formatter: myStylelintFormatter, save: 'my-custom-report.txt' }
       ],
-      debug: true
+      debug: false          // false (default) | true
     }));
 }
 ```
 
 ### `failAfterError`
 
-When set to `true`, the process will end with non-zero error code if any error-level warnings were raised. Defaults to `true`.
+When set to `true`, the process will end with non-zero error code if any error-level warnings were raised. Files are pushed back to the their pipes only if there are no errors. Defaults to `true`.
+
+### `fix`
+
+The `fix: true` (autofix) option instructs stylelint to try to fix as many issues as possible. Defaults to `false`.
 
-### `reportOutputDir`
+> NOTE:
+> - fixed files will automatically overwrite the original files; proceed with caution.
+> - the fixes are applied to the gulp stream only if there are no errors, to allow usage of other plugins.
+> - not all stylelint rules can be automatically fixed, so it's advisable to manually resolve errors.
 
-Base directory for lint results written to filesystem. Defaults to **current working directory** `process.cwd()`.
+```js
+import { src, dest } from 'gulp';
+import gStylelintEsm from 'gulp-stylelint-esm';
+
+function fixCssTask() {
+  return src('src/**/*.css')
+    .pipe(gStylelintEsm({
+      fix: true
+    }))
+    .pipe(dest('src'));
+}
+```
 
 ### `reporters`
 
-List of reporter configuration objects (see below). Defaults to **an empty array** `[]`.
+List of reporter configuration objects (see below). Defaults to:
+
+```js
+reporters: [
+  { formatter: 'stylish', console: true }
+]
+```
 
 ```js
 {
   // stylelint results formatter (required):
+  // - pass a built-in formatter
   // - pass a function for imported, custom or exposed formatters
   // - pass a string for formatters bundled with stylelint
-  //   "string (default)", "compact", "github", "json", "tap", "unix", "verbose"
-  formatter: myFormatter,
-
-  // save the formatted result to a file (optional):
-  save: 'text-report.txt',
+  //   "stylish (default)", "string", "compact", "github", "json", "tap", "unix", "verbose"
+  formatter: stylish,
 
   // log the formatted result to console (optional):
   console: true
+
+  // save the formatted result to a file (optional):
+  save: 'text-report.txt',
 }
 ```
 
 ### `debug`
 
 When set to `true`, the error handler will print an error stack trace. Defaults to `false`.
 
-## Autofix
-
-The `fix: true` option instructs stylelint to try to fix as many issues as possible. The fixes are applied to the gulp stream. The fixed content can be saved to file using gulp `dest`.
-
-> NOTE: Not all stylelint rules can be automatically fixed, so it's advisable to manually resolve errors.
-
-```js
-import { src, dest } from 'gulp';
-import gStylelintEsm from 'gulp-stylelint-esm';
-
-function fixCssTask() {
-  return src('src/**/*.css')
-    .pipe(gStylelintEsm({
-      fix: true
-    }))
-    .pipe(dest('src'));
-}
-```
-
 ## License
 
 See the [LICENSE](LICENSE) file for license rights and limitations (MIT).

.babelrc.cjs → babel.config.cjs

@@ -1,5 +1,5 @@
 /*!
- * Gulp Stylelint (v2.2.0): .babelrc.cjs
+ * Gulp Stylelint (v3.0.0): babel.config.cjs
  * Copyright (c) 2023-24 Adorade (https://github.com/adorade/gulp-stylelint-esm)
  * License under MIT
  * ========================================================================== */

jest.config.js

@@ -1,20 +1,22 @@
 /*!
- * Gulp Stylelint (v2.2.0): jest.config.js
+ * Gulp Stylelint (v3.0.0): jest.config.js
  * Copyright (c) 2023-24 Adorade (https://github.com/adorade/gulp-stylelint-esm)
  * License under MIT
  * ========================================================================== */
 
 /** @type {import('jest').Config} */
 const config =  {
+  displayName: {
+    name: "Gulp Stylelint Plugin",
+    color: "cyan",
+  },
   clearMocks: true,
-  // collectCoverage: true,
   collectCoverageFrom: [
     "src/*.mjs"
   ],
   coverageDirectory: "./.coverage/",
   coverageReporters: [
     "html",
-    "lcov",
     "text"
   ],
   coverageThreshold: {
@@ -25,6 +27,9 @@ const config =  {
       statements: 75
     }
   },
+  // fakeTimers: {
+  //   enableGlobally: true,
+  // },
   transform: {
     "\\.mjs?$": "babel-jest"
   },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gulp-stylelint-esm",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Gulp plugin for stylelint with ES module support.",
   "author": {
     "name": "Adorade",
@@ -10,13 +10,21 @@
   "homepage": "https://github.com/adorade/gulp-stylelint-esm",
   "repository": {
     "type": "git",
-    "url": "https://github.com/adorade/gulp-stylelint-esm.git"
+    "url": "git+https://github.com/adorade/gulp-stylelint-esm.git"
   },
   "type": "module",
-  "exports": "./src/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.mts",
+      "default": "./src/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
-    "/src/*.mjs"
+    "src/*.mjs",
+    "types/*.d.mts"
   ],
+  "types": "types",
   "keywords": [
     "gulpplugin",
     "gulpfriendly",
@@ -28,6 +36,7 @@
   ],
   "scripts": {
     "lint": "eslint {src,test}/**/*.{mjs,js}",
+    "lint:fix": "eslint {src,test}/**/*.{mjs,js} --fix",
     "jest": "node --experimental-vm-modules --no-warnings node_modules/jest/bin/jest.js -i",
     "jest:coverage": "yarn run jest --coverage",
     "test": "yarn run lint && yarn run jest",
@@ -37,24 +46,27 @@
     "stylelint": "16"
   },
   "dependencies": {
-    "@adorade/plugin-error": "1.0.0",
+    "@adorade/plugin-error": "2.0.1",
     "@jridgewell/trace-mapping": "0.3.25",
     "ansi-colors": "4.1.3",
-    "fancy-log": "2.0.0"
+    "fancy-log": "2.0.0",
+    "text-table": "0.2.0",
+    "write-file-atomic": "6.0.0"
   },
   "devDependencies": {
     "@babel/core": "7.25.2",
     "@babel/eslint-parser": "7.25.1",
-    "@babel/preset-env": "7.25.3",
+    "@babel/preset-env": "7.25.4",
     "babel-jest": "29.7.0",
     "eslint": "8.57.0",
     "eslint-config-stylelint": "22.0.0",
     "gulp": "5.0.0",
     "gulp-clean-css": "4.3.0",
     "gulp-concat": "2.6.1",
     "jest": "29.7.0",
-    "sinon": "18.0.0",
-    "stylelint": "16.8.1"
+    "sinon": "19.0.2",
+    "stylelint": "16.9.0",
+    "vinyl": "3.0.0"
   },
   "engines": {
     "node": ">=18.12.0"

src/apply-sourcemap.mjs

@@ -1,48 +1,46 @@
 /*!
- * Gulp Stylelint (v2.2.0): src/apply-sourcemap.mjs
+ * Gulp Stylelint (v3.0.0): src/apply-sourcemap.mjs
  * Copyright (c) 2023-24 Adorade (https://github.com/adorade/gulp-stylelint-esm)
  * License under MIT
  * ========================================================================== */
 
 import {TraceMap, originalPositionFor} from '@jridgewell/trace-mapping';
 
 /**
- * Applies a sourcemap to stylelint lint results, updating warning positions.
- * @param {Object} lintResult - Stylelint lint results.
- * @param {Object} sourceMap - Source map object.
- * @returns {Promise<Object>} - Promise resolving to updated lint results with sourcemap applied.
+ * @typedef {Object} Warning
+ * @property {number} line
+ * @property {number} column
+ *
+ * @typedef {Object} Result
+ * @property {string} source
+ * @property {Warning[]} warnings
+ *
+ * @typedef {Object} LintResult
+ * @property {Result[]} results
+ */
+
+/**
+ * Applies source map to the lint result.
+ *
+ * @param {LintResult} lintResult - The result of the linting process
+ * @param {Object} sourceMap - The source map object
+ * @returns {Promise<LintResult>} The lint result with applied source map
  */
 export default async function applySourcemap(lintResult, sourceMap) {
-  /**
-   * Source map consumer for the provided source map.
-   * @type {TraceMap}
-   */
+  /** @type {TraceMap} */
   const sourceMapConsumer = new TraceMap(sourceMap);
 
-  /**
-   * Applies sourcemap to lint results, updating warning positions.
-   * @type {Object[]}
-   */
   lintResult.results = lintResult.results.reduce((memo, result) => {
     if (result.warnings.length) {
       result.warnings.forEach(warning => {
-        /**
-         * Original position information for the warning from the sourcemap.
-         * @type {Object}
-         */
+        /** @type {import('@jridgewell/trace-mapping').OriginalMapping} */
         const origPos = originalPositionFor(sourceMapConsumer, warning);
 
-        /**
-         * Index of a result with the same source in the memo array.
-         * @type {number}
-         */
         const sameSourceResultIndex = memo.findIndex(r => r.source === origPos.source);
 
-        // Update warning properties with original position information
         warning.line = origPos.line;
         warning.column = origPos.column;
 
-        // Add or update result in the memo array based on the source file
         if (sameSourceResultIndex === -1) {
           memo.push(Object.assign({}, result, {
             source: origPos.source,
@@ -57,8 +55,7 @@ export default async function applySourcemap(lintResult, sourceMap) {
     }
 
     return memo;
-  }, []);
+  }, /** @type {Result[]} */ ([]));
 
-  // Return the updated lint results after applying the source map
   return lintResult;
 }