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

package/dist/configs/codeStyle.js

@@ -0,0 +1,176 @@
+import stylistic from '@stylistic/eslint-plugin';
+import eslintAntfuPlugin from 'eslint-plugin-antfu';
+import { GLOB_FILES_JAVASCRIPT, GLOB_FILES_TYPESCRIPT, GLOB_FILES_VUE, } from "../globs.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,
+            ],
+            plugins: {
+                antfu: eslintAntfuPlugin,
+            },
+            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: 'never',
+                        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 consistent new lines after brackets
+                '@stylistic/array-bracket-newline': 'off',
+                '@stylistic/array-bracket-spacing': 'off',
+                '@stylistic/array-element-newline': 'off',
+                '@stylistic/jsx-function-call-newline': 'off',
+                '@stylistic/object-curly-newline': 'off',
+                '@stylistic/object-curly-spacing': 'off',
+                '@stylistic/object-property-newline': 'off',
+                '@stylistic/exp-list-style': ['error', {
+                        singleLine: {
+                            spacing: 'never',
+                        },
+                        overrides: {
+                            '{}': {
+                                singleLine: { spacing: 'always' },
+                            },
+                        },
+                    }],
+                // 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',
+                // Enforce function declarations for top level functions
+                'antfu/top-level-function': 'error',
+            },
+        },
+        {
+            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,
+            ],
+            // 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,117 @@
+import { jsdoc } 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))',
+];
+const SHARED_JSDOC_SETTINGS = {
+    // We use the alias for legacy reasons to prevent unnecessary noise
+    tagNamePreference: {
+        returns: 'return',
+    },
+};
+/**
+ * Config factory for code documentation related rules (JSDoc)
+ *
+ * @param options options defining the config preset flavor
+ */
+export function documentation(options) {
+    return [
+        {
+            ...jsdoc({
+                config: 'flat/recommended-typescript-flavor',
+                settings: {
+                    ...SHARED_JSDOC_SETTINGS,
+                    mode: 'permissive',
+                },
+            }),
+            name: 'nextcloud/documentation/javascript',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...(options.vueIsTypescript ? [] : GLOB_FILES_VUE),
+            ],
+            ignores: GLOB_FILES_TESTING,
+        },
+        {
+            ...jsdoc({
+                config: 'flat/recommended-typescript',
+                settings: SHARED_JSDOC_SETTINGS,
+            }),
+            name: 'nextcloud/documentation/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 },
+                ],
+            },
+        },
+        {
+            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,25 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import gitignore from 'eslint-config-flat-gitignore';
+/**
+ * General config to exclude known non-source directories from linting
+ */
+export const filesystem = [
+    {
+        ...gitignore(),
+        name: 'nextcloud/filesystem/gitignore',
+    },
+    {
+        name: 'nextcloud/filesystem/ignores',
+        ignores: [
+            'dist/',
+            'js/',
+            'l10n/',
+            'vendor/',
+            'vendor-bin/',
+            '**/package-lock.json',
+        ],
+    },
+];

package/dist/configs/imports.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';
+/**
+ * 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,111 @@
+/*!
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import perfectionist from 'eslint-plugin-perfectionist';
+import { GLOB_FILES_JAVASCRIPT, GLOB_FILES_TYPESCRIPT, GLOB_FILES_VUE, } from "../globs.js";
+import importExtensions from "../plugins/import-extensions/index.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,
+                'import-extensions': importExtensions,
+            },
+        },
+        {
+            name: 'nextcloud/imports/rules',
+            files: [
+                ...GLOB_FILES_JAVASCRIPT,
+                ...GLOB_FILES_TYPESCRIPT,
+                ...GLOB_FILES_VUE,
+            ],
+            rules: {
+                // Require file extensions
+                'import-extensions/extensions': 'error',
+                // enforce explicit type imports (no inline types)
+                'import-extensions/ban-inline-type-imports': 'error',
+                // Sorting of imports
+                'sort-imports': 'off',
+                'perfectionist/sort-imports': [
+                    'error',
+                    {
+                        type: 'natural',
+                        newlinesBetween: 0,
+                        groups: [
+                            // type first
+                            ['type-external', 'type-builtin'],
+                            'type-import',
+                            { newlinesBetween: 1 },
+                            // external things
+                            [
+                                'builtin',
+                                'external',
+                            ],
+                            // Vue components
+                            'vue', // external modules (e.g. nextcloud-vue)
+                            'internalVue', // internal local vue components
+                            // everything else which is everything internal
+                            'unknown',
+                            { newlinesBetween: 1 },
+                            // 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: 0,
+        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-deprecated-globals': ['warn'],
+                    '@nextcloud/no-removed-globals': ['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[];