@nextcloud/eslint-config 8.4.2 → 9.0.0-rc.1

package/CHANGELOG.md

@@ -4,6 +4,49 @@
 -->	
 # Changelog
 
+## [v9.0.0](https://github.com/nextcloud-libraries/eslint-config/tree/v9.0.0) (2025)
+
+### Breaking
+This package now is using ESLint v9 and requires ESLint flat configurations.
+Please refer to the README on how to adjust your configuration for flat config.
+
+### Added
+* feat: new modular config for (and with) ESLint v9 support [#887](https://github.com/nextcloud-libraries/eslint-config/pull/887)
+* feat: merge plugin repository [#899](https://github.com/nextcloud-libraries/eslint-config/pull/899)
+* feat: enforce non-breaking spaces before ellipsis for translations [\#948](https://github.com/nextcloud-libraries/eslint-config/pull/948)
+* feat: add special config for libraries [\#949](https://github.com/nextcloud-libraries/eslint-config/pull/949)
+* feat: add import and export rules [\#981](https://github.com/nextcloud-libraries/eslint-config/pull/981)
+* feat: introduce @nextcloud/vue eslint plugin [\#939](https://github.com/nextcloud-libraries/eslint-config/pull/939)
+
+### Fixed
+* fix(codestyle): do not require splitting chains [\#951](https://github.com/nextcloud-libraries/eslint-config/pull/951)
+* fix(codestyle): adjust empty lines style [\#952](https://github.com/nextcloud-libraries/eslint-config/pull/952)
+* fix(codestyle): Enforce no space before function parenthesis [#901](https://github.com/nextcloud-libraries/eslint-config/pull/901)
+* fix(codeStyle): Adjust `stylistic` rules config [#914](https://github.com/nextcloud-libraries/eslint-config/pull/914)
+* fix(codeStyle): allow single line arrays [\#997](https://github.com/nextcloud-libraries/eslint-config/pull/997)
+* fix(codeStyle): allow devs write small objects in one line [\#996](https://github.com/nextcloud-libraries/eslint-config/pull/996)
+* fix(globs): properly ignore test files [\#974](https://github.com/nextcloud-libraries/eslint-config/pull/974)
+* fix(imports): do not mix externals and internals [\#1000](https://github.com/nextcloud-libraries/eslint-config/pull/1000)
+* fix(javascript): allow using functions before they are defined [\#970](https://github.com/nextcloud-libraries/eslint-config/pull/970)
+* fix(javascript): add missing `appName` and `appVersion` global + fix access [\#972](https://github.com/nextcloud-libraries/eslint-config/pull/972)
+* fix(typescript): allow to use function before definition [\#950](https://github.com/nextcloud-libraries/eslint-config/pull/950)
+* fix(typescript): remove `@typescript-eslint/no-shadow` [\#993](https://github.com/nextcloud-libraries/eslint-config/pull/993)
+* fix(typescript): enforce `import type` for type only imports [\#977](https://github.com/nextcloud-libraries/eslint-config/pull/977)
+
+### Changed
+* Add SPDX header [#802](https://github.com/nextcloud-libraries/eslint-config/pull/802)
+* Updated development dependencies
+* refactor(json): drop now unneeded `@ts-expect-error` [#915](https://github.com/nextcloud-libraries/eslint-config/pull/915)
+* chore: do not bundle config but just use Typescript [#967](https://github.com/nextcloud-libraries/eslint-config/pull/967)
+* chore: require node ^20.19 [\#982](https://github.com/nextcloud-libraries/eslint-config/pull/982)
+* Updated `@eslint/json` to 0.12.0
+* Updated `@stylistic/eslint-plugin` 4.2.0
+* Updated `eslint-plugin-jsdoc` to 50.6.11
+* Updated `eslint-plugin-vue` to 10.0.0
+* Updated `fast-xml-parser` to 5.2.1
+* Updated `sort-package-json` to 3.0.0
+* Updated `typescript-eslint` to 8.31.0
+
 ## [v8.4.2](https://github.com/nextcloud-libraries/eslint-config/tree/v8.4.2) (2025-02-16)
 ### Fixed
 * fix(typescript): do not require returns type in jsdoc by @ShGKme in https://github.com/nextcloud-libraries/eslint-config/pull/857
@@ -14,6 +57,7 @@
 * enh(git): ignore formatting commits in git blame by @max-nextcloud in https://github.com/nextcloud-libraries/eslint-config/pull/854
 
 ## [v8.4.1](https://github.com/nextcloud-libraries/eslint-config/tree/v8.4.1) (2024-05-16)
+
 [Full Changelog](https://github.com/nextcloud-libraries/eslint-config/compare/v8.4.0...v8.4.1)
 
 ### Fixes

package/README.md

@@ -10,11 +10,10 @@
 [![Dependabot status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg?longCache=true&style=flat-square&logo=dependabot)](https://dependabot.com)
 
 
-This is a package containing the unified global eslint config used by all nextcloud apps.
+This is a package containing the unified global eslint config used by all nextcloud apps and libraries.
 It contains the necessary dependencies and peerDependencies so that other apps cannot update if this config does not support it.
 Please always use dependabot to update your apps, OR pay attention to the peer dependencies error messages!
 
-
 ## Installation
 
 ```bash
@@ -23,43 +22,170 @@ npm install @nextcloud/eslint-config --save-dev
 
 ## Usage
 
-Add a file `.eslintrc.js` in the root directory of your app repository with the following content:
+> [!NOTE]
+> Since version 9 this package depends on ESLint 9, which uses the new flat config system.
+
+This package provides some predefined configurations you can choose from.
+For the recommended setup add a file `eslint.config.js` in the root directory of your app repository with the following content:
 
 ```js
-module.exports = {
-	extends: [
-		'@nextcloud',
-	],
-}
+import { recommended } from '@nextcloud/eslint-config'
+
+export default [
+	...recommended,
+]
 ```
 
-### Usage with Typescript projects
+### Available configurations
+
+Instead of the `recommended` configuration this package also provides some alternatives, depending on your app setup you can also choose:
+
+* `recommended`
+  * General rules including code style
+  * Support for Typescript
+  * Support for Vue **3**
+  * Support Vue files with Typescript syntax (the script within `.vue` files will be handled as Typescript).
+* `recommendedJavascript`
+  * Same as `recommended` but Vue files (the script part) will be handled as Javascript.
+* `recommendedVue2`
+  * Same as `recommended` but Vue files are considered in Vue 2 syntax.
+* `recommendedVue2Javascript`
+  * Same as `recommended` but Vue files are considered in Vue 2 syntax and the script part will be handled as Javascript instead of Typescript.
 
-If your projects uses Typescript for vue files, like `<script lang="ts">` then use the Typescript config instead:
+#### Configurations for Nextcloud libraries
 
-Add a file `.eslintrc.js` in the root directory of your app repository with the following content:
+For libraries some of the presets make no sense, like checking Nextcloud deprecated API.
+But on the otherhand some rules should be enforced, like documenting all properties.
+So for libraries use following configurations:
 
+* `recommendedLibrary`
+* `recommendedVue2Library`
+
+### Bundled plugins
+
+This configuration also provides some bundled plugins with new rules, those options are already included in the recommended configurations.
+
+It is possible to override the recommended configurations:
 ```js
-module.exports = {
-	extends: [
-		'@nextcloud/eslint-config/typescript',
-	],
-}
+// eslint.config.js
+import { recommended } from '@nextcloud/eslint-config'
+export default [
+	...recommended,
+	{
+		files: ['**/*.js'],
+		rules: {
+			// Make deprecations error instead of warning level
+			'@nextcloud/no-deprecations': ['error'],
+		}
+	}
+]
 ```
 
-### Usage with Vue 3 projects
+You can even use the plugins without using the Nextcloud ESLint config:
+```js
+// eslint.config.js
+import { nextcloudPlugin } from '@nextcloud/eslint-config'
+export default [
+	{
+		files: ['**/*.js'],
+		plugins: {
+			'@nextcloud': nextcloudPlugin,
+		},
+		rules: {
+			'@nextcloud/no-removed-apis': ['error', { targetVersion: '29.0.0' }],
+		},
+	}
+]
+```
+
+#### `package-json` plugin
+Rules:
+- `sort-package-json`
+  - Ensures the `package.json` is sorted in consistent order
+  - Included as `error` level in recommended configurations
+
+#### `@nextcloud` plugin
+Rules:
+- `no-deprecations`
+  - Report usage of deprecated Nextcloud API
+  - Included as `warn` level in recommended configuration
+  - Available options
+    ```ts
+    {
+      /**
+       * Limit deprecated API to specified Nextcloud version
+       * @example '29.0.0'
+       * @default ''
+       */
+      targetVersion?: string
+      /**
+       * Try to find appinfo.xml to detect targetVersion
+       * @default true
+       */
+      parseAppInfo?: boolean
+    }
+    ```
+- `no-removed-apis`
+  - Report usage of removed Nextcloud API
+  - Included as `error` level in recommended configuration
+  - Available options
+    ```ts
+    {
+      /**
+       * Limit removed API to specified Nextcloud version
+       * @example '29.0.0'
+       * @default ''
+       */
+      targetVersion?: string
+      /**
+       * Try to find appinfo.xml to detect targetVersion
+       * @default true
+       */
+      parseAppInfo?: boolean
+    }
+    ```
+
+#### `@nextcloud-l10n`
+```ts
+import { l10nPlugin  } from '@nextcloud/eslint-config'
+```
+
+Rules:
+- `enforce-ellipsis`
+  - Enforce consistent usageof ellipsis instead of tripple dots
+  - Included as `error` level in recommended configuration
+- `non-breaking-space`
+  - Enforce non-breaking spaces before ellipsis
+  - Included as `error` level in recommended configuration
 
-If your projects uses Vue 3 you have to use the `vue3` sub-configuration.
-This configuration also includes Typescript support by default.
+### Adding custom overrides
+
+Sometimes additional rules need to be added for individual projects,
+and while we do not recommend to override Nextcloud rules for code style (it should be consistent across all Nextcloud projects!),
+it is possible to add such custom rules.
+
+For example to enforce chains to be on separate lines:
+
+```diff
+- const a = foo().then((a) => a.b).catch((e) => e.c)
++ const a = foo()
++ 	.then((a) => a.b)
++ 	.catch((e) => e.c)
+```
 
-Add a file `.eslintrc.js` in the root directory of your app repository with the following content:
+Adjust your `eslint.config.js` like this:
 
 ```js
-module.exports = {
-	extends: [
-		'@nextcloud/eslint-config/vue3',
-	],
-}
+import { recommended } from '@nextcloud/eslint-config'
+
+export default [
+	...recommended,
+	{
+		rules: {
+			'@stylistic/newline-per-chained-call': ['error'],
+		}
+	},
+]
 ```
 
 ## Release new version

package/dist/configs/codeStyle.d.ts

@@ -0,0 +1,13 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { Linter } from 'eslint';
+import type { ConfigOptions } from '../types.d.ts';
+/**
+ * Config factory for general code style related rules
+ * See also: https://docs.nextcloud.com/server/latest/developer_manual/getting_started/coding_standards/javascript.html#code-style
+ *
+ * @param options options defining the config preset flavor
+ */
+export declare function codeStyle(options: ConfigOptions): (Linter.Config | Linter.BaseConfig)[];

package/dist/configs/codeStyle.js

@@ -0,0 +1,178 @@
+import stylistic from '@stylistic/eslint-plugin';
+import { GLOB_FILES_JAVASCRIPT, GLOB_FILES_TYPESCRIPT, GLOB_FILES_VUE, } from "../globs.js";
+import l10nPlugin from "../plugins/l10n/index.js";
+/**
+ * Config factory for general code style related rules
+ * See also: https://docs.nextcloud.com/server/latest/developer_manual/getting_started/coding_standards/javascript.html#code-style
+ *
+ * @param options options defining the config preset flavor
+ */
+export function codeStyle(options) {
+    return [
+        // Nextcloud code style
+        {
+            name: '@stylistic/configs/recommended',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            ...stylistic.configs.customize({
+                indent: 'tab',
+                semi: false,
+                quotes: 'single',
+                quoteProps: 'as-needed',
+                commaDangle: 'always-multiline',
+                arrowParens: true,
+                braceStyle: '1tbs',
+            }),
+        },
+        {
+            name: 'nextcloud/stylistic/rules',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            rules: {
+                // Overrides for the stylistic recommended rules
+                // Tabs should only be used for indention
+                '@stylistic/no-tabs': [
+                    'error',
+                    { allowIndentationTabs: true },
+                ],
+                // allow spaces after tabs for alignment
+                '@stylistic/no-mixed-spaces-and-tabs': [
+                    'error',
+                    'smart-tabs',
+                ],
+                // allow backticks for strings that contain single quotes
+                '@stylistic/quotes': [
+                    'error',
+                    'single',
+                    {
+                        allowTemplateLiterals: false,
+                        avoidEscape: true,
+                    },
+                ],
+                // Not included in stylistic preset but set by us:
+                // Enforce camelCase but allow legacy webpack variables
+                camelcase: [
+                    'error',
+                    {
+                        allow: ['^__webpack_'],
+                        properties: 'never',
+                        ignoreGlobals: true,
+                    },
+                ],
+                // Make sure to use object shorthand properties
+                'object-shorthand': [
+                    'error',
+                    'properties',
+                    { avoidQuotes: true },
+                ],
+                // Enforce new lines after [ and before ] if there are multiline entries or more than 1 item in the array (better git diff)
+                '@stylistic/array-bracket-newline': [
+                    'error',
+                    {
+                        multiline: true,
+                        minItems: null, // disable
+                    },
+                ],
+                // Enforce new lines between array elements (better git diff) but allow to have single line arrays
+                '@stylistic/array-element-newline': ['error', 'consistent'],
+                // Same for objects as for arrays
+                '@stylistic/object-curly-newline': [
+                    'error',
+                    {
+                        consistent: true,
+                        multiline: true,
+                    },
+                ],
+                '@stylistic/object-property-newline': [
+                    'error',
+                    { allowAllPropertiesOnSameLine: true },
+                ],
+                // No space between function name and parenthesis. Enforce fn() instead of fn ()
+                '@stylistic/function-call-spacing': [
+                    'error',
+                    'never',
+                ],
+                // No space between function name and parenthesis on definition. Enforce `function foo()` instead of `function foo ()`.
+                '@stylistic/space-before-function-paren': [
+                    'error',
+                    {
+                        // good: `function() {}` bad: `function () {}`
+                        anonymous: 'never',
+                        // good `function foo() {}` bad: `function foo () {}`
+                        named: 'never',
+                        // consistency for arrow functions regardless of async or sync:
+                        // good `async () => {}` bad `async() => {}`
+                        asyncArrow: 'always',
+                    },
+                ],
+                // Enforce consistent newlines in function parameters, if one parameter is separated by newline, than all should
+                '@stylistic/function-call-argument-newline': [
+                    'error',
+                    'consistent',
+                ],
+                // If parameters are separated by newlines, then the first one should also be separated by a newline from the parenthesis
+                '@stylistic/function-paren-newline': [
+                    'error',
+                    'multiline',
+                ],
+                // Generator functions should have the * on the function keyword as this defines the type of function. "function* generator()"
+                '@stylistic/generator-star-spacing': [
+                    'error',
+                    'after',
+                ],
+                // Arrow functions with implicit return should not have line breaks
+                // TODO: Discuss
+                '@stylistic/implicit-arrow-linebreak': [
+                    'error',
+                    'beside',
+                ],
+                // Prevent issues with different OS by enforcing single line feed for new lien
+                '@stylistic/linebreak-style': [
+                    'error',
+                    'unix',
+                ],
+                // No useless semicolons
+                '@stylistic/no-extra-semi': ['error'],
+                'no-useless-concat': 'error',
+                // Prefer { ...foo } over Object.assign({}, foo)
+                'prefer-object-spread': 'warn',
+            },
+        },
+        {
+            name: 'nextcloud/stylistic/ts-rules',
+            files: [
+                ...GLOB_FILES_TYPESCRIPT,
+                ...(options.vueIsTypescript ? GLOB_FILES_VUE : []),
+            ],
+            rules: {
+                // consistent spacing for types
+                '@stylistic/type-annotation-spacing': 'error',
+                // consistent spacing for generics
+                '@stylistic/type-generic-spacing': 'error',
+                '@stylistic/type-named-tuple-spacing': 'error',
+            },
+        },
+        {
+            name: 'nextcloud/stylistic/l10n',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            plugins: {
+                '@nextcloud-l10n': l10nPlugin,
+            },
+            // Enforce that translations use ellipsis instead of tripple dots
+            rules: {
+                '@nextcloud-l10n/non-breaking-space': 'error',
+                '@nextcloud-l10n/enforce-ellipsis': 'error',
+            },
+        },
+    ];
+}

package/dist/configs/documentation.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { Linter } from 'eslint';
+import type { ConfigOptions } from '../types.d.ts';
+/**
+ * Config factory for code documentation related rules (JSDoc)
+ *
+ * @param options options defining the config preset flavor
+ */
+export declare function documentation(options: ConfigOptions): Linter.Config[];

package/dist/configs/documentation.js

@@ -0,0 +1,84 @@
+import jsdocPlugin from 'eslint-plugin-jsdoc';
+import { GLOB_FILES_JAVASCRIPT, GLOB_FILES_TESTING, GLOB_FILES_TYPESCRIPT, GLOB_FILES_VUE, } from "../globs.js";
+/**
+ * Config factory for code documentation related rules (JSDoc)
+ *
+ * @param options options defining the config preset flavor
+ */
+export function documentation(options) {
+    return [
+        {
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            plugins: {
+                jsdoc: jsdocPlugin,
+            },
+        },
+        {
+            ...jsdocPlugin.configs['flat/recommended-typescript-flavor'],
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...(options.vueIsTypescript ? [] : GLOB_FILES_VUE),
+            ],
+            settings: {
+                jsdoc: {
+                    mode: 'permissive',
+                },
+            },
+            ignores: GLOB_FILES_TESTING,
+        },
+        {
+            ...jsdocPlugin.configs['flat/recommended-typescript'],
+            files: [
+                ...GLOB_FILES_TYPESCRIPT,
+                ...(options.vueIsTypescript ? GLOB_FILES_VUE : []),
+            ],
+            ignores: GLOB_FILES_TESTING,
+        },
+        {
+            rules: {
+                // Force proper documentation
+                'jsdoc/check-tag-names': 'error',
+                // But ignore return values
+                'jsdoc/require-returns': 'off',
+                'jsdoc/require-returns-description': 'off',
+                // Allow one empty line in jsdoc blocks
+                'jsdoc/tag-lines': [
+                    'warn',
+                    'any',
+                    { startLines: 1 },
+                ],
+            },
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            settings: {
+                jsdoc: {
+                    // We use the alias for legacy reasons to prevent unnecessary noise
+                    tagNamePreference: {
+                        returns: 'return',
+                    },
+                },
+            },
+            name: 'nextcloud/documentation/rules',
+        },
+        {
+            rules: {
+                // Overwrites for documentation as types are already provided by Typescript
+                'jsdoc/require-param-type': 'off',
+                'jsdoc/require-property-type': 'off',
+                'jsdoc/require-returns-type': 'off',
+            },
+            files: [
+                ...GLOB_FILES_TYPESCRIPT,
+                ...(options.vueIsTypescript ? GLOB_FILES_VUE : []),
+            ],
+            name: 'nextcloud/documentation/rules-typescript',
+        },
+    ];
+}

package/dist/configs/filesystem.d.ts

@@ -0,0 +1,9 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { Linter } from 'eslint';
+/**
+ * General config to exclude known non-source directories from linting
+ */
+export declare const filesystem: Linter.Config[];

package/dist/configs/filesystem.js

@@ -0,0 +1,18 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+/**
+ * General config to exclude known non-source directories from linting
+ */
+export const filesystem = [
+    {
+        name: 'nextcloud/filesystem/ignores',
+        ignores: [
+            '**/dist',
+            '**/vendor',
+            '**/vendor-bin',
+            '**/package-lock.json',
+        ],
+    },
+];

package/dist/configs/imports.d.ts

@@ -0,0 +1,12 @@
+import type { Linter } from 'eslint';
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { ConfigOptions } from '../types.d.ts';
+/**
+ * Generate imports and exports related ESLint rules.
+ *
+ * @param options - Configuration options
+ */
+export declare function imports(options: ConfigOptions): Linter.Config[];