@scayle/eslint-config-storefront 4.8.2 → 5.0.0

package/config/rules.mjs

@@ -0,0 +1,220 @@
+import comments from '@eslint-community/eslint-plugin-eslint-comments'
+import pluginNode from 'eslint-plugin-n'
+import jsonc from 'eslint-plugin-jsonc'
+import pluginSonarjs from 'eslint-plugin-sonarjs'
+import pluginPromise from 'eslint-plugin-promise'
+import regexp from 'eslint-plugin-regexp'
+import { importX as pluginImportX } from 'eslint-plugin-import-x'
+import jsdoc from 'eslint-plugin-jsdoc'
+import e18e from '@e18e/eslint-plugin'
+
+// Small, single-plugin rule domains that don't warrant their own file. Each
+// still exports its own named factory, so composition and imports elsewhere
+// in the package are unaffected by living in this shared file.
+
+// ESLint directive comment hygiene (e.g. eslint-disable) rules.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries enforcing ESLint directive comment hygiene. */
+export function commentsConfig() {
+  return [
+    {
+      name: 'storefront/comments/rules',
+      plugins: { 'eslint-comments': comments },
+      rules: {
+        'eslint-comments/no-aggregating-enable': 'error',
+        'eslint-comments/no-duplicate-disable': 'error',
+        'eslint-comments/no-unlimited-disable': 'error',
+        'eslint-comments/no-unused-enable': 'error',
+      },
+    },
+  ]
+}
+
+// Node.js best-practice rules.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for Node.js best-practice rules. */
+export function nodeConfig() {
+  return [
+    {
+      name: 'storefront/node/rules',
+      plugins: { node: pluginNode },
+      rules: {
+        'node/handle-callback-err': ['error', '^(err|error)$'],
+        'node/no-deprecated-api': 'error',
+        'node/no-exports-assign': 'error',
+        'node/no-new-require': 'error',
+        'node/no-path-concat': 'error',
+        'node/prefer-global/buffer': ['error', 'never'],
+        'node/prefer-global/process': ['error', 'never'],
+        'node/process-exit-as-throw': 'error',
+      },
+    },
+  ]
+}
+
+// JSON / JSONC structural and stylistic rules.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for JSON/JSONC structural and stylistic rules. */
+export function jsoncConfig() {
+  return [
+    ...jsonc.configs['flat/recommended-with-jsonc'],
+    {
+      name: 'storefront/jsonc/rules',
+      files: ['**/*.json', '**/*.json5', '**/*.jsonc'],
+      rules: {
+        'jsonc/array-bracket-spacing': ['error', 'never'],
+        'jsonc/comma-dangle': ['error', 'never'],
+        'jsonc/comma-style': ['error', 'last'],
+        'jsonc/indent': ['error', 2],
+        'jsonc/key-spacing': [
+          'error',
+          { afterColon: true, beforeColon: false },
+        ],
+        'jsonc/object-curly-newline': [
+          'error',
+          { consistent: true, multiline: true },
+        ],
+        'jsonc/object-curly-spacing': ['error', 'always'],
+        'jsonc/object-property-newline': [
+          'error',
+          { allowAllPropertiesOnSameLine: true },
+        ],
+        'jsonc/quote-props': 'error',
+        'jsonc/quotes': 'error',
+      },
+    },
+  ]
+}
+
+// Pre-defined rule configurations for better performance
+/** @type {import('eslint').Linter.RulesRecord} */
+const SONARJS_RULES = {
+  'sonarjs/no-duplicate-string': 'off',
+  'sonarjs/todo-tag': 'warn',
+  'sonarjs/fixme-tag': 'warn',
+}
+
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for SonarJS rules. */
+export function sonarjsConfig() {
+  return [
+    /** @type {import('eslint').Linter.Config} */ (
+      pluginSonarjs.configs.recommended
+    ),
+    {
+      name: 'storefront/sonarjs/rules',
+      rules: SONARJS_RULES,
+    },
+  ]
+}
+
+// Pre-defined rule configurations for better performance
+/** @type {import('eslint').Linter.RulesRecord} */
+const PROMISE_RULES = {
+  'promise/no-multiple-resolved': 'error',
+  'promise/no-new-statics': 'error',
+  'promise/no-return-wrap': 'error',
+  'promise/always-return': 'warn',
+  'promise/avoid-new': 'warn',
+  'promise/catch-or-return': 'warn',
+  'promise/no-callback-in-promise': 'warn',
+  'promise/no-nesting': 'warn',
+  'promise/no-promise-in-callback': 'warn',
+  'promise/no-return-in-finally': 'warn',
+  'promise/param-names': 'warn',
+  'promise/valid-params': 'warn',
+  'promise/no-native': 'off',
+}
+
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for Promise usage rules. */
+export function promiseConfig() {
+  return [
+    {
+      name: 'storefront/promise/rules',
+      plugins: { promise: pluginPromise },
+      rules: PROMISE_RULES,
+    },
+  ]
+}
+
+// Regex correctness rules, including ReDoS-prone pattern detection.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for regex correctness rules. */
+export function regexpConfig() {
+  return [
+    {
+      name: 'storefront/regexp/rules',
+      ...regexp.configs['flat/recommended'],
+    },
+  ]
+}
+
+// Pre-defined rule configurations for better performance
+/** @type {import('eslint').Linter.RulesRecord} */
+const IMPORT_X_RULES = {
+  'import-x/consistent-type-specifier-style': ['error', 'prefer-top-level'],
+  'import-x/first': 'error',
+  'import-x/no-duplicates': 'error',
+  'import-x/no-mutable-exports': 'error',
+  'import-x/no-named-default': 'error',
+  'import-x/no-self-import': 'error',
+  'import-x/no-extraneous-dependencies': 'error',
+}
+
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for import/export correctness rules. */
+export function importXConfig() {
+  return [
+    {
+      name: 'storefront/import-x/rules',
+      plugins: { 'import-x': pluginImportX },
+      rules: IMPORT_X_RULES,
+    },
+  ]
+}
+
+// JSDoc validation. Storefront SDK packages require JSDoc on every exported symbol.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries validating JSDoc comments. */
+export function jsdocConfig() {
+  return [
+    {
+      name: 'storefront/jsdoc/rules',
+      plugins: { jsdoc },
+      rules: {
+        'jsdoc/check-access': 'warn',
+        'jsdoc/check-param-names': 'warn',
+        'jsdoc/check-property-names': 'warn',
+        'jsdoc/check-types': 'warn',
+        'jsdoc/empty-tags': 'warn',
+        'jsdoc/implements-on-classes': 'warn',
+        'jsdoc/no-defaults': 'warn',
+        'jsdoc/no-multi-asterisks': 'warn',
+        'jsdoc/require-param-name': 'warn',
+        'jsdoc/require-property': 'warn',
+        'jsdoc/require-property-description': 'warn',
+        'jsdoc/require-property-name': 'warn',
+        'jsdoc/require-returns-check': 'warn',
+        'jsdoc/require-returns-description': 'warn',
+        'jsdoc/require-yields-check': 'warn',
+        'jsdoc/check-alignment': 'warn',
+        'jsdoc/multiline-blocks': 'warn',
+      },
+    },
+  ]
+}
+
+// Modernization, module-replacement, and performance rules from the e18e
+// community (https://e18e.dev). Uses the plugin's own `recommended` preset
+// (all three of its rule categories), downgraded to `warn`: the plugin is
+// young (pre-1.0) and its rule set hasn't been reviewed against this
+// codebase yet, so findings surface without blocking CI.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for e18e modernization and performance rules. */
+export function e18eConfig() {
+  const recommendedRules = e18e.configs.recommended.rules ?? {}
+  /** @type {import('eslint').Linter.RulesRecord} */
+  const rules = Object.fromEntries(
+    Object.keys(recommendedRules).map((ruleName) => [ruleName, 'warn']),
+  )
+
+  return [
+    {
+      name: 'storefront/e18e/rules',
+      plugins: e18e.configs.recommended.plugins,
+      rules,
+    },
+  ]
+}

package/config/test.mjs

@@ -0,0 +1,36 @@
+import vitest from '@vitest/eslint-plugin'
+import noOnlyTests from 'eslint-plugin-no-only-tests'
+
+export const GLOB_TESTS = [
+  '**/__tests__/**/*.{js,jsx,ts,tsx,mjs,cjs,mjsx,cts,ctsx}',
+  '**/*.spec.*',
+  '**/*.test.*',
+  '**/*.bench.*',
+  '**/*.benchmark.*',
+]
+
+// Test-file rules (Vitest conventions, no `.only` left behind).
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for test-file conventions. */
+export function testConfig() {
+  return [
+    {
+      name: 'storefront/test/rules',
+      files: GLOB_TESTS,
+      plugins: {
+        vitest,
+        'no-only-tests': noOnlyTests,
+      },
+      rules: {
+        'vitest/consistent-test-it': [
+          'error',
+          { fn: 'it', withinDescribe: 'it' },
+        ],
+        'vitest/no-identical-title': 'error',
+        'vitest/no-import-node-test': 'error',
+        'no-only-tests/no-only-tests': process.env.CI ? 'error' : 'warn',
+        'vitest/prefer-hooks-in-order': 'error',
+        'vitest/prefer-lowercase-title': 'error',
+      },
+    },
+  ]
+}

package/config/typescript.mjs

@@ -0,0 +1,92 @@
+import { defineConfig } from 'eslint/config'
+import tseslint from 'typescript-eslint'
+
+// TypeScript rules. Type-aware rules only activate when `tsconfigPath` is provided,
+// since they require a full TypeScript program build (`parserOptions.projectService`).
+//
+// The `@typescript-eslint` plugin is registered unscoped (no `files`) so that consumers
+// can reference `@typescript-eslint/*` rules from their own `files: ['**/*.vue']`
+// overrides (the plugin, not just the rule set, must be visible to those file globs too).
+// Core `no-unused-vars` is turned off only for the TypeScript file types below, scoped
+// to the same `files:` array as `@typescript-eslint/no-unused-vars`: it isn't type-aware,
+// so it misreads TypeScript-only constructs (e.g. a named parameter inside a type literal)
+// as real unused bindings. `.js`/`.mjs`/`.cjs` files keep the core rule from javascript.mjs.
+// Consumers that wire up `@typescript-eslint/parser` for another extension (like `.vue` via
+// `vue-eslint-parser`) should register `@typescript-eslint/no-unused-vars` there themselves,
+// since only they know which file types actually parse as TypeScript.
+/**
+ * @param {object} [config]
+ * @param {string} [config.tsconfigPath] Absolute path to the tsconfig.json to type-check
+ *   against. When omitted, only non-type-aware TypeScript rules apply.
+ * @returns {import('eslint').Linter.Config[]} Flat config entries for TypeScript rules.
+ */
+export function typescriptConfig(config = {}) {
+  const { tsconfigPath } = config
+
+  return defineConfig(
+    {
+      name: 'storefront/typescript/plugin',
+      plugins: { '@typescript-eslint': tseslint.plugin },
+    },
+    {
+      name: 'storefront/typescript',
+      files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
+      extends: [
+        tseslint.configs.recommended,
+        ...(tsconfigPath ? [tseslint.configs.recommendedTypeChecked] : []),
+      ],
+      ...(tsconfigPath
+        ? {
+            languageOptions: {
+              parserOptions: {
+                projectService: { defaultProject: tsconfigPath },
+                tsconfigRootDir: process.cwd(),
+              },
+            },
+          }
+        : {}),
+      rules: {
+        'no-unused-vars': 'off',
+        'no-use-before-define': 'off',
+        '@typescript-eslint/no-use-before-define': [
+          'error',
+          { functions: false, classes: false, variables: true },
+        ],
+        '@typescript-eslint/consistent-type-definitions': [
+          'error',
+          'interface',
+        ],
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          {
+            prefer: 'type-imports',
+            fixStyle: 'separate-type-imports',
+            disallowTypeAnnotations: false,
+          },
+        ],
+        '@typescript-eslint/method-signature-style': ['error', 'property'],
+        '@typescript-eslint/no-import-type-side-effects': 'error',
+        '@typescript-eslint/no-explicit-any': [
+          'warn',
+          { ignoreRestArgs: true },
+        ],
+        '@typescript-eslint/no-empty-object-type': [
+          'error',
+          { allowInterfaces: 'always' },
+        ],
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          {
+            args: 'all',
+            argsIgnorePattern: '^_',
+            caughtErrors: 'all',
+            caughtErrorsIgnorePattern: '^_',
+            destructuredArrayIgnorePattern: '^_',
+            varsIgnorePattern: '^_',
+            ignoreRestSiblings: true,
+          },
+        ],
+      },
+    },
+  )
+}

package/config/unicorn.mjs

@@ -0,0 +1,33 @@
+import pluginUnicorn from 'eslint-plugin-unicorn'
+
+const GLOB_SRC = '**/*.?([cm])[jt]s?(x)'
+
+// Modernization rules: a curated subset of eslint-plugin-unicorn, not its full
+// `recommended` preset (hundreds of opinionated rules, many stylistic).
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for modernization rules. */
+export function unicornConfig() {
+  return [
+    {
+      name: 'storefront/unicorn/rules',
+      files: [GLOB_SRC],
+      plugins: { unicorn: pluginUnicorn },
+      rules: {
+        'unicorn/consistent-empty-array-spread': 'error',
+        'unicorn/error-message': 'error',
+        'unicorn/escape-case': 'error',
+        'unicorn/new-for-builtins': 'error',
+        'unicorn/no-instanceof-builtins': 'error',
+        'unicorn/no-new-array': 'error',
+        'unicorn/no-new-buffer': 'error',
+        'unicorn/number-literal-case': 'error',
+        'unicorn/prefer-dom-node-text-content': 'error',
+        'unicorn/prefer-includes': 'error',
+        'unicorn/prefer-node-protocol': 'error',
+        'unicorn/prefer-number-properties': 'error',
+        'unicorn/prefer-string-starts-ends-with': 'error',
+        'unicorn/prefer-type-error': 'error',
+        'unicorn/throw-new-error': 'error',
+      },
+    },
+  ]
+}

package/config/v3/storybook.mjs

@@ -0,0 +1,10 @@
+import storybook from 'eslint-plugin-storybook'
+
+// https://github.com/storybookjs/eslint-plugin-storybook
+// Applies only to files matching `*.stories.*` / `*.story.*`.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for Storybook file conventions. */
+export function storybookConfig() {
+  return /** @type {import('eslint').Linter.Config[]} */ (
+    storybook.configs['flat/recommended']
+  )
+}

package/config/v3/tailwind.mjs

@@ -0,0 +1,30 @@
+import { defineConfig } from 'eslint/config'
+import eslintPluginBetterTailwindcss from 'eslint-plugin-better-tailwindcss'
+
+/**
+ * @param {object} config
+ * @param {string} config.entryPoint Path to the project's Tailwind CSS entry point
+ *   (e.g. `./src/client/index.css`), passed to the plugin's `entryPoint` setting.
+ * @returns {import('eslint').Linter.Config[]} Flat config entries for Tailwind CSS class validation.
+ */
+export function tailwindConfig(config) {
+  const { entryPoint } = config ?? {}
+
+  if (!entryPoint) {
+    throw new Error('storefrontV3: config.tailwind.entryPoint is required')
+  }
+
+  return defineConfig({
+    name: 'storefront/v3/tailwind',
+    extends: [eslintPluginBetterTailwindcss.configs.recommended],
+    rules: {
+      'better-tailwindcss/enforce-consistent-line-wrapping': 'off',
+      // The eslint plugin uses a different class order than the prettier plugin.
+      // Disabled to avoid conflicts between the two.
+      'better-tailwindcss/enforce-consistent-class-order': 'off',
+    },
+    settings: {
+      'better-tailwindcss': { entryPoint },
+    },
+  })
+}

package/config/v3/vue.mjs

@@ -0,0 +1,153 @@
+import tseslint from 'typescript-eslint'
+import vueParser from 'vue-eslint-parser'
+import pluginVue from 'eslint-plugin-vue'
+import pluginVueA11y from 'eslint-plugin-vuejs-accessibility'
+
+const GLOB_VUE = ['**/*.vue']
+
+// Vue parser wiring so `.vue` files (including `<script setup lang="ts">`) parse correctly.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries wiring the Vue parser. */
+function vueLanguageConfig() {
+  return [
+    ...pluginVue.configs['flat/essential'],
+    ...pluginVue.configs['flat/strongly-recommended'],
+    ...pluginVue.configs['flat/recommended'],
+    {
+      name: 'storefront/v3/vue-language',
+      files: GLOB_VUE,
+      languageOptions: {
+        parser: vueParser,
+        parserOptions: {
+          ecmaVersion: 'latest',
+          parser: tseslint.parser,
+          sourceType: 'module',
+          extraFileExtensions: ['.vue'],
+          ecmaFeatures: { jsx: true },
+        },
+      },
+    },
+  ]
+}
+
+/**
+ * @param {object} [config]
+ * @param {string[]} [config.undefComponentIgnores] Custom element tag names (e.g. web
+ *   components) to exempt from `vue/no-undef-components`.
+ * @returns {import('eslint').Linter.Config[]} Flat config entries for Vue-specific rule overrides.
+ */
+function vueRulesConfig(config = {}) {
+  const { undefComponentIgnores = [] } = config
+
+  return [
+    {
+      name: 'storefront/v3/vue-rules',
+      files: GLOB_VUE,
+      plugins: { vue: pluginVue },
+      rules: {
+        'eslint-comments/no-unlimited-disable': 'off',
+        // Core no-unused-vars isn't type-aware and misreads TypeScript-only
+        // constructs in <script setup lang="ts"> as real unused bindings.
+        // typescript.mjs only scopes the @typescript-eslint replacement to
+        // .ts/.tsx/.mts/.cts, so .vue files need their own registration.
+        'no-unused-vars': 'off',
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          {
+            args: 'all',
+            argsIgnorePattern: '^_',
+            caughtErrors: 'all',
+            caughtErrorsIgnorePattern: '^_',
+            destructuredArrayIgnorePattern: '^_',
+            varsIgnorePattern: '^_',
+            ignoreRestSiblings: true,
+          },
+        ],
+        '@typescript-eslint/no-empty-object-type': [
+          'error',
+          { allowInterfaces: 'always' },
+        ],
+        'vue/html-self-closing': [
+          'error',
+          {
+            html: { void: 'any', normal: 'any', component: 'always' },
+          },
+        ],
+        'vue/v-bind-style': [
+          'error',
+          'shorthand',
+          { sameNameShorthand: 'never' },
+        ],
+        'vue/no-undef-components': [
+          'error',
+          { ignorePatterns: undefComponentIgnores },
+        ],
+        'vue/define-emits-declaration': ['error', 'type-literal'],
+        'vue/custom-event-name-casing': ['error', 'camelCase'],
+        'vue/slot-name-casing': ['error', 'kebab-case'],
+        'vue/require-default-prop': 'off',
+        'vue/multi-word-component-names': 'warn',
+        'vue/block-order': [
+          'error',
+          { order: ['template', 'script', 'style'] },
+        ],
+        // Vue Styling
+        // Based on https://github.com/nuxt/eslint/blob/main/packages/eslint-config/src/configs/vue.ts#L142
+        'vue/html-closing-bracket-newline': 'off',
+        'vue/html-closing-bracket-spacing': 'off',
+        'vue/html-indent': 'off',
+        'vue/html-quotes': 'off',
+        'vue/max-attributes-per-line': 'off',
+        'vue/multiline-html-element-content-newline': 'off',
+        'vue/mustache-interpolation-spacing': 'off',
+        'vue/no-multi-spaces': 'off',
+        'vue/no-spaces-around-equal-signs-in-attribute': 'off',
+        'vue/singleline-html-element-content-newline': 'off',
+      },
+    },
+  ]
+}
+
+// Vue accessibility. Every rule ships `off` by default: this preset's baseline reflects
+// that a11y coverage is opt-in until a consumer's own audit turns rules on deliberately,
+// not a statement that these rules don't matter.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for Vue accessibility rules, defaulted off. */
+function vueA11yConfig() {
+  return [
+    ...pluginVueA11y.configs['flat/recommended'],
+    {
+      name: 'storefront/v3/vue-a11y',
+      files: GLOB_VUE,
+      rules: {
+        'vuejs-accessibility/mouse-events-have-key-events': 'off',
+        'vuejs-accessibility/no-static-element-interactions': 'off',
+        'vuejs-accessibility/anchor-has-content': 'off',
+        'vuejs-accessibility/aria-props': 'off',
+        'vuejs-accessibility/aria-role': 'off',
+        'vuejs-accessibility/aria-unsupported-elements': 'off',
+        'vuejs-accessibility/click-events-have-key-events': 'off',
+        'vuejs-accessibility/form-control-has-label': 'off',
+        'vuejs-accessibility/heading-has-content': 'off',
+        'vuejs-accessibility/iframe-has-title': 'off',
+        'vuejs-accessibility/interactive-supports-focus': 'off',
+        'vuejs-accessibility/label-has-for': 'off',
+        'vuejs-accessibility/media-has-caption': 'off',
+        'vuejs-accessibility/no-access-key': 'off',
+        'vuejs-accessibility/no-autofocus': 'off',
+        'vuejs-accessibility/no-distracting-elements': 'off',
+        'vuejs-accessibility/no-redundant-roles': 'off',
+        'vuejs-accessibility/role-has-required-aria-props': 'off',
+        'vuejs-accessibility/tabindex-no-positive': 'off',
+      },
+    },
+  ]
+}
+
+/**
+ * @param {object} [config]
+ * @param {string[]} [config.undefComponentIgnores] Custom element tag names exempt from
+ *   `vue/no-undef-components`.
+ * @returns {import('eslint').Linter.Config[]} Flat config entries for Vue language wiring, rules, and accessibility.
+ */
+export function vueConfig(config = {}) {
+  return [...vueLanguageConfig(), ...vueRulesConfig(config), ...vueA11yConfig()]
+}

package/config/v3/vueComposable.mjs

@@ -0,0 +1,29 @@
+import vueComposable from '@scayle/eslint-plugin-vue-composable'
+
+/**
+ * @param {object} [config]
+ * @param {string[]} [config.fallthroughAttrsIgnores] Path fragments (e.g. `/src/client/pages/`)
+ *   exempt from `require-explicit-fallthrough-attrs`, for components that never receive
+ *   fallthrough attributes (page/layout roots mounted by a router).
+ * @returns {import('eslint').Linter.Config[]} Flat config entries for `@scayle/vue-composable` rules.
+ */
+export function vueComposableConfig(config = {}) {
+  const { fallthroughAttrsIgnores = [] } = config
+
+  return [
+    {
+      name: 'storefront/v3/vue-composable',
+      plugins: { '@scayle/vue-composable': vueComposable },
+      rules: {
+        '@scayle/vue-composable/no-composable-after-await': 'error',
+        '@scayle/vue-composable/no-lifecycle-after-await': 'error',
+        '@scayle/vue-composable/no-watch-after-await': 'error',
+        '@scayle/vue-composable/no-computed-after-await': 'error',
+        '@scayle/vue-composable/require-explicit-fallthrough-attrs': [
+          'error',
+          { ignores: fallthroughAttrsIgnores },
+        ],
+      },
+    },
+  ]
+}

package/config/v3/vueI18n.mjs

@@ -0,0 +1,52 @@
+import vueI18n from '@intlify/eslint-plugin-vue-i18n'
+
+/**
+ * @param {object} config
+ * @param {string} config.localeDir Glob pointing at the project's locale JSON files
+ *   (e.g. `./src/i18n/locales/*.json`), passed to the `vue-i18n` plugin's `localeDir` setting.
+ * @param {string} [config.messageSyntaxVersion] `vue-i18n` message syntax version.
+ * @param {string[]} [config.unusedKeyIgnores] Regex-string patterns (e.g. `/foo.bar/`) for keys
+ *   used dynamically in code, which `no-unused-keys` can't detect statically.
+ * @returns {import('eslint').Linter.Config[]} Flat config entries for `vue-i18n` linting.
+ */
+export function vueI18nConfig(config) {
+  const {
+    localeDir,
+    messageSyntaxVersion = '^11.2.8',
+    unusedKeyIgnores = [],
+  } = config ?? {}
+
+  if (!localeDir) {
+    throw new Error('storefrontV3: config.i18n.localeDir is required')
+  }
+
+  return [
+    ...vueI18n.configs['flat/base'],
+    {
+      name: 'storefront/v3/vue-i18n',
+      rules: {
+        '@intlify/vue-i18n/valid-message-syntax': 'error',
+        // Passes when any of the locale files contains a used key
+        '@intlify/vue-i18n/no-missing-keys': 'error',
+        // Passes when all locale files contain the same keys.
+        '@intlify/vue-i18n/no-missing-keys-in-other-locales': process.env.CI
+          ? 'error'
+          : 'warn',
+        '@intlify/vue-i18n/no-duplicate-keys-in-locale': 'error',
+        '@intlify/vue-i18n/no-dynamic-keys': 'off',
+        // Performance-intensive: scans all matching files for unused translation keys.
+        '@intlify/vue-i18n/no-unused-keys': [
+          'error',
+          {
+            src: './src/{client,server,shared}/**',
+            extensions: ['.vue', '.ts'],
+            ignores: unusedKeyIgnores,
+          },
+        ],
+      },
+      settings: {
+        'vue-i18n': { localeDir, messageSyntaxVersion },
+      },
+    },
+  ]
+}