@scayle/eslint-config-storefront 4.8.3-alpha.1 → 5.1.0

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 },
+      },
+    },
+  ]
+}

package/config/v3.mjs

@@ -0,0 +1,66 @@
+import { FlatConfigComposer } from 'eslint-flat-config-utils'
+import { storefront } from './index.mjs'
+import { vueConfig } from './v3/vue.mjs'
+import { vueI18nConfig } from './v3/vueI18n.mjs'
+import { vueComposableConfig } from './v3/vueComposable.mjs'
+import { storybookConfig } from './v3/storybook.mjs'
+import { tailwindConfig } from './v3/tailwind.mjs'
+import {
+  importResolverConfig,
+  importOrderConfig,
+} from './v3/importResolver.mjs'
+
+/**
+ * @typedef {object} EslintConfigStorefrontV3Options
+ * @property {object} [typescript] Options forwarded to `typescriptConfig` (see `storefront`).
+ * @property {string} [typescript.tsconfigPath] Enables type-aware TypeScript rules when set.
+ * @property {object} [resolver] Import resolver settings.
+ * @property {string} [resolver.tsconfigPath] Absolute path to the tsconfig.json the import
+ *   resolver reads `paths` aliases from. Independent of `typescript.tsconfigPath`: passing
+ *   an absolute path here does not switch on type-aware TypeScript rules. Omit to fall back
+ *   to `typescript.tsconfigPath`, then to the resolver's own `<cwd>/tsconfig.json` default,
+ *   which only resolves correctly when ESLint's working directory happens to be this project's
+ *   root (true for `pnpm lint`/CI via Turborepo, not guaranteed for an editor's ESLint
+ *   extension). Set this explicitly, as an absolute path anchored to the config file's own
+ *   location, if ESLint might ever run with a different working directory.
+ * @property {object} tailwind Tailwind CSS settings.
+ * @property {string} tailwind.entryPoint Path to the project's Tailwind CSS entry point.
+ * @property {object} i18n `vue-i18n` linting settings.
+ * @property {string} i18n.localeDir Glob pointing at the project's locale JSON files.
+ * @property {string} [i18n.messageSyntaxVersion] `vue-i18n` message syntax version.
+ * @property {string[]} [i18n.unusedKeyIgnores] Regex-string patterns for dynamically-used keys.
+ * @property {object} [vue] Vue rule settings.
+ * @property {string[]} [vue.undefComponentIgnores] Custom element tag names exempt from `vue/no-undef-components`.
+ * @property {object} [vueComposable] `@scayle/vue-composable` rule settings.
+ * @property {string[]} [vueComposable.fallthroughAttrsIgnores] Path fragments exempt from `require-explicit-fallthrough-attrs`.
+ */
+
+/**
+ * Builds the SCAYLE Storefront ESLint flat config for the Storefront Application V3 stack
+ * (Hono + Inertia.js + Vue 3, not Nuxt). Extends `storefront()` with Vue language wiring,
+ * Vue rules, accessibility rules, `vue-i18n` rules, `@scayle/vue-composable` rules,
+ * Storybook file conventions, Tailwind CSS class validation, and a TypeScript-aware
+ * import resolver. Kept separate from `storefront()`/`storefrontNuxt()` since those two
+ * stay framework-agnostic.
+ *
+ * @param {EslintConfigStorefrontV3Options} config
+ * @returns {FlatConfigComposer<import('eslint').Linter.Config, never>} Returns a FlatConfigComposer object to be consumed in projects eslint.config.mjs files
+ */
+export const storefrontV3 = function (config) {
+  const { typescript, resolver, tailwind, i18n, vue, vueComposable } =
+    config ?? {}
+
+  /** @type {FlatConfigComposer<import('eslint').Linter.Config, never>} */
+  const flatConfigComposer = new FlatConfigComposer()
+
+  return flatConfigComposer.append(
+    storefront({ typescript }),
+    ...tailwindConfig(tailwind),
+    ...storybookConfig(),
+    ...vueConfig(vue),
+    ...vueI18nConfig(i18n),
+    ...vueComposableConfig(vueComposable),
+    ...importResolverConfig(resolver?.tsconfigPath ?? typescript?.tsconfigPath),
+    ...importOrderConfig(),
+  )
+}

package/config/v3.test.mjs

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+import { storefrontV3 } from './v3.mjs'
+
+describe('storefrontV3', () => {
+  it('throws without tailwind.entryPoint', () => {
+    expect(() =>
+      // @ts-expect-error missing required `tailwind`, exercising the runtime guard
+      storefrontV3({ i18n: { localeDir: './src/i18n/locales/*.json' } }),
+    ).toThrow('config.tailwind.entryPoint is required')
+  })
+
+  it('throws without i18n.localeDir', () => {
+    expect(() =>
+      // @ts-expect-error missing required `i18n`, exercising the runtime guard
+      storefrontV3({ tailwind: { entryPoint: './src/client/index.css' } }),
+    ).toThrow('config.i18n.localeDir is required')
+  })
+
+  it('returns a config with both required options set', async () => {
+    const config = storefrontV3({
+      tailwind: { entryPoint: './src/client/index.css' },
+      i18n: { localeDir: './src/i18n/locales/*.json' },
+    })
+
+    const resolved = await config.toConfigs()
+
+    expect(Array.isArray(resolved)).toBe(true)
+    expect(resolved.length).toBeGreaterThan(0)
+  })
+
+  // These settings have no test-visible failure mode of their own: a reverted or
+  // misconfigured resolver/extensions/groups entry still produces a config that loads
+  // and lints without error, it just silently stops catching what it's meant to catch.
+  // Asserting the shape here is what makes a quiet revert fail CI instead of passing it.
+  it('wires the import resolver and no-cycle extensions', async () => {
+    const config = storefrontV3({
+      tailwind: { entryPoint: './src/client/index.css' },
+      i18n: { localeDir: './src/i18n/locales/*.json' },
+    })
+
+    const resolved = await config.toConfigs()
+    const resolverEntry = resolved.find(
+      (c) => c.name === 'storefront/v3/import-resolver',
+    )
+    if (!resolverEntry) {
+      throw new Error('resolverEntry not found')
+    }
+    const { settings } = resolverEntry
+    if (!settings) {
+      throw new Error('resolverEntry.settings not found')
+    }
+
+    const resolverNext =
+      /** @type {{ name: string, interfaceVersion: number }[]} */ (
+        settings['import-x/resolver-next']
+      )
+    expect(resolverNext).toHaveLength(1)
+    expect(resolverNext[0]).toMatchObject({
+      name: 'eslint-import-resolver-typescript',
+      interfaceVersion: 3,
+    })
+    expect(settings['import-x/extensions']).toEqual([
+      '.js',
+      '.mjs',
+      '.cjs',
+      '.ts',
+      '.tsx',
+    ])
+    expect(settings['import-x/extensions']).not.toContain('.vue')
+  })
+
+  it('ranks internal imports alongside external ones in import-x/order', async () => {
+    const config = storefrontV3({
+      tailwind: { entryPoint: './src/client/index.css' },
+      i18n: { localeDir: './src/i18n/locales/*.json' },
+    })
+
+    const resolved = await config.toConfigs()
+    const orderEntry = resolved.find(
+      (c) => c.name === 'storefront/v3/import-order',
+    )
+    if (!orderEntry) {
+      throw new Error('orderEntry not found')
+    }
+    const { rules } = orderEntry
+    if (!rules) {
+      throw new Error('orderEntry.rules not found')
+    }
+    const orderRule = rules['import-x/order']
+    if (!orderRule) {
+      throw new Error('import-x/order rule not found')
+    }
+    const [severity, options] = /** @type {[string, { groups: unknown[] }]} */ (
+      orderRule
+    )
+
+    expect(severity).toBe('error')
+    expect(options.groups).toEqual([
+      'builtin',
+      ['external', 'internal'],
+      'parent',
+      'sibling',
+      'index',
+    ])
+  })
+
+  it('accepts resolver.tsconfigPath independently of typescript.tsconfigPath', async () => {
+    // Both must resolve without throwing: resolver.tsconfigPath alone (no type-aware
+    // TypeScript rules switched on) and typescript.tsconfigPath alone (the fallback
+    // path, still feeding the resolver). The resolver's own internals aren't asserted
+    // on here, only that both option shapes are accepted.
+    await expect(
+      storefrontV3({
+        tailwind: { entryPoint: './src/client/index.css' },
+        i18n: { localeDir: './src/i18n/locales/*.json' },
+        resolver: { tsconfigPath: '/absolute/resolver-tsconfig.json' },
+      }).toConfigs(),
+    ).resolves.toBeInstanceOf(Array)
+
+    await expect(
+      storefrontV3({
+        tailwind: { entryPoint: './src/client/index.css' },
+        i18n: { localeDir: './src/i18n/locales/*.json' },
+        typescript: { tsconfigPath: '/absolute/typescript-tsconfig.json' },
+      }).toConfigs(),
+    ).resolves.toBeInstanceOf(Array)
+  })
+})

package/index.mjs

@@ -1,3 +1,4 @@
-import { eslintConfigStorefront } from './config/flat/index.mjs'
+import { storefront } from './config/index.mjs'
 
-export default eslintConfigStorefront
+export default storefront
+export { storefront }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/eslint-config-storefront",
-  "version": "4.8.3-alpha.1",
+  "version": "5.1.0",
   "description": "SCAYLE Commerce Engine specific eslint configuration",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -17,46 +17,66 @@
   "type": "module",
   "exports": {
     ".": "./index.mjs",
-    "./config/flat/index.mjs": "./config/flat/index.mjs",
-    "./config/flat/sonarjs": "./config/flat/sonarjs.mjs",
-    "./config/flat/promise.mjs": "./config/flat/promise.mjs",
-    "./config/flat/importX.mjs": "./config/flat/importX.mjs"
+    "./nuxt": "./storefront-nuxt.mjs",
+    "./v3": "./storefront-v3.mjs"
   },
   "main": "./index.mjs",
   "files": [
     "CHANGELOG.md",
     "README.md",
     "./index.mjs",
+    "./storefront-nuxt.mjs",
+    "./storefront-v3.mjs",
     "./config/"
   ],
   "engines": {
     "node": ">= 22.0.0"
   },
   "peerDependencies": {
-    "eslint": ">=9.0.0",
+    "eslint": ">=10.4.0",
     "typescript": ">=5.4.0"
   },
   "dependencies": {
-    "@antfu/eslint-config": "^9.0.0",
-    "@eslint/eslintrc": "^3.3.5",
-    "eslint-config-flat-gitignore": "^2.2.0",
+    "@e18e/eslint-plugin": "^0.8.0",
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.7.2",
+    "@eslint/js": "^10.0.0",
+    "@intlify/eslint-plugin-vue-i18n": "^4.5.1",
+    "@scayle/eslint-plugin-vue-composable": "1.2.1",
+    "@vitest/eslint-plugin": "^1.6.20",
+    "eslint-config-flat-gitignore": "^2.3.0",
     "eslint-flat-config-utils": "^3.2.0",
-    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-better-tailwindcss": "^4.7.0",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-jsdoc": "^64.2.1",
+    "eslint-plugin-jsonc": "^3.4.1",
+    "eslint-plugin-n": "^18.3.0",
+    "eslint-plugin-no-only-tests": "^3.4.0",
     "eslint-plugin-promise": "^7.3.0",
-    "eslint-plugin-sonarjs": "^4.0.3",
-    "local-pkg": "^1.2.1",
-    "typescript-eslint": "8.67.0"
+    "eslint-plugin-regexp": "^3.2.0",
+    "eslint-plugin-sonarjs": "^4.2.0",
+    "eslint-plugin-storybook": "^10.5.8",
+    "eslint-plugin-unicorn": "^73.0.0",
+    "eslint-plugin-vue": "^10.10.0",
+    "eslint-plugin-vuejs-accessibility": "^2.6.0",
+    "globals": "^17.7.0",
+    "typescript-eslint": "^8.67.0",
+    "vue-eslint-parser": "^10.4.1"
   },
   "devDependencies": {
-    "eslint": "10.8.1",
+    "@types/node": "^24",
+    "@vitest/coverage-v8": "4.1.11",
+    "eslint": "10.9.1",
     "eslint-formatter-gitlab": "7.2.0",
-    "publint": "0.3.23",
-    "typescript": "6.0.3"
+    "publint": "0.3.24",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
   },
   "scripts": {
     "lint": "eslint .",
     "lint:ci": "eslint . --format gitlab",
     "lint:fix": "eslint . --fix",
-    "package:lint": "publint"
+    "package:lint": "publint",
+    "typecheck": "tsc"
   }
 }

package/storefront-nuxt.mjs

@@ -0,0 +1,4 @@
+import { storefrontNuxt } from './config/index.mjs'
+
+export default storefrontNuxt
+export { storefrontNuxt }

package/storefront-v3.mjs

@@ -0,0 +1,4 @@
+import { storefrontV3 } from './config/v3.mjs'
+
+export default storefrontV3
+export { storefrontV3 }

package/config/flat/importX.mjs

@@ -1,22 +0,0 @@
-import { importX as pluginImportX } from 'eslint-plugin-import-x'
-
-// Pre-defined rule configurations for better performance
-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',
-}
-
-export function importX() {
-  return [
-    {
-      name: 'storefront/import-x/rules',
-      plugins: { 'import-x': pluginImportX },
-      rules: IMPORT_X_RULES,
-    },
-  ]
-}