@scayle/eslint-config-storefront 5.0.0 → 5.1.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @aboutyou/eslint-config-sfc
 
+## 5.1.1
+
+### Patch Changes
+
+- Updated dependency `eslint-plugin-unicorn@^73.0.0` to `eslint-plugin-unicorn@^74.0.0`
+
+## 5.1.0
+
+### Minor Changes
+
+- `@scayle/eslint-config-storefront/v3` now wires an `eslint-import-resolver-typescript` resolver by default, pointed at the project's `tsconfig.json`. Path aliases like `@client/*` or `@server/*` resolve to real files, so `import-x/no-restricted-paths` and `import-x/no-cycle` see through them instead of only matching literal relative imports.
+
+  Two rules also newly cover ground they didn't before, both enabled for the first time rather than tightened:
+
+  - `import-x/order` wasn't configured anywhere in `/v3` until now. It ships at `error`, with an explicit `groups` option ranking aliased imports alongside package imports, ahead of relative ones. A project already using `/v3` may see new ordering errors on upgrade.
+  - `import-x/no-cycle` previously only saw `.js`/`.mjs`/`.cjs` files. `.ts` and `.tsx` are now included, so a circular dependency that only existed between TypeScript files, alias or not, is caught for the first time.
+
+  `resolver.tsconfigPath` points the resolver at a specific tsconfig, independent of `typescript.tsconfigPath` (which also switches on type-aware TypeScript rules). Without either set, the resolver and the `no-restricted-paths` zones fall back to resolving relative to ESLint's working directory, correct when linting runs via `pnpm lint`/CI but not guaranteed for an editor's ESLint extension. Set `resolver.tsconfigPath` to an absolute path if that matters for your setup.
+
+### Patch Changes
+
+- Added dependency `eslint-import-resolver-typescript@^4.4.5`
+
 ## 5.0.0
 
 ### Major Changes

package/README.md

@@ -48,7 +48,7 @@ export default withNuxt(storefrontNuxt())
 The Storefront Application V3 stack (Hono + Inertia.js + Vue 3, not Nuxt) should use the
 `/v3` entry point. It builds on the default config and adds Vue language wiring, Vue rules,
 accessibility rules, `vue-i18n` linting, `@scayle/vue-composable` rules, Storybook file
-conventions, and Tailwind CSS class validation:
+conventions, Tailwind CSS class validation, and a TypeScript-aware import resolver:
 
 ```js
 // eslint.config.mjs
@@ -67,10 +67,42 @@ export default storefrontV3({
 `tailwind.entryPoint` and `i18n.localeDir` are required, the underlying plugins can't
 validate Tailwind classes or i18n keys without a real path. Optional options:
 
+- `typescript.tsconfigPath`: absolute path to a `tsconfig.json`. Enables type-aware
+  TypeScript rules and points the import resolver at that file instead of
+  `<root>/tsconfig.json`
+- `resolver.tsconfigPath`: absolute path to a `tsconfig.json` for the import resolver only,
+  independent of `typescript.tsconfigPath`. Use this instead when you want the resolver
+  fix below without also switching on type-aware TypeScript rules
+- `i18n.messageSyntaxVersion`: `vue-i18n` message syntax version, defaults to `^11.2.8`
 - `i18n.unusedKeyIgnores`: regex-string patterns for translation keys used dynamically in code
 - `vue.undefComponentIgnores`: custom element (web component) tag names to exempt from `vue/no-undef-components`
 - `vueComposable.fallthroughAttrsIgnores`: path fragments to exempt from `require-explicit-fallthrough-attrs` (e.g. router-mounted page/layout roots that never receive fallthrough attributes)
 
+#### Import resolution
+
+`/v3` wires `eslint-import-resolver-typescript`, so `import-x` rules resolve `tsconfig.json`
+path aliases (`@client/*`, `@server/*`, or any other `paths` entry) to their real files
+instead of only matching literal relative imports. Three rules depend on that resolution
+to work correctly against an aliased import:
+
+- `import-x/no-restricted-paths`: zone violations across an alias fail lint, not just
+  across a relative path
+- `import-x/no-cycle`: circular dependencies through an aliased import are caught. `.vue`
+  files are the one exception, a cycle through a `.vue` file only surfaces when ESLint
+  lints that file directly
+- `import-x/order`: aliased imports rank alongside package imports (`external`), ahead of
+  relative ones, instead of dropping to last place once the resolver can see they resolve
+  to a project file
+
+Without `resolver.tsconfigPath` or `typescript.tsconfigPath` set, both the resolver and
+`import-x/no-restricted-paths`'s zones resolve relative to ESLint's own working directory.
+That's correct for `pnpm lint` and CI, since a monorepo's task runner always runs a
+package's lint script with that package as the working directory, but not guaranteed for
+an editor's ESLint extension, which can run with the workspace root as its working
+directory instead. Set `resolver.tsconfigPath` to an absolute path (for example,
+`new URL('./tsconfig.json', import.meta.url).pathname` in your `eslint.config.mjs`) if your
+editor's linting needs to match the command-line result.
+
 ### Add script for package.json
 
 For example:

package/config/v3/importResolver.mjs

@@ -0,0 +1,71 @@
+import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript'
+
+// Resolves aliased imports (e.g. tsconfig.json `paths` like `@client/*`) to their real
+// files, so import-x/no-restricted-paths, import-x/no-cycle, and import-x/order can see
+// through them instead of only matching literal relative imports. Without this, every
+// rule that compares resolved paths silently no-ops on an alias it can't resolve.
+/**
+ * @param {string} [tsconfigPath] Absolute path to the tsconfig.json to resolve aliases
+ *   against (from `resolver.tsconfigPath`, falling back to `typescript.tsconfigPath`).
+ *   Omit both to use the resolver's own `<cwd>/tsconfig.json` default.
+ * @returns {import('eslint').Linter.Config[]} Flat config entries wiring the resolver and
+ *   the setting import-x/no-cycle needs to use it correctly.
+ */
+export function importResolverConfig(tsconfigPath) {
+  return [
+    {
+      name: 'storefront/v3/import-resolver',
+      settings: {
+        'import-x/resolver-next': [
+          createTypeScriptImportResolver(
+            tsconfigPath ? { project: tsconfigPath } : undefined,
+          ),
+        ],
+        // import-x/no-cycle builds its own export map per file and gates that on
+        // this setting (distinct from the import-x/extensions *rule*). It defaults
+        // to .js/.mjs/.cjs only, so without this, every .ts/.tsx file silently
+        // returns a null export map and cycles through them go undetected past
+        // depth 1, alias or not.
+        //
+        // .vue is deliberately not listed here: the export map builder's parser
+        // (via import-x/parsers) can't replicate the <script setup lang="ts">
+        // sub-parser wiring vueConfig() sets up, so it errors on every .vue file's
+        // <template> block. Those errors are swallowed rather than surfaced as lint
+        // failures, but they also mean a walk that needs to build a .vue file's
+        // export map (rather than lint it directly) can't see past it. A cycle
+        // that runs through a .vue file still gets caught when ESLint lints that
+        // .vue file itself, since it parses that one file with the real language
+        // config, not the export map builder.
+        'import-x/extensions': ['.js', '.mjs', '.cjs', '.ts', '.tsx'],
+      },
+    },
+  ]
+}
+
+// The default groups list omits 'internal' (the rank an aliased import gets once it
+// resolves), which would otherwise drop every @client/@server/@shared-style import to
+// last place instead of sorting with 'external' the way Vue 3 projects conventionally
+// write them. 'builtin' stays its own rank, ahead of both: a `node:*` import belongs at
+// the top of the file the same way it already does under the default groups.
+/** @returns {import('eslint').Linter.Config[]} Flat config entries for import ordering, aware of resolved aliases. */
+export function importOrderConfig() {
+  return [
+    {
+      name: 'storefront/v3/import-order',
+      rules: {
+        'import-x/order': [
+          'error',
+          {
+            groups: [
+              'builtin',
+              ['external', 'internal'],
+              'parent',
+              'sibling',
+              'index',
+            ],
+          },
+        ],
+      },
+    },
+  ]
+}

package/config/v3.mjs

@@ -5,11 +5,24 @@ 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.
@@ -26,14 +39,16 @@ import { tailwindConfig } from './v3/tailwind.mjs'
  * 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, and Tailwind CSS class validation. Kept separate from
- * `storefront()`/`storefrontNuxt()` since those two stay framework-agnostic.
+ * 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, tailwind, i18n, vue, vueComposable } = config ?? {}
+  const { typescript, resolver, tailwind, i18n, vue, vueComposable } =
+    config ?? {}
 
   /** @type {FlatConfigComposer<import('eslint').Linter.Config, never>} */
   const flatConfigComposer = new FlatConfigComposer()
@@ -45,5 +60,7 @@ export const storefrontV3 = function (config) {
     ...vueConfig(vue),
     ...vueI18nConfig(i18n),
     ...vueComposableConfig(vueComposable),
+    ...importResolverConfig(resolver?.tsconfigPath ?? typescript?.tsconfigPath),
+    ...importOrderConfig(),
   )
 }

package/config/v3.test.mjs

@@ -27,4 +27,102 @@ describe('storefrontV3', () => {
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/eslint-config-storefront",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "description": "SCAYLE Commerce Engine specific eslint configuration",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -41,9 +41,11 @@
     "@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-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",
@@ -54,20 +56,19 @@
     "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-unicorn": "^74.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",
-    "@scayle/eslint-plugin-vue-composable": "1.2.1"
+    "vue-eslint-parser": "^10.4.1"
   },
   "devDependencies": {
     "@types/node": "^24",
     "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.8.1",
+    "eslint": "10.9.1",
     "eslint-formatter-gitlab": "7.2.0",
-    "publint": "0.3.23",
+    "publint": "0.3.24",
     "typescript": "6.0.3",
     "vitest": "4.1.11"
   },