@nextcloud/eslint-config 9.0.0-rc.0 → 9.0.0-rc.2

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,123 @@
+import jsdocPlugin from 'eslint-plugin-jsdoc';
+import { GLOB_FILES_JAVASCRIPT, GLOB_FILES_TESTING, GLOB_FILES_TYPESCRIPT, GLOB_FILES_VUE, } from "../globs.js";
+const TS_FUNCTION_CONTEXTS = [
+    'FunctionDeclaration:has(TSTypeAnnotation)',
+    'FunctionExpression:has(TSTypeAnnotation)',
+    'ArrowFunctionExpression:has(TSTypeAnnotation)',
+    'MethodDefinition:has(TSTypeAnnotation)',
+];
+const JS_FUNCTION_CONTEXTS = [
+    'FunctionDeclaration:not(:has(TSTypeAnnotation))',
+    'FunctionExpression:not(:has(TSTypeAnnotation))',
+    'ArrowFunctionExpression:not(:has(TSTypeAnnotation))',
+    'MethodDefinition:not(:has(TSTypeAnnotation))',
+];
+/**
+ * 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,
+        },
+        {
+            name: 'nextcloud/documentation/rules',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...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 },
+                ],
+            },
+            settings: {
+                jsdoc: {
+                    // We use the alias for legacy reasons to prevent unnecessary noise
+                    tagNamePreference: {
+                        returns: 'return',
+                    },
+                },
+            },
+        },
+        {
+            name: 'nextcloud/documentation/rules-typescript',
+            files: [...GLOB_FILES_TYPESCRIPT],
+            ignores: GLOB_FILES_TESTING,
+            rules: {
+                // Overwrites for documentation as types are already provided by Typescript
+                'jsdoc/no-types': 'error',
+                'jsdoc/require-param-type': 'off',
+                'jsdoc/require-returns-type': 'off',
+            },
+        },
+        ...(options.vueIsTypescript
+            ? [
+                {
+                    name: 'nextcloud/documentation/rules-vue',
+                    files: [...(options.vueIsTypescript ? GLOB_FILES_VUE : [])],
+                    ignores: GLOB_FILES_TESTING,
+                    rules: {
+                        // Vue files can be both Javascript and Typescript
+                        // Try to apply TS files only for functions with TS definitions
+                        'jsdoc/no-types': [
+                            'error',
+                            { contexts: TS_FUNCTION_CONTEXTS },
+                        ],
+                        'jsdoc/require-param-type': [
+                            'error',
+                            { contexts: JS_FUNCTION_CONTEXTS },
+                        ],
+                        // Unlike params, return values are often inferred and not explicitly typed
+                        'jsdoc/require-returns-type': 'off',
+                        // Unfortunately, we cannot check when it is used in TS context and when not
+                        'jsdoc/check-tag-names': [
+                            'error',
+                            { typed: false },
+                        ],
+                    },
+                },
+            ]
+            : []),
+    ];
+}

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,20 @@
+/*!
+ * 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',
+            '**/js',
+            '**/l10n',
+            '**/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[];

package/dist/configs/imports.js

@@ -0,0 +1,114 @@
+import perfectionist from 'eslint-plugin-perfectionist';
+import { GLOB_FILES_JAVASCRIPT, GLOB_FILES_TYPESCRIPT, GLOB_FILES_VUE, } from "../globs.js";
+/**
+ * Generate imports and exports related ESLint rules.
+ *
+ * @param options - Configuration options
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function imports(options) {
+    return [
+        {
+            name: 'nextcloud/imports/setup',
+            plugins: {
+                perfectionist,
+            },
+        },
+        {
+            name: 'nextcloud/imports/rules',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            rules: {
+                // Require file extensions
+                'no-restricted-imports': [
+                    'error',
+                    {
+                        patterns: [
+                            {
+                                regex: '^(\\.*)/(.+/)*[^/.]+$',
+                                message: 'Import is missing the file extension.',
+                            },
+                        ],
+                    },
+                ],
+                // Sorting of imports
+                'sort-imports': 'off',
+                'perfectionist/sort-imports': [
+                    'error',
+                    {
+                        type: 'natural',
+                        newlinesBetween: 'never',
+                        groups: [
+                            // type first
+                            'external-type',
+                            'type',
+                            { newlinesBetween: 'always' },
+                            // external things
+                            [
+                                'builtin',
+                                'external',
+                                'object',
+                            ],
+                            // Vue components
+                            'vue', // external modules (e.g. nextcloud-vue)
+                            'internalVue', // internal local vue components
+                            // everything else which is everything internal
+                            'unknown',
+                            { newlinesBetween: 'always' },
+                            // side effect only: import 'sideeffect.js'
+                            'side-effect',
+                            // import style from 'my.module.css'
+                            'style',
+                        ],
+                        customGroups: [
+                            {
+                                groupName: 'vue',
+                                selector: 'external',
+                                modifiers: ['value'],
+                                elementNamePattern: [
+                                    '\\.vue$',
+                                    '@nextcloud/vue/components/',
+                                ],
+                            },
+                            {
+                                groupName: 'internalVue',
+                                modifiers: ['value'],
+                                elementNamePattern: ['\\.vue$'],
+                            },
+                        ],
+                    },
+                ],
+                'perfectionist/sort-named-exports': [
+                    'error',
+                    createSortingConfig('export'),
+                ],
+                'perfectionist/sort-named-imports': [
+                    'error',
+                    createSortingConfig('import'),
+                ],
+            },
+        },
+    ];
+}
+/**
+ * Create the same rule config for exports and import.
+ *
+ * @param type The type for which to create the config
+ */
+function createSortingConfig(type) {
+    return {
+        type: 'natural',
+        newlinesBetween: 'always',
+        partitionByNewLine: false,
+        groups: [
+            `type-${type}`,
+            [
+                `value-${type}`,
+                'unknown',
+            ],
+        ],
+    };
+}

package/dist/configs/javascript.d.ts

@@ -0,0 +1,14 @@
+/*!
+ * 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';
+/**
+ * This config provides the base rules for code quality,
+ * the target is a good code quality -> prevent bugs,
+ * code style is handled by another config.
+ *
+ * @param options - Configuration options
+ */
+export declare function javascript(options: ConfigOptions): Linter.Config[];

package/dist/configs/javascript.js

@@ -0,0 +1,118 @@
+import eslintRules from '@eslint/js';
+import globals from 'globals';
+import { GLOB_FILES_JAVASCRIPT, GLOB_FILES_TESTING, GLOB_FILES_TYPESCRIPT, GLOB_FILES_VUE, } from "../globs.js";
+import nextcloudPlugin from "../plugins/nextcloud/index.js";
+/**
+ * This config provides the base rules for code quality,
+ * the target is a good code quality -> prevent bugs,
+ * code style is handled by another config.
+ *
+ * @param options - Configuration options
+ */
+export function javascript(options) {
+    return [
+        {
+            name: 'nextcloud/javascript/setup',
+            languageOptions: {
+                ecmaVersion: 'latest',
+                globals: {
+                    ...globals.browser,
+                    ...globals.es2025,
+                    OC: 'readonly',
+                    OCA: 'writable',
+                    OCP: 'readonly',
+                    // injected by shared Vite and Webpack config
+                    appName: 'readonly',
+                    appVersion: 'readonly',
+                    // legacy global Nextcloud translation function
+                    t: 'readonly',
+                    n: 'readonly',
+                    // webpack support
+                    __webpack_nonce__: 'writable',
+                },
+                parserOptions: {
+                    ecmaFeatures: {
+                        jsx: true,
+                    },
+                    ecmaVersion: 'latest',
+                    sourceType: 'module',
+                },
+                sourceType: 'module',
+            },
+            linterOptions: {
+                reportUnusedDisableDirectives: true,
+            },
+        },
+        // General rules we built upon
+        {
+            name: 'eslint/configs/recommended',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            ...eslintRules.configs.recommended,
+        },
+        // The Nextcloud plugin for detecting deprecated and removed global API
+        (options.isLibrary
+            ? {}
+            : {
+                name: 'nextcloud/javascript/plugin',
+                plugins: {
+                    '@nextcloud': nextcloudPlugin,
+                },
+                rules: {
+                    '@nextcloud/no-deprecations': ['warn'],
+                    '@nextcloud/no-removed-apis': ['error'],
+                },
+                files: [
+                    ...GLOB_FILES_JAVASCRIPT,
+                    ...GLOB_FILES_TYPESCRIPT,
+                    ...GLOB_FILES_VUE,
+                ],
+            }),
+        // Nextcloud specific overwrite
+        {
+            name: 'nextcloud/javascript/rules',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            rules: {
+                'no-eval': 'error',
+                // Require strict checks
+                eqeqeq: 'error',
+                // Use dot notation where possible as we also only use quote where needed
+                'dot-notation': 'error',
+                // prevent bugs and increasing code clarity by ensuring that block statements are wrapped in curly braces
+                curly: [
+                    'error',
+                    'all',
+                ],
+                // disallow use of "var", use let and const - see rule description for reasons.
+                'no-var': 'error',
+                // Prevent bugs by enforce const if variable is not changed.
+                'prefer-const': 'error',
+                // `@nextcloud/logger` should be used
+                'no-console': 'error',
+                // We support ES2022 so we should use `hasOwn` instead
+                'prefer-object-has-own': 'error',
+                // Allow to write code in reading order for functions
+                'no-use-before-define': [
+                    'error',
+                    { functions: false },
+                ],
+            },
+        },
+        // Testing related overwrites
+        {
+            name: 'nextcloud/javascript/testing-overwrites',
+            files: GLOB_FILES_TESTING,
+            rules: {
+                // Allow to test console output
+                'no-console': 'off',
+            },
+        },
+    ];
+}

package/dist/configs/json.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';
+/**
+ * JSON related ESLint rules for Nextcloud
+ */
+export declare const json: Linter.Config[];

package/dist/configs/json.js

@@ -0,0 +1,45 @@
+import jsonPlugin from '@eslint/json';
+import { GLOB_FILES_JSON, GLOB_FILES_JSONC, GLOB_FILES_MS_JSON, } from "../globs.js";
+import packageJsonPlugin from "../plugins/packageJson.js";
+/**
+ * JSON related ESLint rules for Nextcloud
+ */
+export const json = [
+    {
+        language: 'json/json',
+        plugins: {
+            json: jsonPlugin,
+            'package-json': packageJsonPlugin,
+        },
+        rules: {
+            ...jsonPlugin.configs.recommended.rules,
+        },
+        files: GLOB_FILES_JSON,
+        name: 'nextcloud/json',
+    },
+    // lint package.json files
+    {
+        files: ['**/package.json'],
+        language: 'json/json',
+        rules: {
+            'package-json/sort-package-json': 'error',
+        },
+    },
+    // Special handing of JSONC
+    {
+        files: GLOB_FILES_JSONC,
+        language: 'json/jsonc',
+        ...jsonPlugin.configs.recommended,
+        name: 'nextcloud/jsonc',
+    },
+    // Microsoft specific JSONC (e.g. Typescript config)
+    {
+        files: GLOB_FILES_MS_JSON,
+        language: 'json/jsonc',
+        languageOptions: {
+            allowTrailingCommas: true,
+        },
+        ...jsonPlugin.configs.recommended,
+        name: 'nextcloud/ms-json',
+    },
+];

package/dist/configs/node.d.ts

@@ -0,0 +1,10 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import type { Linter } from 'eslint';
+/**
+ * Config setup for the node environment.
+ * Config files should be parsed as Node.JS scripts with Node globals etc.
+ */
+export declare const node: Linter.Config[];

package/dist/configs/node.js

@@ -0,0 +1,24 @@
+import globals from 'globals';
+import { GLOB_FILES_TESTING } from "../globs.js";
+/**
+ * Config setup for the node environment.
+ * Config files should be parsed as Node.JS scripts with Node globals etc.
+ */
+export const node = [
+    {
+        name: 'nextcloud/node/setup',
+        files: [
+            '**/*.config.*',
+            '**/*.cjs',
+            '**/*.cts',
+            ...GLOB_FILES_TESTING,
+        ],
+        languageOptions: {
+            globals: {
+                ...globals.es2023,
+                ...globals.node,
+                ...globals.nodeBuiltin,
+            },
+        },
+    },
+];

package/dist/configs/typescript.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';
+/**
+ * Typescript related ESLint rules for Nextcloud
+ *
+ * @param options options defining the config preset flavor
+ */
+export declare function typescript(options: ConfigOptions): Linter.Config[];

package/dist/configs/typescript.js

@@ -0,0 +1,60 @@
+import typescriptPlugin from 'typescript-eslint';
+import { GLOB_FILES_TESTING, GLOB_FILES_TYPESCRIPT, GLOB_FILES_TYPESCRIPT_DECLARATIONS, GLOB_FILES_VUE, } from "../globs.js";
+import { restrictConfigFiles } from "../utils.js";
+/**
+ * Typescript related ESLint rules for Nextcloud
+ *
+ * @param options options defining the config preset flavor
+ */
+export function typescript(options) {
+    return [
+        ...restrictConfigFiles(typescriptPlugin.configs.recommended, [
+            ...GLOB_FILES_TYPESCRIPT,
+            ...(options.vueIsTypescript ? GLOB_FILES_VUE : []),
+        ]),
+        {
+            name: 'nextcloud/typescript/rules',
+            files: [
+                ...GLOB_FILES_TYPESCRIPT,
+                ...(options.vueIsTypescript ? GLOB_FILES_VUE : []),
+            ],
+            rules: {
+                // Do not allow to import types with `import` but require `import type`
+                '@typescript-eslint/consistent-type-imports': 'error',
+                // Allow expect-error as we can sometimes not prevent it...
+                '@typescript-eslint/ban-ts-comment': [
+                    'error',
+                    {
+                        'ts-expect-error': 'allow-with-description',
+                        minimumDescriptionLength: 9,
+                    },
+                ],
+                // No nullish coalescing if left side can not be nullish
+                '@typescript-eslint/no-non-null-asserted-nullish-coalescing': 'error',
+                // Do not use types, variables etc before they are defined
+                'no-use-before-define': 'off',
+                '@typescript-eslint/no-use-before-define': [
+                    'error',
+                    {
+                        functions: false,
+                    },
+                ],
+            },
+        },
+        {
+            name: 'nextcloud/typescript/declaration-rules',
+            files: [...GLOB_FILES_TYPESCRIPT_DECLARATIONS],
+            rules: {
+                '@typescript-eslint/consistent-type-imports': ['error', { disallowTypeAnnotations: false }],
+            },
+        },
+        {
+            files: GLOB_FILES_TESTING,
+            rules: {
+                // Allow "any" in tests
+                '@typescript-eslint/no-explicit-any': 'off',
+            },
+            name: 'nextcloud/typescript/test-rules',
+        },
+    ];
+}

package/dist/configs/vue.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';
+/**
+ * General vue related rules for both versions
+ *
+ * @param options options defining the config preset flavor
+ */
+export declare function vue(options: ConfigOptions): Linter.Config[];