@open-xchange/linter-presets 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.0.1] - 2024-07-05
+
+- Added: ESLint project configuration (core, js, ts, json, yaml, license, directives, promises, jsdoc, stylistic)
+- Added: ESLint environment presets (tsconfig, node, browser, jest, vitest, codecept, react, plugin)
+
+## [0.0.2] - 2024-07-08
+
+- Added: StyleLint project configuration (core, less, sass, license, stylistic)

package/doc/eslint.md

@@ -23,13 +23,13 @@ Generates standard configuration targeting the source files in the entire projec
 
 #### `configure` Signature
 
-`function configure(options?: ESLintPresetsOptions): Linter.FlatConfig[]`
+`function configure(options?: ESLintConfigureOptions): Linter.FlatConfig[]`
 
 #### `configure` Options
 
 | Name | Type | Default | Description |
 | - | - | - | - |
-| `ignores` | `string[]` | `[]` | Glob patterns with all files and folders to be ignored by ESlint. |
+| `ignores` | `string[]` | `[]` | Glob patterns with all files and folders to be ignored by ESLint. |
 | `license` | `string` | `""` | Full path to the template file containing the license header to be used in all source files. |
 | `language` | `LanguageOptions` | | Configuration options for language and project setup. |
 | `language.ecmaVersion` | `number` | `2022` | The ECMAScript version to be used in the project (version or year). |

package/doc/stylelint.md

@@ -1,3 +1,39 @@
 # StyleLint Presets
 
 The module `stylelint` provides a `configure` function for project-wide StyleLint configuration.
+
+## Functions
+
+### Function `configure`
+
+Generates standard configuration targeting the source files in the entire project. Internally, various StyleLint plugins will be included and configured to use their recommended rule sets.
+
+#### `configure` Signature
+
+`function configure(options?: StyleLintConfigureOptions): Linter.FlatConfig[]`
+
+#### `configure` Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `ignores` | `string[]` | `[]` | Glob patterns with all files and folders to be ignored by StyleLint. |
+| `license` | `string` | `""` | Full path to the template file containing the license header to be used in all source files. |
+| `stylistic` | `StylisticOptions` | | Configuration options for code style. |
+| `stylistic.indent` | `number` | `2` | Default indentation size (number of space characters). Will be applied to JavaScript, TypeScript, JSON, and YAML files, as well as JSX markup. |
+| `stylistic.quotes` | `"single"\|"double"\|"off"` | `"single"` | The type of the string delimiter character. |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the global configuration. |
+
+#### `configure` Example
+
+```js
+// stylelint.config.js
+import { utils, stylelint } from "@open-xchange/linter-presets"
+
+const resolve = utils.resolver(import.meta.url)
+
+export default stylelint.configure({
+  ignores: ["dist/*", "external/**/*.scss"],
+  license: resolve("./license.txt"),
+  stylistic: { indent: 4, quotes: "double" },
+})
+```

package/lib/eslint/index.d.ts

@@ -1,7 +1,5 @@
 
-import { Linter } from "eslint";
-
-import { FlatConfigArray, LanguageOptions, StylisticOptions } from "./shared/types";
+import { FlatConfigArray, ESLintConfigureOptions } from "./shared/types";
 
 import tsconfig from "./env/tsconfig";
 import node from "./env/node";
@@ -12,41 +10,6 @@ import codecept from "./env/codecept";
 import react from "./env/react";
 import plugin from "./env/plugin";
 
-// types ======================================================================
-
-/**
- * Configuration options for linting the entire project.
- */
-export interface ESLintPresetsOptions {
-
-    /**
-     * Glob patterns with all files and folders to be ignored by ESlint.
-     */
-    ignores?: readonly string[];
-
-    /**
-     * Full path to the template file containing the license header to be used
-     * in all source files. The function `resolver` helps to to convert a local
-     * path to an absolute path.
-     */
-    license?: string;
-
-    /**
-     * Configuration options for language and project setup.
-     */
-    language?: LanguageOptions;
-
-    /**
-     * Configuration options for code style.
-     */
-    stylistic?: StylisticOptions;
-
-    /**
-     * Additional linter rules to be added to the global configuration.
-     */
-    rules?: Linter.RulesRecord;
-}
-
 // environments ===============================================================
 
 /**
@@ -65,26 +28,14 @@ export const env: {
 
 // functions ==================================================================
 
-/**
- * Creates and returns a resolver function for file paths relative to the given
- * base URL of a script file.
- *
- * @param url
- *  The base URL of the calling script, usually `import.meta.url`.
- *
- * @returns
- *  A function that converts relative file paths to absolute file paths.
- */
-export function resolver(url: string): (file: string) => string;
-
 /**
  * Defines standard configuration objects targeting the source files in the
  * entire project.
  *
- * @param config
- *  Plugin configuration.
+ * @param options
+ *  Plugin configuration options.
  *
  * @returns
  *  An array of configuration objects to be added to the flat configuration.
  */
-export function configure(config?: ESLintPresetsOptions): FlatConfigArray;
+export function configure(options?: ESLintConfigureOptions): FlatConfigArray;

package/lib/eslint/index.js

@@ -41,23 +41,23 @@ export const env = {
  * Generates standard configuration objects targeting the source files in the
  * entire project.
  *
- * @param {import("./shared/types.js").ESLintPresetsOptions} [options]
+ * @param {import("./shared/types").ESLintConfigureOptions} [options]
  *  Plugin configuration options.
  *
- * @returns {import("./shared/types.js").FlatConfigArray}
+ * @returns {import("./shared/types").FlatConfigArray}
  *  An array of configuration objects to be added to the flat configuration.
  */
 export function configure(options) {
 
     // resolve language configuration options
-    const languageConfig = {
+    const languageOptions = {
         ecmaVersion: 2022,
         sourceType: "module",
         ...options?.language,
     };
 
     // resolve stylistic configuration options
-    const stylisticConfig = {
+    const stylisticOptions = {
         indent: 2,
         semi: false,
         quotes: "single",
@@ -71,7 +71,7 @@ export function configure(options) {
         ...(options?.ignores?.length ? [{ ignores: options.ignores }] : []),
 
         // module types and standard rules for all JS/TS source files
-        ...base(languageConfig),
+        ...base(languageOptions),
 
         // default configuration for JavaScript files
         ...js(),
@@ -80,10 +80,10 @@ export function configure(options) {
         ...ts(),
 
         // default configuration for JSON files
-        ...json(stylisticConfig),
+        ...json(stylisticOptions),
 
         // default configuration for YAML files
-        ...yaml(stylisticConfig),
+        ...yaml(stylisticOptions),
 
         // check for correct license headers
         ...(options?.license ? license(options.license) : []),
@@ -98,7 +98,7 @@ export function configure(options) {
         ...jsdoc(),
 
         // default configuration for code style checks
-        ...stylistic(stylisticConfig),
+        ...stylistic(stylisticOptions),
 
         // custom rules
         ...(options?.rules ? [{ rules: options.rules }] : []),

package/lib/eslint/shared/types.d.ts

@@ -8,6 +8,8 @@ import { Linter } from "eslint";
  */
 export type FlatConfigArray = Linter.FlatConfig[];
 
+// ----------------------------------------------------------------------------
+
 /**
  * Configuration options for language and project setup.
  */
@@ -30,6 +32,8 @@ export interface LanguageOptions {
     sourceType?: "module" | "commonjs";
 }
 
+// ----------------------------------------------------------------------------
+
 /**
  * Configuration options for code style.
  */
@@ -67,6 +71,43 @@ export interface StylisticOptions {
     dangle?: "always" | "never" | "off";
 }
 
+// ----------------------------------------------------------------------------
+
+/**
+ * Configuration options for linting the entire project with ESLint.
+ */
+export interface ESLintConfigureOptions {
+
+    /**
+     * Glob patterns with all files and folders to be ignored by ESLint.
+     */
+    ignores?: readonly string[];
+
+    /**
+     * Full path to the template file containing the license header to be used
+     * in all source files. The function `resolver` helps to to convert a local
+     * path to an absolute path.
+     */
+    license?: string;
+
+    /**
+     * Configuration options for language and project setup.
+     */
+    language?: LanguageOptions;
+
+    /**
+     * Configuration options for code style.
+     */
+    stylistic?: StylisticOptions;
+
+    /**
+     * Additional linter rules to be added to the global configuration.
+     */
+    rules?: Linter.RulesRecord;
+}
+
+// ----------------------------------------------------------------------------
+
 /**
  * Shared options for an environment preset: include and exclude files, and add
  * more linter rules.

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 
 export * as utils from "./utils/index";
 export * as eslint from "./eslint/index";
+export * as stylelint from "./stylelint/index.js";

package/lib/index.js

@@ -1,3 +1,4 @@
 
 export * as utils from "./utils/index.js";
 export * as eslint from "./eslint/index.js";
+export * as stylelint from "./stylelint/index.js";

package/lib/stylelint/index.d.ts

@@ -0,0 +1,18 @@
+
+import { Config } from "stylelint";
+
+import { StyleLintConfigureOptions } from "./types";
+
+// functions ==================================================================
+
+/**
+ * Defines standard configuration objects targeting the source files in the
+ * entire project.
+ *
+ * @param config
+ *  Plugin configuration.
+ *
+ * @returns
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export function configure(config?: StyleLintConfigureOptions): Config;

package/lib/stylelint/index.js

@@ -0,0 +1,76 @@
+
+// functions ==================================================================
+
+/**
+ * Generates standard configuration objects targeting the source files in the
+ * entire project.
+ *
+ * @param {import("./types").StyleLintConfigureOptions} [options]
+ *  Plugin configuration options.
+ *
+ * @returns {import("stylelint").Config}
+ *  The configuration object to be exported from `stylelint.config.js`.
+ */
+export function configure(options) {
+
+    // resolve stylistic configuration options
+    const stylistic = {
+        indent: 2,
+        quotes: "single",
+        ...options?.stylistic,
+    };
+
+    return {
+
+        // ignore certain files and folders
+        ignoreFiles: options?.ignores ?? [],
+
+        // add the stylistic plugin
+        plugins: [
+            "stylelint-plugin-license-header",
+            "@stylistic/stylelint-plugin",
+        ],
+
+        // add recommended configurations
+        extends: [
+            "stylelint-config-standard-less",
+            "stylelint-config-standard-scss",
+            "@stylistic/stylelint-config",
+        ],
+
+        // reconfigure linter rules
+        rules: {
+
+            "at-rule-empty-line-before": null,
+            "color-function-notation": ["modern", { ignore: ["with-var-inside"] }],
+            "color-hex-length": null,
+            "custom-property-empty-line-before": null,
+            "declaration-block-no-redundant-longhand-properties": [true, { ignoreShorthands: ["inset"] }], // Safari does not support "inset"
+            "declaration-block-single-line-max-declarations": null,
+            "declaration-empty-line-before": null,
+            "function-url-no-scheme-relative": true,
+            "function-url-scheme-allowed-list": ["data"],
+            "media-feature-range-notation": null, // Safari 16.3 does not work with this notation
+            "no-descending-specificity": null,
+            "property-no-vendor-prefix": null,
+            "rule-empty-line-before": null,
+
+            ...(options?.license ? { "plugin/license-header": [true, { license: options.license }] } : null),
+
+            "scss/double-slash-comment-empty-line-before": null,
+
+            "@stylistic/declaration-colon-newline-after": null,
+            "@stylistic/indentation": [stylistic.indent, { ignore: ["inside-parens"] }],
+            "@stylistic/max-line-length": null,
+            "@stylistic/selector-list-comma-newline-after": null,
+            "@stylistic/string-quotes": (stylistic.quotes === "off") ? null : [stylistic.quotes, { avoidEscape: true }],
+
+            ...options?.rules,
+        },
+
+        // check inline directives
+        reportDescriptionlessDisables: null,
+        reportInvalidScopeDisables: true,
+        reportNeedlessDisables: true,
+    };
+}

package/lib/stylelint/types.d.ts

@@ -0,0 +1,44 @@
+
+import { Config } from "stylelint";
+
+// types ======================================================================
+
+/**
+ * Configuration options for code style.
+ */
+export interface StylisticOptions {
+
+    /**
+     * Default indentation size (number of space characters). Default value is
+     * `2`.
+     */
+    indent?: number;
+
+    /**
+     * The type of the string delimiter character. Default value is "single".
+     */
+    quotes?: "single" | "double" | "off";
+}
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Configuration options for linting the entire project.
+ */
+export interface StyleLintConfigureOptions {
+
+    /**
+     * Glob patterns with all files and folders to be ignored by StyleLint.
+     */
+    ignores?: readonly string[];
+
+    /**
+     * Configuration options for code style.
+     */
+    stylistic?: StylisticOptions;
+
+    /**
+     * Additional linter rules to be added to the global configuration.
+     */
+    rules?: Config["rules"];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-xchange/linter-presets",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Configuration presets for ESLint and StyleLint",
   "repository": "https://gitlab.open-xchange.com/fspd/npm-packages/linter-presets",
   "license": "MIT",
@@ -23,13 +23,15 @@
     "@eslint/js": "9.6.0",
     "@stylistic/eslint-plugin": "2.3.0",
     "@stylistic/eslint-plugin-migrate": "2.3.0",
+    "@stylistic/stylelint-config": "1.0.1",
+    "@stylistic/stylelint-plugin": "2.1.2",
     "confusing-browser-globals": "1.0.11",
     "eslint-plugin-chai-expect": "3.1.0",
     "eslint-plugin-codeceptjs": "1.3.0",
     "eslint-plugin-eslint-plugin": "6.2.0",
     "eslint-plugin-jest": "28.6.0",
     "eslint-plugin-jest-dom": "5.4.0",
-    "eslint-plugin-jsdoc": "48.5.0",
+    "eslint-plugin-jsdoc": "48.5.2",
     "eslint-plugin-jsonc": "2.16.0",
     "eslint-plugin-jsx-a11y": "6.9.0",
     "eslint-plugin-jsx-expressions": "1.3.2",
@@ -44,15 +46,22 @@
     "eslint-plugin-vitest": "0.5.4",
     "eslint-plugin-yml": "1.14.0",
     "globals": "15.8.0",
+    "stylelint-config-standard": "36.0.1",
+    "stylelint-config-standard-less": "3.0.1",
+    "stylelint-config-standard-scss": "13.1.0",
+    "stylelint-plugin-license-header": "1.0.3",
     "typescript-eslint": "7.15.0"
   },
   "devDependencies": {
     "eslint": "9.6.0",
     "husky": "9.0.11",
+    "lint-staged": "15.2.7",
+    "stylelint": "16.6.1",
     "typescript": "5.5.3"
   },
   "peerDependencies": {
     "eslint": "^9.6.0",
+    "stylelint": "^16.6.1",
     "typescript": "^5.5.3"
   },
   "resolutions": {